ASP.NET Core Blazor WebAssembly .NET çalışma zamanı ve uygulama paketi önbelleğe alma

  • Makale

Not

Bu, bu makalenin en son sürümü değildir. Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Önemli

Bu bilgiler, ticari olarak piyasaya sürülmeden önce önemli ölçüde değiştirilebilen bir yayın öncesi ürünle ilgilidir. Burada verilen bilgilerle ilgili olarak Microsoft açık veya zımni hiçbir garanti vermez.

Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Bir Blazor WebAssembly uygulama tarayıcıda yüklendiğinde, uygulama sunucudan önyükleme kaynaklarını indirir:

  • Uygulamayı önyüklemek için JavaScript kodu
  • .NET çalışma zamanı ve derlemeleri
  • Yerel ayara özgü veriler

Blazor'nin önyükleme kaynakları dosyası (blazor.boot.json ) dışında, WebAssembly .NET çalışma zamanı ve uygulama paketi dosyaları istemcilerde önbelleğe alınır. Dosya, blazor.boot.json önyükleme kaynaklarından herhangi birinin değişip değişmediğini algılamak için kullanılan dosyanın içeriğinin karmasıyla birlikte indirilmesi gereken uygulamayı oluşturan dosyaların bildirimini içerir. Blazor tarayıcı Önbellek API'sini kullanarak indirilen dosyaları önbelleğe alır .

Bir uygulamanın başlangıç dosyalarını indirdiğinde Blazor WebAssembly , tarayıcıya yanıtlar üzerinde bütünlük denetimleri gerçekleştirmesini belirtir. BlazorDLL (), WebAssembly (.dll.wasm ) ve dosyadaki blazor.boot.json diğer dosyalar için SHA-256 karma değerlerini gönderir. Önbelleğe alınan dosyaların dosya karmaları, dosyadaki blazor.boot.json karmalarla karşılaştırılır. Eşleşen karma içeren önbelleğe alınmış dosyalar için önbelleğe Blazor alınmış dosyaları kullanır. Aksi takdirde, dosyalar sunucudan istenir. Bir dosya indirildikten sonra karma değeri bütünlük doğrulaması için yeniden denetlenecektir. İndirilen herhangi bir dosyanın bütünlük denetimi başarısız olursa tarayıcı tarafından bir hata oluşturulur.

Blazor'nin dosya bütünlüğünü yönetme algoritması:

  • Kullanıcının uygulama dosyalarını indirme işlemi sırasında web sunucunuza yeni bir dağıtım uygulanması gibi, uygulamanın tutarsız bir dosya kümesini yükleme riskini almamasını sağlar. Tutarsız dosyalar hatalı çalışan bir uygulamaya neden olabilir.
  • Kullanıcının tarayıcısının hiçbir zaman tutarsız veya geçersiz yanıtları önbelleğe almamasını sağlar. Bu, kullanıcı sayfayı el ile yenilese bile uygulamanın başlatılmasını engelleyebilir.
  • Beklenen SHA-256 karmaları değişene kadar yanıtları önbelleğe alma ve sunucu tarafı değişikliklerini denetlememenizi güvenli hale getirir, böylece sonraki sayfa yüklemeleri daha az istek içerir ve daha hızlı tamamlanır.

Web sunucusu beklenen SHA-256 karmalarıyla eşleşmeyen yanıtlar döndürürse, tarayıcının geliştirici konsolunda aşağıdaki örneğe benzer bir hata görüntülenir:

Hesaplanan SHA-256 bütünlüğü 'IIa70iwvmEg5WiDV17OpQ5eCztNYqL186J56852RpJY=' ile 'https://myapp.example.com/_framework/MyBlazorApp.dll' kaynağının 'integrity' özniteliğinde geçerli bir özet bulunamadı. Kaynak engellendi.

Çoğu durumda, uyarı bütünlük denetimiyle ilgili bir sorun olduğunu göstermez. Bunun yerine, uyarı genellikle başka bir sorunun var olduğu anlamına gelir.

Not

.NET başvuru kaynağına yönelik belge bağlantıları genellikle deponun varsayılan dalını yükler ve bu dal .NET'in sonraki sürümü için geçerli geliştirmeyi temsil eder. Belirli bir sürümün etiketini seçmek için Dalları veya etiketleri değiştir açılan listesini kullanın. Daha fazla bilgi için bkz. ASP.NET Core kaynak kodunun sürüm etiketini seçme (dotnet/AspNetCore.Docs #26205).

Bütünlük sorunlarını tanılama

Bir uygulama oluşturulduğunda, oluşturulan blazor.boot.json bildirim, derleme çıkışının oluşturulduğu sırada önyükleme kaynaklarının SHA-256 karmalarını açıklar. Içindeki SHA-256 karmaları tarayıcıya teslim edilen dosyalarla blazor.boot.json eşleştiği sürece bütünlük denetimi geçer.

Bunun başarısız olmasının yaygın nedenleri şunlardır:

  • Web sunucusunun yanıtı, tarayıcının istediği dosya yerine bir hatadır (örneğin, 404 - Bulunamadı veya 500 - İç Sunucu Hatası). Bu, tarayıcı tarafından yanıt hatası olarak değil bütünlük denetimi hatası olarak bildirilir.
  • Dosyaların derlemesi ve tarayıcıya teslimi arasında dosyaların içeriğini değiştiren bir şey var. Bu durum oluşabilir:
    • Siz veya derleme araçları derleme çıktısını el ile değiştirirseniz.
    • Dağıtım işleminin bazı yönleri dosyaları değiştirdiyse. Örneğin, Git tabanlı dağıtım mekanizması kullanıyorsanız, Windows'da dosya işleyip Bunları Linux'ta kullanıma alırsanız Git'in Windows stili satır sonlarını saydam bir şekilde Unix stili satır sonlarına dönüştürdüğünü unutmayın. Dosya satırı sonlarının değiştirilmesi SHA-256 karmalarını değiştirir. Bu sorunu önlemek için derleme yapıtlarını dosya olarak kabul etmek için kullanmayı .gitattributes göz önünde bulundurun.binary
    • Web sunucusu, dosya içeriğini sunmanın bir parçası olarak değiştirir. Örneğin, bazı içerik dağıtım ağları (CDN'ler) HTML'yi otomatik olarak küçültmeyi dener ve bu şekilde değiştirir. Bu tür özellikleri devre dışı bırakmanız gerekebilir.
  • Dosya blazor.boot.json düzgün yüklenemedi veya istemcide yanlış önbelleğe alınmış. Yaygın nedenler şunlardan birini içerir:
    • Yanlış yapılandırılmış veya hatalı çalışan özel geliştirici kodu.
    • Bir veya daha fazla yanlış yapılandırılmış ara önbelleğe alma katmanı.

Sizin durumunuzda bunlardan hangisinin geçerli olduğunu tanılamak için:

  1. Hata iletisini okuyarak hangi dosyanın hatayı tetiklediğine dikkat edin.
  2. Tarayıcınızın geliştirici araçlarını açın ve Ağ sekmesine bakın. Gerekirse, istek ve yanıt listesini görmek için sayfayı yeniden yükleyin. Bu listede hatayı tetikleyen dosyayı bulun.
  3. Yanıttaki HTTP durum kodunu denetleyin. Sunucu 200 - Tamam (veya başka bir 2xx durum kodu) dışında bir şey döndürürse tanılamanız gereken bir sunucu tarafı sorununuz vardır. Örneğin, durum kodu 403 yetkilendirme sorunu olduğu, durum kodu 500 ise sunucunun belirtilmeyen bir şekilde başarısız olduğu anlamına gelir. Uygulamayı tanılamak ve düzeltmek için sunucu tarafı günlüklerine başvurun.
  4. Durum kodu 200 - Kaynak için Tamam ise, tarayıcının geliştirici araçlarında yanıt içeriğine bakın ve içeriğin beklenen verilerle eşleşip eşleşmediğini denetleyin. Örneğin, sık karşılaşılan bir sorun, isteklerin diğer dosyalar için bile verilerinizi index.html döndürmesi için yönlendirmeyi yanlış yapılandırmaktır. İsteklere .wasm verilen yanıtların WebAssembly ikilileri olduğundan ve isteklere verilen .dll yanıtların .NET derleme ikili dosyaları olduğundan emin olun. Aksi takdirde, tanılamanız gereken bir sunucu tarafı yönlendirme sorununuz vardır.
  5. Bütünlük sorunlarını giderme PowerShell betiğiyle uygulamanın yayımlanan ve dağıtılan çıkışını doğrulamaya bakın.

Sunucunun makul şekilde doğru veriler döndürdüğünü onaylarsanız, dosyanın derlemesi ve teslimi arasında içeriği değiştiren başka bir şey olmalıdır. Bunu araştırmak için:

  • Derleme araç zincirini ve dağıtım mekanizmasını, dosyalar oluşturulduktan sonra dosyaları değiştirip değiştirmediklerini inceleyin. Bunun bir örneği, Git'in daha önce açıklandığı gibi dosya satırı sonlarını dönüştürmesidir.
  • Yanıtları dinamik olarak değiştirmeye (örneğin, HTML'yi küçültmeye çalışma) ayarlanmış olma ihtimaline karşı web sunucusunu veya CDN yapılandırmasını inceleyin. Web sunucusunun HTTP sıkıştırması (örneğin, döndüren content-encoding: br veya content-encoding: gzip) uygulaması sorun değildir, çünkü bu durum sıkıştırmadan sonra sonucu etkilemez. Ancak, web sunucusunun sıkıştırılmamış verileri değiştirmesi uygun değildir .

Bütünlük sorunlarını giderme PowerShell betiği

integrity.ps1 Yayımlanan ve dağıtılan Blazor bir uygulamayı doğrulamak için PowerShell betiğini kullanın. Betik, uygulamanın çerçevenin tanımlayabildiği bütünlük sorunları Blazor olduğunda başlangıç noktası olarak PowerShell Core 7 veya üzeri için sağlanır. PowerShell'in 7.2.0 sürümünden sonraki bir sürümde çalışıyor olması da dahil olmak üzere, uygulamalarınız için betiğin özelleştirilmesi gerekebilir.

Betik, bütünlük karmaları içeren farklı bildirimlerdeki publish sorunları algılamak için klasördeki ve dağıtılan uygulamadan indirilen dosyaları denetler. Bu denetimler en yaygın sorunları algılamalıdır:

  • Yayımlanan çıktıdaki bir dosyayı farkında olmadan değiştirdiniz.
  • Uygulama dağıtım hedefine doğru dağıtılmadı veya dağıtım hedefinin ortamında bir şey değiştirildi.
  • Dağıtılan uygulama ile uygulamayı yayımlama çıktısı arasında farklar vardır.

Betiği bir PowerShell komut kabuğunda aşağıdaki komutla çağırın:

.\integrity.ps1 {BASE URL} {PUBLISH OUTPUT FOLDER}

Aşağıdaki örnekte, betik konumunda yerel olarak çalışan bir uygulamada https://localhost:5001/yürütülür:

.\integrity.ps1 https://localhost:5001/ C:\TestApps\BlazorSample\bin\Release\net6.0\publish\

Yer tutucu:

  • {BASE URL}: Dağıtılan uygulamanın URL'si. Sondaki eğik çizgi (/) gereklidir.
  • {PUBLISH OUTPUT FOLDER}: Uygulamanın publish dağıtım için yayımlandığı klasörün veya konumun yolu.

Not

GitHub deposunu dotnet/AspNetCore.Docs klonlarken betik Bitdefender integrity.ps1 veya sistemde bulunan başka bir virüs tarayıcısı tarafından karantinaya alınmış olabilir. Dosya genellikle bir virüs tarayıcısının buluşsal tarama teknolojisi tarafından tuzağa düşürülür ve bu teknoloji yalnızca kötü amaçlı yazılım varlığını gösterebilecek dosyalarda desenleri arar. Virüs tarayıcısının dosyayı hazırlamasını önlemek için, depoyu kopyalamadan önce virüs tarayıcısına bir özel durum ekleyin. Aşağıdaki örnek, Windows sistemindeki betiğin tipik bir yoludur. Yolu diğer sistemler için gerektiği gibi ayarlayın. Yer tutucu {USER} , kullanıcının yol kesimidir.

C:\Users\{USER}\Documents\GitHub\AspNetCore.Docs\aspnetcore\blazor\host-and-deploy\webassembly\_samples\integrity.ps1

Uyarı: Virüs tarayıcısı özel durumlarının oluşturulması tehlikelidir ve yalnızca dosyanın güvenli olduğundan emin olduğunuzda gerçekleştirilmelidir.

Bir dosyanın sağlama toplamını geçerli bir sağlama toplamı değeriyle karşılaştırmak, dosya güvenliğini garanti etmez, ancak bir dosyayı sağlama toplamı değerini koruyacak şekilde değiştirmek kötü amaçlı kullanıcılar için önemsiz değildir. Bu nedenle sağlama toplamları genel bir güvenlik yaklaşımı olarak kullanışlıdır. Yerel integrity.ps1 dosyanın sağlama toplamını aşağıdaki değerlerden biriyle karşılaştırın:

  • SHA256: 32c24cb667d79a701135cb72f6bae490d81703323f61b8af2c7e5e5dc0f0c2bb
  • MD5: 9cee7d7ec86ee809a329b5406fbf21a8

Aşağıdaki komutla Windows işletim sisteminde dosyanın sağlama toplamını alın. Yer tutucunun yolunu ve dosya adını {PATH AND FILE NAME} belirtin ve yer tutucu için {SHA512|MD5}SHA256 üretilmesi gereken sağlama toplamı türünü (veya MD5) belirtin:

CertUtil -hashfile {PATH AND FILE NAME} {SHA256|MD5}

Sağlama toplamı doğrulamasının ortamınızda yeterince güvenli olmadığı konusunda endişeleriniz varsa, rehberlik için kuruluşunuzun güvenlik liderliğine başvurun.

Daha fazla bilgi için bkz. Microsoft Defender Virüsten Koruma tarafından tehdit korumasına genel bakış.

PWA dışı uygulamalar için kaynak önbelleğe alma ve bütünlük denetimlerini devre dışı bırakma

Çoğu durumda, bütünlük denetimini devre dışı bırakmayın. Bütünlük denetiminin devre dışı bırakılması, beklenmeyen yanıtlara neden olan ve daha önce listelenen avantajların kaybolmasına neden olan temel sorunu çözmez.

Web sunucusunun tutarlı yanıtlar döndürmeye dayanamayabileceği durumlar olabilir ve temel alınan sorun çözülene kadar bütünlük denetimlerini geçici olarak devre dışı bırakmaktan başka seçeneğiniz olmayabilir.

Bütünlük denetimlerini devre dışı bırakmak için Blazor WebAssembly , uygulamanın proje dosyasında.csproj ():

<BlazorCacheBootResources>false</BlazorCacheBootResources>

BlazorCacheBootResourcesayrıca , .wasmve diğer dosyaları SHA-256 karmalarına göre önbelleğe alma .dllvarsayılan davranışını devre dışı bırakır Blazorçünkü özelliği SHA-256 karmalarının doğruluğuna dayanamazsınız. Bu ayarda bile tarayıcının normal HTTP önbelleği bu dosyaları önbelleğe almaya devam edebilir, ancak bunun olup olmaması web sunucusu yapılandırmanıza ve cache-control hizmet veren üst bilgilere bağlıdır.

Not

özelliği, BlazorCacheBootResources Aşamalı Web Uygulamaları (PWA) için bütünlük denetimlerini devre dışı bırakmaz. PWA'larla ilgili yönergeler için PWA'lar için bütünlük denetimini devre dışı bırakma bölümüne bakın.

Bütünlük denetimini devre dışı bırakmanın gerekli olduğu senaryoların kapsamlı bir listesini sağlayamıyoruz. Sunucular, isteği çerçevenin kapsamı Blazor dışında rastgele yollarla yanıtlayabilir. Çerçeve, uygulamanın sağlayabilecekleri BlazorCacheBootResources bütünlük garantisini kaybetme pahasına uygulamayı çalıştırılabilir hale getirme ayarını sağlar. Yine, özellikle üretim dağıtımları için bütünlük denetimini devre dışı bırakmanızı önermiyoruz. Geliştiriciler, bütünlük denetiminin başarısız olmasına neden olan temel bütünlük sorununu çözmeye çalışmalıdır.

Bütünlük sorunlarına neden olabilecek birkaç genel durum şunlardır:

  • Bütünlüğün denetlenemez olduğu HTTP üzerinde çalışıyor.
  • Dağıtım işleminiz herhangi bir şekilde yayımlandıktan sonra dosyaları değiştirirse.
  • Konağınız dosyaları herhangi bir şekilde değiştirirse.

PWA'lar için kaynak önbelleğe alma ve bütünlük denetimlerini devre dışı bırakma

Blazor'nin Aşamalı Web Uygulaması (PWA) şablonu, uygulama dosyalarını çevrimdışı kullanım için getirmek ve depolamaktan sorumlu olan önerilen service-worker.published.js bir dosya içeriyor. Bu, normal uygulama başlatma mekanizmasından ayrı bir işlemdir ve kendi ayrı bütünlük denetimi mantığına sahiptir.

Dosyanın içinde service-worker.published.js aşağıdaki satır bulunur:

.map(asset => new Request(asset.url, { integrity: asset.hash }));

Bütünlük denetimini devre dışı bırakmak için, satırı aşağıdaki şekilde değiştirerek parametresini kaldırın integrity :

.map(asset => new Request(asset.url));

Bütünlük denetiminin devre dışı bırakılması, bütünlük denetimi tarafından sunulan güvenlik garantilerini kaybetmeniz anlamına gelir. Örneğin, yeni bir sürümü dağıttığınız anda kullanıcının tarayıcısı uygulamayı önbelleğe alırsa, eski dağıtımdaki bazı dosyaları ve yeni dağıtımdaki bazı dosyaları önbelleğe alma riski vardır. Böyle bir durumda uygulama, siz daha fazla güncelleştirme dağıtana kadar bozuk durumda takılır.

Ek kaynaklar

Önyükleme kaynağı yükleme