ASP.NET Core Blazor arquivos estáticos

Este artigo descreve a configuração da aplicação Blazor para disponibilizar arquivos estáticos.

Para obter informações gerais sobre como servir arquivos estáticos com as convenções de roteamento de ativos estáticos, consulte Mapear arquivos estáticos no ASP.NET Core antes de ler este artigo.

Entrega de ativos estáticos em aplicativos Blazor do lado do servidor

O serviço de recursos estáticos é gerido por convenções de endpoints de roteamento ou por um middleware descrito na tabela a seguir.

Característica	API (Interface de Programação de Aplicações)	Versão .NET	Descrição
Mapear convenções de ponto de extremidade de roteamento de ativos estáticos	MapStaticAssets	.NET 9 ou posterior	Otimiza a entrega de ativos estáticos aos clientes.
Middleware de arquivos estáticos	UseStaticFiles	Todas as versões do .NET	Sirve ativos estáticos para clientes sem as otimizações de Mapear Ativos Estáticos, mas útil para algumas tarefas que o Mapear Ativos Estáticos não é capaz de gerenciar.

Os Ativos Estáticos do Mapa podem substituir UseStaticFiles na maioria das situações. No entanto, o Map Static Assets é otimizado para servir os ativos de locais conhecidos no aplicativo no momento da compilação e publicação. Se a aplicação servir recursos de outros locais, como disco ou recursos incorporados, UseStaticFiles deve ser usado.

Map Static Assets (MapStaticAssets) substitui a chamada de UseBlazorFrameworkFiles em aplicações que disponibilizam ficheiros de frameworks Blazor WebAssembly, e invocar explicitamente UseBlazorFrameworkFiles num Blazor Web App não é necessário porque a API é chamada automaticamente ao invocar AddInteractiveWebAssemblyComponents.

Quando os modos de renderização Interactive WebAssembly ou Interactive Auto estão ativados:

• Blazor cria um ponto de extremidade para expor a coleção de recursos como um módulo JS.
• A URL é emitida para o corpo da solicitação como estado de componente persistente quando um componente WebAssembly é processado na página.
• Durante a inicialização do WebAssembly, Blazor recupera a URL, importa o módulo e chama uma função para recuperar a coleção de ativos e reconstruí-la na memória. O URL é específico para o conteúdo e armazenado em cache para sempre, portanto, esse custo geral é pago apenas uma vez por usuário até que o aplicativo seja atualizado.
• A coleção de recursos também é exposta numa URL compreensível (_framework/resource-collection.js), para que JS tenha acesso à coleção de recursos para navegação aprimorada ou para implementar funcionalidades de outros frameworks e componentes de terceiros.

O middleware de arquivo estático (UseStaticFiles) é útil nas seguintes situações que o Map Static Assets (MapStaticAssets) não pode lidar:

• Aplicar um prefixo de caminho aos ficheiros de recursos Blazor WebAssembly estáticos, conforme abordado na seção Prefixo para recursos do ativo Blazor WebAssembly.
• Configuração de mapeamentos de arquivo de extensões para tipos de conteúdo específicos e definição de opções de arquivo estático, que é abordado na seção Mapeamentos de arquivos e opções de arquivos estáticos.

Para obter mais informações, consulte ficheiros estáticos no ASP.NET Core.

Entregue ativos com convenções de roteamento de endpoints para Ativos Estáticos do Mapa

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

Os ativos são entregues por meio da propriedade ComponentBase.Assets, que resolve a URL digitalizada de um determinado ativo. No exemplo a seguir, Bootstrap, a folha de estilo do aplicativo de modelo de projeto Blazor (app.css) e a folha de estilo de isolamento CSS (com base no namespace de um aplicativo chamado BlazorSample) estão associados no componente raiz, normalmente o componente App (Components/App.razor):

<link rel="stylesheet" href="@Assets["bootstrap/bootstrap.min.css"]" />
<link rel="stylesheet" href="@Assets["app.css"]" />
<link rel="stylesheet" href="@Assets["BlazorSample.styles.css"]" />

Importar mapas

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

O componente Mapa de Importação (ImportMap) representa um elemento de mapa de importação (<script type="importmap"></script>) que define o mapa de importação para scripts de módulo. O componente Import Map é colocado no conteúdo <head> do componente raiz, normalmente no componente App (Components/App.razor).

<ImportMap />

Observação

Em Blazor Web Appque adotam renderização global do Interactive WebAssembly, o componente ImportMap não serve para nada e pode ser removido do componente App. Para obter mais informações, consulte as observações introdutórias deste artigo.

Se um ImportMapDefinition personalizado não for atribuído a um componente de mapa de importação, o mapa de importação será gerado com base nos ativos da aplicação.

Os exemplos a seguir demonstram definições de mapa de importação personalizadas e os mapas de importação que eles criam.

Mapa de importação básico:

new ImportMapDefinition(
    new Dictionary<string, string>
    {
        { "jquery", "https://cdn.example.com/jquery.js" },
    },
    null,
    null);

O código anterior resulta no seguinte mapa de importação:

{
  "imports": {
    "jquery": "https://cdn.example.com/jquery.js"
  }
}

Mapa de importação com alcance delimitado

new ImportMapDefinition(
    null,
    new Dictionary<string, IReadOnlyDictionary<string, string>>
    {
        ["/scoped/"] = new Dictionary<string, string>
        {
            { "jquery", "https://cdn.example.com/jquery.js" },
        }
    },
    null);

O código anterior resulta no seguinte mapa de importação:

{
  "scopes": {
    "/scoped/": {
      "jquery": "https://cdn.example.com/jquery.js"
    }
  }
}

Importar mapa com integridade:

new ImportMapDefinition(
    new Dictionary<string, string>
    {
        { "jquery", "https://cdn.example.com/jquery.js" },
    },
    null,
    new Dictionary<string, string>
    {
        { "https://cdn.example.com/jquery.js", "sha384-abc123" },
    });

O código anterior resulta no seguinte mapa de importação:

{
  "imports": {
    "jquery": "https://cdn.example.com/jquery.js"
  },
  "integrity": {
    "https://cdn.example.com/jquery.js": "sha384-abc123"
  }
}

Combine definições de mapa de importação (ImportMapDefinition) com ImportMapDefinition.Combine.

Mapa de importação criado a partir de um ResourceAssetCollection que relaciona os ativos estáticos aos seus URLs únicos correspondentes:

ImportMapDefinition.FromResourceCollection(
    new ResourceAssetCollection(
    [
        new ResourceAsset(
            "jquery.fingerprint.js",
            [
                new ResourceAssetProperty("integrity", "sha384-abc123"),
                new ResourceAssetProperty("label", "jquery.js"),
            ])
    ]));

O código anterior resulta no seguinte mapa de importação:

{
  "imports": {
    "./jquery.js": "./jquery.fingerprint.js"
  },
  "integrity": {
    "jquery.fingerprint.js": "sha384-abc123"
  }
}

Em versões anteriores ao .NET 8, Blazor arquivos estáticos do framework, como o script Blazor, são servidos por meio do Static File Middleware. No .NET 8 ou posterior, os ficheiros estáticos do framework Blazor são mapeados usando o roteamento de endpoints, e o Middleware de Ficheiros Estáticos já não é utilizado.

Resumo dos formatos de ficheiros estáticos <link>href

Esta seção se aplica a todas as versões do .NET e aplicativos Blazor.

As tabelas a seguir resumem os formatos de <link>href de arquivos estáticos por versão .NET.

Para obter o local do conteúdo <head> onde os links de arquivos estáticos são colocados, consulte a estrutura do projeto ASP.NET Core Blazor. Os links de ativos estáticos também podem ser fornecidos usando componentes <HeadContent> em componentes Razor individuais.

.NET 9 ou posterior

Tipo de aplicativo	Valor href	Exemplos
Blazor Web App	@Assets["{PATH}"]	<link rel="stylesheet" href="@Assets["app.css"]" /> <link href="@Assets["_content/ComponentLib/styles.css"]" rel="stylesheet" />
Blazor Server†	@Assets["{PATH}"]	<link href="@Assets["css/site.css"]" rel="stylesheet" /> <link href="@Assets["_content/ComponentLib/styles.css"]" rel="stylesheet" />
Autônomo Blazor WebAssembly	{PATH}	<link rel="stylesheet" href="css/app.css" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />

.NET 8.x

Tipo de aplicativo	Valor href	Exemplos
Blazor Web App	{PATH}	<link rel="stylesheet" href="app.css" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Blazor Server†	{PATH}	<link href="css/site.css" rel="stylesheet" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Autônomo Blazor WebAssembly	{PATH}	<link rel="stylesheet" href="css/app.css" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />

.NET 7.x ou anterior

Tipo de aplicativo	Valor href	Exemplos
Blazor Server†	{PATH}	<link href="css/site.css" rel="stylesheet" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Hospedado Blazor WebAssembly‡	{PATH}	<link href="css/app.css" rel="stylesheet" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Blazor WebAssembly	{PATH}	<link href="css/app.css" rel="stylesheet" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />

†Blazor Server é suportado no .NET 8 ou posterior, mas não é mais um modelo de projeto após o .NET 7.
‡Recomendamos atualizar os aplicativos Hosted Blazor WebAssembly para Blazor Web Apps ao adotar o .NET 8 ou posterior.

Modo de Projeto para Ativos Web Estáticos

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

A configuração necessária de <StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode> no projeto .Client de um Blazor Web App restaura os comportamentos de Blazor WebAssembly ativos estáticos aos padrões originais, para que o projeto se comporte como parte do projeto hospedado. O Blazor WebAssembly SDK (Microsoft.NET.Sdk.BlazorWebAssembly) configura ativos da Web estáticos de uma maneira específica para trabalhar no modo "autônomo" com um servidor simplesmente consumindo as saídas da biblioteca. Isso não é apropriado para um Blazor Web App, onde a parte WebAssembly do aplicativo é uma parte lógica do host e deve 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 de projeto, para que o host possa incluí-lo em seu próprio pacote de estilos.

Não há suporte para alterar o valor (Default) de <StaticWebAssetProjectMode> ou remover a propriedade do projeto .Client.

Arquivos estáticos em ambientes nãoDevelopment

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 no ambiente Development. Para habilitar arquivos estáticos para ambientes diferentes de Development durante o desenvolvimento e teste locais (por exemplo, Staging), chame UseStaticWebAssets no WebApplicationBuilder no arquivo Program.

Advertência

Chame UseStaticWebAssets para o ambiente exato para evitar a ativação da funcionalidade em produção, já que ele fornece arquivos de locais separados no disco , diferentes daqueles 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 ativos Blazor WebAssembly

Esta secção aplica-se a Blazor Web Apps.

Utilize a opção de ponto final WebAssemblyComponentsEndpointOptions.PathPrefix para definir a sequência de caminho que indica o prefixo para os recursos Blazor WebAssembly. O caminho deve corresponder a um projeto de aplicativo Blazor WebAssembly referenciado.

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

No exemplo anterior, o marcador de posição {PATH PREFIX} é o prefixo do caminho e deve começar com uma barra inclinada para a frente (/).

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

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

Caminho base dos ativos estáticos da web

Esta secção aplica-se a aplicações Blazor WebAssembly autónomas.

A publicação da aplicação coloca os recursos estáticos da aplicação, incluindo ficheiros de estrutura Blazor (ativos de pasta_framework), no caminho raiz (/) na saída publicada. A propriedade <StaticWebAssetBasePath> especificada no arquivo de projeto (.csproj) define o caminho base para 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>, uma aplicação independente é publicada em /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/.

No exemplo anterior, o espaço reservado {TFM} corresponde ao Target Framework Moniker (TFM) (por exemplo, net6.0).

Se a propriedade <StaticWebAssetBasePath> numa aplicação Blazor WebAssembly autónoma definir o caminho do ativo estático publicado como app1, o caminho raiz para a aplicação na saída publicada será /app1.

No arquivo de projeto do aplicativo independente Blazor WebAssembly (.csproj):

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

Na saída publicada, o caminho para a aplicação Blazor WebAssembly independente é /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/.

No exemplo anterior, o espaço reservado {TFM} é o Target Framework Moniker (TFM) (por exemplo, net6.0).

Mapeamentos de arquivos e opções de arquivos estáticos

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

Para criar mapeamentos de arquivo adicionais com um FileExtensionContentTypeProvider ou configurar outros StaticFileOptions, use uma das seguintes abordagens. 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 para a API a seguir é Microsoft.AspNetCore.StaticFiles.

• Configure opções por meio de 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 });
  

Sirva arquivos de vários locais

As orientações nesta secção aplicam-se apenas a Blazor Web Apps.

Para servir ficheiros a partir de várias localizações com uma CompositeFileProvider:

• Adicione o namespace para Microsoft.Extensions.FileProviders à parte superior do arquivo de Program do projeto de servidor.
• No arquivo Program do projeto de servidor antes de a chamada para UseStaticFiles:
  • Crie um PhysicalFileProvider com o caminho para os ativos estáticos.
  • Crie um CompositeFileProvider a partir do WebRootFileProvider e do PhysicalFileProvider. Atribua novamente o provedor de arquivos compostos ao WebRootFileProviderda aplicação.

Exemplo:

Crie uma nova pasta no projeto de servidor chamado AdditionalStaticAssets. Coloque uma imagem na pasta.

Adicione a seguinte instrução using à parte superior do arquivo de Program do projeto de servidor:

using Microsoft.Extensions.FileProviders;

No arquivo Program do projeto de servidor antes de a chamada para UseStaticFiles, adicione o seguinte código:

var secondaryProvider = new PhysicalFileProvider(
    Path.Combine(builder.Environment.ContentRootPath, "AdditionalStaticAssets"));
app.Environment.WebRootFileProvider = new CompositeFileProvider(
    app.Environment.WebRootFileProvider, secondaryProvider);

Na marcação do componente Home (Home.razor) da aplicação, referencie a imagem com a tag <img>:

<img src="{IMAGE FILE NAME}" alt="{ALT TEXT}" />

No exemplo anterior:

• O marcador de posição {IMAGE FILE NAME} é o nome do ficheiro de imagem. Não há necessidade de fornecer um segmento de caminho se o arquivo de imagem estiver na raiz da pasta AdditionalStaticAssets.
• O marcador de posição {ALT TEXT} é o texto alternativo da imagem.

Execute o aplicativo.

Recursos adicionais

• Caminho base do aplicativo
• Evite a captura de arquivos em um parâmetro de rota