Move to GitStaticAssets/4

aspnetcore/fundamentals/static-files.md

@@ -5,7 +5,7 @@ description: Learn how to serve and secure static files and configure static fil
 monikerRange: '>= aspnetcore-3.1'
 ms.author: riande
 ms.custom: mvc
-ms.date: 7/4/2024
+ms.date: 7/25/2024
 uid: fundamentals/static-files
 ---
 # Static files in ASP.NET Core
@@ -24,7 +24,7 @@ Static files are stored within the project's [web root](xref:fundamentals/index#
 
 The <xref:Microsoft.AspNetCore.Builder.WebApplication.CreateBuilder%2A> method sets the content root to the current directory:
 
-[!code-csharp[](~/fundamentals/static-files/samples/9.x/StaticFilesSample/Program.cs?name=snippet&highlight=1)]
+[!code-csharp[](~/fundamentals/static-files/samples/9.x/StaticFilesSample/Program.cs?name=snippet&highlight=1,15)]
 
 Static files are accessible via a path relative to the [web root](xref:fundamentals/index#web-root). For example, the **Web Application** project templates contain several folders within the `wwwroot` folder:
 
@@ -33,16 +33,28 @@ Static files are accessible via a path relative to the [web root](xref:fundament
   * `js`
   * `lib`
 
-Consider creating the *wwwroot/images* folder and adding the `wwwroot/images/MyImage.jpg` file. The URI format to access a file in the `images` folder is `https://<hostname>/images/<image_file_name>`. For example, `https://localhost:5001/images/MyImage.jpg`
+Consider an app with the `wwwroot/images/MyImage.jpg` file. The URI format to access a file in the `images` folder is `https://<hostname>/images/<image_file_name>`. For example, `https://localhost:5001/images/MyImage.jpg`
 
 ### MapStaticAssets
 
-`MapStaticAssets` is a middleware that helps optimize the delivery of static assets in an app. For more information, see [Optimizing static web asset delivery
+Creating performant web apps requires optimizing asset delivery to the browser. Possible optimizations include:
+
+* Serve a given asset once until the file changes or the browser clears its cache. Set the [ETag](https://developer.mozilla.org/docs/Web/HTTP/Headers/ETag) header.
+* Prevent the browser from using old or stale assets after an app is updated. Set the [Last-Modified](https://developer.mozilla.org/docs/Web/HTTP/Headers/Last-Modified) header.
+* Set up proper [caching headers](https://developer.mozilla.org/docs/Web/HTTP/Headers/Cache-Control).
+* Use [caching middleware](xref:performance/caching/middleware).
+* Serve [compressed](/aspnet/core/performance/response-compression) versions of the assets when possible.
+* Use a [CDN](/microsoft-365/enterprise/content-delivery-networks?view=o365-worldwide&preserve-view=true) to serve the assets closer to the user.
+* Minimize the size of assets served to the browser. This optimization doesn't include minification.
+
+[`MapStaticAssets`](/dotnet/api/microsoft.aspnetcore.builder.staticassetsendpointroutebuilderextensions.mapstaticassets) is a middleware that helps optimize the delivery of static assets in an app. It's designed to work with all UI frameworks, including Blazor, Razor Pages, and MVC.
+
+[`UseStaticFiles`](/dotnet/api/microsoft.aspnetcore.builder.staticfileextensions.usestaticfiles) also serves static files, but it doesn't provide the same level of optimization as `MapStaticAssets`. For a comparison of  `UseStaticFiles` and `MapStaticAssets`, see [Optimizing static web asset delivery
 ](xref:aspnetcore-9#optimizing-static-web-asset-delivery).
 
 ### Serve files in web root
 
-The default web app templates call the <xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A> method in `Program.cs`, which enables static files to be served:
+The default web app templates call the [`MapStaticAssets`](/dotnet/api/microsoft.aspnetcore.builder.staticassetsendpointroutebuilderextensions.mapstaticassets) method in `Program.cs`, which enables static files to be served:
 
 [!code-csharp[](~/fundamentals/static-files/samples/9.x/StaticFilesSample/Program.cs?name=snippet&highlight=15)]
 
@@ -84,11 +96,11 @@ A <xref:Microsoft.AspNetCore.Builder.StaticFileOptions> object can be used to se
 
 [!code-csharp[](~/fundamentals/static-files/samples/9.x/StaticFilesSample/Program.cs?name=snippet_rh&highlight=16-24)]
 
-The preceding code makes static files publicly available in the local cache for one week (604800 seconds).
+The preceding code makes static files publicly available in the local cache for one week.
 
 ## Static file authorization
 
-The ASP.NET Core templates call <xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A> before calling <xref:Microsoft.AspNetCore.Builder.AuthorizationAppBuilderExtensions.UseAuthorization%2A>. Most apps follow this pattern. When the Static File Middleware is called before the authorization middleware:
+The ASP.NET Core templates call [`MapStaticAssets`](/dotnet/api/microsoft.aspnetcore.builder.staticassetsendpointroutebuilderextensions.mapstaticassets) before calling <xref:Microsoft.AspNetCore.Builder.AuthorizationAppBuilderExtensions.UseAuthorization%2A>. Most apps follow this pattern. When the Static File Middleware is called before the authorization middleware:
 
   * No authorization checks are performed on the static files.
   * Static files served by the Static File Middleware, such as those under `wwwroot`, are publicly accessible.
@@ -99,25 +111,29 @@ To serve static files based on authorization:
   * Call `UseStaticFiles`, specifying a path, after calling `UseAuthorization`.
   * Set the [fallback authorization policy](xref:Microsoft.AspNetCore.Authorization.AuthorizationOptions.FallbackPolicy).
 
-[!code-csharp[](~/fundamentals/static-files/samples/9.x/StaticFileAuth/Program.cs?name=snippet_auth&highlight=18-23,38,45-50)]
+<!-- ~/fundamentals/static-files/samples/8.x/StaticFileAuth is a different app that ~/fundamentals/static-files/samples/6.x/StaticFileAuth -->
+[!code-csharp[](~/fundamentals/static-files/samples/6.x/StaticFileAuth/Program.cs?name=snippet_auth&highlight=18-23,38,45-50)]
 
   In the preceding code, the fallback authorization policy requires ***all*** users to be authenticated. Endpoints such as controllers, Razor Pages, etc that specify their own authorization requirements don't use the fallback authorization policy. For example, Razor Pages, controllers, or action methods with `[AllowAnonymous]` or `[Authorize(PolicyName="MyPolicy")]` use the applied authorization attribute rather than the fallback authorization policy.
 
   <xref:Microsoft.AspNetCore.Authorization.AuthorizationPolicyBuilder.RequireAuthenticatedUser%2A> adds <xref:Microsoft.AspNetCore.Authorization.Infrastructure.DenyAnonymousAuthorizationRequirement> to the current instance, which enforces that the current user is authenticated.
 
-  Static assets under `wwwroot` are publicly accessible because the default Static File Middleware (`app.UseStaticFiles();`) is called before `UseAuthentication`. Static assets in the ***MyStaticFiles*** folder require authentication. The [sample code](https://github.com/dotnet/AspNetCore.Docs/tree/main/aspnetcore/fundamentals/static-files/samples/9.x) demonstrates this.
+  Static assets under `wwwroot` are publicly accessible because the default Static File Middleware (`app.UseStaticFiles();`) is called before `UseAuthentication`. Static assets in the ***MyStaticFiles*** folder require authentication. The [sample code](https://github.com/dotnet/AspNetCore.Docs/tree/main/aspnetcore/fundamentals/static-files/samples/8.x) demonstrates this.
 
 An alternative approach to serve files based on authorization is to:
 
 * Store them outside of `wwwroot` and any directory accessible to the Static File Middleware.
 * Serve them via an action method to which authorization is applied and return a <xref:Microsoft.AspNetCore.Mvc.FileResult> object:
 
+
   [!code-csharp[](~/fundamentals/static-files/samples/6.x/StaticFileAuth/Pages/BannerImage.cshtml.cs?name=snippet)]
 
 The preceding approach requires a page or endpoint per file. The following code returns files or uploads files for authenticated users:
 
 :::code language="csharp" source="~/fundamentals/static-files/samples/9.x/StaticFileAuth/Program.cs" id="snippet_1":::
 
+IFormFile in the preceding sample uses memory buffer for uploading. For handling large file use streaming. See [Upload large files with streaming](/mvc/models/file-uploads#upload-large-files-with-streaming).
+
 See the [StaticFileAuth](https://github.com/dotnet/AspNetCore.Docs/tree/main/aspnetcore/fundamentals/static-files/samples/9.x/StaticFileAuth) GitHub folder for the complete sample.
 
 ## Directory browsing
@@ -154,11 +170,11 @@ With `UseDefaultFiles`, requests to a folder in `wwwroot` search for:
 * `index.htm`
 * `index.html`
 
-The first file found from the list is served as though the request included the file's name. The browser URL continues to reflect the URI requested.
+The first file found from the list is served as though the request included the file's name. The browser URL continues to reflect the URI requested. For example, in the [sample app](https://github.com/dotnet/AspNetCore.Docs/tree/main/aspnetcore/fundamentals/static-files/samples/9.x/StaticFilesSample/Program.cs), a request to `https://localhost:<port>/def/` serves `default.html` from `wwwroot/def`.
 
 The following code changes the default file name to `mydefault.html`:
 
-[!code-csharp[](~/fundamentals/static-files/samples/9.x/StaticFilesSample/Program.cs?name=snippet_df2&highlight=16-19)] 
+[!code-csharp[](~/fundamentals/static-files/samples/9.x/StaticFilesSample/Program.cs?name=snippet_df2&highlight=16-19)]
 
 ### UseFileServer for default documents
 
@@ -182,9 +198,11 @@ Consider the following directory hierarchy:
   * `images`
   * `js`
 * `MyStaticFiles`
+  * `defaultFiles`
+    * `default.html`
+    * `image3.png`
   * `images`
     * `MyImage.jpg`
-  * `default.html`
 
 The following code enables the serving of static files, the default file, and directory browsing of `MyStaticFiles`:
 
@@ -199,7 +217,9 @@ Using the preceding file hierarchy and code, URLs resolve as follows:
 | URI            |      Response  |
 | ------- | ------|
 | `https://<hostname>/StaticFiles/images/MyImage.jpg` | `MyStaticFiles/images/MyImage.jpg` |
-| `https://<hostname>/StaticFiles` | `MyStaticFiles/default.html` |
+| `https://<hostname>/StaticFiles` | directory listing |
+| `https://<hostname>/StaticFiles/defaultFiles` | `MyStaticFiles/defaultFiles/default.html` |
+| `https://<hostname>/StaticFiles/defaultFiles/image3.png` | `MyStaticFiles/defaultFiles//image3.png` |
 
 If no default-named file exists in the *MyStaticFiles* directory, `https://<hostname>/StaticFiles` returns the directory listing with clickable links:
 
@@ -209,7 +229,7 @@ If no default-named file exists in the *MyStaticFiles* directory, `https://<host
 
 ## FileExtensionContentTypeProvider
 
-The <xref:Microsoft.AspNetCore.StaticFiles.FileExtensionContentTypeProvider> class contains a `Mappings` property that serves as a mapping of file extensions to MIME content types. In the following sample, several file extensions are mapped to known MIME types. The *.rtf* extension is replaced, and *.mp4* is removed:
+The <xref:Microsoft.AspNetCore.StaticFiles.FileExtensionContentTypeProvider> class contains a [Mappings](/dotnet/api/microsoft.aspnetcore.staticfiles.fileextensioncontenttypeprovider.mappings) property that serves as a mapping of file extensions to MIME content types. In the following sample, several file extensions are mapped to known MIME types. The *.rtf* extension is replaced, and *.mp4* is removed:
 
 <!-- test via /mapTest/image1.image and mapTest/test.htm3 /mapTest/TextFile.rtf -->
 [!code-csharp[](~/fundamentals/static-files/samples/9.x/StaticFilesSample/Program.cs?name=snippet_fec&highlight=19-33)] 
@@ -253,9 +273,9 @@ The following code updates the `WebRootFileProvider`, which enables the Image Ta
 ### Security considerations for static files
 
 > [!WARNING]
-> `UseDirectoryBrowser` and `UseStaticFiles` can leak secrets. Disabling directory browsing in production is highly recommended. Carefully review which directories are enabled via `UseStaticFiles` or `UseDirectoryBrowser`. The entire directory and its sub-directories become publicly accessible. Store files suitable for serving to the public in a dedicated directory, such as `<content_root>/wwwroot`. Separate these files from MVC views, Razor Pages, configuration files, etc.
+> `UseDirectoryBrowser` and `UseStaticFiles` <!-- but not MapStaticAssets --> can leak secrets. Disabling directory browsing in production is highly recommended. Carefully review which directories are enabled via `UseStaticFiles` or `UseDirectoryBrowser`. The entire directory and its sub-directories become publicly accessible. Store files suitable for serving to the public in a dedicated directory, such as `<content_root>/wwwroot`. Separate these files from MVC views, Razor Pages, configuration files, etc.
 
-* The URLs for content exposed with `UseDirectoryBrowser` and `UseStaticFiles` are subject to the case sensitivity and character restrictions of the underlying file system. For example, Windows is case insensitive, but macOS and Linux aren't.
+* The URLs for content exposed with `UseDirectoryBrowser`, `UseStaticFiles`, and `MapStaticAssets` are subject to the case sensitivity and character restrictions of the underlying file system. For example, Windows is case insensitive, but macOS and Linux aren't.
 
 * ASP.NET Core apps hosted in IIS use the [ASP.NET Core Module](xref:host-and-deploy/aspnet-core-module) to forward all requests to the app, including static file requests. The IIS static file handler isn't used and has no chance to handle requests.
 

aspnetcore/fundamentals/static-files/samples/6.x/StaticFileAuth/Program.cs

@@ -1,7 +1,7 @@
 #define DEFAULT // DEFAULT AUTH AUTH2
 #if NEVER
 #elif DEFAULT
-#region snippet
+// <snippet>
 using Microsoft.AspNetCore.Identity;
 using Microsoft.EntityFrameworkCore;
 using StaticFileAuth.Data;
@@ -38,9 +38,9 @@
 app.MapRazorPages();
 
 app.Run();
-#endregion
+// </snippet>
 #elif AUTH
-#region snippet_auth
+// <snippet_auth>
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Identity;
 using Microsoft.EntityFrameworkCore;
@@ -95,9 +95,9 @@
 app.MapRazorPages();
 
 app.Run();
-#endregion
+// </snippet_auth>
 #elif AUTH2
-#region snippet_auth2
+// <snippet_auth2>
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Identity;
 using Microsoft.EntityFrameworkCore;
@@ -135,5 +135,5 @@
 app.MapRazorPages();
 
 app.Run();
-#endregion
-#endif
+// </snippet_auth2>
+#endif

aspnetcore/fundamentals/static-files/samples/9.x/StaticFileAuth/Program.cs

@@ -131,25 +131,29 @@ async Task SaveFileWithCustomFileName(IFormFile file, string fileSaveName)
 
         if (File.Exists(filePath))
         {
-            return TypedResults.PhysicalFile(filePath, fileDownloadName: $"{fileName}");
+           return TypedResults.PhysicalFile(filePath, fileDownloadName: $"{fileName}");
         }
 
         return TypedResults.NotFound("No file found with the supplied file name");
     })
     .WithName("GetFileByName")
     .RequireAuthorization("AuthenticatedUsers");
 
-// IFormFile uses memory buffer for uploading. For handling large file use streaming instead.
-// https://learn.microsoft.com/aspnet/core/mvc/models/file-uploads#upload-large-files-with-streaming
-app.MapPost("/files", async (IFormFile file, LinkGenerator linker, HttpContext context) =>
+app.MapPost("/files", 
+       async (IFormFile file, LinkGenerator linker, HttpContext context) =>
     {
-        // Don't rely on the file.FileName as it is only metadata that can be manipulated by the end-user
-        // Take a look at the `Utilities.IsFileValid` method that takes an IFormFile and validates its signature within the AllowedFileSignatures
+        // Don't rely on the file.FileName as it is only metadata that can be
+        // manipulated by the end-user. See 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);
+        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}));
+        context.Response.Headers.Append("Location",
+                                     linker.GetPathByName(context, "GetFileByName", 
+                                     new { fileName = fileSaveName}));
         return TypedResults.Ok("File Uploaded Successfully!");
     })
     .RequireAuthorization("AdminsOnly");

aspnetcore/fundamentals/static-files/samples/9.x/StaticFileAuth/StaticFilesAuth.csproj

@@ -8,9 +8,9 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="8.0.0-preview.2.23153.2" />
-    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="8.0.0-preview.2.23153.2" />
-    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0" />
+    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="8.0.7" />
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="8.0.7" />
+    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.6.2" />
   </ItemGroup>
 
   <ItemGroup>

aspnetcore/fundamentals/static-files/samples/9.x/StaticFilesSample/wwwroot/default.html → aspnetcore/fundamentals/static-files/samples/9.x/StaticFilesSample/MyStaticFiles/defaultFiles/default.html

@@ -1,11 +1,11 @@
-<!DOCTYPE html>
+<!DOCTYPE html>
 <html>
 <head>
     <meta charset="utf-8" />
     <title>Default page</title>
 </head>
 <body>
     <h1>This is the default page </h1>
-    <b><i>default.html</i></b> in wwwroot. comment out @*@page*@ in Pages\Index.cshtml
+    <b><i>default.html</i></b> in wwwroot/def comment out @*@page*@ in Pages\Index.cshtml
 </body>
-</html>
+</html>

aspnetcore/fundamentals/static-files/samples/9.x/StaticFilesSample/Pages/Privacy.cshtml

@@ -7,4 +7,17 @@
 
 <p>RP: Use this page to detail your site's privacy policy.</p>
 
+<p>The following inmage doesn't display with app.UseStaticFiles(new StaticFileOptions </p>
 <img src="~/images/MyImage.jpg" class="img" alt="My image" asp-append-version="true" />
+<p> The following image requires:</p>
+<pre><code>
+app.UseStaticFiles(new StaticFileOptions //
+{
+  FileProvider = new PhysicalFileProvider(
+      Path.Combine(builder.Environment.ContentRootPath, "MyStaticFiles")),
+  RequestPath = "/StaticFiles"
+});
+</code></pre>
+
+<img src="~/StaticFiles/images/red-rose.jpg" class="img" alt="A red rose"
+     asp-append-version="true" />