Hospedar e implantar o ASP.NET Core Blazor

Este artigo explica como hospedar e implantar aplicativos Blazor.

Publicar o aplicativo

Os aplicativos são publicados para implantação na configuração de versão.

Visual Studio

1. Selecione o comando Publicar {APPLICATION} no menu Compilar, em que o espaço reservado {APPLICATION} é o nome do aplicativo.
2. Selecione o botão destino de publicação. Para publicar localmente, selecione Pasta.
3. Aceite o local padrão no campo Escolher uma pasta ou especifique um local diferente. Selecione o botão Publish.

CLI do .NET Core

Use o comando dotnet publish para publicar o aplicativo com uma configuração de Versão:

dotnet publish -c Release

Publicar o aplicativo dispara uma restauração das dependências do projeto e compila o projeto antes de criar os ativos para implantação. Como parte do processo de build, os assemblies e métodos não usados são removidos para reduzir o tamanho de download do aplicativo e os tempos de carregamento.

Locais de publicação:

• Aplicativo Web Blazor: por padrão, o aplicativo é publicado na pasta /bin/Release/{TARGET FRAMEWORK}/publish. Implante o conteúdo da pasta publish no host.
• Blazor WebAssembly: por padrão, o aplicativo é publicado na pasta bin\Release\net8.0\browser-wasm\publish\. Para implantar o aplicativo como um site estático, copie o conteúdo da pasta wwwroot para o host do site estático.

O {TARGET FRAMEWORK} nos caminhos anteriores é a estrutura de destino (por exemplo, net8.0).

IIS

Para hospedar um aplicativo Blazor no IIS, consulte os seguintes recursos:

• Hospedagem do IIS
  • Publicar um aplicativo ASP.NET Core no IIS
  • Hospedar o ASP.NET Core no Windows com o IIS
• Hospedar e implantar aplicativos Blazor no ASP.NET Core do lado do servidor: aplicativos do servidor em execução no IIS, incluindo IIS com Máquinas Virtuais (VMs) do Azure executando o sistema operacional Windows e o Serviço de Aplicativo do Azure.
• Hospedar e implantar ASP.NET CoreBlazor WebAssembly: inclui diretrizes adicionais para aplicativos Blazor WebAssembly hospedados no IIS, incluindo hospedagem de site estático, arquivos web.config personalizados, reescrita de URL, subaplicativos, compactação e hospedagem de arquivos estáticos do Armazenamento do Azure.
• Hospedagem de subaplicação do IIS
  • Siga as diretrizes na seção Caminho base do aplicativo para o aplicativo Blazor antes de publicar o aplicativo. Os exemplos usam um caminho base do aplicativo de /CoolApp e mostram como obter o caminho base das configurações do aplicativo ou de outros provedores de configuração.
  • Siga as diretrizes de configuração de subaplicação em Configuração avançada. O caminho da pasta do subaplicativo no site raiz torna-se o caminho virtual do subaplicativo. Para um caminho base de aplicativo /CoolApp, o aplicativo Blazor é colocado em uma pasta chamada CoolApp no site raiz e o subaplicativo assume um caminho virtual de /CoolApp.

Não há suporte para o compartilhamento de um pool de aplicativos entre aplicativos ASP.NET Core, inclusive para aplicativos Blazor. Use um pool de aplicativos por aplicativo ao hospedar com o IIS e evite o uso dos diretórios virtuais do IIS para hospedar vários aplicativos.

Caminho base do aplicativo

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

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

• O aplicativo ASP.NET Core é chamado MyApp:
  • O aplicativo reside fisicamente em d:/MyApp.
  • As solicitações são recebidas em https://www.contoso.com/{MYAPP RESOURCE}.
• Um aplicativo Blazor chamado CoolApp é um subaplicativo de MyApp:
  • O subaplicativo reside fisicamente em d:/MyApp/CoolApp.
  • As solicitações são recebidas em https://www.contoso.com/CoolApp/{COOLAPP RESOURCE}.

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

Tela de fundo

O destino de uma marca de âncora (href) pode ser composto com qualquer um dos dois pontos de extremidade:

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

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

• Locais relativos que contêm apenas um caminho e não começam com uma barra (/). Eles são resolvidas em relação à URL do documento atual ou ao valor da marca <base>, se especificado.

  Exemplo: a/b/c

A presença de uma barra à direita (/) em um caminho base de aplicativo configurado é significativa para calcular o caminho base para URLs do aplicativo. 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 base de https://example.com/a.

Há três fontes de links que pertencem a Blazor em aplicativos do ASP.NET Core:

• As URLs em componentes Razor (.razor) costumam ser relativas.
• URLs em scripts, como os scripts do Blazor (blazor.*.js), que são relativos ao documento.

Se você estiver renderizando um Blazor aplicativo de documentos diferentes (por exemplo, /Admin/B/C/ e /Admin/D/E/), deverá levar em conta o caminho base do aplicativo ou o caminho base será diferente quando o aplicativo for renderizado em cada documento e os recursos forem obtidos das URLs erradas.

Há duas abordagens para lidar com o desafio de resolver vínculos relativos corretamente:

• Mapeie os recursos dinamicamente usando o documento no qual foram renderizados como a raiz.
• Defina um caminho base consistente para o documento e mapeie os recursos nesse 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 em /Admin/B/C/, a página é renderizada com um caminho de /Admin/B/C/Something/Else.
• Renderizada em /Admin/D/E/, a página é renderizada no mesmo caminho de /Admin/B/C/Something/Else.

Na primeira abordagem, o roteamento oferece IDynamicEndpointMetadata e MatcherPolicy, que, em combinação, podem ser a base para implementar uma solução completamente dinâmica que determina em runtime sobre como as solicitações são roteadas.

Para a segunda opção, que é a abordagem usual tomada, o aplicativo define o caminho base no documento e mapeia os pontos de extremidade do servidor para caminhos sob a base. As diretrizes a seguir adotam essa abordagem.

Blazor do lado do servidor

Mapeie o hub SignalR de um aplicativo Blazor do lado do servidor transmitindo o caminho para o 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.

Também é possível mapear o hub SignalR quando o aplicativo estiver em uma pasta virtual com um pipeline de middleware ramificado. No exemplo a seguir, as solicitações para /base/path/ a serem tratadas pelo hub de BlazorSignalR:

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

Configure a tag <base>, de acordo com as diretrizes na seção Configurar o caminho base do aplicativo.

Blazor WebAssembly autônomo

Em um aplicativo Blazor WebAssembly autônomo, somente a tag <base> é configurada, de acordo com as diretrizes na seção Configurar o caminho base do aplicativo.

Configurar o caminho base do aplicativo

Para fornecer configuração para o Blazorcaminho base de aplicativo de https://www.contoso.com/CoolApp/, defina o caminho base do aplicativo, 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 níveis diferentes 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 interceptar hiperlinks selecionados em que o destino href do link está dentro do espaço do URI do caminho base do aplicativo. O componente Router manipula a navegação interna.

Em muitos cenários de hospedagem, o caminho da URL relativa para o aplicativo é a raiz do aplicativo. Nesses casos padrão, o caminho básico da URL relativa do aplicativo é / configurado como <base href="/" /> no conteúdo <head>.

Observação

Em alguns cenários de hospedagem, como as páginas do GitHub e os sub-aplicativos do IIS, o caminho base do aplicativo deve ser definido como o caminho de URL relativo do aplicativo do servidor.

• Em um aplicativo Blazor do lado do servidor, use uma das seguintes abordagens:

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

    <base href="/CoolApp/">
    

    A barra à direita é necessária.

  • Opção 2: chame UsePathBaseprimeiro do pipeline de processamento de solicitação do aplicativo (Program.cs) imediatamente após WebApplicationBuilder ser criado (builder.Build()) para configurar o caminho base para qualquer middleware seguinte que interaja com o caminho da solicitação:

    app.UsePathBase("/CoolApp");
    

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

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

    O espaço reservado {PORT} no exemplo anterior é a porta que corresponde à porta segura no caminho de configuração applicationUrl. O seguinte exemplo 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 arquivo launchSettings.json, consulte Uso de vários ambientes no ASP.NET Core. Para obter informações adicionais sobre caminhos base do aplicativo Blazor e hospedagem, consulte <base href="/" /> ou alternativa de marca base para integração do MVC Blazor (dotnet/aspnetcore #43191).

• Blazor WebAssembly autônomo (wwwroot/index.html):

  <base href="/CoolApp/">
  

  A barra à direita é necessária.

Observação

Ao usar WebApplication (consulte Migrar do ASP.NET Core 5.0 para o 6.0), app.UseRouting precisa ser chamado após UsePathBase para que o middleware de roteamento possa observar o caminho modificado antes de fazer a correspondência entre as rotas. Caso contrário, a correspondência das rotas é feita antes que o caminho seja reescrito por UsePathBase, conforme descrito nos artigos Ordenação de middleware e Roteamento.

Não prefixe links no aplicativo com uma barra "/". Evite o uso de um separador de segmento de caminho ou use a notação de caminho relativo de barra de ponto (./):

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

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

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

Não prefixe links relativos do Gerenciador de Navegação com uma barra "/". Evite o uso de um separador de segmento de caminho ou use a notação de caminho relativo de barra de ponto (./) (Navigation é NavigationManager inserido):

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

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

• Para servir arquivos estáticos corretamente (por exemplo, app.UseStaticFiles("/CoolApp");).
• Para disponibilizar o script do Blazor (_framework/blazor.*.js). Saiba mais em Arquivos estáticos de Blazor no ASP.NET Core.

Para um aplicativo Blazor WebAssembly com um caminho de URL relativa não raiz (por exemplo, <base href="/CoolApp/">), o aplicativo não consegue localizar seus recursos quando é executado localmente. Para superar esse problema durante o desenvolvimento e os testes locais, você pode fornecer um argumento base de caminho que corresponde ao valor de href da tag <base> no runtime. Não inclua uma barra à direita. Para passar o argumento base do caminho ao executar o aplicativo localmente, execute o comando dotnet run no diretório do aplicativo com a opção --pathbase:

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

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

dotnet run --pathbase=/CoolApp

Se preferir configurar o perfil de inicialização do aplicativo para especificar pathbase automaticamente em vez de manualmente com dotnet run,defina a propriedade commandLineArgs em Properties/launchSettings.json. O seguinte também configura a 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 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 arquivo launchSettings.json, consulte Uso de vários ambientes no ASP.NET Core. Para obter informações adicionais sobre caminhos base do aplicativo Blazor e hospedagem, consulte <base href="/" /> ou alternativa de marca base para integração do 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 para a marca <base> de um arquivo de configurações de aplicativo para diferentes ambientes.

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

{
  "AppBasePath": "staging/"
}

Em um aplicativo Blazor do lado do servidor, carregue o caminho base da configuração no conteúdo <head>:

@inject IConfiguration Config

...

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

Como alternativa, um aplicativo do lado do servidor pode obter o valor da configuração para UsePathBase. Coloque o código a seguir primeiro no pipeline de processamento de solicitações do aplicativo (Program.cs) imediatamente após a compilação de WebApplicationBuilder (builder.Build()). O seguinte exemplo usa a chave de configuração AppBasePath:

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

Em um aplicativo Blazor WebAssembly do lado do cliente:

• Remova a marca <base> de wwwroot/index.html:

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

• Forneça o caminho base do aplicativo por meio de um componente HeadContent no componenteApp (App.razor):

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

Se não houver nenhum valor de configuração a ser carregado, por exemplo, em ambientes sem preparo, o href anterior será 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 leitura do caminho de IConfiguration é válida para qualquer provedor de configuração. Para saber mais, consulte os recursos a seguir:

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

Configuração de Blazor ServerMapFallbackToPage

Esta seção só se aplica a aplicativos Blazor Server. MapFallbackToPage não tem suporte em aplicativos Web Blazor e aplicativos Blazor WebAssembly.

Em cenários em que um aplicativo requer uma área separada com recursos personalizados e componentes Razor:

• Crie uma pasta dentro da pasta Pages do aplicativo para manter os recursos. Por exemplo, uma seção de administrador de um aplicativo é criada em uma nova pasta chamada Admin (Pages/Admin).

• Crie uma página raiz (_Host.cshtml) para a área. Por exemplo, crie um arquivo Pages/Admin/_Host.cshtml na página raiz principal do aplicativo (Pages/_Host.cshtml). Não forneça uma diretiva @page na página _Host do Administrador.

• Adicione um layout à pasta da área (por exemplo, Pages/Admin/_Layout.razor). No layout da área separada, defina a marca <base>href para corresponder à pasta da área (por exemplo, <base href="/Admin/" />). Para fins de demonstração, adicione ~/ aos recursos estáticos na página. Por exemplo:

  • ~/css/bootstrap/bootstrap.min.css
  • ~/css/site.css
  • ~/BlazorSample.styles.css (o namespace do aplicativo de exemplo é BlazorSample)
  • ~/_framework/blazor.server.js (script Blazor)

• Se a área deve ter a própria pasta de ativo estático, adicione a pasta e especifique seu local para o Middleware de Arquivo Estático em Program.cs (por exemplo, app.UseStaticFiles("/Admin/wwwroot")).

• Componentes Razor são adicionados à pasta da área. No mínimo, adicione um componente Index à pasta da área com a diretiva @page correta para a área. Por exemplo, adicione um arquivo Pages/Admin/Index.razor com base no arquivo Pages/Index.razor padrão do aplicativo. Indique a área do Administrador como o modelo de rota na parte superior do arquivo (@page "/admin"). Adicione componentes adicionais conforme necessário. Por exemplo, Pages/Admin/Component1.razor com uma diretiva @page e um modelo de rota de @page "/admin/component1.

• Em Program.cs, chame MapFallbackToPage para o caminho de solicitação da área imediatamente antes do caminho da página raiz de fallback para a página _Host:

  ...
  app.UseRouting();
  
  app.MapBlazorHub();
  app.MapFallbackToPage("~/Admin/{*clientroutes:nonfile}", "/Admin/_Host");
  app.MapFallbackToPage("/_Host");
  
  app.Run();
  

Implantação

Confira orientações de implantação nos tópicos a seguir:

• Hospedar e implantar o ASP.NET Core Blazor WebAssembly
• Hospedar e implantar aplicativos Blazor no ASP.NET Core no lado do servidor