Partilhar via

ASP.NET Core Blazor arquivos estáticos

Observação

Esta não é a versão mais recente deste artigo. Para a versão atual, consulte a versão .NET 10 deste artigo.

Advertência

Esta versão do ASP.NET Core não é mais suportada. Para obter mais informações, consulte a Política de suporte do .NET e .NET Core. Para a versão atual, consulte a versão .NET 10 deste artigo.

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 convenções de ponto de extremidade de roteamento de ativos estáticos do Map, consulte Arquivos estáticos no ASP.NET Core antes de ler este artigo.

Ativos estáticos da estrutura pré-carregados Blazor

Em Blazor Web Apps, os ativos estáticos da estrutura são pré-carregados automaticamente usando Link cabeçalhos, o que permite que o navegador pré-carregue recursos antes que a página inicial seja buscada e renderizada.

Em aplicações independentes Blazor WebAssembly, os recursos da estrutura são agendados para efetuar o download e armazenamento em cache de alta prioridade no início do processamento da página do navegador index.html quando:

  • A OverrideHtmlAssetPlaceholders propriedade MSBuild no arquivo de projeto do aplicativo (.csproj) é definida como true:

    <PropertyGroup>
  <OverrideHtmlAssetPlaceholders>true</OverrideHtmlAssetPlaceholders>
</PropertyGroup>

  • O seguinte <link> elemento que contém rel="preload" está presente no <head> conteúdo de wwwroot/index.html:

    <link rel="preload" id="webassembly" />

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 Versão .NET Descrição
Definir convenções de ponto final de roteamento para ativos estáticos MapStaticAssets .NET 9 ou posterior Otimiza a entrega de ativos estáticos aos clientes.
Middleware de ficheiros 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 está otimizado para servir os ativos a partir de locais conhecidos no aplicativo durante o processo de compilação e publicação. Se a aplicação servir recursos de outros locais, como disco ou recursos incorporados, UseStaticFiles deve ser usado.

O Map Static Assets (MapStaticAssets) também substitui a chamada de UseBlazorFrameworkFiles em aplicativos que servem arquivos da estrutura Blazor WebAssembly, e não é necessário chamar explicitamente UseBlazorFrameworkFiles em um Blazor Web App 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:

  • Servir arquivos do disco que não fazem parte do processo de compilação ou publicação, por exemplo, arquivos adicionados à pasta do aplicativo durante ou após a implantação.
  • 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 determina a URL com impressão digital 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"]" />

componente ImportMap

Esta seção se aplica a Blazor Web Apps que chamam MapRazorComponents.

O ImportMap componente (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 />

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.

Observação

ImportMapDefinition A criação de instâncias é cara, por isso recomendamos armazená-las em cache ao criar uma instância adicional.

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"
  }
}

Violações da Política de Segurança de Conteúdo (CSP) do mapa de importação

Esta seção se aplica a Blazor Web Apps que chamam MapRazorComponents.

O ImportMap componente é processado como um tag embutido <script>, que viola uma Política de Segurança de Conteúdo (CSP) rígida que define a diretiva default-src ou script-src.

Para obter exemplos de como abordar a violação de política com Subresource Integrity (SRI) ou um nonce criptográfico, consulte Resolvendo violações de CSP com Subresource Integrity (SRI) ou um nonce.

Configure o Middleware de Ficheiros Estáticos para servir ficheiros estáticos aos clientes chamando UseStaticFiles no fluxo de trabalho de processamento de pedidos do aplicativo. Para obter mais informações, consulte ficheiros estáticos no ASP.NET Core.

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.

Identificação de ativos estáticos do lado do cliente em aplicativos independentes Blazor WebAssembly

Em aplicativos autónomos Blazor WebAssembly durante a compilação/publicação, o framework substitui os espaços reservados em index.html por valores computados durante a compilação para gerar impressões digitais de ativos estáticos para o lado do cliente. Uma impressão digital é colocada no nome do blazor.webassembly.js arquivo de script e um mapa de importação é gerado para outros ativos .NET.

A seguinte configuração deve estar presente no ficheiro wwwwoot/index.html de um aplicativo autônomo Blazor WebAssembly para adotar impressão digital.

<head>
    ...
    <script type="importmap"></script>
    ...
</head>

<body>
    ...
    <script src="_framework/blazor.webassembly#[.{fingerprint}].js"></script>
    ...
</body>

</html>

No arquivo de projeto (.csproj), a <OverrideHtmlAssetPlaceholders> propriedade é definida como true:

<PropertyGroup>
  <OverrideHtmlAssetPlaceholders>true</OverrideHtmlAssetPlaceholders>
</PropertyGroup>

Ao resolver importações para interoperabilidade JavaScript, o mapa de importação é usado pelo navegador resolver arquivos com impressão digital.

Qualquer script em index.html com o marcador de impressão digital é assinalado pela estrutura. Por exemplo, um ficheiro de script nomeado scripts.js na pasta wwwroot/js da aplicação é identificado adicionando #[.{fingerprint}] antes da extensão do ficheiro (.js):

<script src="js/scripts#[.{fingerprint}].js"></script>

Marcação de ativos estáticos no lado do cliente em Blazor Web Apps

Para renderização do lado do cliente (CSR) em Blazor Web Apps (modos de renderização Interactive Auto ou Interactive WebAssembly), a impressão digital do lado do servidor de ativos estáticos é habilitada adotando convenções de ponto de extremidade de roteamento de Ativos Estáticos de Mapa (MapStaticAssets), ImportMap componente e a ComponentBase.Assets propriedade (@Assets["..."]). Para obter mais informações, consulte ficheiros estáticos no ASP.NET Core.

Para gerar a impressão digital de módulos de JavaScript adicionais para CSR, use o item <StaticWebAssetFingerprintPattern> no ficheiro de projeto da aplicação (.csproj). No exemplo a seguir, uma impressão digital é adicionada para todos os arquivos fornecidos pelo .mjs desenvolvedor no aplicativo:

<ItemGroup>
  <StaticWebAssetFingerprintPattern Include="JSModule" Pattern="*.mjs" 
    Expression="#[.{fingerprint}]!" />
</ItemGroup>

Ao resolver importações para interoperabilidade JavaScript, o mapa de importação é usado pelo navegador resolver arquivos com impressão digital.

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.

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.

.NET 9 ou posterior

Tipo de aplicativo href valor 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 href valor 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 href valor 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.

Prefixo para ativos Blazor WebAssembly

Esta seçã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 de marcação {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} é o Target Framework Moniker (TFM).

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).

Esta seção se aplica a aplicativos de Blazor WebAssembly autônomos e soluções de Blazor WebAssembly hospedadas.

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 de marcação {PATH} é o caminho.

Sem definir a propriedade <StaticWebAssetBasePath>, o aplicativo cliente de uma solução hospedada ou um aplicativo autônomo é publicado nos seguintes caminhos:

  • No projeto Server de uma solução hospedada Blazor WebAssembly: /BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/
  • Em um aplicativo de Blazor WebAssembly autônomo: /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/

Se a propriedade <StaticWebAssetBasePath> no projeto Client de uma aplicação Blazor WebAssembly hospedada ou numa aplicação Blazor WebAssembly independente 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 Client (.csproj) ou no arquivo de projeto do aplicativo Blazor WebAssembly autônomo (.csproj):

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

Na produção publicada:

  • Caminho para a aplicação cliente no projeto Server de uma solução hospedada Blazor WebAssembly: /BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/app1/
  • Caminho para um aplicativo Blazor WebAssembly autônomo: /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/

A propriedade <StaticWebAssetBasePath> é mais frequentemente usada para controlar os caminhos para recursos estáticos publicados de múltiplas aplicações Blazor WebAssembly numa única implementação alojada. Para obter mais informações, consulte Vários aplicativos ASP.NET Core hospedados Blazor WebAssembly. A propriedade também é eficaz em aplicações de Blazor WebAssembly independentes.

Nos exemplos anteriores, a marca de posição {TFM} é o "Target Framework Moniker (TFM)".

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.

  • Configure as opções através da injeção de dependência (DI) no ficheiro usando Program:

    using Microsoft.AspNetCore.StaticFiles;

...

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

builder.Services.Configure<StaticFileOptions>(options =>
{
    options.ContentTypeProvider = provider;
});

    Essa abordagem configura o mesmo provedor de arquivos usado para servir o script Blazor. Certifique-se de que sua configuração personalizada não interfira com o fornecimento do script Blazor. Por exemplo, não remova o mapeamento para arquivos JavaScript configurando o provedor com provider.Mappings.Remove(".js").

  • Use duas chamadas para UseStaticFiles no arquivo Program:

    • Configure o provedor de arquivos personalizado na primeira chamada com StaticFileOptions.
    • O segundo middleware serve o script Blazor, que usa a configuração padrão de arquivos estáticos fornecida pela estrutura Blazor.
    using Microsoft.AspNetCore.StaticFiles;

...

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

app.UseStaticFiles(new StaticFileOptions { ContentTypeProvider = provider });
app.UseStaticFiles();

  • Você pode evitar interferir na gestão de _framework/blazor.server.js usando MapWhen para executar um middleware personalizado de ficheiros estáticos:

    app.MapWhen(ctx => !ctx.Request.Path
    .StartsWithSegments("/_framework/blazor.server.js"),
        subApp => subApp.UseStaticFiles(new StaticFileOptions() { ... }));

Sirva arquivos de vários locais

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

Para servir ficheiros de várias localizações utilizando um CompositeFileProvider:

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

  • Last updated on