다음을 통해 공유

ASP.NET Core Blazor 앱 기본 경로

비고

이 기사는 최신 버전이 아닙니다. 현재 릴리스에 대해서는 본 기사의 .NET 9 버전을 참조하십시오.

경고

이 버전의 ASP.NET Core는 더 이상 지원되지 않습니다. 자세한 내용은 .NET 및 .NET Core 지원 정책을 참조하세요. 현재 릴리스에 대해서는 본 기사의 .NET 9 버전을 참조하십시오.

중요합니다

이 정보는 사전 출시 제품과 관련이 있으며, 상업적으로 출시되기 전에 상당히 수정될 수 있습니다. Microsoft는 여기에 제공된 정보에 대해 어떠한 명시적이거나 묵시적인 보증도 하지 않습니다.

현재 릴리스에 대해서는 본 기사의 .NET 9 버전을 참조하십시오.

이 문서에서는 구성 지침을 포함하여 ASP.NET Core 앱의 앱 Blazor 설명합니다.

앱 기본 경로는 앱의 루트 URL 경로입니다. 앱에서 Blazor 성공적으로 라우팅하려면 기본 앱 기본 /경로에 없는 루트 URL 경로에 대한 프레임워크 구성이 필요합니다.

다음 ASP.NET Core 앱 및 Blazor 하위 앱을 고려하세요.

  • ASP.NET Core 앱의 이름은 MyApp다음과 같습니다.
    • 앱의 실제 위치는 d:/MyApp입니다.
    • 요청은 https://www.contoso.com/{MYAPP RESOURCE}에서 수신됩니다.
  • Blazor 이름이 지정된 CoolApp 앱은 다음의 MyApp하위 앱입니다.
    • 하위 앱의 실제 위치는 d:/MyApp/CoolApp입니다.
    • 요청은 https://www.contoso.com/CoolApp/{COOLAPP RESOURCE}에서 수신됩니다.

CoolApp에 대한 추가 구성을 지정하지 않으면 이 시나리오의 하위 앱은 서버에 상주하는 위치에 대해 알지 못합니다. 예를 들어 앱은 상대 URL 경로 /CoolApp/에 상주한다는 사실을 모르는 상태에서는 해당 리소스의 올바른 상대 URL을 생성할 수 없습니다. 이 시나리오는 앱이 루트 URL 경로에서 호스트되지 않는 경우 다양한 호스팅 및 역방향 프록시 시나리오에도 적용됩니다.

배경

앵커 태그의 대상(href)은 다음 두 엔드포인트 중 하나를 사용하여 구성할 수 있습니다.

  • 스키마를 포함하는 절대 위치(생략된 경우 페이지 구성표의 기본값), 호스트, 포트 및 경로 또는 슬래시(/)와 경로가 뒤따릅니다.

    예: https://example.com/a/b/c 또는 /a/b/c

  • 경로만 포함하고 슬래시(/)로 시작하지 않는 상대 위치입니다. 지정된 경우 현재 문서 URL 또는 <base> 태그 값을 기준으로 확인됩니다.

    예: a/b/c

구성된 앱 기본 경로에 후행 슬래시(/)가 있는 것은 앱의 URL에 대한 기본 경로를 계산하는 데 중요합니다. 예를 들어 https://example.com/a 후행 슬래시에는 기본 경로 https://example.com/가 있는 반면 https://example.com/a/ 에 기본 경로 https://example.com/a는 다음과 같습니다.

ASP.NET Core 앱의 Blazor 관련된 링크 원본의 경우:

  • 구성 요소(Razor)의 .razor URL은 일반적으로 상대적입니다.
  • 스크립트(예: Blazor 스크립트)blazor.*.js의 URL은 문서를 기준으로 합니다.
  • 파일()_Host.cshtml에 Blazor Server 수동으로 작성된 URL로, 다른 문서 내에서 렌더링하는 경우 항상 절대적이어야 합니다.
  • 구성 요소(Razor)의 .razor URL은 일반적으로 상대적입니다.
  • 스크립트(예: Blazor 스크립트)blazor.*.js의 URL은 문서를 기준으로 합니다.

다른 문서에서 앱을 렌더링하는 Blazor 경우(예 /Admin/B/C//Admin/D/E/: ) 앱 기본 경로를 고려해야 합니다. 또는 앱이 각 문서에서 렌더링되고 리소스가 잘못된 URL에서 인출될 때 기본 경로가 다릅니다.

상대 링크를 올바르게 해결하는 문제를 처리하는 두 가지 방법이 있습니다.

  • 루트로 렌더링된 문서를 사용하여 리소스를 동적으로 매핑합니다.
  • 문서의 일관된 기본 경로를 설정하고 해당 기본 경로 아래에 리소스를 매핑합니다.

첫 번째 옵션은 더 복잡하며 각 문서에 대해 탐색을 다르게 만들기 때문에 가장 일반적인 방법은 아닙니다. 페이지를 /Something/Else렌더링하는 다음 예제를 고려하세요.

  • 아래에 /Admin/B/C/렌더링된 페이지는 .의 /Admin/B/C/Something/Else경로로 렌더링됩니다.
  • 아래에 /Admin/D/E/렌더링된 페이지는 같은 경로

첫 번째 방법에서 라우팅은 런타임에 요청 라우팅 방법을 결정하는 완전히 동적 솔루션을 구현하기 위한 기초가 될 수 있는 라우팅 제안과 IDynamicEndpointMetadata함께 제공됩니다MatcherPolicy.

일반적인 방식인 두 번째 옵션의 경우 앱은 문서의 기본 경로를 설정하고 서버 엔드포인트를 기본 경로에 매핑합니다. 다음 지침에서는 이 방법을 채택합니다.

서버 쪽 Blazor

SignalR 파일에 경로를 전달하여 서버 쪽 Blazor 앱의 허브를 MapBlazorHubProgram 매핑합니다.

app.MapBlazorHub("base/path");

사용 MapBlazorHub 의 이점은 구체적인 경로뿐만 아니라 패턴을 "{tenant}" 매핑할 수 있다는 것입니다.

분기된 미들웨어 파이프라인이 SignalR 있는 가상 폴더에 앱이 있을 때 허브를 매핑할 수도 있습니다. 다음 예제에서 요청은 /base/path/ 's Blazor 허브'에 의해 SignalR처리됩니다.

app.Map("/base/path/", subapp => {
    subapp.UsePathBase("/base/path/");
    subapp.UseRouting();
    subapp.UseEndpoints(endpoints => endpoints.MapBlazorHub());
});

<base> 앱 기본 경로 구성 섹션의 지침에 따라 태그를 구성합니다.

호스트 Blazor WebAssembly

앱이 호스트 Blazor WebAssembly 된 앱인 경우:

  • 프로젝트의 에서:ServerProgram.cs>
    • 경로 UseBlazorFrameworkFiles (예: app.UseBlazorFrameworkFiles("/base/path");)를 조정합니다.
    • 호출을 구성합니다 UseStaticFiles (예: app.UseStaticFiles("/base/path");).
  • 프로젝트에서 다음을 수행 Client 합니다.
    • 정적 웹 자산(예<StaticWebAssetBasePath>: )을 제공하는 경로와 일치하도록 프로젝트 파일에서 구성 <StaticWebAssetBasePath>base/path</StaticWebAssetBasePath> 합니다.
    • <base> 앱 기본 경로 구성 섹션의 지침에 따라 태그를 구성합니다.

호스트 Blazor WebAssembly 된 솔루션에서 여러 Blazor WebAssembly 앱을 호스팅하는 예제는 여러 호스트된 ASP.NET Core Blazor WebAssembly 앱을 참조의 도메인/포트 호스팅 및 하위 경로 호스팅에 대한 방법을 설명합니다.

독립 실행형 Blazor WebAssembly

독립 실행형 Blazor WebAssembly 앱에서는 앱 기본 경로 구성 섹션의 <base> 지침에 따라 태그만 구성됩니다.

앱 기본 경로 구성

앱의 기본 경로에 대한 Blazor 구성을 제공하려면 상대 루트 경로https://www.contoso.com/CoolApp/라고도 하는 앱 기본 경로(<base>)를 설정합니다.

앱 기본 경로를 구성하여 루트 디렉터리에 없는 구성 요소는 앱의 루트 경로를 기준으로 URL을 생성할 수 있습니다. 디렉터리 구조의 다른 수준에 있는 구성 요소는 앱 전체의 위치에서 다른 리소스에 대한 링크를 만들 수 있습니다. 또한 링크의 href 대상이 앱 기본 경로 URI 공간 내에 있는 경우 선택한 하이퍼링크를 가로채는 데 앱 기본 경로가 사용됩니다. Router 구성 요소는 내부 탐색을 처리합니다.

<base> 태그를 <head> 마크업(<head> 콘텐츠의위치)에 배치하되, 이는 URL이 들어간 특성 값이 있는 요소들, 예를 들어, href 요소의 <link> 특성 값이 오기 전에 배치해야 합니다.

많은 호스팅 시나리오에서 앱에 대한 상대 URL 경로는 앱의 루트입니다. 이러한 기본 경우 앱의 상대 URL 기본 경로는 콘텐츠에서와 같이 / 구성됩니다<base href="/" />.<head>

많은 호스팅 시나리오에서 앱에 대한 상대 URL 경로는 앱의 루트입니다. 이러한 기본 사례에서 앱의 상대 URL 기본 경로는 콘텐츠<head> 다음과 같습니다.

  • Blazor Server: ~/는 <base href="~/" />로 구성됩니다.
  • Blazor WebAssembly: /는 <base href="/" />로 구성됩니다.

비고

GitHub Pages 및 IIS 하위 앱과 같은 일부 호스팅 시나리오에서는 앱 기본 경로를 앱의 서버 상대 URL 경로로 설정해야 합니다.

  • 서버 쪽 Blazor 앱에서 다음 방법 중 하나를 사용합니다.

    • 옵션 1: <base> 태그를 사용하여 앱의 기본 경로(<head> 컨텐츠의 위치)를 설정합니다.

      <base href="/CoolApp/">

      후행 슬래시가 필요합니다.

    • 옵션 2: 빌드 직후 앱의 요청 처리 파이프라인(UsePathBase)에서 먼저Program.cs하여 요청 경로와 상호 작용하는 다음 미들웨어에 대한 기본 경로를 구성합니다.

      app.UsePathBase("/CoolApp");

      UsePathBase 앱을 로컬로 실행하려는 경우에도 Blazor Server 호출이 권장됩니다. 예를 들어 Properties/launchSettings.json에 시작 URL을 제공합니다.

      "launchUrl": "https://localhost:{PORT}/CoolApp",

      앞의 예제에서 {PORT} 자리 표시자는 applicationUrl 구성 경로의 보안 포트와 일치하는 포트입니다. 다음 예제에서는 7279 포트에서 앱의 전체 시작 프로필을 보여 줍니다.

      "BlazorSample": {
  "commandName": "Project",
  "dotnetRunMessages": true,
  "launchBrowser": true,
  "applicationUrl": "https://localhost:7279;http://localhost:5279",
  "launchUrl": "https://localhost:7279/CoolApp",
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Development"
}

      launchSettings.json 파일의 자세한 내용은 ASP.NET Core에서 여러 환경 사용을 참조하세요. Blazor 앱 기본 경로 및 호스팅에 대한 자세한 내용은 <base href="/" /> 또는 Blazor MVC 통합에 대한 기본 태그 대체(dotnet/aspnetcore #43191)를 참조하세요.

  • 독립 실행형 Blazor WebAssembly (wwwroot/index.html):

    <base href="/CoolApp/">

    후행 슬래시가 필요합니다.

  • 호스팅된 Blazor WebAssembly (Client 프로젝트, wwwroot/index.html)

    <base href="/CoolApp/">

    후행 슬래시가 필요합니다.

    Server 프로젝트에서 빌드 직후 앱의 요청 처리 파이프라인(UsePathBase)에서 먼저Program.cs하여 요청 경로와 상호 작용하는 다음 미들웨어에 대한 기본 경로를 구성합니다.

    app.UsePathBase("/CoolApp");

비고

WebApplication를 사용할 때( .NET 5의 ASP.NET Core에서 .NET 6으로 마이그레이션 참조), 수정된 경로를 일치시키기 전에 라우팅 미들웨어가 경로를 관찰할 수 있도록 app.UseRouting 후에 UsePathBase를 호출해야 합니다. 그렇지 않은 경우 UsePathBase 및 라우팅 문서에서 설명하는 것과 같이 에서 경로를 다시 작성하기 전에 경로가 일치합니다.

슬래시를 사용하여 앱 전체의 링크에 접두사를 추가하지 마세요. 경로 세그먼트 구분 기호를 사용하지 않거나 점 슬래시(./) 상대 경로 표기법을 사용하지 마세요.

  • 잘못된 예: <a href="/account">
  • 맞는: <a href="account">
  • 맞는: <a href="./account">

서비스를 사용하는 웹 API 요청에서 Blazor WebAssembly

  • 잘못된 예: var rsp = await client.GetFromJsonAsync("/api/Account");
  • 맞는: var rsp = await client.GetFromJsonAsync("api/Account");

앞으로 슬래시가 있는 탐색 관리자 상대 링크 앞에 접두사를 지정하지 마세요. 경로 세그먼트 구분 기호를 사용하지 않거나 점 슬래시(./) 상대 경로 표기법을 사용하지 마세요(Navigation는 NavigationManager으로 삽입됩니다).

  • 잘못된 예: Navigation.NavigateTo("/other");
  • 맞는: Navigation.NavigateTo("other");
  • 맞는: Navigation.NavigateTo("./other");

Azure/IIS 호스팅을 위한 일반적인 구성에서는 일반적으로 추가 구성이 필요하지 않습니다. 일부 비 IIS 호스팅 및 역방향 프록시 호스팅 시나리오에서는 추가 정적 파일 미들웨어 구성이 필요할 수 있습니다.

  • 정적 파일을 올바르게 제공하려면(예: app.UseStaticFiles("/CoolApp");).
  • 스크립트를 Blazor 제공하려면(_framework/blazor.*.js). 자세한 내용은 ASP.NET Core Blazor 정적 파일참조하세요.

루트가 아닌 Blazor WebAssembly 상대 URL 경로(예<base href="/CoolApp/">: )가 있는 앱의 경우 로컬로 실행할 때 앱이 해당 리소스를 찾지 못합니다. 로컬 개발 및 시험 중에 이 문제를 해결하려면 런타임에 태그의 href 값과 일치하는 <base> 인수를 제공할 수 있습니다. 후행 슬래시를 포함하지 않습니다. 앱을 로컬로 실행할 때 경로 기본 인수를 전달하려면 다음 옵션을 사용하여 앱 디렉터리 dotnet watch 에서 (또는dotnet run) 명령을 실행 --pathbase 합니다.

dotnet watch --pathbase=/{RELATIVE URL PATH (no trailing slash)}

Blazor WebAssembly의 상대 URL 경로를 사용하는 /CoolApp/ 앱의 경우(<base href="/CoolApp/">) 명령은 다음과 같습니다.

dotnet watch --pathbase=/CoolApp

수동으로 사용하거나 pathbase속성을 설정하는 dotnet watchdotnet run대신 자동으로 지정 commandLineArgs 하도록 앱의 시작 프로필을 구성하려는 Properties/launchSettings.json 경우 . 다음은 시작 URL(launchUrl)도 구성합니다.

"commandLineArgs": "--pathbase=/{RELATIVE URL PATH (no trailing slash)}",
"launchUrl": "{RELATIVE URL PATH (no trailing slash)}",

CoolApp을 예로 사용:

"commandLineArgs": "--pathbase=/CoolApp",
"launchUrl": "CoolApp",

dotnet watch 기본 경로를 설정하는 옵션 또는 시작 프로필 구성과 함께 dotnet run (또는--pathbase) 사용하여 앱은 Blazor WebAssembly 로컬로 http://localhost:port/CoolApp응답합니다.

launchSettings.json 파일의 자세한 내용은 ASP.NET Core에서 여러 환경 사용을 참조하세요. Blazor 앱 기본 경로 및 호스팅에 대한 자세한 내용은 <base href="/" /> 또는 Blazor MVC 통합에 대한 기본 태그 대체(dotnet/aspnetcore #43191)를 참조하세요.

구성에서 앱 기본 경로 가져오기

다음 지침에서는 다양한 환경에 대한 <base> 앱 설정 파일에서 태그의 경로를 가져오는 방법을 설명합니다.

앱에 앱 설정 파일을 추가합니다. 다음 예제는 환경(Staging)에 대한 appsettings.Staging.json 것입니다.

{
  "AppBasePath": "staging/"
}

서버 쪽 Blazor 앱에서 콘텐츠<head> 에서 기본 경로를 로드합니다.

@inject IConfiguration Config

...

<head>
    ...
    <base href="/@(Config.GetValue<string>("AppBasePath"))" />
    ...
</head>

또는 서버 쪽 앱은 에 대한 UsePathBase구성에서 값을 가져올 수 있습니다. 다음 코드를 배치합니다. 다음 예제에서는 구성 키를 AppBasePath사용합니다.

app.UsePathBase($"/{app.Configuration.GetValue<string>("AppBasePath")}");

클라이언트 쪽 Blazor WebAssembly 앱에서:

  • 다음 <base> 에서 태그를 제거합니다.wwwroot/index.html

    - <base href="..." />

  • 구성 요소의 구성 요소를 HeadContent 통해 App 앱 기본 경로를 제공합니다(App.razor).

    @inject IConfiguration Config

...

<HeadContent>
    <base href="/@(Config.GetValue<string>("AppBasePath"))" />
</HeadContent>

예를 들어 비 스테이징 환경에서 로드할 구성 값이 없으면 위의 href 루트 경로 /가 확인됩니다.

이 섹션의 예제에서는 앱 설정에서 앱 기본 경로를 제공하는 데 중점을 두지만 경로를 읽 IConfiguration 는 방법은 모든 구성 공급자에 유효합니다. 자세한 내용은 다음 리소스를 참조하세요.