Arquivos estáticos no ASP.NET CoreStatic files in ASP.NET Core

Por Rick Anderson e Scott AddieBy Rick Anderson and Scott Addie

Arquivos estáticos, como HTML, CSS, imagens e JavaScript, são ativos que um aplicativo ASP.NET Core fornece diretamente para os clientes.Static files, such as HTML, CSS, images, and JavaScript, are assets an ASP.NET Core app serves directly to clients. Algumas etapas de configuração são necessárias para habilitar o fornecimento desses arquivos.Some configuration is required to enable serving of these files.

Exibir ou baixar código de exemplo (como baixar)View or download sample code (how to download)

Fornecer arquivos estáticosServe static files

Os arquivos estáticos são armazenados no diretório raiz Web do projeto.Static files are stored within your project's web root directory. O diretório padrão é <content_root>/wwwroot, mas pode ser alterado por meio do método UseWebRoot.The default directory is <content_root>/wwwroot, but it can be changed via the UseWebRoot method. Consulte Raiz de conteúdo e Diretório base para obter mais informações.See Content root and Web root for more information.

O host Web do aplicativo deve ser informado do diretório raiz do conteúdo.The app's web host must be made aware of the content root directory.

O método WebHost.CreateDefaultBuilder define a raiz do conteúdo como o diretório atual:The WebHost.CreateDefaultBuilder method sets the content root to the current directory:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

Defina a raiz do conteúdo com o diretório atual invocando UseContentRoot dentro de Program.Main:Set the content root to the current directory by invoking UseContentRoot inside of Program.Main:

public class Program
{
    public static void Main(string[] args)
    {
        var host = new WebHostBuilder()
            .UseKestrel()
            .UseContentRoot(Directory.GetCurrentDirectory())
            .UseIISIntegration()
            .UseStartup<Startup>()
            .UseApplicationInsights()
            .Build();

        host.Run();
    }        
}

Os arquivos estáticos são acessíveis por meio de um caminho relativo ao diretório base.Static files are accessible via a path relative to the web root. Por exemplo, o modelo de projeto do Aplicativo Web contém várias pastas dentro da pasta wwwroot:For example, the Web Application project template contains several folders within the wwwroot folder:

  • wwwrootwwwroot
    • csscss
    • imagesimages
    • jsjs

O formato de URI para acessar um arquivo na subpasta images é http://<server_address>/images/<image_file_name>.The URI format to access a file in the images subfolder is http://<server_address>/images/<image_file_name>. Por exemplo, http://localhost:9189/images/banner3.svg.For example, http://localhost:9189/images/banner3.svg.

Se estiver direcionando o .NET Framework, adicione o pacote Microsoft.AspNetCore.StaticFiles ao projeto.If targeting .NET Framework, add the Microsoft.AspNetCore.StaticFiles package to your project. Se você estiver direcionando para o .NET Core, o metapacote Microsoft.AspNetCore.App incluirá esse pacote.If targeting .NET Core, the Microsoft.AspNetCore.App metapackage includes this package.

Se estiver direcionando o .NET Framework, adicione o pacote Microsoft.AspNetCore.StaticFiles ao projeto.If targeting .NET Framework, add the Microsoft.AspNetCore.StaticFiles package to your project. Se estiver direcionando o .NET Core, o metapacote Microsoft.AspNetCore.All incluirá esse pacote.If targeting .NET Core, the Microsoft.AspNetCore.All metapackage includes this package.

Adicione o pacote Microsoft.AspNetCore.StaticFiles ao projeto.Add the Microsoft.AspNetCore.StaticFiles package to your project.

Configure o middleware que permite o fornecimento de arquivos estáticos.Configure the middleware which enables the serving of static files.

Fornecer arquivos dentro do diretório baseServe files inside of web root

Invoque o método UseStaticFiles dentro de Startup.Configure:Invoke the UseStaticFiles method within Startup.Configure:

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();
}

A sobrecarga do método UseStaticFiles sem parâmetro marca os arquivos no diretório base como fornecíveis.The parameterless UseStaticFiles method overload marks the files in web root as servable. A seguinte marcação referencia wwwroot/images/banner1.svg:The following markup references wwwroot/images/banner1.svg:

<img src="~/images/banner1.svg" alt="ASP.NET" class="img-responsive" />

No código anterior, o caractere til ~/ aponta para o diretório base.In the preceding code, the tilde character ~/ points to webroot. Para obter mais informações, confira Diretório base.For more information, see Web root.

Fornecer arquivos fora do diretório baseServe files outside of web root

Considere uma hierarquia de diretórios na qual os arquivos estáticos a serem atendidos residam fora do diretório base:Consider a directory hierarchy in which the static files to be served reside outside of the web root:

  • wwwrootwwwroot
    • csscss
    • imagesimages
    • jsjs
  • MyStaticFilesMyStaticFiles
    • imagesimages
      • banner1.svgbanner1.svg

Uma solicitação pode acessar o arquivo banner1.svg configurando o middleware de arquivos estáticos da seguinte maneira:A request can access the banner1.svg file by configuring the Static File Middleware as follows:

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles(); // For the wwwroot folder

    app.UseStaticFiles(new StaticFileOptions
    {
        FileProvider = new PhysicalFileProvider(
            Path.Combine(Directory.GetCurrentDirectory(), "MyStaticFiles")),
        RequestPath = "/StaticFiles"
    });
}

No código anterior, a hierarquia de diretórios MyStaticFiles é exposta publicamente por meio do segmento do URI StaticFiles.In the preceding code, the MyStaticFiles directory hierarchy is exposed publicly via the StaticFiles URI segment. Uma solicitação para http://<server_address>/StaticFiles/images/banner1.svg atende ao arquivo banner1.svg.A request to http://<server_address>/StaticFiles/images/banner1.svg serves the banner1.svg file.

A seguinte marcação referencia MyStaticFiles/images/banner1.svg:The following markup references MyStaticFiles/images/banner1.svg:

<img src="~/StaticFiles/images/banner1.svg" alt="ASP.NET" class="img-responsive" />

Definir cabeçalhos de resposta HTTPSet HTTP response headers

Um objeto StaticFileOptions pode ser usado para definir cabeçalhos de resposta HTTP.A StaticFileOptions object can be used to set HTTP response headers. Além de configurar o fornecimento de arquivos estáticos do diretório base, o seguinte código define o cabeçalho Cache-Control:In addition to configuring static file serving from the web root, the following code sets the Cache-Control header:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    var cachePeriod = env.IsDevelopment() ? "600" : "604800";
    app.UseStaticFiles(new StaticFileOptions
    {
        OnPrepareResponse = ctx =>
        {
            // Requires the following import:
            // using Microsoft.AspNetCore.Http;
            ctx.Context.Response.Headers.Append("Cache-Control", $"public, max-age={cachePeriod}");
        }
    });
}

O método HeaderDictionaryExtensions.Append existe no pacote Microsoft.AspNetCore.Http.The HeaderDictionaryExtensions.Append method exists in the Microsoft.AspNetCore.Http package.

Os arquivos se tornaram armazenáveis em cache publicamente por 10 minutos (600 segundos) no ambiente de desenvolvimento:The files have been made publicly cacheable for 10 minutes (600 seconds) in the Development environment:

Cabeçalho de resposta mostrando que o cabeçalho Cache-Control foi adicionado

Autorização de arquivo estáticoStatic file authorization

O middleware de arquivos estáticos não fornece verificações de autorização.The Static File Middleware doesn't provide authorization checks. Todos os arquivos atendidos, incluindo aqueles em wwwroot, estão acessíveis publicamente.Any files served by it, including those under wwwroot, are publicly accessible. Para fornecer arquivos com base na autorização:To serve files based on authorization:

  • Armazene-os fora do wwwroot e de qualquer diretório acessível ao middleware de arquivos estáticos.Store them outside of wwwroot and any directory accessible to the Static File Middleware.

  • Forneça-os por meio de um método de ação ao qual a autorização é aplicada.Serve them via an action method to which authorization is applied. Retorne um objeto FileResult:Return a FileResult object:

    [Authorize]
    public IActionResult BannerImage()
    {
        var file = Path.Combine(Directory.GetCurrentDirectory(), 
                                "MyStaticFiles", "images", "banner1.svg");
    
        return PhysicalFile(file, "image/svg+xml");
    }
    

Habilitar navegação no diretórioEnable directory browsing

A navegação no diretório permite que os usuários do aplicativo Web vejam uma listagem de diretório e arquivos em um diretório especificado.Directory browsing allows users of your web app to see a directory listing and files within a specified directory. A navegação no diretório está desabilitada por padrão por motivos de segurança (consulte Considerações).Directory browsing is disabled by default for security reasons (see Considerations). Habilite a navegação no diretório invocando o método UseDirectoryBrowser em Startup.Configure:Enable directory browsing by invoking the UseDirectoryBrowser method in Startup.Configure:

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles(); // For the wwwroot folder

    app.UseStaticFiles(new StaticFileOptions
    {
        FileProvider = new PhysicalFileProvider(
            Path.Combine(Directory.GetCurrentDirectory(), "wwwroot", "images")),
        RequestPath = "/MyImages"
    });

    app.UseDirectoryBrowser(new DirectoryBrowserOptions
    {
        FileProvider = new PhysicalFileProvider(
            Path.Combine(Directory.GetCurrentDirectory(), "wwwroot", "images")),
        RequestPath = "/MyImages"
    });
}

Adicione os serviços necessários invocando o método AddDirectoryBrowser em Startup.ConfigureServices:Add required services by invoking the AddDirectoryBrowser method from Startup.ConfigureServices:

public void ConfigureServices(IServiceCollection services)
{
    services.AddDirectoryBrowser();
}

O código anterior permite a navegação no diretório da pasta wwwroot/images usando a URL http://<server_address>/MyImages, com links para cada arquivo e pasta:The preceding code allows directory browsing of the wwwroot/images folder using the URL http://<server_address>/MyImages, with links to each file and folder:

navegação no diretório

Consulte Considerações para saber mais sobre os riscos de segurança ao habilitar a navegação.See Considerations on the security risks when enabling browsing.

Observe as duas chamadas UseStaticFiles no exemplo a seguir.Note the two UseStaticFiles calls in the following example. A primeira chamada permite o fornecimento de arquivos estáticos na pasta wwwroot.The first call enables the serving of static files in the wwwroot folder. A segunda chamada habilita a navegação no diretório da pasta wwwroot/images usando a URL http://<server_address>/MyImages:The second call enables directory browsing of the wwwroot/images folder using the URL http://<server_address>/MyImages:

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles(); // For the wwwroot folder

    app.UseStaticFiles(new StaticFileOptions
    {
        FileProvider = new PhysicalFileProvider(
            Path.Combine(Directory.GetCurrentDirectory(), "wwwroot", "images")),
        RequestPath = "/MyImages"
    });

    app.UseDirectoryBrowser(new DirectoryBrowserOptions
    {
        FileProvider = new PhysicalFileProvider(
            Path.Combine(Directory.GetCurrentDirectory(), "wwwroot", "images")),
        RequestPath = "/MyImages"
    });
}

Fornecer um documento padrãoServe a default document

Definir uma home page padrão fornece ao visitantes um ponto de partida lógico de ao visitar o site.Setting a default home page provides visitors a logical starting point when visiting your site. Para fornecer uma página padrão sem qualificar totalmente o URI do usuário, chame o UseDefaultFiles método de Startup.Configure:To serve a default page without the user fully qualifying the URI, call the UseDefaultFiles method from Startup.Configure:

public void Configure(IApplicationBuilder app)
{
    app.UseDefaultFiles();
    app.UseStaticFiles();
}

Importante

UseDefaultFiles deve ser chamado antes de UseStaticFiles para fornecer o arquivo padrão.UseDefaultFiles must be called before UseStaticFiles to serve the default file. UseDefaultFiles é um rewriter de URL que, na verdade, não fornece o arquivo.UseDefaultFiles is a URL rewriter that doesn't actually serve the file. Habilite o middleware de arquivos estáticos por meio de UseStaticFiles para fornecer o arquivo.Enable Static File Middleware via UseStaticFiles to serve the file.

Com UseDefaultFiles, as solicitações para uma pasta pesquisam:With UseDefaultFiles, requests to a folder search for:

  • default.htmdefault.htm
  • default.htmldefault.html
  • index.htmindex.htm
  • index.htmlindex.html

O primeiro arquivo encontrado na lista é fornecido como se a solicitação fosse o URI totalmente qualificado.The first file found from the list is served as though the request were the fully qualified URI. A URL do navegador continua refletindo o URI solicitado.The browser URL continues to reflect the URI requested.

O seguinte código altera o nome de arquivo padrão para mydefault.html:The following code changes the default file name to mydefault.html:

public void Configure(IApplicationBuilder app)
{
    // Serve my app-specific default file, if present.
    DefaultFilesOptions options = new DefaultFilesOptions();
    options.DefaultFileNames.Clear();
    options.DefaultFileNames.Add("mydefault.html");
    app.UseDefaultFiles(options);
    app.UseStaticFiles();
}

UseFileServerUseFileServer

UseFileServer combina a funcionalidade de UseStaticFiles, UseDefaultFiles e UseDirectoryBrowser.UseFileServer combines the functionality of UseStaticFiles, UseDefaultFiles, and UseDirectoryBrowser.

O código a seguir permite o fornecimento de arquivos estáticos e do arquivo padrão.The following code enables the serving of static files and the default file. A navegação no diretório não está habilitada.Directory browsing isn't enabled.

app.UseFileServer();

O seguinte código baseia-se na sobrecarga sem parâmetros, habilitando a navegação no diretório:The following code builds upon the parameterless overload by enabling directory browsing:

app.UseFileServer(enableDirectoryBrowsing: true);

Considere a seguinte hierarquia de diretórios:Consider the following directory hierarchy:

  • wwwrootwwwroot
    • csscss
    • imagesimages
    • jsjs
  • MyStaticFilesMyStaticFiles
    • imagesimages
      • banner1.svgbanner1.svg
    • default.htmldefault.html

O seguinte código habilita arquivos estáticos, arquivos padrão e a navegação no diretório de MyStaticFiles:The following code enables static files, default files, and directory browsing of MyStaticFiles:

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles(); // For the wwwroot folder

    app.UseFileServer(new FileServerOptions
    {
        FileProvider = new PhysicalFileProvider(
            Path.Combine(Directory.GetCurrentDirectory(), "MyStaticFiles")),
        RequestPath = "/StaticFiles",
        EnableDirectoryBrowsing = true
    });
}

AddDirectoryBrowser precisa ser chamado quando o valor da propriedade EnableDirectoryBrowsing é true:AddDirectoryBrowser must be called when the EnableDirectoryBrowsing property value is true:

public void ConfigureServices(IServiceCollection services)
{
    services.AddDirectoryBrowser();
}

Com o uso da hierarquia de arquivos e do código anterior, as URLs são resolvidas da seguinte maneira:Using the file hierarchy and preceding code, URLs resolve as follows:

URIURI RespostaResponse
http://<server_address>/StaticFiles/images/banner1.svghttp://<server_address>/StaticFiles/images/banner1.svg MyStaticFiles/images/banner1.svgMyStaticFiles/images/banner1.svg
http://<server_address>/StaticFileshttp://<server_address>/StaticFiles MyStaticFiles/default.htmlMyStaticFiles/default.html

Se nenhum arquivo nomeado como padrão existir no diretório MyStaticFiles, http://<server_address>/StaticFiles retornará a listagem de diretórios com links clicáveis:If no default-named file exists in the MyStaticFiles directory, http://<server_address>/StaticFiles returns the directory listing with clickable links:

Lista de arquivos estáticos

Observação

UseDefaultFiles e UseDirectoryBrowser executam um redirecionamento do lado do cliente de http://{SERVER ADDRESS}/StaticFiles (sem uma barra à direita) para http://{SERVER ADDRESS}/StaticFiles/ (com uma barra à direita).UseDefaultFiles and UseDirectoryBrowser perform a client-side redirect from http://{SERVER ADDRESS}/StaticFiles (without a trailing slash) to http://{SERVER ADDRESS}/StaticFiles/ (with a trailing slash). As URLs relativas dentro do diretório StaticFiles são inválidas sem uma barra "" à direita.Relative URLs within the StaticFiles directory are invalid without a trailing slash.

FileExtensionContentTypeProviderFileExtensionContentTypeProvider

A classe FileExtensionContentTypeProvider contém uma propriedade Mappings que serve como um mapeamento de extensões de arquivo para tipos de conteúdo MIME.The FileExtensionContentTypeProvider class contains a Mappings property serving as a mapping of file extensions to MIME content types. Na amostra a seguir, várias extensões de arquivo são registradas para tipos MIME conhecidos.In the following sample, several file extensions are registered to known MIME types. A extensão .rtf é substituída, e .mp4 é removida.The .rtf extension is replaced, and .mp4 is removed.

public void Configure(IApplicationBuilder app)
{
    // 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(Directory.GetCurrentDirectory(), "wwwroot", "images")),
        RequestPath = "/MyImages",
        ContentTypeProvider = provider
    });

    app.UseDirectoryBrowser(new DirectoryBrowserOptions
    {
        FileProvider = new PhysicalFileProvider(
            Path.Combine(Directory.GetCurrentDirectory(), "wwwroot", "images")),
        RequestPath = "/MyImages"
    });
}

Consulte Tipos de conteúdo MIME.See MIME content types.

Tipos de conteúdo não padrãoNon-standard content types

O middleware de arquivo estático compreende quase 400 tipos de conteúdo de arquivo conhecidos.Static File Middleware understands almost 400 known file content types. Se o usuário solicitar um arquivo com um tipo desconhecido, o middleware de arquivo estático passará a solicitação para o próximo middleware no pipeline.If the user requests a file with an unknown file type, Static File Middleware passes the request to the next middleware in the pipeline. Se nenhum middleware manipular a solicitação, uma resposta 404 Não Encontrado será retornada.If no middleware handles the request, a 404 Not Found response is returned. Se a navegação no diretório estiver habilitada, um link para o arquivo será exibido na lista do diretório.If directory browsing is enabled, a link to the file is displayed in a directory listing.

O seguinte código habilita o fornecimento de tipos desconhecidos e renderiza o arquivo desconhecido como uma imagem:The following code enables serving unknown types and renders the unknown file as an image:

public void Configure(IApplicationBuilder app)
{
    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.With the preceding code, a request for a file with an unknown content type is returned as an image.

Aviso

A habilitação de ServeUnknownFileTypes é um risco de segurança.Enabling ServeUnknownFileTypes is a security risk. Ela está desabilitada por padrão, e seu uso não é recomendado.It's disabled by default, and its use is discouraged. FileExtensionContentTypeProvider fornece uma alternativa mais segura para o fornecimento de arquivos com extensões não padrão.FileExtensionContentTypeProvider provides a safer alternative to serving files with non-standard extensions.

ConsideraçõesConsiderations

Aviso

UseDirectoryBrowser e UseStaticFiles podem causar a perda de segredos.UseDirectoryBrowser and UseStaticFiles can leak secrets. A desabilitação da navegação no diretório em produção é altamente recomendada.Disabling directory browsing in production is highly recommended. Examine com atenção os diretórios que são habilitados por meio de UseStaticFiles ou UseDirectoryBrowser.Carefully review which directories are enabled via UseStaticFiles or UseDirectoryBrowser. Todo o diretório e seus subdiretórios se tornam publicamente acessíveis.The entire directory and its sub-directories become publicly accessible. Armazene arquivos adequados para fornecimento ao público em um diretório dedicado, como <content_root>/wwwroot.Store files suitable for serving to the public in a dedicated directory, such as <content_root>/wwwroot. Separe esses arquivos das exibições MVC, Páginas do Razor (somente 2.x), arquivos de configuração, etc.Separate these files from MVC views, Razor Pages (2.x only), configuration files, etc.

  • As URLs para o conteúdo exposto com UseDirectoryBrowser e UseStaticFiles estão sujeitas à diferenciação de maiúsculas e minúsculas e a restrições de caracteres do sistema de arquivos subjacente.The URLs for content exposed with UseDirectoryBrowser and UseStaticFiles are subject to the case sensitivity and character restrictions of the underlying file system. Por exemplo, o Windows diferencia maiúsculas de minúsculas, o macOS e o Linux não.For example, Windows is case insensitive—macOS and Linux aren't.

  • Os aplicativos ASP.NET Core hospedados no IIS usam o Módulo do ASP.NET Core para encaminhar todas as solicitações ao aplicativo, inclusive as solicitações de arquivo estático.ASP.NET Core apps hosted in IIS use the ASP.NET Core Module to forward all requests to the app, including static file requests. O manipulador de arquivos estáticos do IIS não é usado.The IIS static file handler isn't used. Ele não tem nenhuma possibilidade de manipular as solicitações antes que elas sejam manipuladas pelo módulo.It has no chance to handle requests before they're handled by the module.

  • Conclua as etapas seguinte no Gerenciador do IIS para remover o manipulador de arquivos estáticos no IIS no nível do servidor ou do site:Complete the following steps in IIS Manager to remove the IIS static file handler at the server or website level:

    1. Navegue para o recurso Módulos.Navigate to the Modules feature.
    2. Selecione StaticFileModule na lista.Select StaticFileModule in the list.
    3. Clique em Remover na barra lateral Ações.Click Remove in the Actions sidebar.

Aviso

Se o manipulador de arquivo estático do IIS estiver habilitado e o Módulo do ASP.NET Core não estiver configurado corretamente, os arquivos estáticos serão atendidos.If the IIS static file handler is enabled and the ASP.NET Core Module is configured incorrectly, static files are served. Isso acontece, por exemplo, se o arquivo web.config não foi implantado.This happens, for example, if the web.config file isn't deployed.

  • Coloque arquivos de código (incluindo .cs e .cshtml) fora do diretório base do projeto do aplicativo.Place code files (including .cs and .cshtml) outside of the app project's web root. Portanto, uma separação lógica é criada entre o conteúdo do lado do cliente do aplicativo e o código baseado em servidor.A logical separation is therefore created between the app's client-side content and server-based code. Isso impede a perda de código do lado do servidor.This prevents server-side code from being leaked.

Recursos adicionaisAdditional resources