Partilhar via

Arquivos estáticos no ASP.NET Core

Note

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

Warning

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.

Arquivos estáticos, também chamados de ativos estáticos, são arquivos de um aplicativo ASP.NET Core que não são gerados dinamicamente. Em vez disso, eles são servidos diretamente aos clientes mediante solicitação, como arquivos HTML, CSS, imagem e JavaScript.

Para orientação sobre Blazor arquivos estáticos, que adiciona ou substitui a orientação neste artigo, consulte arquivos estáticos do ASP.NET Core Blazor.

Para habilitar a manipulação de arquivos estáticos no ASP.NET Core, chame MapStaticAssets.

Por padrão, os arquivos estáticos são armazenados no diretório raiz da web do projeto. O diretório padrão é {CONTENT ROOT}/wwwroot, onde o espaço reservado {CONTENT ROOT} é a raiz do Conteúdo do aplicativo. Somente os arquivos na pasta wwwroot serão endereçáveis, então você não precisa se preocupar com o resto do seu código.

Somente arquivos com extensões de arquivo específicas mapeadas para tipos de mídia suportados são tratados como ativos da Web estáticos.

Os ativos da Web estáticos são descobertos em tempo de compilação e otimizados usando impressões digitais baseadas em conteúdo para evitar a reutilização de arquivos antigos. Os ativos também são compactados para reduzir o tempo de entrega dos ativos.

Durante o tempo de execução, os ativos web estáticos descobertos são expostos como endereços finais com cabeçalhos HTTP aplicados, tais como cabeçalhos de cache e de tipo de conteúdo. Um ativo é servido uma vez até que o arquivo seja alterado ou o navegador limpe seu cache. Os cabeçalhos ETag, Last-Modified e Content-Type estão definidos. O navegador é impedido de usar ativos obsoletos depois que um aplicativo é atualizado.

A entrega de ativos estáticos é baseada no roteamento de endpoints, portanto, funciona com outros recursos que reconhecem endpoints, como autorização. Ele foi projetado para funcionar com todas as estruturas de interface do usuário, incluindo Blazor, Razor Pages e MVC.

O Map Static Assets oferece os seguintes benefícios:

  • Compactação em tempo de compilação para todos os ativos no aplicativo, incluindo JavaScript (JS) e folhas de estilo, mas excluindo ativos de imagem e fonte que já estão compactados. A compressão Gzip (Content-Encoding: gz) é utilizada durante o desenvolvimento. A compressão Gzip e Brotli (Content-Encoding: br) são usadas durante a publicação.
  • Impressão digital de todos os ativos em tempo de compilação com uma cadeia de caracteres, codificada em Base64, do hash SHA-256 do conteúdo de cada arquivo. Isso impede a reutilização de uma versão antiga de um arquivo, mesmo que o arquivo antigo esteja armazenado em cache. Os ativos com impressão digital são armazenados em cache usando a diretiva immutable, o que faz com que o navegador nunca mais solicite o ativo até que ele seja alterado. Para navegadores que não suportam a diretiva immutable, uma diretiva max-age é adicionada.
    • Mesmo que um ativo não tenha impressões digitais, ETags baseadas em conteúdo são geradas para cada ativo estático usando o hash de impressão digital do arquivo como o valor ETag. Isso garante que o navegador só baixe um arquivo se seu conteúdo for alterado (ou se o arquivo estiver sendo baixado pela primeira vez).
    • Internamente, a estrutura mapeia ativos físicos para suas impressões digitais, o que permite que o aplicativo:
      • Encontre ativos gerados automaticamente, como CSS com escopo de componente Razor para o recurso de isolamento CSS de Blazor e ativos JS descritos em mapas de importação JS.
      • Gere etiquetas de ligação no conteúdo <head> da página para pré-carregar recursos.

O Map Static Assets não fornece recursos para minificação ou outras transformações de arquivos. A minificação é geralmente gerida por código personalizado ou ferramentas de terceiros.

Para habilitar a manipulação de arquivos estáticos no ASP.NET Core, chame UseStaticFiles.

Por padrão, os arquivos estáticos são armazenados no diretório raiz da web do projeto. O diretório padrão é {CONTENT ROOT}/wwwroot, onde o espaço reservado {CONTENT ROOT} é a raiz do Conteúdo do aplicativo. Somente os arquivos na pasta wwwroot serão endereçáveis, então você não precisa se preocupar com o resto do seu código.

No tempo de execução, os ativos da Web estáticos são retornados pelo Middleware de Arquivo Estático quando solicitado com modificação de ativos e cabeçalhos de tipo de conteúdo aplicados. Os cabeçalhos ETag, Last-Modified e Content-Type estão definidos.

O middleware estático de ficheiros permite o serviço de ficheiros estáticos e é usado por uma aplicação quando UseStaticFiles é chamado na cadeia de processamento de pedidos da aplicação. Os arquivos são servidos a partir do caminho especificado em IWebHostEnvironment.WebRootPath ou WebRootFileProvider, que assume como padrão a pasta raiz da Web, normalmente wwwroot.

Você também pode servir ativos da Web estáticos a partir de projetos e pacotes referenciados.

Alterar o diretório raiz da Web

Use o UseWebRoot método se pretender alterar o diretório raiz da web. Para obter mais informações, consulte ASP.NET Visão geral dos fundamentos básicos.

Impedir a publicação de arquivos em wwwroot com o item de <Content> projeto no arquivo de projeto. O exemplo a seguir impede a publicação de conteúdo em wwwroot/local e nos seus subdiretórios.

<ItemGroup>
  <Content Update="wwwroot\local\**\*.*" CopyToPublishDirectory="Never" />
</ItemGroup>

O método CreateBuilder define a raiz do conteúdo para o diretório atual:

var builder = WebApplication.CreateBuilder(args);

O método CreateDefaultBuilder define a raiz do conteúdo para o diretório atual:

Host.CreateDefaultBuilder(args)

No pipeline de processamento de solicitações após a chamada para UseHttpsRedirection, chame MapStaticAssets dentro do pipeline de processamento de solicitações do aplicativo para habilitar a disponibilização de arquivos estáticos da raiz da Web do aplicativo:

app.MapStaticAssets();

No pipeline de processamento de solicitações após a chamada para UseHttpsRedirection, chame UseStaticFiles dentro do pipeline de processamento de solicitações do aplicativo para habilitar a disponibilização de arquivos estáticos da raiz da Web do aplicativo:

app.UseStaticFiles();

Os arquivos estáticos são acessíveis através de um caminho relativo à raiz webdo .

Para aceder a uma imagem em wwwroot/images/favicon.png:

  • Formato URL: https://{HOST}/images/{FILE NAME}
    • O {HOST} marcador de posição é o host.
    • O {FILE NAME} marcador de posição é o nome do ficheiro.
  • Exemplos
    • URL absoluta: https://localhost:5001/images/favicon.png
    • URL relativo da raiz: images/favicon.png

Em um Blazor aplicativo, images/favicon.png carrega a imagem do ícone (favicon.png) da wwwroot/images pasta do aplicativo:

<link rel="icon" type="image/png" href="images/favicon.png" />

Em Razor aplicativos Pages e MVC, o caractere ~ til aponta para a raiz da Web. No exemplo a seguir, ~/images/favicon.png carrega a imagem do ícone (favicon.png) da wwwroot/images pasta do aplicativo:

<link rel="icon" type="image/png" href="~/images/favicon.png" />

Desviar o fluxo no pipeline de middleware

Para evitar a execução de todo o pipeline de middleware depois que um ativo estático é correspondido, que é o comportamento do UseStaticFiles, chame ShortCircuit em MapStaticAssets. Ao chamar ShortCircuit, o endpoint é executado imediatamente e a resposta é retornada, impedindo que outros middleware sejam executados para pedidos de ativos estáticos.

app.MapStaticAssets().ShortCircuit();

Controle o cache de arquivos estáticos durante o desenvolvimento

Quando o ambiente Development é executado, por exemplo, durante os testes de desenvolvimento com o Visual Studio Hot Reload, o framework substitui os cabeçalhos de cache para impedir que os navegadores memorizem ficheiros estáticos em cache. Isso ajuda a garantir que a versão mais recente dos arquivos seja usada quando os arquivos forem alterados, evitando problemas com conteúdo obsoleto. Na produção, os cabeçalhos de cache corretos são definidos, permitindo que os navegadores armazenem ativos estáticos em cache conforme o esperado.

Para desativar este comportamento, defina EnableStaticAssetsDevelopmentCaching para true no Development ficheiro de definições da aplicação do ambiente (appsettings.Development.json).

Arquivos estáticos em ambientes não-Development

Ao executar uma aplicação localmente, os ativos web estáticos só estão ativados no Development ambiente. Para ativar ficheiros estáticos para ambientes diferentes de Development durante o desenvolvimento e testes locais (por exemplo, no ambiente Staging), chame UseStaticWebAssets no ficheiro WebApplicationBuilder.

Warning

Ligue para UseStaticWebAssets o ambiente exato para evitar a ativação do recurso em produção, pois ele serve arquivos a partir de locais distintos no disco que não pertencem ao projeto. O exemplo nesta secção verifica o ambiente Staging com IsStaging.

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

Sirva arquivos fora do diretório raiz da Web via IWebHostEnvironment.WebRootPath

Quando IWebHostEnvironment.WebRootPath é definido como uma pasta diferente de wwwroot, os seguintes comportamentos padrão são exibidos:

  • No Development ambiente, os ativos estáticos são servidos a partir de wwwroot se ativos com o mesmo nome estiverem em ambos wwwroot e numa pasta diferente atribuída a WebRootPath.
  • Em qualquer ambiente que não Development, ativos estáticos duplicados são servidos na WebRootPath diretório.

Considere um aplicativo Web criado a partir do modelo da Web vazio:

  • Contendo um ficheiro Index.html no wwwroot e wwwroot-custom.
  • O Program arquivo é atualizado para definir WebRootPath = "wwwroot-custom".
var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    WebRootPath = "wwwroot-custom"
});

Por padrão, para solicitações de /:

  • No ambiente Development, wwwroot/Index.html é retornado.
  • Em qualquer ambiente que não seja Development, wwwroot-custom/Index.html é devolvido.

Para garantir que os ativos de wwwroot-custom sejam sempre devolvidos, use uma das seguintes abordagens:

  • Exclua ativos nomeados duplicados no wwwroot.

  • Defina ASPNETCORE_ENVIRONMENT em Properties/launchSettings.json para qualquer valor diferente de Development.

  • Desative ativos da Web estáticos definindo <StaticWebAssetsEnabled> como false no arquivo de projeto do aplicativo. ATENÇÃO: A desativação de ativos estáticos da Web desativa as bibliotecas de Razor classes.

  • Adicione o seguinte XML ao arquivo de projeto:

    <ItemGroup>
  <Content Remove="wwwroot\**" />
</ItemGroup>

O código a seguir atualiza WebRootPath para um valor não-dev (Staging), garantindo que o conteúdo duplicado seja retornado de wwwroot-custom em vez de wwwroot.

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    EnvironmentName = Environments.Staging,
    WebRootPath = "wwwroot-custom"
});

Middleware de ficheiros estáticos

O Middleware de Arquivo Estático permite o serviço de arquivos estáticos em cenários específicos de arquivos estáticos, geralmente além das convenções de roteamento de ponto de extremidade de Ativos Estáticos de Mapa (MapStaticAssets).

O Middleware de Arquivo Estático é incluído no processamento de solicitações quando UseStaticFiles é chamado no pipeline de processamento de solicitações do aplicativo, normalmente depois que as convenções de mapeamento de ativos estáticos (MapStaticAssets) são adicionadas.

As convenções de endpoint de Ativos Estáticos de Mapa são usadas em aplicativos que visam o .NET 9 ou posterior. O middleware de arquivo estático deve ser usado em aplicativos destinados a versões do .NET anteriores ao .NET 9.

O Middleware de Arquivo Estático serve arquivos estáticos, mas não fornece o mesmo nível de otimização que as convenções de endpoint do Map Static Assets. Os recursos de compactação em tempo de compilação e impressão digital das convenções de ponto final da Map Static Assets não estão disponíveis quando se depende apenas do Static File Middleware.

As convenções de terminal são otimizadas para servir ativos que a aplicação conhece durante a execução. Se o aplicativo servir ativos de outros locais, como disco ou recursos incorporados, o Middleware de Arquivo Estático deverá ser usado.

Os seguintes recursos abordados neste artigo são suportados com o Middleware de Ficheiros Estáticos, mas não com as convenções de endpoint para Map Static Assets.

Sirva arquivos fora do diretório raiz da Web via UseStaticFiles

Considere a seguinte hierarquia de diretórios com arquivos estáticos que residem fora da raiz da Web do aplicativo em uma pasta chamada ExtraStaticFiles:

  • wwwroot
    • css
    • images
    • js
  • ExtraStaticFiles
    • images
      • red-rose.jpg

Uma solicitação pode acessar red-rose.jpg configurando uma nova instância de um Static File Middleware:

Namespaces para a API seguinte:

using Microsoft.Extensions.FileProviders;

No pipeline de processamento de solicitação após a chamada existente para MapStaticAssets (.NET 9 ou posterior) ou UseStaticFiles (.NET 8 ou anterior):

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(builder.Environment.ContentRootPath, "ExtraStaticFiles")),
    RequestPath = "/static-files"
});

No código anterior, a hierarquia de ExtraStaticFiles diretórios é exposta publicamente por meio do static-files segmento URL. Uma solicitação para https://{HOST}/StaticFiles/images/red-rose.jpg, onde o espaço reservado {HOST} é o host, disponibiliza o arquivo red-rose.jpg.

As marcações seguintes referem-se a ExtraStaticFiles/images/red-rose.jpg:

<img src="static-files/images/red-rose.jpg" alt="A red rose" />

No exemplo anterior, a notação tilde-slash é suportada em Razor páginas e visões MVC (src="~/StaticFiles/images/red-rose.jpg"), não para Razor componentes em Blazor aplicações.

Sirva arquivos de vários locais

As orientações nesta secção aplicam-se a Razor Páginas e aplicações MVC. Para obter orientações que se aplicam a Blazor Web Apps, consulte ASP.NET Core Blazor arquivos estáticos.

Considere a seguinte marcação que exibe o logotipo de uma empresa:

<img src="~/logo.png" asp-append-version="true" alt="Company logo">

O desenvolvedor pretende usar o Image Tag Helper para anexar uma versão e servir o arquivo de um local personalizado, uma pasta chamada ExtraStaticFiles.

O exemplo a seguir chama MapStaticAssets para servir arquivos de wwwroot e UseStaticFiles para servir arquivos de ExtraStaticFiles:

No pipeline de processamento de solicitação após a chamada existente para MapStaticAssets (.NET 9 ou posterior) ou UseStaticFiles (.NET 8 ou anterior):

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(builder.Environment.ContentRootPath, "ExtraStaticFiles"))
});

O exemplo a seguir chama UseStaticFiles duas vezes para servir arquivos de ambos wwwroot e ExtraStaticFiles.

No pipeline de processamento da solicitação após a chamada atual para UseStaticFiles:

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(builder.Environment.ContentRootPath, "ExtraStaticFiles"))
});

Usando o código anterior, o ExtraStaticFiles/logo.png arquivo é exibido. No entanto, o Image Tag Helper (AppendVersion) não é aplicado porque o Tag Helper depende de WebRootFileProvider, que não foi atualizado para incluir a pasta ExtraStaticFiles.

O código a seguir atualiza o WebRootFileProvider para incluir a pasta ExtraStaticFiles usando um CompositeFileProvider. Isso permite que o Image Tag Helper aplique uma versão às imagens na ExtraStaticFiles pasta.

Namespace para a seguinte API:

using Microsoft.Extensions.FileProviders;

No pipeline de processamento de solicitação antes da chamada existente para MapStaticAssets (.NET 9 ou posterior) ou UseStaticFiles (.NET 8 ou anterior):

var webRootProvider = new PhysicalFileProvider(builder.Environment.WebRootPath);
var newPathProvider = new PhysicalFileProvider(
    Path.Combine(builder.Environment.ContentRootPath, "ExtraStaticFiles"));

var compositeProvider = new CompositeFileProvider(webRootProvider, newPathProvider);

app.Environment.WebRootFileProvider = compositeProvider;

UseStaticFiles e UseFileServer são configurados por padrão para o provedor de arquivos que aponta para wwwroot. Instâncias adicionais de UseStaticFiles e UseFileServer podem ser fornecidas com outros provedores de arquivos para servir arquivos de outros locais. Para obter mais informações, consulte UseStaticFiles ainda necessário com UseFileServer para wwwroot (dotnet/AspNetCore.Docs #15578).

Definir cabeçalhos de resposta HTTP

Use StaticFileOptions para definir cabeçalhos de resposta HTTP. Além de configurar o Static File Middleware para servir arquivos estáticos, o código a seguir define o Cache-Control cabeçalho para 604.800 segundos (uma semana).

Namespaces para a API seguinte:

using Microsoft.AspNetCore.Http;

No pipeline de processamento de solicitação após a chamada existente para MapStaticAssets (.NET 9 ou posterior) ou UseStaticFiles (.NET 8 ou anterior):

app.UseStaticFiles(new StaticFileOptions
{
    OnPrepareResponse = ctx =>
    {
        ctx.Context.Response.Headers.Append(
            "Cache-Control", "public, max-age=604800");
    }
});

Grande coleção de ativos

Ao lidar com grandes coleções, aproximadamente 1.000 ou mais ativos, recomendamos o uso de um bundler para reduzir o número final de ativos servidos pela aplicação ou combinar MapStaticAssets com UseStaticFiles.

MapStaticAssets Carrega ansiosamente os metadados pré-computados capturados durante o processo de compilação para os recursos, a fim de suportar compactação, cache e impressão digital. Esses recursos têm o custo de um maior uso de memória pelo aplicativo. Para ativos que são acessados com frequência, geralmente vale a pena os custos. Para ativos que não são acessados com frequência, o trade-off pode não valer a pena os custos.

Se não utilizar a agrupação, recomendamos que combine MapStaticAssets com UseStaticFiles. O exemplo a seguir demonstra a abordagem.

No arquivo de projeto (.csproj), a propriedade StaticWebAssetEndpointExclusionPattern MSBuild é usada para filtrar endpoints do manifesto final para MapStaticAssets. Os arquivos excluídos são servidos por UseStaticFiles e não se beneficiam da compactação, armazenamento em cache e impressão digital.

Ao definir o valor de StaticWebAssetEndpointExclusionPattern, mantenha $(StaticWebAssetEndpointExclusionPattern) para preservar o padrão de exclusão da estrutura. Adicione padrões adicionais em uma lista separada por ponto-e-vírgula.

No exemplo a seguir, o padrão de exclusão remove os arquivos estáticos na pasta lib/icons, que representa um lote hipotético de ícones.

<StaticWebAssetEndpointExclusionPattern>
  $(StaticWebAssetEndpointExclusionPattern);lib/icons/**
</StaticWebAssetEndpointExclusionPattern>

Após o processamento do Middleware de redirecionamento HTTPS (app.UseHttpsRedirection();) no arquivo Program:

app.UseStaticFiles();

app.UseAuthorization();

app.MapStaticAssets();

Autorização de arquivo estático

Quando um aplicativo adota uma política de autorização de fallback, a autorização é necessária para todas as solicitações que não especificam explicitamente uma política de autorização, incluindo solicitações de arquivos estáticos depois que o Middleware de Autorização processa solicitações. Permita acesso anônimo a arquivos estáticos aplicando AllowAnonymousAttribute ao construtor de pontos finais para arquivos estáticos:

app.MapStaticAssets().Add(endpointBuilder => 
    endpointBuilder.Metadata.Add(new AllowAnonymousAttribute()));

Quando um aplicativo adota uma política de autorização de fallback, a autorização é necessária para todas as solicitações que não especificam explicitamente uma política de autorização, incluindo solicitações de arquivos estáticos depois que o Middleware de Autorização processa solicitações. Os modelos ASP.NET Core permitem o acesso anônimo a arquivos estáticos chamando UseStaticFiles antes de chamar UseAuthorization. A maioria das aplicações segue este padrão. Quando o middleware de ficheiro estático é chamado antes do middleware de autenticação:

  • Nenhuma verificação de autorização é executada nos arquivos estáticos.
  • Os arquivos estáticos servidos pelo Static File Middleware, como a raiz do site (normalmente, wwwroot), são acessíveis publicamente.

Para servir arquivos estáticos com base na autorização:

Namespaces para a API seguinte:

using Microsoft.AspNetCore.Authorization;
using Microsoft.Extensions.FileProviders;

Registo do serviço:

builder.Services.AddAuthorization(options =>
{
    options.FallbackPolicy = new AuthorizationPolicyBuilder()
        .RequireAuthenticatedUser()
        .Build();
});

No pipeline de processamento de solicitação após a chamada para UseAuthorization:

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(builder.Environment.ContentRootPath, "SecureStaticFiles")),
    RequestPath = "/static-files"
});

Namespaces para a API seguinte:

using Microsoft.AspNetCore.Authorization;
using Microsoft.Extensions.FileProviders;

Em Startup.ConfigureServices:

services.AddAuthorization(options =>
{
    options.FallbackPolicy = new AuthorizationPolicyBuilder()
        .RequireAuthenticatedUser()
        .Build();
});

Após a chamada para Startup.Configure em UseAuthorization:

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(env.ContentRootPath, "SecureStaticFiles")),
    RequestPath = "/static-files"
});

No código anterior, a política de autorização de fallback requer usuários autenticados. Pontos de extremidade, como controladores e Razor Páginas, que especificam seus próprios requisitos de autorização não usam a política de autorização de fallback. Por exemplo, Razor Páginas, controladores ou métodos de ação com [AllowAnonymous] ou [Authorize(PolicyName="MyPolicy")] usam o atributo de autorização aplicado em vez da política de autorização de substituição.

RequireAuthenticatedUser adiciona DenyAnonymousAuthorizationRequirement à instância atual, o que impõe que o usuário atual seja autenticado.

Os ativos estáticos armazenados na raiz da web do aplicativo são acessíveis publicamente porque o Middleware de Ficheiros Estáticos padrão (UseStaticFiles) é chamado antes de UseAuthorization. Os ativos estáticos na SecureStaticFiles pasta exigem autenticação.

Uma abordagem alternativa para servir ficheiros com base na autorização é:

  • Armazene os arquivos fora da raiz do site e de qualquer diretório acessível ao Static File Middleware.
  • Servir os arquivos através de um método de ação ao qual a autorização é aplicada e retornar um objeto FileResult.

De uma Razor página (Pages/BannerImage.cshtml.cs):

public class BannerImageModel : PageModel
{
    private readonly IWebHostEnvironment _env;

    public BannerImageModel(IWebHostEnvironment env) => _env = env;

    public PhysicalFileResult OnGet()
    {
        var filePath = Path.Combine(
            _env.ContentRootPath, "SecureStaticFiles", "images", "red-rose.jpg");

        return PhysicalFile(filePath, "image/jpeg");
    }
}

De um controlador (Controllers/HomeController.cs):

[Authorize]
public IActionResult BannerImage()
{
    var filePath = Path.Combine(
        _env.ContentRootPath, "SecureStaticFiles", "images", "red-rose.jpg");

    return PhysicalFile(filePath, "image/jpeg");
}

A abordagem anterior requer uma página ou endpoint por ficheiro.

O exemplo seguinte do ponto de extremidade da rota retorna arquivos para usuários autenticados.

No ficheiro Program:

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("AuthenticatedUsers", b => b.RequireAuthenticatedUser());
});

...

app.MapGet("/files/{fileName}", IResult (string fileName) => 
{
    var filePath = GetOrCreateFilePath(fileName);

    if (File.Exists(filePath))
    {
        return TypedResults.PhysicalFile(filePath, fileName);
    }

    return TypedResults.NotFound("No file found with the supplied file name");
})
.WithName("GetFileByName")
.RequireAuthorization("AuthenticatedUsers");

O exemplo de endpoint de rota a seguir faz upload de arquivos para utilizadores autenticados com a função de administrador ("admin").

No ficheiro Program:

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("AdminsOnly", b => b.RequireRole("admin"));
});

...

// IFormFile uses memory buffer for uploading. For handling large 
// files, use streaming instead. See the *File uploads* article
// in the ASP.NET Core documentation:
// https://learn.microsoft.com/aspnet/core/mvc/models/file-uploads
app.MapPost("/files", async (IFormFile file, LinkGenerator linker, 
    HttpContext context) =>
{
    // Don't rely on the value in 'file.FileName', as it's only metadata that can 
    // be manipulated by the end-user. Consider the 'Utilities.IsFileValid' method 
    // that takes an 'IFormFile' and validates its signature within the 
    // 'AllowedFileSignatures'.

    var fileSaveName = Guid.NewGuid().ToString("N") + 
        Path.GetExtension(file.FileName);
    await SaveFileWithCustomFileName(file, fileSaveName);

    context.Response.Headers.Append("Location", linker.GetPathByName(context, 
        "GetFileByName", new { fileName = fileSaveName}));

    return TypedResults.Ok("File Uploaded Successfully!");
})
.RequireAuthorization("AdminsOnly");

Em Startup.ConfigureServices:

services.AddAuthorization(options =>
{
    options.AddPolicy("AuthenticatedUsers", b => b.RequireAuthenticatedUser());
});

Em Startup.Configure:

app.MapGet("/files/{fileName}", IResult (string fileName) => 
{
    var filePath = GetOrCreateFilePath(fileName);

    if (File.Exists(filePath))
    {
        return TypedResults.PhysicalFile(filePath, fileName);
    }

    return TypedResults.NotFound("No file found with the supplied file name");
})
.WithName("GetFileByName")
.RequireAuthorization("AuthenticatedUsers");

O código a seguir carrega arquivos para usuários autenticados na função de administrador ("admin").

Em Startup.ConfigureServices:

services.AddAuthorization(options =>
{
    options.AddPolicy("AdminsOnly", b => b.RequireRole("admin"));
});

Em Startup.Configure:

// IFormFile uses memory buffer for uploading. For handling large 
// files, use streaming instead. See the *File uploads* article
// in the ASP.NET Core documentation:
// https://learn.microsoft.com/aspnet/core/mvc/models/file-uploads
app.MapPost("/files", async (IFormFile file, LinkGenerator linker, 
    HttpContext context) =>
{
    // Don't rely on the value in 'file.FileName', as it's only metadata that can 
    // be manipulated by the end-user. Consider the 'Utilities.IsFileValid' method 
    // that takes an 'IFormFile' and validates its signature within the 
    // 'AllowedFileSignatures'.

    var fileSaveName = Guid.NewGuid().ToString("N") + 
        Path.GetExtension(file.FileName);
    await SaveFileWithCustomFileName(file, fileSaveName);

    context.Response.Headers.Append("Location", linker.GetPathByName(context, 
        "GetFileByName", new { fileName = fileSaveName}));

    return TypedResults.Ok("File Uploaded Successfully!");
})
.RequireAuthorization("AdminsOnly");

Navegação no diretório

A navegação no diretório permite a listagem de diretórios dentro de diretórios especificados.

A navegação no diretório é desativada por padrão por motivos de segurança. Para obter mais informações, consulte Considerações de segurança para arquivos estáticos.

Habilite a navegação no diretório com a seguinte API:

No exemplo a seguir:

  • Uma images pasta na raiz do aplicativo contém imagens para navegação no diretório.
  • O caminho da solicitação para navegar pelas imagens é /DirectoryImages.
  • Chamar UseStaticFiles e definir o FileProvider de StaticFileOptions permite exibir links para os arquivos individuais no navegador.

Namespaces para a API seguinte:

using Microsoft.AspNetCore.StaticFiles;
using Microsoft.Extensions.FileProviders;

Registo do serviço:

builder.Services.AddDirectoryBrowser();

No pipeline de processamento de solicitação após a chamada existente para MapStaticAssets (.NET 9 ou posterior) ou UseStaticFiles (.NET 8 ou anterior):

var fileProvider = new PhysicalFileProvider(
    Path.Combine(builder.Environment.WebRootPath, "images"));
var requestPath = "/DirectoryImages";

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = fileProvider,
    RequestPath = requestPath
});

app.UseDirectoryBrowser(new DirectoryBrowserOptions
{
    FileProvider = fileProvider,
    RequestPath = requestPath
});

Namespaces para a API seguinte:

using Microsoft.Extensions.FileProviders;
using System.IO;

Em Startup.ConfigureServices:

services.AddDirectoryBrowser();

Dentro de Startup.Configure, após a chamada existente para UseStaticFiles:

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(env.WebRootPath, "images")),
    RequestPath = "/DirectoryImages"
});

app.UseDirectoryBrowser(new DirectoryBrowserOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(env.WebRootPath, "images")),
    RequestPath = "/DirectoryImages"
});

O código anterior permite a navegação no diretório da pasta wwwroot/images usando a URL https://{HOST}/DirectoryImages com links para cada ficheiro e pasta, onde o espaço reservado {HOST} é o host.

AddDirectoryBrowser adiciona serviços exigidos pelo Middleware de Navegação no Diretório, incluindo HtmlEncoder. Esses serviços podem ser adicionados por outras chamadas, como AddRazorPages, mas recomendamos ligar AddDirectoryBrowser para garantir que os serviços sejam adicionados.

Servir documentos predefinidos

Definir uma página padrão fornece aos visitantes um ponto de partida em um site. Para servir um arquivo padrão sem exigir que a URL da wwwroot solicitação inclua o nome do arquivo, chame o UseDefaultFiles método.

UseDefaultFiles é um reescritor de URL que não serve o arquivo. No pipeline de processamento de solicitação antes da chamada existente para MapStaticAssets (.NET 9 ou posterior) ou UseStaticFiles (.NET 8 ou anterior):

app.UseDefaultFiles();

Com UseDefaultFiles, as solicitações para uma pasta em wwwroot procuram:

  • default.htm
  • default.html
  • index.htm
  • index.html

O primeiro arquivo encontrado na lista é servido como se a solicitação incluísse o nome do arquivo. O URL do navegador continua a refletir o URI solicitado.

O código a seguir altera o nome de arquivo padrão para default-document.html:

var options = new DefaultFilesOptions();
options.DefaultFileNames.Clear();
options.DefaultFileNames.Add("default-document.html");
app.UseDefaultFiles(options);

Combine arquivos estáticos, documentos padrão e navegação em diretórios

UseFileServer combina a funcionalidade de UseStaticFiles, UseDefaultFilese, opcionalmente, UseDirectoryBrowser.

No pipeline de processamento de solicitação, após a chamada existente para MapStaticAssets (.NET 9 ou posterior) ou UseStaticFiles (.NET 8 ou anterior), chame UseFileServer para ativar a disponibilização de ficheiros estáticos e o ficheiro padrão.

app.UseFileServer();

A navegação no diretório não está habilitada para o exemplo anterior.

O código a seguir permite o serviço de arquivos estáticos, o arquivo padrão e a navegação no diretório.

Registo do serviço:

builder.Services.AddDirectoryBrowser();

No pipeline de processamento da solicitação após a chamada atual para UseStaticFiles:

app.UseFileServer(enableDirectoryBrowsing: true);

Em Startup.ConfigureServices:

services.AddDirectoryBrowser();

Dentro de Startup.Configure, após a chamada existente para UseStaticFiles:

app.UseFileServer(enableDirectoryBrowsing: true);

Para o endereço do host (/), UseFileServer retorna o documento HTML padrão antes da Página (Razor) padrão ou da exibição MVC padrão (Pages/Index.cshtmlHome/Index.cshtml).

Considere a seguinte hierarquia de diretórios:

  • wwwroot
    • css
    • images
    • js
  • ExtraStaticFiles
    • images
      • logo.png
    • default.html

O código a seguir permite o serviço de arquivos estáticos, o arquivo padrão e a navegação no diretório do ExtraStaticFiles.

Namespaces para a API seguinte:

using Microsoft.Extensions.FileProviders;

Registo do serviço:

builder.Services.AddDirectoryBrowser();

No pipeline de processamento da solicitação após a chamada atual para UseStaticFiles:

app.UseFileServer(new FileServerOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(builder.Environment.ContentRootPath, "ExtraStaticFiles")),
    RequestPath = "/static-files",
    EnableDirectoryBrowsing = true
});

Namespaces para a API seguinte:

using Microsoft.Extensions.FileProviders;
using System.IO;

Em Startup.ConfigureServices:

services.AddDirectoryBrowser();

Dentro de Startup.Configure, após a chamada existente para UseStaticFiles:

app.UseFileServer(new FileServerOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(env.ContentRootPath, "ExtraStaticFiles")),
    RequestPath = "/static-files",
    EnableDirectoryBrowsing = true
});

AddDirectoryBrowser deve ser chamado quando o valor EnableDirectoryBrowsing da propriedade é true.

Usando a hierarquia de arquivos e o código anteriores, as URLs são resolvidas conforme mostrado na tabela a seguir (o marcador de posição {HOST} é o host).

URI Arquivo de resposta
https://{HOST}/static-files/images/logo.png ExtraStaticFiles/images/logo.png
https://{HOST}/static-files ExtraStaticFiles/default.html

Se não existir nenhum arquivo com nome padrão no ExtraStaticFiles diretório, https://{HOST}/static-files retornará a listagem de diretórios com links clicáveis, onde o espaço reservado {HOST} é o host.

UseDefaultFiles e UseDirectoryBrowser realizam um redirecionamento no lado do cliente do URI de destino sem um / para o URI de destino com um /. Por exemplo, de https://{HOST}/static-files (sem trailing /) para https://{HOST}/static-files/ (inclui um trailing /). As URLs relativas dentro do diretório ExtraStaticFiles são inválidas sem uma barra final (/), a menos que a opção RedirectToAppendTrailingSlash de DefaultFilesOptions seja usada.

Mapear extensões de arquivo para tipos MIME

Note

Para obter orientações que se aplicam a Blazor aplicativos, consulte ASP.NET arquivos estáticos principaisBlazor.

Use FileExtensionContentTypeProvider.Mappings para adicionar ou modificar a extensão de arquivo para mapeamentos de tipo de conteúdo MIME. No exemplo a seguir, várias extensões de arquivo são mapeadas para tipos MIME conhecidos. A .rtf extensão é substituída e .mp4 removida:

using Microsoft.AspNetCore.StaticFiles;
using Microsoft.Extensions.FileProviders;

...

// Set up custom content types - associating file extension to MIME type
var provider = new FileExtensionContentTypeProvider();
// Add new mappings
provider.Mappings[".myapp"] = "application/x-msdownload";
provider.Mappings[".htm3"] = "text/html";
provider.Mappings[".image"] = "image/png";
// Replace an existing mapping
provider.Mappings[".rtf"] = "application/x-msdownload";
// Remove MP4 videos
provider.Mappings.Remove(".mp4");

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

Quando você tiver várias opções de arquivo estático para configurar, você pode alternativamente definir o provedor usando StaticFileOptions:

var provider = new FileExtensionContentTypeProvider();

...

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

app.UseStaticFiles();

Em Startup.Configure:

using Microsoft.AspNetCore.StaticFiles;
using Microsoft.Extensions.FileProviders;
using System.IO;

...

// Set up custom content types - associating file extension to MIME type
var provider = new FileExtensionContentTypeProvider();
// Add new mappings
provider.Mappings[".myapp"] = "application/x-msdownload";
provider.Mappings[".htm3"] = "text/html";
provider.Mappings[".image"] = "image/png";
// Replace an existing mapping
provider.Mappings[".rtf"] = "application/x-msdownload";
// Remove MP4 videos
provider.Mappings.Remove(".mp4");

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(env.WebRootPath, "images")),
    RequestPath = "/images",
    ContentTypeProvider = provider
});

app.UseDirectoryBrowser(new DirectoryBrowserOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(env.WebRootPath, "images")),
    RequestPath = "/images"
});

Para obter mais informações, consulte Tipos de conteúdo MIME.

Tipos de conteúdo não padrão

O Static File Middleware compreende quase 400 tipos de conteúdo de arquivo conhecidos. Se o usuário solicitar um arquivo com um tipo de arquivo desconhecido, o Middleware de Arquivo Estático passará a solicitação para o próximo middleware no pipeline. Se nenhum middleware lidar com a solicitação, uma resposta 404 Not Found será retornada. Se a navegação no diretório estiver habilitada, um link para o arquivo será exibido em uma listagem de diretório.

O código a seguir permite servir tipos de conteúdo desconhecidos e renderiza o arquivo desconhecido como uma imagem:

app.UseStaticFiles(new StaticFileOptions
{
    ServeUnknownFileTypes = true,
    DefaultContentType = "image/png"
});

Com o código anterior, uma solicitação para um arquivo com um tipo de conteúdo desconhecido é retornada como uma imagem.

Warning

Ativar ServeUnknownFileTypes é um risco de segurança. Ele está desativado por padrão, e seu uso é desencorajado. Mapear extensões de arquivo para tipos MIME fornece uma alternativa mais segura para servir arquivos com extensões não padrão.

Forneça um manifesto de ficheiros estáticos personalizados

Se staticAssetsManifestPath é null, o IHostEnvironment.ApplicationName é utilizado para localizar o manifesto. Como alternativa, especifique um caminho completo para o arquivo de manifesto. Se um caminho relativo for usado, a estrutura procurará o arquivo no AppContext.BaseDirectory.

Considerações de segurança para arquivos estáticos

Warning

UseDirectoryBrowser e UseStaticFiles podem vazar segredos. Desativar a navegação no diretório em produção é altamente recomendado. Analise cuidadosamente quais diretórios estão habilitados via UseStaticFiles ou UseDirectoryBrowser. Todo o diretório e seus subdiretórios tornam-se acessíveis ao público. Armazene arquivos adequados para servir ao público em um diretório dedicado, como <content_root>/wwwroot. Separe esses arquivos de visualizações MVC, Razor Pages, arquivos de configuração, etc.

  • Os URLs para conteúdo exposto com UseDirectoryBrowser e UseStaticFiles estão sujeitos às restrições de diferenciação de maiúsculas e minúsculas e caracteres do sistema de arquivos subjacente. Por exemplo, o Windows não diferencia maiúsculas de minúsculas, mas o macOS e o Linux não.

  • Aplicações ASP.NET Core hospedadas no IIS usam o Módulo ASP.NET Core para encaminhar todas as solicitações para a aplicação, incluindo solicitações de arquivos estáticos. O manipulador de arquivos estáticos do IIS não é usado e não tem chance de lidar com solicitações.

  • Conclua as seguintes etapas no Gerenciador do IIS para remover o manipulador de arquivos estáticos do IIS no nível do servidor ou do site:

    1. Navegue até a funcionalidade Módulos.
    2. Selecione StaticFileModule na lista.
    3. Clique Remover na barra lateral Ações.

Warning

Se o manipulador de arquivos estáticos do IIS estiver habilitado e o módulo principal do ASP.NET estiver configurado incorretamente, os arquivos estáticos serão servidos. Isso acontece, por exemplo, se o web.config arquivo não for implantado.

  • Coloque ficheiros de código, incluindo e , fora da raiz webdo projeto da aplicação . Portanto, uma separação lógica é criada entre o conteúdo do lado do cliente do aplicativo e o código baseado em servidor. Isso evita que o código do lado do servidor seja vazado.

Propriedades do MSBuild

As tabelas a seguir mostram as propriedades MSBuild de arquivos estáticos e as descrições dos seus metadados.

Propriedade Description
EnableDefaultCompressedItems Permite padrões predefinidos de inclusão/exclusão para a compactação.
CompressionIncludePatterns Lista separada por ponto-e-vírgula de padrões de arquivo a serem incluídos para compactação.
CompressionExcludePatterns Lista separada por ponto-e-vírgula de padrões de arquivo a serem excluídos da compactação.
EnableDefaultCompressionFormats Permite formatos de compressão padrão (Gzip e Brotli).
BuildCompressionFormats Formatos de compressão para usar durante a compilação.
PublishCompressionFormats Formatos de compressão para usar durante a publicação.
DisableBuildCompression Desativa a compressão durante a compilação.
CompressDiscoveredAssetsDuringBuild Compacta elementos identificados durante a compilação.
BrotliCompressionLevel Nível de compressão para o algoritmo Brotli.
StaticWebAssetBuildCompressAllAssets Compacta todos os ativos durante a compilação, não apenas os ativos descobertos ou computados durante uma compilação.
StaticWebAssetPublishCompressAllAssets Compacta todos os ativos durante a publicação, não apenas os ativos descobertos ou computados durante uma compilação.
Propriedade Description
StaticWebAssetBasePath Caminho de URL base para todos os ativos em uma biblioteca.
StaticWebAssetsFingerprintContent Habilita a impressão digital de conteúdo para a eliminação de cache.
StaticWebAssetFingerprintingEnabled Habilita o recurso de impressão digital para ativos da Web estáticos.
StaticWebAssetsCacheDefineStaticWebAssetsEnabled Permite o armazenamento em cache para definições estáticas de ativos da Web.
StaticWebAssetEndpointExclusionPattern Padrão para exclusão de endpoints.
Grupo de itens Description Metadados
StaticWebAssetContentTypeMapping Mapeia padrões de ficheiro para tipos de conteúdo e cabeçalhos de cache para endpoints. Pattern, Cache
StaticWebAssetFingerprintPattern Define padrões para aplicar impressões digitais a ativos da Web estáticos para quebra de cache. Pattern, Expression

Descrições dos metadados:

  • Pattern: Um padrão glob usado para encontrar arquivos. Para StaticWebAssetContentTypeMapping, ele corresponde a arquivos para determinar seu tipo de conteúdo (por exemplo, *.js para arquivos JavaScript). Para StaticWebAssetFingerprintPattern, ele identifica arquivos com várias extensões que requerem tratamento especial de identificação por impressão digital (por exemplo, *.lib.module.js).

  • Cache: Especifica o valor do Cache-Control cabeçalho para o tipo de conteúdo correspondente. Isso controla o comportamento de cache do navegador (por exemplo, max-age=3600, must-revalidate para arquivos de mídia).

  • Expression: Define como a impressão digital é inserida no nome do arquivo. O padrão é #[.{FINGERPRINT}], que insere a impressão digital ({FINGERPRINT} marcador de posição) antes da extensão.

O exemplo a seguir mapeia o padrão de arquivo bitmap (.bmp) para o tipo de conteúdo image/bmp, com o espaço reservado {CACHE HEADER} a representar o cabeçalho Cache-Control que será usado para endpoints não associados a impressões digitais.

<ItemGroup>
  <StaticWebAssetContentTypeMapping Include="image/bmp" Cache="{CACHE HEADER}" Pattern="*.bmp" />
</ItemGroup>

Opções de configuração de tempo de execução

A tabela a seguir descreve as opções de configuração de tempo de execução.

Chave de configuração Description
ReloadStaticAssetsAtRuntime Permite o recarregamento a quente em tempo de desenvolvimento de ativos estáticos: serve arquivos de raiz da Web modificados (wwwrootrecalcula ETag, recompacta se necessário) em vez de versões de manifesto em tempo de compilação. O padrão é ativado apenas quando se está a fornecer um manifesto de compilação, a menos que definido explicitamente de outra forma.
DisableStaticAssetNotFoundRuntimeFallback Quando true é utilizado, elimina o ponto final de fallback que serve ficheiros recém-adicionados não presentes no manifesto de compilação. Quando false está presente ou ausente, uma verificação da existência do arquivo {**path} (GET/HEAD) regista um aviso e o arquivo é servido com um cálculo ETag.
EnableStaticAssetsDevelopmentCaching Quando true, preserva os cabeçalhos originais Cache-Control nos descritores de ativos. Quando false está presente ou ausente, reescreve os cabeçalhos Cache-Control para no-cache evitar o cache agressivo do cliente durante o desenvolvimento.
EnableStaticAssetsDevelopmentIntegrity Quando true, mantém propriedades de integridade nos descritores de ativos. Quando false ou ausente, remove qualquer propriedade de integridade para evitar incompatibilidades quando os arquivos são alterados durante o desenvolvimento.

Recursos adicionais

  • Last updated on