ASP.NET Core caminho base da aplicação Blazor

Este artigo explica o caminho base da aplicação nas aplicações ASP.NET Core Blazor, incluindo diretrizes de configuração.

O caminho base da aplicação é o caminho raiz do URL da aplicação. O roteamento bem-sucedido em aplicativos Blazor requer configuração de estrutura para qualquer caminho de URL raiz que não esteja no caminho base padrão do aplicativo /.

Considere o seguinte ASP.NET aplicativo principal e Blazor subaplicativo:

• O aplicativo ASP.NET Core é chamado MyApp:
  • O aplicativo reside fisicamente em d:/MyApp.
  • Os pedidos são recebidos em https://www.contoso.com/{MYAPP RESOURCE}.
• Um aplicativo Blazor chamado CoolApp é um subaplicativo de MyApp:
  • O subaplicativo reside fisicamente em d:/MyApp/CoolApp.
  • Os pedidos são recebidos em https://www.contoso.com/CoolApp/{COOLAPP RESOURCE}.

Sem especificar a configuração adicional para CoolApp, o subaplicativo neste cenário não tem conhecimento de onde reside no servidor. Por exemplo, a aplicação não pode construir URLs relativas corretas para os seus recursos sem saber que está localizada no caminho de URL relativo /CoolApp/. Esse cenário também se aplica em vários cenários de hospedagem e proxy reverso quando um aplicativo não está hospedado em um caminho de URL raiz.

Contexto geral

O destino de uma etiqueta âncora (href) pode ser composto por um dos dois pontos de extremidade:

• Locais absolutos que incluem um esquema (esquema da página por padrão, se omitido), host, porta e trajeto ou apenas uma barra (/) seguida pelo trajeto.

  Exemplos: https://example.com/a/b/c ou /a/b/c

• Localizações relativas que contêm apenas um caminho e não começam com uma barra inclinada (/). Eles são resolvidos em relação à URL do documento atual ou ao valor da tag <base>, se especificado.

  Exemplo: a/b/c

A presença de uma barra final (/) num caminho base de aplicação configurado é significativa para calcular o caminho base para URLs da aplicação. Por exemplo, https://example.com/a tem um caminho base de https://example.com/, enquanto https://example.com/a/ com uma barra à direita tem um caminho de base de https://example.com/a.

Para as fontes de links que pertencem ao Blazor em aplicativos ASP.NET Core:

Se estiver a renderizar uma aplicação Blazor a partir de vários documentos (por exemplo, /Admin/B/C/ e /Admin/D/E/), deve levar em conta o caminho base da aplicação, caso contrário, o caminho base será diferente quando a aplicação for renderizada em cada documento e os recursos serão buscados das URLs erradas.

Existem duas abordagens para lidar com o desafio de resolver corretamente as ligações relativas:

• Mapeie os recursos dinamicamente usando o documento em que foram renderizados como raiz.
• Defina um caminho base consistente para o documento e mapeie os recursos sob esse caminho base.

A primeira opção é mais complicada e não é a abordagem mais típica, pois torna a navegação diferente para cada documento. Considere o exemplo a seguir para renderizar uma página /Something/Else:

• Renderizada como /Admin/B/C/, a página é renderizada seguindo o caminho de /Admin/B/C/Something/Else.
• Renderizada sob /Admin/D/E/, a página é renderizada no mesmo caminho de /Admin/B/C/Something/Else.

Sob a primeira abordagem, o roteamento oferece IDynamicEndpointMetadata e MatcherPolicy, que em combinação pode ser a base para a implementação de uma solução completamente dinâmica que determina em tempo de execução sobre como as solicitações são roteadas.

Para a segunda opção, que é a abordagem usual, a aplicação define o caminho base no documento e mapeia os endpoints do servidor para caminhos sob o caminho base. As orientações que se seguem adotam esta abordagem.

Blazor do lado do servidor

Mapeie o hub de SignalR de um aplicativo de Blazor do lado do servidor passando o caminho para MapBlazorHub no arquivo Program:

app.MapBlazorHub("base/path");

O benefício de usar MapBlazorHub é que você pode mapear padrões, como "{tenant}" e não apenas caminhos concretos.

Você também pode mapear o hub SignalR quando a aplicação estiver numa pasta virtual com um pipeline de middleware ramificado . No exemplo a seguir, as solicitações para /base/path/ são tratadas pelo hub de Blazor do SignalR:

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

Configure a etiqueta <base>, de acordo com o guia na seção Configurar o caminho base da aplicação.

Autônomo Blazor WebAssembly

Em um aplicativo Blazor WebAssembly autónomo, somente a etiqueta <base> é configurada, conforme as orientações na seção Configurar o caminho base do aplicativo.

Configurar o caminho base do aplicativo

Para fornecer configuração para o caminho base do aplicativo Blazorhttps://www.contoso.com/CoolApp/, defina o caminho base do aplicativo (<base>), que também é chamado de caminho raiz relativo.

Ao configurar o caminho base do aplicativo, um componente que não está no diretório raiz pode construir URLs relativas ao caminho raiz do aplicativo. Componentes em diferentes níveis da estrutura de diretórios podem criar links para outros recursos em locais em todo o aplicativo. O caminho base do aplicativo também é usado para intercetar hiperlinks selecionados em que o destino href do link está dentro do espaço URI do caminho base do aplicativo. O componente Router lida com a navegação interna.

Coloque a marca <base> na marcação <head> (localização de <head> conteúdo) antes de qualquer elemento que tenha valores de atributo que sejam URLs, como os atributos href nos elementos <link>.

• Use uma das seguintes abordagens em uma aplicação do lado do servidor Blazor:

  • Opção 1: Use a tag <base> para definir o caminho base do aplicativo (local do conteúdo <head>):

    <base href="/CoolApp/">
    

    É necessária a barra final.

  • Opção 2: Chame UsePathBaseprimeiro no pipeline de processamento de pedidos da aplicação (Program.cs) imediatamente após a construção do WebApplicationBuilder (builder.Build()) para configurar o caminho base para qualquer middleware subsequente que interaja com o caminho do pedido.

    app.UsePathBase("/CoolApp");
    

    Chamar UsePathBase é recomendado quando você também deseja executar o aplicativo Blazor Server localmente. Por exemplo, forneça o URL de inicialização em Properties/launchSettings.json:

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

    O marcador {PORT} no exemplo anterior é a porta que corresponde à porta segura na configuração do caminho applicationUrl. O exemplo a seguir mostra o perfil de inicialização completo de um aplicativo na porta 7279:

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

    Para obter mais informações sobre o launchSettings.json arquivo, consulte ASP.NET ambientes de tempo de execução principais. Para obter informações adicionais sobre os caminhos base da app Blazor e alojamento, consulte <base href="/" /> ou a alternativa de tag de base para integração MVC Blazor (dotnet/aspnetcore #43191).

• Blazor WebAssembly autónomos (wwwroot/index.html):

  <base href="/CoolApp/">
  

  É necessária a barra final.

Não prefixe links em toda a aplicação com uma barra oblíqua. Evite o uso de um separador de segmento de caminho ou use a notação de caminho relativo com barra de pontos (./):

• ❌ Incorreto: <a href="/account">
• ✔️ Correto: <a href="account">
• ✔️ Correto: <a href="./account">

Em solicitações de API da Web Blazor WebAssembly com o serviço HttpClient, confirme se os auxiliares JSON (HttpClientJsonExtensions) não prefixam URLs com uma barra diagonal (/):

• ❌ Incorreto: var rsp = await client.GetFromJsonAsync("/api/Account");
• ✔️ Correto: var rsp = await client.GetFromJsonAsync("api/Account");

Não prefixe links relativos do Gestor de Navegação com uma barra. Evite o uso de um separador de segmento de caminho ou use a notação de caminho relativo 'ponto-barra' (./) (./ é um elemento injetado Navigation):

• ❌ Incorreto: Navigation.NavigateTo("/other");
• ✔️ Correto: Navigation.NavigateTo("other");
• ✔️ Correto: Navigation.NavigateTo("./other");

Em configurações típicas para hospedagem do Azure/IIS, a configuração adicional geralmente não é necessária. Em alguns cenários de alojamento não IIS e alojamento de proxy reverso, pode ser necessária configuração adicional do Middleware de Ficheiros Estáticos:

• Para servir arquivos estáticos corretamente (por exemplo, app.UseStaticFiles("/CoolApp");).
• Para servir o script Blazor (_framework/blazor.*.js). Para mais informações, consulte ASP.NET Core Blazor ficheiros estáticos.

Para um aplicativo Blazor WebAssembly com um caminho de URL relativo que não é a raiz (por exemplo, <base href="/CoolApp/">), o aplicativo não consegue encontrar os seus recursos quando é executado localmente. Para superar este problema durante o desenvolvimento local e os testes, pode fornecer um argumento de base de caminho que corresponda ao valor href da marca <base> em tempo de execução. Não inclua uma barra final. Para passar o argumento base do caminho ao executar o aplicativo localmente, execute o comando dotnet watch (ou dotnet run) do diretório do aplicativo com a opção --pathbase:

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

Para um aplicativo Blazor WebAssembly com um caminho de URL relativo de /CoolApp/ (<base href="/CoolApp/">), o comando é:

dotnet watch --pathbase=/CoolApp

Se preferir configurar o perfil de inicialização do aplicativo para especificar o pathbase automaticamente em vez de manualmente com dotnet watch (ou dotnet run), defina a propriedade commandLineArgs em Properties/launchSettings.json. O seguinte também configura o URL de inicialização (launchUrl):

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

Usando CoolApp como exemplo:

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

Usando dotnet watch (ou dotnet run) com a opção --pathbase ou uma configuração de perfil de inicialização que define o caminho base, o aplicativo Blazor WebAssembly responde localmente em http://localhost:port/CoolApp.

Para obter mais informações sobre o launchSettings.json arquivo, consulte ASP.NET ambientes de tempo de execução principais. Para obter informações adicionais sobre os caminhos base da app Blazor e alojamento, consulte <base href="/" /> ou a alternativa de tag de base para integração MVC Blazor (dotnet/aspnetcore #43191).

Obter o caminho base do aplicativo a partir da configuração

As diretrizes a seguir explicam como obter o caminho a partir de um arquivo de configurações de aplicativo para a etiqueta <base> em diferentes ambientes .

Adicione o arquivo de configurações do aplicativo ao aplicativo. O exemplo a seguir é para o ambiente Staging (appsettings.Staging.json):

{
  "AppBasePath": "staging/"
}

Numa aplicação do lado do servidor Blazor, carregue o caminho base a partir da configuração em <head> conteúdo:

@inject IConfiguration Config

...

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

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

Se não houver nenhum valor de configuração para carregar, por exemplo, em ambientes não-testados, o href anterior é resolvido para o caminho raiz /.

Os exemplos nesta seção se concentram em fornecer o caminho base do aplicativo a partir das configurações do aplicativo, mas a abordagem de ler o caminho do IConfiguration é válida para qualquer provedor de configuração. Para obter mais informações, consulte os seguintes recursos:

• Blazor
• Configuração no ASP.NET Core