ASP.NET Core Blazor 시작

이 문서에서는 앱 시작 구성에 대해 설명합니다 Blazor .

서버 쪽 개발을 위한 ASP.NET Core 앱 구성에 대한 일반적인 지침은 ASP.NET Core의 구성을 참조 하세요.

시작 프로세스 및 구성

Blazor 시작 프로세스는 Blazor 스크립트 (blazor.*.js)를 통해 자동 및 비동기적으로 수행되며, 여기서 * 자리 표시자는:

• web 의 경우 Blazor Web App
• server Blazor Server 앱을 위해
• webassembly Blazor WebAssembly 앱을 위해

스크립트의 위치는 ASP.NET Core Blazor 프로젝트 구조를 참조하세요.

수동으로 Blazor을 시작하려면 다음을 수행합니다.

Blazor Web App:

• autostart="false" Blazor 태그에 <script> 특성 및 값을 추가합니다.
• Blazor.start()를 호출하는 스크립트를 Blazor<script> 태그 뒤, 닫는 </body> 태그 안에 배치합니다.
• 속성에 정적 서버 쪽 렌더링(정적 SSR) 옵션을 배치합니다 ssr .
• 서버 쪽 Blazor-SignalR 회로 옵션을 속성에 배치합니다 circuit .
• 클라이언트 쪽 WebAssembly 옵션을 속성에 배치합니다 webAssembly .

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  ...
  Blazor.start({
    ssr: {
      ...
    },
    circuit: {
      ...
    },
    webAssembly: {
      ...
    }
  });
  ...
</script>

독립 실행형 Blazor WebAssembly 및 Blazor Server:

• autostart="false" Blazor 태그에 <script> 특성 및 값을 추가합니다.
• Blazor.start()를 호출하는 스크립트를 Blazor<script> 태그 뒤, 닫는 </body> 태그 안에 배치합니다.
• 매개 변수에 Blazor.start() 추가 옵션을 제공할 수 있습니다.

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  ...
  Blazor.start({
    ...
  });
  ...
</script>

앞의 예제 {BLAZOR SCRIPT} 에서 자리 표시자는 스크립트 경로 및 파일 이름입니다 Blazor . 스크립트의 위치는 ASP.NET Core Blazor 프로젝트 구조를 참조하세요.

JavaScript 이니셜라이저

JS(JavaScript) 이니셜라이저는 Blazor 앱 로드 전후에 논리를 실행합니다. JS 이니셜라이저는 다음 시나리오에서 유용합니다.

• Blazor 앱 로드 방법 사용자 지정.
• Blazor 시작 전에 라이브러리 초기화.
• Blazor의 설정 구성.

JS 이니셜라이저는 빌드 프로세스의 일부로 검색되고 자동으로 가져옵니다. JS 이니셜라이저를 이용하면 대부분의 경우 을 사용할 때 Razor하지 않아도 됩니다.

JS 이니셜라이저를 정의하려면 JS라는 프로젝트에 {NAME}.lib.module.js 모듈을 추가합니다. 여기서 {NAME} 자리 표시자는 어셈블리 이름, 라이브러리 이름 또는 패키지 식별자입니다. 프로젝트의 웹 루트(일반적으로 wwwroot 폴더)에 파일을 저장합니다.

Blazor Web App의 경우:

• beforeWebStart(options): 시작하기 전에 Blazor Web App 호출됩니다. 예를 들어 로드 프로세스, beforeWebStart 로깅 수준 및 기타 옵션을 사용자 지정하는 데 사용됩니다. Blazor 웹 옵션을 options에서 받습니다.
• afterWebStarted(blazor): 모든 beforeWebStart 약속이 해결된 후에 호출됩니다. 예를 들어 이벤트 afterWebStarted 수신기 및 사용자 지정 이벤트 유형을 등록 Blazor 하는 데 사용할 수 있습니다. Blazor 인스턴스는 인수로 afterWebStarted에 blazor 전달됩니다.
• beforeServerStart(options, extensions): 첫 번째 서버 런타임이 시작되기 전에 호출됩니다. 게시하는 동안 추가된 SignalR 회로 시작 옵션(options) 및 모든 확장(extensions)을 받습니다.
• afterServerStarted(blazor): 첫 번째 대화형 서버 런타임이 시작된 후 호출됩니다.
• beforeWebAssemblyStart(options, extensions): Interactive WebAssembly 런타임이 시작되기 전에 호출됩니다. 게시하는 동안 추가된 Blazor 옵션(options) 및 모든 확장(extensions)을 받습니다. 예를 들어 옵션은 사용자 지정 부팅 리소스 로더의 용도를 지정할 수 있습니다.
• afterWebAssemblyStarted(blazor): Interactive WebAssembly 런타임이 시작된 후 호출됩니다.

참고

레거시 JS 이니셜라이저(beforeStart, afterStarted)는 기본적으로 Blazor Web App에서 호출되지 않습니다. enableClassicInitializers 옵션을 사용하여 레거시 이니셜라이저를 실행하도록 설정할 수 있습니다. 그러나 레거시 이니셜라이저 실행은 예측할 수 없습니다.

<script>
  Blazor.start({ enableClassicInitializers: true });
</script>

.NET 8 및 9(dotnet/aspnetcore#54049)의 프레임워크 버그로 인해, Blazor 또는 beforeWebAssemblyStart(options, extensions)가 호출될 때 스크립트를 수동으로 시작해야 합니다. 서버 앱이 WebAssembly (Blazor) 설정으로 webAssembly: {...}가 수동으로 시작되지 않은 경우, 서버 프로젝트의 구성 요소 App을(를) 다음을 기반으로 업데이트하십시오.

에서 Components/App.razor기존 태그를 제거합니다.Blazor<script>

- <script src="_framework/blazor.web.js"></script>

<script> 태그를 WebAssembly(Blazor) 구성으로 수동으로 시작하는 webAssembly: {...}으로 다음의 마크업으로 교체하십시오.

<script src="_framework/blazor.web.js" autostart="false"></script>
<script>
    Blazor.start({
        webAssembly: {}
    });
</script>

Blazor Server, Blazor WebAssembly, 및 Blazor Hybrid 앱의 경우:

• beforeStart(options, extensions): Blazor가 시작되기 전에 호출됩니다. 예를 들어, beforeStart를 사용하여 로딩 프로세스, 로깅 수준, 호스팅 모델과 관련된 기타 옵션을 사용자 지정합니다.
  • 클라이언트 쪽에서는 beforeStart 게시 중에 추가된 Blazor 옵션(options) 및 모든 확장(extensions)을 받습니다. 예를 들어 옵션은 사용자 지정 부팅 리소스 로더의 용도를 지정할 수 있습니다.
  • 서버 쪽에서 beforeStart 회로 시작 옵션(SignalR)을 수신합니다options.
  • 에서 BlazorWebView옵션은 전달되지 않습니다.
• afterStarted(blazor): Blazor가 JS에서 호출을 수신할 준비가 된 후에 호출됩니다. 예를 들어, afterStarted는 JS interop 호출을 만들고 사용자 지정 요소를 등록하여 라이브러리를 초기화하는 데 사용됩니다. Blazor 인스턴스는 인수로 afterStarted에 blazor 전달됩니다.

.NET WebAssembly 런타임 콜백 추가:

• onRuntimeConfigLoaded(config): 부팅 구성을 다운로드할 때 호출됩니다. 런타임이 시작되기 전에 앱이 매개 변수(구성)를 수정할 수 있도록 허용합니다(매개 변수는 원본MonoConfig)dotnet.d.ts.

  export function onRuntimeConfigLoaded(config) {
    // Sample: Enable startup diagnostic logging when the URL contains 
    // parameter debug=1
    const params = new URLSearchParams(location.search);
    if (params.get("debug") == "1") {
      config.diagnosticTracing = true;
    }
  }
  

• onRuntimeReady({ getAssemblyExports, getConfig }): .NET WebAssembly 런타임이 시작된 후 호출됩니다 (매개 변수는 RuntimeAPI의 dotnet.d.ts입니다).

  export function onRuntimeReady({ getAssemblyExports, getConfig }) {
    // Sample: After the runtime starts, but before Main method is called, 
    // call [JSExport]ed method.
    const config = getConfig();
    const exports = await getAssemblyExports(config.mainAssemblyName);
    exports.Sample.Greet();
  }
  

두 콜백은 모두 Promise을 반환할 수 있으며, 시작이 계속되기 전에 약속을 기다립니다.

파일 이름:

• JS 이니셜라이저가 프로젝트에서 정적 자산으로 사용되는 경우, {ASSEMBLY NAME}.lib.module.js 형식을 사용합니다. 여기서 {ASSEMBLY NAME} 자리 표시자는 앱의 어셈블리 이름입니다. 예를 들어, 어셈블리 이름이 BlazorSample.lib.module.js인 프로젝트에 대해 BlazorSample 파일 이름을 지정합니다. 앱의 wwwroot 폴더에 파일을 저장합니다.
• JS 초기화자가 RCL에서 사용되는 경우, {LIBRARY NAME/PACKAGE ID} 자리표시자가 프로젝트의 라이브러리 이름 또는 패키지 식별자(<PackageId> 라이브러리의 프로젝트 파일의 값)인 형식 {LIBRARY NAME/PACKAGE ID}.lib.module.js을 사용합니다. 예를 들어, 패키지 식별자가 RazorClassLibrary1.lib.module.js인 RCL에 대해 RazorClassLibrary1 파일 이름을 지정합니다. 라이브러리의 wwwroot 폴더에 파일을 저장합니다.

Blazor Web App의 경우:

다음 예는 JS 시작 전에 및 후에 사용자 지정 스크립트를 Blazor Web App와 <head>의 beforeWebStart에 추가하여 로드하는 이니셜라이저를 afterWebStarted에 보여 줍니다.

export function beforeWebStart() {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'beforeStartScripts.js');
  document.head.appendChild(customScript);
}

export function afterWebStarted() {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'afterStartedScripts.js');
  document.head.appendChild(customScript);
}

앞의 beforeWebStart 예제에서는 사용자 지정 스크립트가 시작되기 전에 Blazor 로드되도록 보장합니다. 스크립트의 대기 중인 약속이 실행을 완료하기 전에 Blazor가 시작된다고 보장하지는 않습니다.

Blazor Server, Blazor WebAssembly, 및 Blazor Hybrid 앱의 경우:

다음 예제에서는 JS 및 Blazor에서 <head>에 추가하여 beforeStart가 시작되기 전후에 사용자 지정 스크립트를 로드하는 afterStarted 이니셜라이저를 보여줍니다.

export function beforeStart(options, extensions) {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'beforeStartScripts.js');
  document.head.appendChild(customScript);
}

export function afterStarted(blazor) {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'afterStartedScripts.js');
  document.head.appendChild(customScript);
}

앞의 beforeStart 예제에서는 사용자 지정 스크립트가 시작되기 전에 Blazor 로드되도록 보장합니다. 스크립트의 대기 중인 약속이 실행을 완료하기 전에 Blazor가 시작된다고 보장하지는 않습니다.

참고

MVC 및 Razor Pages 앱은 JS 이니셜라이저를 자동으로 로드하지 않습니다. 그러나 개발자 코드는 앱의 매니페스트를 페치하고 JS 이니셜라이저의 로드를 트리거하는 스크립트를 포함할 수 있습니다.

이니셜라이저의 JS 예제는 다음 리소스를 참조하세요.

• Blazor Web App 로드 표시기 (미리 렌더링하지 않고 전역 대화형 WebAssembly 렌더링 예)
• Blazor
• Razor
• ASP.NET Core Blazor 이벤트 처리 (사용자 지정 클립보드 붙여넣기 이벤트 예제)
• ASP.NET Core에서 TOTP 인증자 앱에 QR 코드 생성 사용 Blazor Web App
• ASP.NET Core GitHub 리포지토리의 기본 테스트 앱(BasicTestApp.lib.module.js)

참고

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

라이브러리가 특정 순서로 로드되었는지 확인

사용자 지정 스크립트를 <head>에 추가하고, beforeStart과 afterStarted에 로드해야 하는 순서대로 배치합니다.

다음 예제에서는 script1.js을 script2.js보다 먼저, 그리고 script3.js을 script4.js보다 먼저 로드합니다.

export function beforeStart(options, extensions) {
    var customScript1 = document.createElement('script');
    customScript1.setAttribute('src', 'script1.js');
    document.head.appendChild(customScript1);

    var customScript2 = document.createElement('script');
    customScript2.setAttribute('src', 'script2.js');
    document.head.appendChild(customScript2);
}

export function afterStarted(blazor) {
    var customScript1 = document.createElement('script');
    customScript1.setAttribute('src', 'script3.js');
    document.head.appendChild(customScript1);

    var customScript2 = document.createElement('script');
    customScript2.setAttribute('src', 'script4.js');
    document.head.appendChild(customScript2);
}

추가 모듈 가져오기

import 이니셜라이저 파일에서 최상위 JS 문을 사용하여 추가 모듈을 가져옵니다.

additionalModule.js:

export function logMessage() {
  console.log('logMessage is logging');
}

초기화 파일 JS(.lib.module.js)에서:

import { logMessage } from "/additionalModule.js";

export function beforeStart(options, extensions) {
  ...

  logMessage();
}

맵 가져오기

가져오기 맵 은 ASP.NET Core 및 Blazor.에서 지원됩니다.

문서가 준비되면 Blazor을 초기화하세요.

다음 예제는 문서가 준비되면 Blazor를 시작합니다.

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    Blazor.start();
  });
</script>

앞의 예제 {BLAZOR SCRIPT} 에서 자리 표시자는 스크립트 경로 및 파일 이름입니다 Blazor . 스크립트의 위치는 ASP.NET Core Blazor 프로젝트 구조를 참조하세요.

수동 시작의 결과로 생성되는 Promise에 연결

수동 JS 앱 시작의 결과로 생성되는 then에 연결하려면, Promise interop 초기화와 같은 추가 작업을 수행하기 위해 Blazor을 사용하세요.

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start().then(function () {
    ...
  });
</script>

앞의 예제 {BLAZOR SCRIPT} 에서 자리 표시자는 스크립트 경로 및 파일 이름입니다 Blazor . 스크립트의 위치는 ASP.NET Core Blazor 프로젝트 구조를 참조하세요.

참고

라이브러리가 시작된 후 Blazor 추가 작업을 자동으로 실행하려면 JavaScript 이니셜라이저를 사용합니다. 이니셜라이저 JS의 사용은 라이브러리 소비자가 JS의 수동 시작에 Blazor 호출을 연결할 필요가 없게 합니다.

클라이언트 쪽 부팅 리소스 로드

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

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

loadBootResource API를 사용하여 부팅 리소스를 로드하는 방법 사용자 지정 loadBootResource 함수는 기본 제공 부팅 리소스 로드 메커니즘을 재정의합니다. 다음 시나리오에 loadBootResource를 사용합니다.

• CDN에서 표준 시간대 데이터 또는 dotnet.wasm과 같은 정적 리소스를 로드합니다.
• HTTP 요청을 사용하여 압축된 어셈블리를 로드한 다음, 서버에서 압축된 콘텐츠를 페치하는 기능을 지원하지 않는 호스트의 경우 클라이언트 측에서 압축을 풉니다.
• 각 fetch 요청을 새 이름으로 리디렉션하여 리소스 별칭을 다른 이름으로 지정합니다.

참고

외부 소스는 브라우저에서 원본 간 리소스 로드를 허용하는 데 필요한 CORS(원본 간 리소스 공유) 헤더를 반환해야 합니다. CDN은 일반적으로 필요한 헤더를 제공합니다.

loadBootResource 매개 변수는 다음 표에 나와 있습니다.

매개 변수	설명
type	리소스의 형식입니다. 가능한 형식은 assembly, pdb, dotnetjs, dotnetwasm, timezonedata입니다. 사용자 지정 동작의 경우에만 형식을 지정해야 합니다. loadBootResource에 지정되지 않은 형식은 기본 로드 동작에 따라 프레임워크에서 로드됩니다. dotnetjs 부팅 리소스 (dotnet.*.js)는 기본 로딩 동작을 위해 null를 반환하거나 부팅 리소스의 원본에 대한 URI를 반환해야 합니다.
name	리소스의 이름입니다.
defaultUri	리소스의 상대 또는 절대 URI입니다.
integrity	응답에서 예상되는 콘텐츠를 나타내는 무결성 문자열입니다.

loadBootResource 함수는 URI 문자열을 반환하여 로드 프로세스를 재정의할 수 있습니다. 다음 예제에서 bin/Release/{TARGET FRAMEWORK}/wwwroot/_framework의 다음 파일은 https://cdn.example.com/blazorwebassembly/{VERSION}/의 CDN에서 제공됩니다.

• dotnet.*.js
• dotnet.wasm
• 표준 시간대 데이터

{TARGET FRAMEWORK} 자리 표시자는 대상 프레임워크 모니커(예: net7.0)입니다. {VERSION} 자리 표시자는 공유 프레임워크 버전(예: 7.0.0)입니다.

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    webAssembly: {
      loadBootResource: function (type, name, defaultUri, integrity) {
        console.log(`Loading: '${type}', '${name}', '${defaultUri}', '${integrity}'`);
        switch (type) {
          case 'dotnetjs':
          case 'dotnetwasm':
          case 'timezonedata':
            return `https://cdn.example.com/blazorwebassembly/{VERSION}/${name}`;
        }
      }
    }
  });
</script>

독립 실행형 Blazor WebAssembly:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      console.log(`Loading: '${type}', '${name}', '${defaultUri}', '${integrity}'`);
      switch (type) {
        case 'dotnetjs':
        case 'dotnetwasm':
        case 'timezonedata':
          return `https://cdn.example.com/blazorwebassembly/{VERSION}/${name}`;
      }
    }
  });
</script>

앞의 예제 {BLAZOR SCRIPT} 에서 자리 표시자는 스크립트 경로 및 파일 이름입니다 Blazor . 스크립트의 위치는 ASP.NET Core Blazor 프로젝트 구조를 참조하세요.

부팅 리소스에 대한 URL 이상을 사용자 지정하기 위해 loadBootResource 함수는 fetch를 직접 호출하고 결과를 반환할 수 있습니다. 다음 예제에서는 사용자 지정 HTTP 헤더를 아웃바운드 요청에 추가합니다. 기본 무결성 검사 동작을 유지하려면 integrity 매개 변수를 통해 전달합니다.

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    webAssembly: {
      loadBootResource: function (type, name, defaultUri, integrity) {
        if (type == 'dotnetjs') {
          return null;
        } else {
          return fetch(defaultUri, {
            cache: 'no-cache',
            integrity: integrity,
            headers: { 'Custom-Header': 'Custom Value' }
          });
        }
      }
    }
  });
</script>

독립 실행형 Blazor WebAssembly:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      if (type == 'dotnetjs') {
        return null;
      } else {
        return fetch(defaultUri, {
          cache: 'no-cache',
          integrity: integrity,
          headers: { 'Custom-Header': 'Custom Value' }
        });
      }
    }
  });
</script>

앞의 예제 {BLAZOR SCRIPT} 에서 자리 표시자는 스크립트 경로 및 파일 이름입니다 Blazor . 스크립트의 위치는 ASP.NET Core Blazor 프로젝트 구조를 참조하세요.

함수가 반환loadBootResource되면 nullBlazor 리소스에 대한 기본 로드 동작을 사용합니다. 예를 들어, 위의 코드는 null 부팅 리소스(dotnetjs)에 대해 dotnet.*.js을 반환합니다. 이는 dotnetjs 부팅 리소스가 기본 로드 동작을 위해 null을 반환하거나, 부팅 리소스의 원본에 대한 URI를 반환해야 하기 때문입니다.

loadBootResource 함수는 Response를 반환할 수도 있습니다. 예제는 ASP.NET Core Blazor WebAssembly 호스트 및 배포를 참조하세요.

자세한 내용은 ASP.NET Core Blazor WebAssembly .NET 번들 캐싱 및 무결성 검사 실패를 참조하세요.

C# 코드의 헤더 제어

다음 방법을 사용하여 C# 코드에서 시작할 때 헤더를 제어합니다.

다음 예제에서는 CSP(콘텐츠 보안 정책) 헤더를 통해 애플리케이션에 CSP를 적용합니다. {POLICY STRING} 자리 표시자는 CSP 정책 문자열입니다. CSP에 대한 자세한 내용은 ASP.NET Core Blazor 콘텐츠 보안 정책 적용을 참조하세요.

참고

응답이 시작된 후에는 헤더를 설정할 수 없습니다. 이 섹션의 접근 방식은 응답이 시작되기 전에 헤더만 설정하므로 여기에 설명된 접근 방식은 안전합니다. 자세한 내용은 ASP.NET Core Blazor 앱 에서 IHttpContextAccessor/HttpContext를 참조하세요.

서버 쪽 및 미리 렌더링된 클라이언트 쪽 시나리오

ASP.NET Core 미들웨어를 사용하여 헤더 컬렉션을 제어합니다.

Program 파일에서:

app.Use(async (context, next) =>
{
    context.Response.Headers.Append("Content-Security-Policy", "{POLICY STRING}");
    await next();
});

앞의 예제에서는 인라인 미들웨어를 사용하지만 사용자 지정 미들웨어 클래스를 만들고 파일의 확장 메서드 Program 를 사용하여 미들웨어를 호출할 수도 있습니다. 자세한 내용은 사용자 지정 ASP.NET Core 미들웨어 작성을 참조하세요.

클라이언트 쪽 로드 표시기

로드 표시기는 앱이 정상적으로 로드되고 있으며 로드가 완료될 때까지 사용자가 기다려야 한다는 것을 보여줍니다.

Blazor Web App 로드 표시기

Blazor WebAssembly 앱에 사용되는 로딩 표시기가 Blazor Web App 프로젝트 템플릿에서 만든 앱에는 없습니다. 일반적으로 빠른 초기 로드 시간을 위해 서버의 클라이언트 쪽 구성 요소를 미리 렌더링하기 때문에 Blazor Web App대화형 WebAssembly 구성 요소에는 로드 표시기가 바람직하지 않습니다. 혼합 렌더링 모드 상황의 경우 프레임워크 또는 개발자 코드도 다음과 같은 문제를 방지하기 위해 주의해야 합니다.

• 동일한 렌더링된 페이지에 여러 로드 표시기를 표시합니다.
• .NET WebAssembly 런타임이 로드되는 동안 실수로 미리 렌더링된 콘텐츠를 삭제합니다.

.NET의 향후 릴리스는 프레임워크 기반 로드 표시기를 제공할 수 있습니다. 그동안 Blazor Web App에 사용자 지정 로드 중 표시기를 추가할 수 있습니다.

구성 요소별 대화형 WebAssembly 렌더링을 사전 렌더링과 함께 수행하기

이 시나리오는 구성 요소별 Interactive WebAssembly 렌더링에 적용됩니다(@rendermode InteractiveWebAssembly 개별 구성 요소에 적용됨).

ContentLoading 앱의 Layout 폴더에 .Client 구성 요소를 만들고 OperatingSystem.IsBrowser을(를) 호출합니다.

• false이(가) 표시될 때 로딩 표시기를 보여줍니다.
• 때 true요청된 구성 요소의 콘텐츠를 렌더링합니다.

표시기에 대한 CSS 스타일을 로드하려면 <head> 스타일을 HeadContent 구성 요소의 콘텐츠에 추가하세요. 자세한 내용은 ASP.NET Core Blazor 앱의 헤드 콘텐츠 제어를 참조하세요.

Layout/ContentLoading.razor:

@if (!RendererInfo.IsInteractive)
{
    <!-- OPTIONAL ...
    <HeadContent>
        <style>
            ...
        </style>
    </HeadContent>
    -->
    <progress id="loadingIndicator" aria-label="Content loading…"></progress>
}
else
{
    @ChildContent
}

@code {
    [Parameter]
    public RenderFragment? ChildContent { get; set; }
}

프로젝트 Layout 에 폴더 .Client 가 아직 없는 경우, 폴더 Layout 의 네임스페이스를 파일 _Imports.razor 에 추가합니다. 다음 예제에서 프로젝트의 네임스페이스는 다음과 같습니다 BlazorSample.Client.

@using BlazorSample.Client.Layout

Interactive WebAssembly 렌더링을 채택하는 구성 요소에서는 구성 요소의 Razor 마크업을 ContentLoading 구성 요소로 감쌉니다. 다음 예제는 Counter 프로젝트 템플릿에서 생성된 앱의 Blazor Web App 구성 요소를 사용하는 방법을 보여 줍니다.

Pages/Counter.razor:

@page "/counter"
@rendermode InteractiveWebAssembly

<PageTitle>Counter</PageTitle>

<ContentLoading>
    <h1>Counter</h1>

    <p role="status">Current count: @currentCount</p>

    <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
</ContentLoading>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

미리 렌더링을 사용하여 전역 대화형 WebAssembly 렌더링

@rendermode="InteractiveWebAssembly"

ContentLoading 앱의 Layout 폴더에 .Client 구성 요소를 만들고 RendererInfo.IsInteractive을(를) 호출합니다.

• false이(가) 표시될 때 로딩 표시기를 보여줍니다.
• 때 true요청된 구성 요소의 콘텐츠를 렌더링합니다.

표시기에 대한 CSS 스타일을 로드하려면 <head> 스타일을 HeadContent 구성 요소의 콘텐츠에 추가하세요. 자세한 내용은 ASP.NET Core Blazor 앱의 헤드 콘텐츠 제어를 참조하세요.

Layout/ContentLoading.razor:

@if (!RendererInfo.IsInteractive)
{
    <!-- OPTIONAL ...
    <HeadContent>
        <style>
            ...
        </style>
    </HeadContent>
    -->
    <progress id="loadingIndicator" aria-label="Content loading…"></progress>
}
else
{
    @ChildContent
}

@code {
    [Parameter]
    public RenderFragment? ChildContent { get; set; }
}

프로젝트 Layout 에 폴더 .Client 가 아직 없는 경우, 폴더 Layout 의 네임스페이스를 파일 _Imports.razor 에 추가합니다. 다음 예제에서 프로젝트의 네임스페이스는 다음과 같습니다 BlazorSample.Client.

@using BlazorSample.Client.Layout

MainLayout 프로젝트의 Layout/MainLayout.razor 구성 요소(.Client)에서 Body 구성 요소를 사용하여 @Body 속성(ContentLoading)을 래핑합니다.

Layout/MainLayout.razor의 경우

+ <ContentLoading>
    @Body
+ </ContentLoading>

대화형 글로벌 WebAssembly 렌더링 - 사전 렌더링 없이

이 시나리오는 @rendermode="new InteractiveWebAssemblyRenderMode(prerender: false)" 구성 요소의 HeadOutlet 및 Routes 구성 요소에 대해 미리 렌더링 없이 전역 Interactive WebAssembly 렌더링에 적용됩니다App.

앱에 JavaScript 이니셜라이저 를 추가합니다. 다음 JavaScript 모듈 파일 이름 예제 {ASSEMBLY NAME} 에서 자리 표시자는 서버 프로젝트의 어셈블리 이름입니다(예: BlazorSample). wwwroot 모듈이 배치되는 폴더는 wwwroot 서버 쪽 프로젝트의 폴더이며, .Client 프로젝트의 폴더가 아닙니다.

다음 예제에서는 progress 실제 진행률을 나타내지 않는 표시기를 사용 하지만 진행률 표시기가 앱의 부팅 리소스 로드의 실제 진행률을 표시하려는 경우 추가 개발을 위한 일반적인 방법으로 사용됩니다.

wwwroot/{ASSEMBLY NAME}.lib.module.js:

export function beforeWebStart(options) {
  var progress = document.createElement("progress");
  progress.id = 'loadingIndicator';
  progress.ariaLabel = 'Blazor loading…';
  progress.style = 'position:absolute;top:50%;left:50%;margin-right:-50%;' +
    'transform:translate(-50%,-50%);';
  document.body.appendChild(progress);
}

export function afterWebAssemblyStarted(blazor) {
  var progress = document.getElementById('loadingIndicator');
  progress.remove();
}

.NET 8 및 9(dotnet/aspnetcore#54049)의 프레임워크 버그로 인해 스크립트를 Blazor 수동으로 시작해야 합니다. 서버 앱이 WebAssembly (Blazor) 설정으로 webAssembly: {...}가 수동으로 시작되지 않은 경우, 서버 프로젝트의 구성 요소 App을(를) 다음을 기반으로 업데이트하십시오.

에서 Components/App.razor기존 태그를 제거합니다.Blazor<script>

- <script src="_framework/blazor.web.js"></script>

<script> 태그를 WebAssembly(Blazor) 구성으로 수동으로 시작하는 webAssembly: {...}으로 다음의 마크업으로 교체하십시오.

<script src="_framework/blazor.web.js" autostart="false"></script>
<script>
    Blazor.start({
        webAssembly: {}
    });
</script>

렌더링 표시기 제거와 첫 번째 페이지가 렌더링 되기까지 약간의 지연이 발생하는 것을 발견한 경우, 렌더링 후에 표시기가 제거되도록 하려면 OnAfterRenderAsync 또는 구성 요소의 MainLayout에서 표시기 제거를 호출하여 제거를 보장할 수 있습니다. 자세한 내용 및 코드 예제는 미리 렌더링dotnet/AspNetCore.Docs 하지 않고 전역 Interactive WebAssembly에서 작동하는 로드 표시기(#35111)에 대한 접근 방식 문서를 참조하세요.

Blazor WebAssembly 앱 로드 진행률

프로젝트 템플릿에는 앱의 로드 진행률을 보여 주는 SVG(Scalable Vector Graphics) 및 텍스트 표시기가 포함되어 있습니다.

진행률 표시기는 Blazor에서 제공하는 두 개의 CSS 사용자 지정 속성(변수)을 사용하여 HTML 및 CSS로 구현됩니다.

• --blazor-load-percentage: 로드된 앱 파일의 백분율입니다.
• --blazor-load-percentage-text: 로드된 앱 파일의 백분율로, 가장 가까운 정수로 반올림됩니다.

위의 CSS 변수를 사용하여 앱의 스타일과 일치하는 사용자 지정 진행률 표시기를 만들 수 있습니다.

다음 예제에서

• resourcesLoaded는 앱 시작 중에 로드된 리소스의 순간적인 수입니다.
• totalResources는 로드할 총 리소스 수입니다.

const percentage = resourcesLoaded / totalResources * 100;
document.documentElement.style.setProperty(
  '--blazor-load-percentage', `${percentage}%`);
document.documentElement.style.setProperty(
  '--blazor-load-percentage-text', `"${Math.floor(percentage)}%"`);

기본 라운드 진행률 표시기는 wwwroot/index.html 파일의 HTML에서 구현됩니다.

<div id="app">
    <svg class="loading-progress">
        <circle r="40%" cx="50%" cy="50%" />
        <circle r="40%" cx="50%" cy="50%" />
    </svg>
    <div class="loading-progress-text"></div>
</div>

기본 진행률 표시기에서 프로젝트 템플릿 태그 및 스타일을 검토하려면 ASP.NET Core 참조 원본을 참조하세요.

• wwwroot/index.html
• app.css

참고

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

다음 예제에서는 기본 라운드 진행률 표시기를 사용하는 대신 선형 진행률 표시기를 구현하는 방법을 보여줍니다.

wwwroot/css/app.css에 다음 스타일을 추가합니다.

.linear-progress {
    background: silver;
    width: 50vw;
    margin: 20% auto;
    height: 1rem;
    border-radius: 10rem;
    overflow: hidden;
    position: relative;
}

.linear-progress:after {
    content: '';
    position: absolute;
    inset: 0;
    background: blue;
    scale: var(--blazor-load-percentage, 0%) 100%;
    transform-origin: left top;
    transition: scale ease-out 0.5s;
}

CSS 변수(var(...))는 --blazor-load-percentage의 값을 앱 파일의 로드 진행률을 나타내는 파란색 모조 요소의 scale 속성에 전달하는 데 사용됩니다. 앱이 로드되면, --blazor-load-percentage가 자동으로 업데이트되어 진행률 표시기의 모습이 동적으로 변경됩니다.

wwwroot/index.html에서, <div id="app">...</div>에서 기본 SVG 라운드 표시기를 제거하고 다음 표시로 바꿉니다.

<div class="linear-progress"></div>

.NET WebAssembly 런타임 구성

고급 프로그래밍 시나리오에서는 configureRuntime 함수를 dotnet 런타임 호스트 빌더와 함께 사용하여 .NET WebAssembly 런타임을 구성합니다. 예를 들어 다음과 dotnet.withEnvironmentVariable 같은 환경 변수를 설정합니다.

• .NET WebAssembly 런타임을 구성합니다.
• C 라이브러리의 동작을 변경합니다.

참고

.NET WebAssembly 런타임을 구성하거나 C 라이브러리의 동작에 영향을 주는 환경 변수에 대한 더 많은 정보를 얻기 위해 dotnet/runtime GitHub 리포지토리에서 문서 요청이 보류 중입니다. 설명서 요청이 보류 중이지만, 요청에는 추가 정보와 추가 리소스에 대한 교차 링크가 포함되어 있습니다. .NET WASM 런타임 환경 변수(dotnet/runtime #98225)에 대한 설명서에 대한 질문/요청입니다.

이 함수를 configureRuntime 사용하여 브라우저 프로파일러와 통합할 수도 있습니다.

환경 변수를 설정하는 다음 예제의 자리 표시자의 경우:

• {BLAZOR SCRIPT} 자리 표시자는 스크립트 경로 및 파일 이름입니다Blazor. 스크립트의 위치는 ASP.NET Core Blazor 프로젝트 구조를 참조하세요.
• {NAME} 자리 표시자는 환경 변수의 이름입니다.
• {VALUE} 자리 표시자는 환경 변수의 값입니다.

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    webAssembly: {
      configureRuntime: dotnet => {
        dotnet.withEnvironmentVariable("{NAME}", "{VALUE}");
      }
    }
  });
</script>

독립 실행형 Blazor WebAssembly:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    configureRuntime: dotnet => {
      dotnet.withEnvironmentVariable("{NAME}", "{VALUE}");
    }
  });
</script>

참고

.NET WebAssembly 런타임 API(Blazor.runtime)를 사용하여 .NET 런타임 인스턴스에 액세스할 수 있습니다. 예를 들어 을 사용하여 Blazor.runtime.runtimeBuildInfo.buildConfiguration앱의 빌드 구성을 가져올 수 있습니다.

.NET WebAssembly 런타임 구성에 대한 자세한 내용은 GitHub 리포지토리에서 dotnet.d.ts 런타임의 TypeScript 정의 파일(dotnet/runtime)을 참조하세요.

참고

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

향상된 탐색 및 양식 처리 사용 안 함

이 섹션은 s에 Blazor Web App적용됩니다.

향상된 탐색 및 양식 처리를 비활성화하려면 을/를 disableDomPreservation로 설정하고 true를 사용하세요.

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    ssr: { disableDomPreservation: true }
  });
</script>

앞의 예제 {BLAZOR SCRIPT} 에서 자리 표시자는 스크립트 경로 및 파일 이름입니다 Blazor . 스크립트의 위치는 ASP.NET Core Blazor 프로젝트 구조를 참조하세요.

추가 리소스

• 환경: 앱의 환경 설정
• SignalR (시작 구성에 대한 SignalR 섹션 포함)
• 세계화 및 지역화: 정적으로 문화권을 Blazor.start() 설정(클라이언트 쪽에만 해당)
• Blazor WebAssembly 압축