Fichiers statiques dans ASP.NET CoreStatic files in ASP.NET Core

Par Rick Anderson et Scott AddieBy Rick Anderson and Scott Addie

Les fichiers statiques, comme les fichiers HTML, CSS, images et JavaScript, sont des ressources qu’une application ASP.NET Core délivre directement aux clients.Static files, such as HTML, CSS, images, and JavaScript, are assets an ASP.NET Core app serves directly to clients. Une configuration est nécessaire pour pouvoir délivrer ces fichiers.Some configuration is required to enable serving of these files.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)View or download sample code (how to download)

Délivrer des fichiers statiquesServe static files

Les fichiers statiques sont stockés dans le répertoire racine du projet web.Static files are stored within the project's web root directory. Le répertoire par défaut est <racine_contenu>/wwwroot, mais il peut être changé via la méthode UseWebRoot.The default directory is <content_root>/wwwroot, but it can be changed via the UseWebRoot method. Pour plus d’informations, consultez Racine du contenu et Racine web.See Content root and Web root for more information.

L’hôte web de l’application doit être informé du répertoire racine du contenu.The app's web host must be made aware of the content root directory.

La méthode WebHost.CreateDefaultBuilder définit le répertoire actif comme racine du contenu :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>();
}

Définissez le répertoire actif comme racine du contenu en appelant UseContentRoot à l’intérieur 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();
    }        
}

Les fichiers statiques sont accessibles via un chemin relatif à la racine web.Static files are accessible via a path relative to the web root. Par exemple, le modèle de projet Application web contient plusieurs dossiers dans le dossier wwwroot :For example, the Web Application project template contains several folders within the wwwroot folder:

  • wwwrootwwwroot
    • csscss
    • imagesimages
    • jsjs

Le format d’URI pour accéder à un fichier dans le sous-dossier images est http://<adresse_serveur>/images/<nom_fichier_image> .The URI format to access a file in the images subfolder is http://<server_address>/images/<image_file_name>. Par exemple, http://localhost:9189/images/banner3.svg .For example, http://localhost:9189/images/banner3.svg.

Si vous ciblez .NET Framework, ajoutez le package Microsoft.AspNetCore.StaticFiles au projet.If targeting .NET Framework, add the Microsoft.AspNetCore.StaticFiles package to the project. Si vous ciblez .NET Core, le métapackage Microsoft.AspNetCore.App comprend ce package.If targeting .NET Core, the Microsoft.AspNetCore.App metapackage includes this package.

Si vous ciblez .NET Framework, ajoutez le package Microsoft.AspNetCore.StaticFiles au projet.If targeting .NET Framework, add the Microsoft.AspNetCore.StaticFiles package to the project. Si vous ciblez .NET Core, le métapackage Microsoft.AspNetCore.All inclut ce package.If targeting .NET Core, the Microsoft.AspNetCore.All metapackage includes this package.

Ajoutez le package Microsoft.AspNetCore.StaticFiles au projet.Add the Microsoft.AspNetCore.StaticFiles package to the project.

Configurez le middleware qui permet de délivrer des fichiers statiques.Configure the middleware which enables the serving of static files.

Délivrer des fichiers dans la racine webServe files inside of web root

Appelez la méthode UseStaticFiles dans Startup.Configure :Invoke the UseStaticFiles method within Startup.Configure:

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

La surcharge de la méthode UseStaticFiles sans paramètres marque les fichiers dans la racine web comme étant délivrables.The parameterless UseStaticFiles method overload marks the files in web root as servable. Le balisage suivant référence wwwroot/images/banner1.svg :The following markup references wwwroot/images/banner1.svg:

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

Dans le code précédent, le caractère tilde ~/ pointe vers la racine web.In the preceding code, the tilde character ~/ points to webroot. Pour plus d’informations, consultez Racine web.For more information, see Web root.

Délivrer des fichiers en dehors de la racine webServe files outside of web root

Considérez une hiérarchie de répertoires dans laquelle les fichiers statiques à délivrer se trouvent en dehors de la racine web :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

Vous permettez à une requête d’accéder au fichier banner1.svg en configurant le middleware (intergiciel) des fichiers statiques comme suit :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"
    });
}

Dans le code précédent, la hiérarchie de répertoires MyStaticFiles est exposée publiquement via le segment d’URI StaticFiles.In the preceding code, the MyStaticFiles directory hierarchy is exposed publicly via the StaticFiles URI segment. Une requête à http://<adresse_serveur>/StaticFiles/images/banner1.svg délivre le fichier banner1.svg.A request to http://<server_address>/StaticFiles/images/banner1.svg serves the banner1.svg file.

Le balisage suivant référence MyStaticFiles/images/banner1.svg :The following markup references MyStaticFiles/images/banner1.svg:

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

Définir des en-têtes de réponse HTTPSet HTTP response headers

Un objet StaticFileOptions peut être utilisé pour définir des en-têtes de réponse HTTP.A StaticFileOptions object can be used to set HTTP response headers. En plus de configurer la possibilité de délivrer des fichiers statiques à partir de la racine web, le code suivant définit l’en-tête 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}");
        }
    });
}

La méthode HeaderDictionaryExtensions.Append se trouve dans le package Microsoft.AspNetCore.Http.The HeaderDictionaryExtensions.Append method exists in the Microsoft.AspNetCore.Http package.

Les fichiers peuvent être mis en cache publiquement pendant 10 minutes (600 secondes) dans l’environnement de développement :The files have been made publicly cacheable for 10 minutes (600 seconds) in the Development environment:

En-têtes de réponse montrant que l’en-tête Cache-Control a été ajouté

Autorisations des fichiers statiquesStatic file authorization

Le middleware de fichiers statiques ne fournit pas de vérification des autorisations.The Static File Middleware doesn't provide authorization checks. Tous les fichiers qu’il délivre, notamment ceux sous wwwroot, sont accessibles publiquement.Any files served by it, including those under wwwroot, are publicly accessible. Pour délivrer des fichiers en fonction d’une autorisation :To serve files based on authorization:

  • Stockez-les en dehors de wwwroot et de tout répertoire accessible au middleware de fichiers statiques.Store them outside of wwwroot and any directory accessible to the Static File Middleware.

  • Délivrez-les via une méthode d’action à laquelle une autorisation est appliquée.Serve them via an action method to which authorization is applied. Retournez un objet 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");
    }
    

Activer l’exploration des répertoiresEnable directory browsing

L’exploration des répertoires permet aux utilisateurs de votre application web de voir une liste des répertoires et des fichiers dans un répertoire spécifié.Directory browsing allows users of your web app to see a directory listing and files within a specified directory. L’exploration des répertoires est désactivée par défaut pour des raisons de sécurité (consultez Considérations).Directory browsing is disabled by default for security reasons (see Considerations). Activez l’exploration des répertoires en appelant la méthode UseDirectoryBrowser dans 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"
    });
}

Ajoutez les services nécessaires en appelant la méthode AddDirectoryBrowser depuis Startup.ConfigureServices :Add required services by invoking the AddDirectoryBrowser method from Startup.ConfigureServices:

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

Le code précédent permet l’exploration des répertoires du dossier wwwroot/images en utilisant l’URL http://<adresse_serveur>/MyImages, avec des liens vers chaque fichier et dossier :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:

exploration des répertoires

Consultez Considérations sur les risques de sécurité lors de l’activation de l’exploration.See Considerations on the security risks when enabling browsing.

Notez les deux appels de UseStaticFiles dans l’exemple suivant.Note the two UseStaticFiles calls in the following example. Le premier appel permet de délivrer des fichiers statiques dans le dossier wwwroot.The first call enables the serving of static files in the wwwroot folder. Le deuxième appel active l’exploration des répertoires du dossier wwwroot/images en utilisant l’URL http://<adresse_serveur>/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"
    });
}

Délivrer un document par défautServe a default document

La définition d’une page d’accueil par défaut donne aux visiteurs un point de départ logique lors de la visite de votre site.Setting a default home page provides visitors a logical starting point when visiting your site. Pour délivrer une page par défaut sans que l’utilisateur qualifie complètement l’URI, appelez la méthode UseDefaultFiles depuis 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();
}

Important

UseDefaultFiles doit être appelé avant UseStaticFiles pour délivrer le fichier par défaut.UseDefaultFiles must be called before UseStaticFiles to serve the default file. UseDefaultFiles est un module de réécriture d’URL qui ne délivre pas réellement le fichier.UseDefaultFiles is a URL rewriter that doesn't actually serve the file. Activez le middleware de fichiers statiques via UseStaticFiles pour délivrer le fichier.Enable Static File Middleware via UseStaticFiles to serve the file.

Avec UseDefaultFiles, les requêtes sur un dossier recherchent :With UseDefaultFiles, requests to a folder search for:

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

Le premier fichier trouvé dans la liste est délivré comme si la requête était l’URI qualifié complet.The first file found from the list is served as though the request were the fully qualified URI. L’URL du navigateur continue de refléter l’URI demandé.The browser URL continues to reflect the URI requested.

Le code suivant change le nom de fichier par défaut en 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 combine les fonctionnalités de UseStaticFiles, UseDefaultFiles et UseDirectoryBrowser.UseFileServer combines the functionality of UseStaticFiles, UseDefaultFiles, and UseDirectoryBrowser.

Le code suivant active la possibilité de délivrer des fichiers statiques et le fichier par défaut.The following code enables the serving of static files and the default file. L’exploration des répertoires n’est pas activée.Directory browsing isn't enabled.

app.UseFileServer();

Le code suivant s’appuie sur la surcharge sans paramètre en activant l’exploration des répertoires :The following code builds upon the parameterless overload by enabling directory browsing:

app.UseFileServer(enableDirectoryBrowsing: true);

Considérez la hiérarchie de répertoires suivante :Consider the following directory hierarchy:

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

Le code suivant active les fichiers statiques, les fichiers par défaut et l’exploration des répertoires 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 doit être appelé quand la valeur de la propriété EnableDirectoryBrowsing est true :AddDirectoryBrowser must be called when the EnableDirectoryBrowsing property value is true:

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

En utilisant la hiérarchie de fichiers et le code précédent, les URL sont résolues comme suit :Using the file hierarchy and preceding code, URLs resolve as follows:

URIURI RéponseResponse
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

Si aucun fichier nommé default n’existe dans le répertoire MyStaticFiles, http://<adresse_serveur>/StaticFiles retourne la liste des répertoires avec des liens cliquables :If no default-named file exists in the MyStaticFiles directory, http://<server_address>/StaticFiles returns the directory listing with clickable links:

Liste des fichiers statiques

Notes

UseDefaultFiles et UseDirectoryBrowser effectuent une redirection côté client à partir de http://{SERVER ADDRESS}/StaticFiles (sans barre oblique) vers http://{SERVER ADDRESS}/StaticFiles/ (avec barre oblique).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). Les URL relatives du répertoire StaticFiles ne sont pas valides sans barre oblique de fin.Relative URLs within the StaticFiles directory are invalid without a trailing slash.

FileExtensionContentTypeProviderFileExtensionContentTypeProvider

La classe FileExtensionContentTypeProvider contient une propriété Mappings agissant comme un mappage des extensions de fichiers à des types de contenu MIME.The FileExtensionContentTypeProvider class contains a Mappings property serving as a mapping of file extensions to MIME content types. Dans l’exemple suivant, plusieurs extensions de fichiers sont inscrites avec des types MIME connus.In the following sample, several file extensions are registered to known MIME types. L’extension .rtf est remplacée et .mp4 est supprimée.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"
    });
}

Consultez Types de contenu MIME.See MIME content types.

Types de contenu non standardNon-standard content types

Static File Middleware comprend près de 400 types connus de contenu de fichier.Static File Middleware understands almost 400 known file content types. Si l’utilisateur demande un fichier d’un type inconnu, Static File Middleware transmet la requête à l’intergiciel (middleware) suivant dans le 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. Si aucun intergiciel ne gère la requête, une réponse 404 introuvable est retournée.If no middleware handles the request, a 404 Not Found response is returned. Si l’exploration des répertoires est activée, un lien vers le fichier est affiché dans la liste de répertoires.If directory browsing is enabled, a link to the file is displayed in a directory listing.

Le code suivant permet de délivrer des types inconnus et rend le fichier inconnu en tant qu’image :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"
    });
}

Avec le code précédent, une requête pour un fichier avec un type de contenu inconnu est retournée en tant qu’image.With the preceding code, a request for a file with an unknown content type is returned as an image.

Avertissement

L’activation de ServeUnknownFileTypes présente un risque de sécurité.Enabling ServeUnknownFileTypes is a security risk. Il est désactivé par défaut et son utilisation est déconseillée.It's disabled by default, and its use is discouraged. FileExtensionContentTypeProvider fournit une alternative plus sûre pour délivrer des fichiers avec des extensions non standard.FileExtensionContentTypeProvider provides a safer alternative to serving files with non-standard extensions.

Éléments à prendre en considérationConsiderations

Avertissement

UseDirectoryBrowser et UseStaticFiles peuvent entraîner une fuite de secrets.UseDirectoryBrowser and UseStaticFiles can leak secrets. La désactivation de l’exploration de répertoires est fortement recommandée en production.Disabling directory browsing in production is highly recommended. Examinez attentivement les répertoires qui sont activés via UseStaticFiles ou UseDirectoryBrowser.Carefully review which directories are enabled via UseStaticFiles or UseDirectoryBrowser. L’ensemble du répertoire et de ses sous-répertoires deviennent accessibles publiquement.The entire directory and its sub-directories become publicly accessible. Stockez les fichiers qui peuvent être délivrés au public dans un dossier dédié, comme <racine-contenu>/wwwroot.Store files suitable for serving to the public in a dedicated directory, such as <content_root>/wwwroot. Séparez ces fichiers des vues MVC, des Pages Razor (2.x uniquement), des fichiers de configuration, etc.Separate these files from MVC views, Razor Pages (2.x only), configuration files, etc.

  • Les URL pour le contenu exposé avec UseDirectoryBrowser et UseStaticFiles sont soumises aux restrictions de respect de la casse et de caractères du système de fichiers sous-jacent.The URLs for content exposed with UseDirectoryBrowser and UseStaticFiles are subject to the case sensitivity and character restrictions of the underlying file system. Par exemple, Windows ne respecte pas la casse, mais macOS et Linux la respectent.For example, Windows is case insensitive—macOS and Linux aren't.

  • Les applications ASP.NET Core hébergées dans IIS utilisent le module ASP.NET Core pour transférer toutes les requêtes à l’application, notamment les requêtes de fichiers statiques.ASP.NET Core apps hosted in IIS use the ASP.NET Core Module to forward all requests to the app, including static file requests. Le gestionnaire de fichiers statiques d’IIS n’est pas utilisé.The IIS static file handler isn't used. Il ne lui est pas permis de traiter les requêtes avant qu’elles soient gérées par le module.It has no chance to handle requests before they're handled by the module.

  • Effectuez les étapes suivantes dans le Gestionnaire des services Internet (IIS) pour supprimer le gestionnaire de fichiers statiques d’IIS au niveau du serveur ou du site web :Complete the following steps in IIS Manager to remove the IIS static file handler at the server or website level:

    1. Accédez à la fonctionnalité Modules.Navigate to the Modules feature.
    2. Sélectionnez StaticFileModule dans la liste.Select StaticFileModule in the list.
    3. Cliquez sur Supprimer dans l’encadré Actions.Click Remove in the Actions sidebar.

Avertissement

Si le gestionnaire de fichiers statiques d’IIS est activé et que le module ASP.NET Core est incorrectement configuré, les fichiers statiques peuvent être délivrés.If the IIS static file handler is enabled and the ASP.NET Core Module is configured incorrectly, static files are served. Cela se produit par exemple si le fichier web.config n’est pas déployé.This happens, for example, if the web.config file isn't deployed.

  • Placez les fichiers de code (notamment .cs et .cshtml) en dehors de la racine web du projet d’application.Place code files (including .cs and .cshtml) outside of the app project's web root. Par conséquent, une séparation logique est créée entre le contenu côté client et le code basé sur le serveur de l’application.A logical separation is therefore created between the app's client-side content and server-based code. Ceci empêche la fuite de code côté serveur.This prevents server-side code from being leaked.

Ressources supplémentairesAdditional resources