다음을 통해 공유

ASP.NET Core Blazor WebAssembly .NET 런타임 및 앱 번들 캐싱

  • 아티클

참고 항목

이 문서의 최신 버전은 아닙니다. 현재 릴리스는 이 문서의 .NET 9 버전을 참조 하세요.

Warning

이 버전의 ASP.NET Core는 더 이상 지원되지 않습니다. 자세한 내용은 .NET 및 .NET Core 지원 정책을 참조 하세요. 현재 릴리스는 이 문서의 .NET 9 버전을 참조 하세요.

Important

이 정보는 상업적으로 출시되기 전에 실질적으로 수정될 수 있는 시험판 제품과 관련이 있습니다. Microsoft는 여기에 제공된 정보에 대해 어떠한 명시적, 또는 묵시적인 보증을 하지 않습니다.

현재 릴리스는 이 문서의 .NET 9 버전을 참조 하세요.

Blazor WebAssembly 앱이 브라우저에 로드되면 앱은 서버에서 부팅 리소스를 다운로드합니다.

  • 앱을 부트스트랩하는 JavaScript 코드
  • .NET 런타임 및 어셈블리
  • 로캘별 데이터

Blazor'의 부팅 리소스 파일(blazor.boot.json)을 제외하고 WebAssembly .NET 런타임 및 앱 번들 파일은 클라이언트에 캐시됩니다. 이 파일에는 blazor.boot.json 다운로드해야 하는 앱을 구성하는 파일의 매니페스트와 부팅 리소스가 변경되었는지 여부를 감지하는 데 사용되는 파일 콘텐츠의 해시가 포함되어 있습니다. Blazor 는 브라우저 캐시 API를 사용하여 다운로드한 파일을 캐시 합니다.

Blazor WebAssembly는 앱의 시작 파일을 다운로드할 때 응답에 대한 무결성 검사를 수행하도록 브라우저에 지시합니다. Blazor는 DLL(), WebAssembly.wasm(.dll) 및 파일의 blazor.boot.json 다른 파일에 대한 SHA-256 해시 값을 보냅니다. 캐시된 파일의 파일 해시는 blazor.boot.json 파일의 해시와 비교됩니다. 캐시된 파일에 일치하는 해시가 있는 경우 Blazor가 캐시된 파일을 사용합니다. 그렇지 않으면 서버에 파일을 요청합니다. 파일을 다운로드한 후 무결성 유효성 검사를 위해 해당 해시를 다시 확인합니다. 다운로드한 파일의 무결성 검사가 실패하면 브라우저에서 오류가 생성됩니다.

파일 무결성을 관리하기 위한 Blazor의 알고리즘:

  • 사용자가 애플리케이션 파일을 다운로드하는 동안 새 배포가 웹 서버에 적용되는 경우와 같이 앱이 일관되지 않은 파일 세트를 로드할 위험이 없도록 합니다. 파일이 일관되지 않으면 앱이 오작동할 수 있습니다.
  • 사용자의 브라우저가 일관되지 않은 또는 잘못된 응답을 캐시하지 않도록 합니다. 일관되지 않거나 잘못된 응답을 캐시할 경우 사용자가 수동으로 페이지를 새로 고치더라도 앱이 시작하지 않을 수 있습니다.
  • 응답을 안전하게 캐시하며 예상된 SHA-256 해시가 변경될 때까지 서버 쪽 변경 내용을 확인하지 않도록 하므로 후속 페이지 로드는 더 적은 요청을 포함하여 더 빠르게 완료됩니다.

웹 서버가 예상된 SHA-256 해시와 일치하지 않는 응답을 반환하는 경우에는 브라우저의 개발자 콘솔에 다음과 같은 오류가 표시됩니다.

컴퓨팅된 SHA-256 무결성 ‘IIa70iwvmEg5WiDV17OpQ5eCztNYqL186J56852RpJY=’가 지정된 ‘https://myapp.example.com/_framework/MyBlazorApp.dlll’ 리소스의 ‘integrity’ 특성에서 유효한 다이제스트를 찾지 못했습니다. 리소스가 차단되었습니다.

대부분의 경우 경고는 무결성 검사에 문제가 있음을 나타내지 않습니다. 대신, 경고는 일반적으로 다른 문제가 있음을 의미합니다.

참고 항목

.NET 참조 원본의 설명서 링크는 일반적으로 다음 릴리스의 .NET을 위한 현재 개발을 나타내는 리포지토리의 기본 분기를 로드합니다. 특정 릴리스를 위한 태그를 선택하려면 Switch branches or tags(분기 또는 태그 전환) 드롭다운 목록을 사용합니다. 자세한 내용은 ASP.NET Core 소스 코드(dotnet/AspNetCore.Docs #26205)의 버전 태그를 선택하는 방법을 참조하세요.

무결성 문제 진단

앱이 빌드되면 생성된 blazor.boot.json 매니페스트는 빌드 출력이 생성될 때 부팅 리소스의 SHA-256 해시를 설명합니다. blazor.boot.json의 SHA-256 해시가 브라우저에 배달된 파일과 일치하는 경우 무결성 검사가 통과합니다.

이것이 실패하는 일반적인 이유는 다음과 같습니다.

  • 웹 서버의 응답은 브라우저가 요청한 파일이 아닌 오류(예: ‘404 - 찾을 수 없음’ 또는 ‘500 - 내부 서버 오류’)입니다. 이는 브라우저에서 응답 실패가 아닌 무결성 검사 실패로 보고됩니다.
  • 무엇인가 브라우저에 대한 파일의 빌드와 제공 사이에 파일 콘텐츠를 변경했습니다. 이 경우 다음이 발생할 수 있습니다.
    • 사용자 또는 빌드 도구가 빌드 출력을 수동으로 수정하는 경우.
    • 배포 프로세스의 일부 측면이 파일을 수정한 경우. 예를 들어 Git 기반 배포 메커니즘을 사용하는 경우 파일을 Windows에서 커밋하고 Linux에서 체크 아웃하는 경우 Git에서는 Windows 스타일 줄 끝을 Unix 스타일 줄 끝으로 투명하게 변환합니다. 파일 줄 끝을 변경하면 SHA-256 해시가 변경됩니다. 이 문제를 방지하려면 .gitattributes를 사용하여 빌드 아티팩트를 binary 파일로 처리하는 것이 좋습니다.
    • 웹 서버는 파일 콘텐츠를 제공하는 동안 수정합니다. 예를 들어 일부 CDN(Content Delivery Network)은 자동으로 HTML을 축소함으로써 수정합니다. 관련 기능을 사용하지 않도록 설정해야 할 수 있습니다.
  • blazor.boot.json 파일이 제대로 로드되지 않거나 클라이언트에 잘못 캐시됩니다. 일반적인 원인은 다음 중 하나를 포함합니다.
    • 사용자 지정 개발자 코드가 잘못 구성되었거나 오작동합니다.
    • 하나 이상의 중간 캐싱 레이어가 잘못 구성되었습니다.

어떤 기능이 해당 사례에서 적용되는지 진단하려면:

  1. 오류 메시지를 읽어서 어떤 파일이 오류를 트리거하는지 확인합니다.
  2. 브라우저의 개발자 도구를 열고 네트워크 탭을 확인합니다. 필요한 경우 페이지를 다시 로드하여 요청 및 응답 목록을 확인합니다. 해당 목록에서 오류를 트리거하는 파일을 찾습니다.
  3. 응답의 HTTP 상태 코드를 확인합니다. 서버가 200 - OK(또는 또 다른 2xx 상태 코드) 이외의 값을 반환하면 진단해야 하는 서버 쪽 문제가 있는 것입니다. 예를 들어 상태 코드 403은 권한 부여 문제가 있음을 의미하는 반면, 상태 코드 500은 서버가 지정되지 않은 방식으로 실패함을 의미합니다. 서버 쪽 로그를 참조하여 앱을 진단하고 수정합니다.
  4. 리소스의 상태 코드가 200 - OK인 경우 브라우저의 개발자 도구에서 응답 콘텐츠를 보고 예상되는 데이터와 콘텐츠가 일치하는지 확인합니다. 예를 들어 일반적인 문제는 요청이 다른 파일에 대해서도 index.html 데이터를 반환하도록 라우팅을 잘못 구성하는 것입니다. .wasm 요청에 대한 응답이 WebAssembly 이진 파일이고 .dll 요청에 대한 응답이 .NET 어셈블리 이진 파일인지 확인합니다. 그렇지 않으면 진단해야 할 서버 쪽 라우팅 문제가 있는 것입니다.
  5. 무결성 PowerShell 스크립트 문제 해결을 사용하여 게시 및 배포된 앱 출력의 유효성을 검사해 보세요.

서버가 올바른 것 같은 데이터를 반환하고 있는지 확인하는 경우 파일의 빌드와 제공 사이에 콘텐츠를 수정하는 다른 항목이 있어야 합니다. 이를 조사하려면:

  • 파일이 빌드된 후 파일을 수정 중인 경우 빌드 도구 체인 및 배포 메커니즘을 검토합니다. 여기에 해당하는 예제는 앞에서 설명한 대로 Git이 파일 줄 끝을 변환하는 경우입니다.
  • 응답을 동적으로 수정하도록(예: HTML 축소 시도) 설정된 경우 웹 서버 또는 CDN 구성을 검토합니다. 압축을 푼 후 결과에 영향을 주지 않으므로 웹 서버가 HTTP 압축을 구현해도 괜찮습니다(예: content-encoding: br 또는 content-encoding: gzip 반환). 그러나 웹 서버가 압축되지 않은 데이터를 수정하는 것은 괜찮지 ‘않습니다’.

무결성 PowerShell 스크립트 문제 해결

integrity.ps1 PowerShell 스크립트를 사용하여 게시 및 배포된 Blazor 앱의 유효성을 검사합니다. 이 스크립트는 앱에 Blazor 프레임워크가 식별할 수 없는 무결성 문제가 있는 경우 PowerShell Core 7 이상에 시작 지점으로 제공됩니다. 버전 7.2.0 이상 버전의 PowerShell을 실행하는 경우를 포함하여 앱을 위해 스크립트를 사용자 지정해야 할 수 있습니다.

이 스크립트는 publish 폴더의 파일과 배포된 앱에서 다운로드한 파일을 검사하여 무결성 해시가 포함된 다른 매니페스트의 문제를 검색합니다. 이 검사에서 다음과 같은 가장 일반적인 문제가 검색되어야 합니다.

  • 게시된 출력의 파일을 사용자가 무심코 수정했습니다.
  • 앱이 배포 대상에 올바르게 배포되지 않았거나 배포 대상 환경 내에 변경된 내용이 있습니다.
  • 배포된 앱과 앱 게시의 출력 간에 차이가 있습니다.

PowerShell 명령 셸에서 다음 명령을 사용하여 스크립트를 호출합니다.

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

다음 예제에서 스크립트는 https://localhost:5001/에서 로컬로 실행 중인 앱에서 실행됩니다.

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

자리 표시자:

  • {BASE URL}: 배포된 앱의 URL입니다. 후행 슬래시(/)가 필요합니다.
  • {PUBLISH OUTPUT FOLDER}: 앱의 publish 폴더 또는 배포를 위해 앱이 게시된 위치의 경로입니다.

참고 항목

dotnet/AspNetCore.Docs GitHub 리포지토리를 복제하는 경우 integrity.ps1 스크립트는 Bitdefender 또는 시스템에 있는 다른 바이러스 검색 프로그램으로 격리될 수 있습니다. 일반적으로 파일은 바이러스 검사 프로그램의 추론 검색 기술을 통해 트래핑됩니다. 이 기술은 파일에서 맬웨어가 있음을 나타낼 수 있는 패턴만 찾습니다. 바이러스 검사 프로그램이 파일을 격리하지 않도록 하려면 리포지토리를 복제하기 전에 바이러스 검사 프로그램에 예외를 추가합니다. 다음 예제는 Windows 시스템의 일반적인 스크립트 경로입니다. 다른 시스템의 필요에 따라 경로를 조정합니다. {USER} 자리 표시자는 사용자의 경로 세그먼트입니다.

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

경고: 바이러스 검사기 예외를 만드는 것은 위험하며 파일이 안전하다고 확신하는 경우에만 수행해야 합니다.

파일의 체크섬을 유효한 체크섬 값과 비교해도 파일 보안을 보장할 수 없지만 체크섬 값을 유지하는 방식으로 파일을 수정하는 것은 악의적인 사용자에게 사소하지 않습니다. 따라서 체크섬은 일반적인 보안 방법으로 유용합니다. 로컬 integrity.ps1 파일의 체크섬을 다음 값 중 하나와 비교합니다.

  • SHA256: 32c24cb667d79a701135cb72f6bae490d81703323f61b8af2c7e5e5dc0f0c2bb
  • MD5: 9cee7d7ec86ee809a329b5406fbf21a8

다음 명령을 사용하여 Windows OS에서 파일의 체크섬을 가져옵니다. {PATH AND FILE NAME} 자리 표시자의 경로 및 파일 이름을 제공하고 {SHA512|MD5} 자리 표시자에 대해 생성할 체크섬의 형식(SHA256 또는 MD5)을 나타냅니다.

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

사용자 환경에서 체크섬 유효성 검사가 충분히 안전하지 않을 수 있다고 생각될 경우 조직의 보안 책임자에게 문의하세요.

자세한 내용은 Microsoft Defender 바이러스 백신 의한 위협 방지 개요를 참조하세요.

PWA가 아닌 앱에 대한 리소스 캐싱 및 무결성 검사 사용 안 함

대부분의 경우 무결성 검사를 사용하지 않도록 설정하지 마세요. 무결성 검사를 사용하지 않으면 예기치 않은 응답을 발생시킨 근본적인 문제가 해결되지 않아 앞서 언급한 이점을 얻을 수 없습니다.

웹 서버를 사용하여 일관된 응답을 반환할 수 없고 근본 문제가 해결될 때까지 일시적으로 무결성 검사를 사용하지 않도록 설정할 수밖에 없는 경우가 있습니다.

무결성 검사를 사용하지 않도록 설정하려면 Blazor WebAssembly 앱의 프로젝트 파일(.csproj)에서 속성 그룹에 다음을 추가합니다.

<BlazorCacheBootResources>false</BlazorCacheBootResources>

또한, BlazorCacheBootResources 속성은 SHA-256 해시의 정확성을 기대할 수 없음을 나타내기 때문에 .dll, .wasm 및 SHA-256 해시 기반 기타 파일을 캐시하는 Blazor의 기본 동작을 사용하지 않도록 설정합니다. 이 설정을 사용하는 경우에도 브라우저의 일반 HTTP 캐시는 해당 파일을 캐시할 수 있지만 이 상황이 발생하는지는 웹 서버 구성 및 해당 구성이 제공하는 cache-control 헤더에 따라 달라집니다.

참고 항목

BlazorCacheBootResources 속성은 PWA(프로그레시브 웹 애플리케이션)에 대한 무결성 검사를 사용하지 않도록 설정하지 않습니다. PWA 관련 지침은 PWA에 대한 무결성 검사 사용 안 함 섹션을 참조하세요.

무결성 검사를 사용하지 않도록 설정해야 하는 시나리오를 모두 나열할 수는 없습니다. 서버는 Blazor 프레임워크의 범위를 벗어나는 임의의 방법으로 요청에 응답할 수 있습니다. 프레임워크는 앱이 제공할 수 있는 무결성에 대한 보장을 하지 않는 대신 앱을 계속 실행할 수 있도록 BlazorCacheBootResources 설정을 제공합니다. 다시 한 번 말하지만, 특히 프로덕션 배포의 경우, 무결성 검사를 사용하지 않도록 설정하는 것은 권장하지 않습니다. 개발자는 무결성 검사가 실패하는 근본적인 무결성 문제를 해결하려고 노력해야 합니다.

무결성 문제를 일으킬 수 있는 몇 가지 일반적인 사례는 다음과 같습니다.

  • 무결성을 검사할 수 없는 HTTP에서 실행하는 경우
  • 배포 프로세스에서 어떤 방식으로든 게시 후 파일을 수정하는 경우
  • 호스트가 어떤 방식으로든 파일을 수정하는 경우

PWA에 대한 리소스 캐싱 및 무결성 검사 사용 안 함

Blazor의 PWA(프로그레시브 웹 애플리케이션) 템플릿에는 오프라인에서 사용하기 위해 애플리케이션 파일을 페치하고 저장해야 하는 제안된 service-worker.published.js 파일이 포함됩니다. 이는 일반적인 앱 시작 메커니즘과 별도의 프로세스이며 자체적인 별도의 무결성 검사 논리를 포함합니다.

service-worker.published.js 파일 내에 다음 줄이 있습니다.

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

무결성 검사를 사용하지 않으려면 줄을 다음으로 변경하여 integrity 매개 변수를 제거합니다.

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

또한 무결성 검사를 사용하지 않도록 설정하면 무결성 검사를 통해 제공되는 안전 보증이 손실됩니다. 예를 들어 사용자의 브라우저가 새 버전을 배포하는 바로 그 순간에 앱을 캐시 중인 경우 이전 배포의 일부 파일과 새 배포의 일부 파일을 캐시할 수 있는 위험이 있습니다. 이 경우 추가 업데이트를 배포할 때까지 앱이 중단됨 상태로 중단됩니다.

추가 리소스

부팅 리소스 로드