Arquivos estáticos Blazor do ASP.NET Core

Este artigo descreve a configuração do aplicativo Blazor para servir arquivos estáticos.

Middleware de ativo estático

Esta seção se aplica a aplicativos Blazor do lado do servidor.

Configure o Middleware de arquivos estáticos para fornecer ativos estáticos aos clientes chamando UseStaticFiles no pipeline de processamento de solicitação do aplicativo. Saiba mais em Arquivos estáticos no ASP.NET Core.

Em versões anteriores ao .NET 8, os arquivos estáticos da estrutura Blazor, como o script Blazor, são atendidos por meio do Middleware de Arquivo Estático. No .NET 8 ou posterior, os arquivos estáticos da estrutura Blazor são mapeados usando o roteamento de ponto de extremidade e o Middleware de Arquivo Estático não é mais usado.

Modo de projeto de ativo da Web estático

Esta seção se aplica ao projeto .Client de um aplicativo Web Blazor.

A configuração necessária <StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode> no projeto .Client de um aplicativo Web Blazor reverte comportamentos de ativos estáticos Blazor WebAssembly de volta para os padrões, para que o projeto se comporte como parte do projeto hospedado. O SDK Blazor WebAssembly (Microsoft.NET.Sdk.BlazorWebAssembly) configura ativos da Web estáticos de uma maneira específica para funcionar no modo "autônomo" com um servidor simplesmente consumindo as saídas da biblioteca. Isso não é apropriado para um aplicativo Web Blazor, onde a parte WebAssembly do aplicativo é uma parte lógica do host e precisa se comportar mais como uma biblioteca. Por exemplo, o projeto não expõe o pacote de estilos (por exemplo, BlazorSample.Client.styles.css) e, em vez disso, fornece apenas ao host o pacote do projeto, para que o host possa incluí-lo no próprio pacote de estilos.

A alteração do valor (Default) de <StaticWebAssetProjectMode> ou remoção da propriedade do projeto .Clientnão tem suporte.

Arquivos estáticos em ambientes não Development estáticos

Esta seção se aplica a arquivos estáticos do lado do servidor.

Ao executar um aplicativo localmente, os ativos da Web estáticos só são habilitados por padrão no ambiente Development. Para habilitar arquivos estáticos para ambientes diferentes de Development durante o desenvolvimento e teste local (por exemplo, Staging), chame UseStaticWebAssets no WebApplicationBuilder no arquivo Program.

Aviso

Chame UseStaticWebAssets para o ambiente exato para impedir a ativação do recurso em produção, pois ele atende arquivos de locais separados em disco diferente do projeto, se chamado em um ambiente de produção. O exemplo nesta seção verifica o ambiente Staging chamando IsStaging.

if (builder.Environment.IsStaging())
{
    builder.WebHost.UseStaticWebAssets();
}

Prefixo para Blazor WebAssembly ativos

Esta seção aplica-se a Aplicativos Web Blazor.

Use a opção de ponto de extremidade WebAssemblyComponentsEndpointOptions.PathPrefix para definir a cadeia de caracteres do caminho que indica o prefixo para os ativos Blazor WebAssembly. O caminho deve corresponder a um projeto de aplicativo referenciado Blazor WebAssembly.

endpoints.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode(options => 
        options.PathPrefix = "{PATH PREFIX}");

No exemplo anterior, o {PATH PREFIX} espaço reservado é o prefixo do caminho e deve começar com uma barra (/).

No exemplo a seguir, o prefixo de caminho é definido como /path-prefix:

endpoints.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode(options => 
        options.PathPrefix = "/path-prefix");

Caminho de base do ativo da Web estático

Esta seção se aplica a aplicativos Blazor WebAssembly autônomos.

Por padrão, a publicação do aplicativo coloca os ativos estáticos do aplicativo, incluindo arquivos de estrutura Blazor (_framework ativos de pasta), no caminho raiz (/) na saída publicada. A propriedade <StaticWebAssetBasePath> especificada no arquivo de projeto (.csproj) define o caminho base como um caminho não raiz:

<PropertyGroup>
  <StaticWebAssetBasePath>{PATH}</StaticWebAssetBasePath>
</PropertyGroup>

No exemplo anterior, o espaço reservado {PATH} é o caminho.

Sem definir a propriedade <StaticWebAssetBasePath>, um aplicativo autônomo é publicado em /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/.

No exemplo anterior, o espaço reservado {TFM} é o Moniker da Estrutura de Destino (TFM) (por exemplo, net6.0).

Se a propriedade <StaticWebAssetBasePath> em um aplicativo Blazor WebAssembly autônomo definir o caminho do ativo estático publicado como app1, o caminho raiz para o aplicativo na saída publicada será /app1.

No arquivo do projeto de aplicativo Blazor WebAssembly autônomo (.csproj):

<PropertyGroup>
  <StaticWebAssetBasePath>app1</StaticWebAssetBasePath>
</PropertyGroup>

Na saída publicada, o caminho para o aplicativo autônomo Blazor WebAssembly é /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/.

No exemplo anterior, o espaço reservado {TFM} é o Moniker da Estrutura de Destino (TFM) (por exemplo, net6.0).

Mapeamentos de arquivo e opções de arquivo estático

Esta seção se aplica a arquivos estáticos do lado do servidor.

Para criar mapeamentos de arquivo adicionais com FileExtensionContentTypeProvider ou configurar outro StaticFileOptions, use uma das abordagens a seguir. Nos exemplos a seguir, o espaço reservado {EXTENSION} é a extensão de arquivo e o espaço reservado {CONTENT TYPE} é o tipo de conteúdo. O namespace da API a seguir é Microsoft.AspNetCore.StaticFiles.

• Configure opções por meio da injeção de dependência (DI) no arquivo Program usando StaticFileOptions:

  var provider = new FileExtensionContentTypeProvider();
  provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";
  
  builder.Services.Configure<StaticFileOptions>(options =>
  {
      options.ContentTypeProvider = provider;
  });
  
  app.UseStaticFiles();
  

• Passe o StaticFileOptions diretamente para UseStaticFiles no arquivo Program:

  var provider = new FileExtensionContentTypeProvider();
  provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";
  
  app.UseStaticFiles(new StaticFileOptions { ContentTypeProvider = provider });
  

Recursos adicionais

Caminho base do aplicativo