ASP.NET Core 호스트 및 배포 Blazor WebAssembly

이 문서에서는 Blazor WebAssembly 앱을 호스트하고 배포하는 방법을 설명합니다.

Blazor WebAssembly 호스팅 모델을 사용하면 다음과 같이 실행됩니다.

• Blazor 앱, 해당 앱의 종속성 및 .NET 런타임이 병렬로 브라우저에 다운로드됩니다.
• 해당 앱은 브라우저 UI 스레드에서 직접 실행됩니다.

이 문서는 앱이 Blazor 정적 호스팅 웹 서버 또는 서비스에 배치되는 배포 시나리오와 관련이 있습니다. .NET은 앱을 제공하는 Blazor 데 사용되지 않습니다. 이 전략은 독립 실행형 배포 섹션 및 IIS, Azure 서비스, Apache, Nginx 및 GitHub Pages에 대한 이 노드의 다른 문서에서 다룹니다.

하위 도메인 및 IIS 하위 애플리케이션 호스팅

하위 도메인 호스팅에는 앱의 특별한 구성이 필요하지 않습니다. 앱을 하위 도메인에서 호스팅하기 위해 앱 기본 경로( 태그가 내에 있음)를 구성할 필요가 없습니다.

IIS 하위 애플리케이션 호스팅 을 사용하려면 앱 기본 경로를 설정해야 합니다. IIS 하위 애플리케이션 호스팅에 대한 추가 지침에 대한 자세한 내용 및 교차 링크는 ASP.NET Core Blazor호스트 및 배포를 참조하세요.

일부 모바일 디바이스 브라우저의 최대 힙 크기 감소

클라이언트(Blazor또는 독립 실행형 .Client 앱의 프로젝트)에서 실행되고 모바일 디바이스 브라우저, 특히 iOS의 Blazor Web App Safari를 대상으로 하는 앱을 빌드 Blazor WebAssembly 할 때 MSBuild 속성을 EmccMaximumHeapSize 사용하여 앱의 최대 메모리를 줄여야 할 수 있습니다. 기본값은 2,147,483,648바이트이며, 이 값이 너무 큰 경우 앱이 추가 메모리 할당을 시도하지만 브라우저가 이를 허용하지 않으면 앱 충돌이 발생할 수 있습니다. 다음 예제에서는 파일의 값을 268,435,456바이트로 Program 설정합니다.

<EmccMaximumHeapSize>268435456</EmccMaximumHeapSize>

Mono/WebAssembly MSBuild 속성 및 대상에 대한 자세한 내용은 ( GitHub 리포지토리)를 참고하세요.

.NET 어셈블리를 위한 Webcil 패키징 형식

웹빌 은 제한적인 네트워크 환경에서 사용하도록 Blazor WebAssembly 설계된 .NET 어셈블리에 대한 웹 친화적인 패키징 형식입니다. 웹빌 파일은 표준 WebAssembly 래퍼를 사용합니다. 여기서 어셈블리는 표준 .wasm 파일 확장자를 사용하는 WebAssembly 파일로 배포됩니다.

Webcil은 Blazor WebAssembly 앱을 게시할 때 기본 포장 형식입니다. 웹실 사용을 사용하지 않도록 설정하려면 앱의 프로젝트 파일에서 다음 MSBuild 속성을 설정합니다.

<PropertyGroup>
  <WasmEnableWebcil>false</WasmEnableWebcil>
</PropertyGroup>

부팅 리소스를 로드하는 방법 사용자 지정

loadBootResource API를 사용하여 부팅 리소스를 로드하는 방법 사용자 지정 자세한 내용은 ASP.NET Core Blazor 시작을 참조하세요.

압축

Blazor WebAssembly 앱이 게시될 때 게시하는 도중에 출력을 정적으로 압축하여 앱의 크기를 줄이고 런타임 압축의 오버헤드를 제거합니다. 다음 압축 알고리즘이 사용됩니다.

• Brotli(최고 수준)
• Gzip

Blazor 는 호스트를 사용하여 적절한 압축 파일을 제공합니다. Blazor WebAssembly 독립 실행형 앱을 호스트하는 경우 정적으로 압축된 파일이 제공되도록 추가 작업이 필요할 수도 있습니다.

• IIS web.config 압축 구성의 경우 IIS: Brotli 및 Gzip 압축 섹션을 참조하세요.
• 정적으로 압축된 파일 콘텐츠 협상을 지원하지 않는 정적 호스팅 솔루션을 호스팅하는 경우 Brotli 압축 파일을 가져오고 디코딩하도록 앱을 구성하는 것이 좋습니다.

JavaScript Brotli 디코더를 GitHub 리포지토리에서 가져옵니다. 축소된 디코더 파일은 이름이 decode.min.js이며 리포지토리의 js 폴더에 있습니다.

비고

decode.js 스크립트(decode.min.js)의 축소된 버전이 실패하는 경우 축소 해제한 버전(decode.js)을 대신 사용해 보세요.

디코더를 사용하도록 앱을 업데이트합니다.

wwwroot/index.html 파일의 autostart의 false 태그에서 Blazor를 <script>로 설정합니다.

<script src="_framework/blazor.webassembly.js" autostart="false"></script>

Blazor'의 <script> 태그 뒤와 닫는 </body> 태그 앞에 다음 JavaScript 코드 <script> 블록을 추가합니다. 다음 함수는 브라우저의 캐시를 업데이트된 상태로 유지하기 위해 fetchcache: 'no-cache' 호출합니다.

Blazor Web App:

<script type="module">
  import { BrotliDecode } from './decode.min.js';
  Blazor.start({
    webAssembly: {
      loadBootResource: function (type, name, defaultUri, integrity) {
        if (type !== 'dotnetjs' && location.hostname !== 'localhost' && type !== 'configuration' && type !== 'manifest') {
          return (async function () {
            const response = await fetch(defaultUri + '.br', { cache: 'no-cache' });
            if (!response.ok) {
              throw new Error(response.statusText);
            }
            const originalResponseBuffer = await response.arrayBuffer();
            const originalResponseArray = new Int8Array(originalResponseBuffer);
            const decompressedResponseArray = BrotliDecode(originalResponseArray);
            const contentType = type === 
              'dotnetwasm' ? 'application/wasm' : 'application/octet-stream';
            return new Response(decompressedResponseArray, 
              { headers: { 'content-type': contentType } });
          })();
        }
      }
    }
  });
</script>

독립 실행형 Blazor WebAssembly:

<script type="module">
  import { BrotliDecode } from './decode.min.js';
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      if (type !== 'dotnetjs' && location.hostname !== 'localhost' && type !== 'configuration') {
        return (async function () {
          const response = await fetch(defaultUri + '.br', { cache: 'no-cache' });
          if (!response.ok) {
            throw new Error(response.statusText);
          }
          const originalResponseBuffer = await response.arrayBuffer();
          const originalResponseArray = new Int8Array(originalResponseBuffer);
          const decompressedResponseArray = BrotliDecode(originalResponseArray);
          const contentType = type === 
            'dotnetwasm' ? 'application/wasm' : 'application/octet-stream';
          return new Response(decompressedResponseArray, 
            { headers: { 'content-type': contentType } });
        })();
      }
    }
  });
</script>

부팅 리소스를 로드하는 방법에 대한 자세한 내용은 ASP.NET Core Blazor 시작을 참조하세요.

압축을 해제하려면 앱의 프로젝트 파일에 CompressionEnabled MSBuild 속성을 추가하고 값을 false로 설정합니다.

<PropertyGroup>
  <CompressionEnabled>false</CompressionEnabled>
</PropertyGroup>

명령 셸에서 다음 구문을 사용하여 CompressionEnabled 속성을 dotnet publish 명령에 전달할 수 있습니다.

dotnet publish -p:CompressionEnabled=false

올바른 라우팅을 위해 URL 다시 생성

Blazor WebAssembly 앱의 페이지 구성 요소에 대한 라우팅 요청은 Blazor Server 앱에서의 요청 라우팅만큼 간단하지 않습니다. 다음 두 구성 요소를 사용하는 Blazor WebAssembly 앱을 살펴보겠습니다.

• Main.razor: 앱의 루트에 로드되고 About 구성 요소에 대한 링크가 href="About"에 포함됩니다.
• About.razor: About 구성 요소입니다.

브라우저의 주소 표시줄을 사용하여 앱의 기본 문서를 요청하는 경우(예: https://www.contoso.com/):

1. 브라우저가 요청을 합니다.
2. 기본 페이지(일반적으로 index.html)가 반환됩니다.
3. index.html이 앱을 부트스트랩합니다.
4. Router 구성 요소가 로드되고 RazorMain 구성 요소가 렌더링됩니다.

About 라우터는 브라우저가 인터넷에서 Blazor으로 www.contoso.com을 요청하는 것을 중단하고 렌더링된 About 구성 요소를 직접 제공하므로 기본 페이지에서 About 구성 요소에 대한 링크 선택은 클라이언트에서 작동합니다. Blazor WebAssembly 앱 내의 내부 엔드포인트에 대한 모든 요청도 같은 방법으로 작동합니다. 요청은 인터넷상에서 서버가 호스트하는 리소스에 대한 브라우저 기반 요청을 트리거하지 않습니다. 라우터가 내부적으로 요청을 처리합니다.

브라우저의 주소 표시줄을 사용하여 www.contoso.com/About을 요청하면 해당 요청이 실패합니다. 앱의 인터넷 호스트에 해당 리소스가 없으므로 404 - 찾을 수 없음 응답이 반환됩니다.

브라우저는 인터넷 기반 호스트에 클라이언트 쪽 페이지를 요청하므로, 웹 서버 및 호스팅 서비스는 서버에 실제로 존재하지 않는 리소스에 대한 모든 요청을 index.html 페이지에 다시 써야 합니다. index.html이 반환되는 경우 앱의 Blazor 라우터가 넘겨받아 올바른 리소스로 응답합니다.

IIS 서버에 배포하는 경우 앱의 게시된 web.config 파일과 함께 URL 재작성 모듈을 사용할 수 있습니다. 자세한 내용은 IIS를 사용하여 ASP.NET Core Blazor WebAssembly 호스트 및 배포를 참조하세요.

독립 실행형 배포

‘독립 실행형 배포’는 앱을 클라이언트가 직접 요청하는 정적 파일 세트로 제공합니다.Blazor WebAssembly 모든 정적 파일 서버는 Blazor 앱을 사용할 수 있습니다.

독립 실행형 배포 자산은 /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot 자리 표시자가 대상 프레임워크인 bin/Release/{TARGET FRAMEWORK}/browser-wasm/publish 또는 {TARGET FRAMEWORK} 폴더에 게시됩니다.

Azure App Service

Blazor WebAssembly 앱을 IIS에서 앱을 호스트하는 Windows의 Azure App Services에 배포할 수 있습니다.

Linux용 Azure App Service에 독립 실행형 Blazor WebAssembly 앱 배포는 현재 지원되지 않습니다. 이 시나리오를 지원하는 Blazor WebAssembly를 사용하여 독립 실행형 앱을 호스팅하는 것이 좋습니다.

독립 실행형 Docker

독립 실행형 Blazor WebAssembly 앱은 정적 파일 서버에서 호스팅하기 위한 정적 파일 집합으로 게시됩니다.

Docker에서 앱을 호스트하려면 다음을 수행합니다.

• Nginx 또는 Apache와 같은 웹 서버 지원이 있는 Docker 컨테이너를 선택합니다.
• 정적 파일을 제공하기 위해 웹 서버에 정의된 위치 폴더에 publish 폴더 자산을 복사합니다.
• 필요에 따라 추가 구성을 적용하여 Blazor WebAssembly 앱을 제공합니다.

구성 지침은 다음 리소스를 참조하세요.

• Nginx 또는 Apache 문서
• Docker 설명서

호스트 구성 값

Blazor WebAssembly 앱은 개발 환경의 런타임에 다음 호스트 구성 값을 명령줄 인수로 허용할 수 있습니다.

콘텐츠 루트

--contentroot 인수는 앱의 콘텐츠 파일을 포함하는 디렉터리(콘텐츠 루트)에 대한 절대 경로를 설정합니다. 다음 예제에서 /content-root-path는 앱의 콘텐츠 루트 경로입니다.

• 명령 프롬프트에서 앱을 로컬로 실행할 때 인수를 전달합니다. 앱의 디렉터리에서 다음을 실행합니다.

  dotnet watch --contentroot=/content-root-path
  

• launchSettings.json 프로필의 앱 파일에 항목을 추가합니다. 이 설정은 Visual Studio 디버거 및 명령 프롬프트 dotnet watch (또는 dotnet run)를 사용하여 앱을 실행할 때 사용됩니다.

  "commandLineArgs": "--contentroot=/content-root-path"
  

• Visual Studio의 속성>디버그>애플리케이션 인수에서 인수를 지정합니다. Visual Studio 속성 페이지에서 인수를 설정하면 해당 인수가 launchSettings.json 파일에 추가됩니다.

  --contentroot=/content-root-path
  

경로 기준

--pathbase 인수는 루트가 아닌 상대 URL 경로를 사용하여 로컬로 앱을 실행하기 위한 앱 기본 경로를 설정합니다. (준비 및 프로덕션의 경우 <base> 태그 href는 / 이외의 경로로 설정됩니다.) 다음 예제에서 /relative-URL-path는 앱의 경로 기준입니다. 자세한 내용은 ASP.NET Core Blazor 앱 기본 경로를 참조하세요.

중요합니다

href 태그의 <base>에 대해 제공되는 경로와 달리 / 인수 값을 전달할 때 뒤에 슬래시(--pathbase)를 포함하지 않습니다. 앱 기본 경로가 <base> 태그에 <base href="/CoolApp/">로 제공되는 경우(뒤에 슬래시 포함) 명령줄 인수 값을 --pathbase=/CoolApp로 전달합니다(뒤에 슬래시 없음).

• 명령 프롬프트에서 앱을 로컬로 실행할 때 인수를 전달합니다. 앱의 디렉터리에서 다음을 실행합니다.

  dotnet watch --pathbase=/relative-URL-path
  

• launchSettings.json 프로필의 앱 파일에 항목을 추가합니다. 이 설정은 Visual Studio 디버거 및 명령 프롬프트 dotnet watch (또는 dotnet run)를 사용하여 앱을 실행할 때 사용됩니다.

  "commandLineArgs": "--pathbase=/relative-URL-path"
  

• Visual Studio의 속성>디버그>애플리케이션 인수에서 인수를 지정합니다. Visual Studio 속성 페이지에서 인수를 설정하면 해당 인수가 launchSettings.json 파일에 추가됩니다.

  --pathbase=/relative-URL-path
  

자세한 내용은 ASP.NET Core Blazor 앱 기본 경로를 참조하세요.

URL들

--urls 인수는 요청을 수신하기 위한 포트 및 프로토콜을 포함하는 IP 주소 또는 호스트 주소를 설정합니다.

• 명령 프롬프트에서 앱을 로컬로 실행할 때 인수를 전달합니다. 앱의 디렉터리에서 다음을 실행합니다.

  dotnet watch --urls=http://127.0.0.1:0
  

• launchSettings.json 프로필의 앱 파일에 항목을 추가합니다. 이 설정은 Visual Studio 디버거 및 명령 프롬프트 dotnet watch (또는 dotnet run)를 사용하여 앱을 실행할 때 사용됩니다.

  "commandLineArgs": "--urls=http://127.0.0.1:0"
  

• Visual Studio의 속성>디버그>애플리케이션 인수에서 인수를 지정합니다. Visual Studio 속성 페이지에서 인수를 설정하면 해당 인수가 launchSettings.json 파일에 추가됩니다.

  --urls=http://127.0.0.1:0
  

트리머를 구성하십시오

Blazor는 각 릴리스 빌드에 IL(중간 언어) 트리밍을 수행하여 출력 어셈블리에서 필요 없는 IL을 제거합니다. 자세한 내용은 ASP.NET Core Blazor용 트리머 구성을 참조하세요.

이전 배포 시의 손상

일반적으로 배포 시 다음 현상이 나타납니다.

• 변경된 파일만 대체되어 일반적으로 배포 속도가 빨라집니다.
• 새 배포에 포함되지 않은 기존 파일은 새 배포에서 사용할 수 있도록 남아 있습니다.

드문 경우에 이전 배포에서 남은 파일 때문에 새 배포가 손상될 수 있습니다. 기존 배포(또는 배포 전에 로컬로 게시된 앱)를 완전히 삭제하면 손상된 배포와 관련된 문제가 해결될 수 있습니다. 종종 기존 배포를 한번 삭제하면 DevOps 빌드 및 배포 파이프라인을 포함하는 문제를 해결할 수 있습니다.

DevOps 빌드 및 배포 파이프라인을 사용할 때 항상 이전 배포를 지워야 하는 경우 손상의 정확한 원인을 해결할 때까지 새 배포마다 이전 배포를 삭제하는 단계를 빌드 파이프라인에 일시적으로 추가할 수 있습니다.