Merge pull request #34972 from dotnet/main

Merge to Live

Author: Rick-Anderson

aspnetcore/blazor/components/layouts.md

@@ -98,7 +98,7 @@ In an app created from a [Blazor project template](xref:blazor/project-structure
 
 ### Make the layout namespace available
 
- Layout file locations and namespaces changed over time for the Blazor framework. Depending on the version of Blazor and type of Blazor app that you're building, you may need to indicate the layout's namespace when using it. When referencing a layout implementation and the layout isn't found without indicating the layout's namespace, take any of the following approaches:
+Layout file locations and namespaces changed over time for the Blazor framework. Depending on the version of Blazor and type of Blazor app that you're building, you may need to indicate the layout's namespace when using it. When referencing a layout implementation and the layout isn't found without indicating the layout's namespace, take any of the following approaches:
 
 * Add an `@using` directive to the `_Imports.razor` file for the location of the layouts. In the following example, a folder of layouts with the name `Layout` is inside a `Components` folder, and the app's namespace is `BlazorSample`:
 
@@ -206,6 +206,8 @@ Specifying a layout in `_Imports.razor` overrides a layout specified as the rout
 
 > [!WARNING]
 > Do **not** add a Razor `@layout` directive to the root `_Imports.razor` file, which results in an infinite loop of layouts. To control the default app layout, specify the layout in the <xref:Microsoft.AspNetCore.Components.Routing.Router> component. For more information, see the following [Apply a default layout to an app](#apply-a-default-layout-to-an-app) section.
+> 
+> The same condition results when using an `_Imports.razor` file to apply a layout to a folder of components with the `@layout` directive and the layout component itself is in the same folder or folder hierarchy of the `_Imports.razor` file. An infinite loop of applying the layout occurs because the `@layout` directive is also applied to the layout component. To avoid recursion problems, we recommend storing layout components in their own folder (for example, `Layouts`), away from where `_Imports.razor` files are applying them.
 
 > [!NOTE]
 > The [`@layout`](xref:mvc/views/razor#layout) Razor directive only applies a layout to routable Razor components with an [`@page`](xref:mvc/views/razor#page) directive.

aspnetcore/blazor/components/quickgrid.md

@@ -219,6 +219,40 @@ In the following example:
 
 :::moniker-end
 
+
+:::moniker range=">= aspnetcore-10.0"
+
+<!-- UPDATE 10.0 - API cross-link -->
+
+:::moniker-end
+
+### Close `QuickGrid` column options
+
+Close the `QuickGrid` column options UI with the `CloseColumnOptionsAsync` method.
+
+The following example closes the column options UI as soon as the title filter is applied:
+
+```razor
+<QuickGrid @ref="movieGrid" Items="movies">
+    <PropertyColumn Property="@(m => m.Title)" Title="Title">
+        <ColumnOptions>
+            <input type="search" @bind="titleFilter" placeholder="Filter by title" 
+                @bind:after="@(() => movieGrid.CloseColumnOptionsAsync())" />
+        </ColumnOptions>
+    </PropertyColumn>
+    <PropertyColumn Property="@(m => m.Genre)" Title="Genre" />
+    <PropertyColumn Property="@(m => m.ReleaseYear)" Title="Release Year" />
+</QuickGrid>
+
+@code {
+    private QuickGrid<Movie>? movieGrid;
+    private string titleFilter = string.Empty;
+    private IQueryable<Movie> movies = new List<Movie> { ... }.AsQueryable();
+    private IQueryable<Movie> filteredMovies => 
+        movies.Where(m => m.Title!.Contains(titleFilter));
+}
+```
+
 ## Entity Framework Core (EF Core) data source
 
 Use the factory pattern to resolve an EF Core database context that provides data to a `QuickGrid` component. For more information on why the factory pattern is recommended, see <xref:blazor/blazor-ef-core>.

aspnetcore/blazor/fundamentals/routing.md

@@ -1620,13 +1620,44 @@ For additional example code, see the [`ConfigurableNavigationLock` component in
 
 Use a <xref:Microsoft.AspNetCore.Components.Routing.NavLink> component in place of HTML hyperlink elements (`<a>`) when creating navigation links. A <xref:Microsoft.AspNetCore.Components.Routing.NavLink> component behaves like an `<a>` element, except it toggles an `active` CSS class based on whether its `href` matches the current URL. The `active` class helps a user understand which page is the active page among the navigation links displayed. Optionally, assign a CSS class name to <xref:Microsoft.AspNetCore.Components.Routing.NavLink.ActiveClass?displayProperty=nameWithType> to apply a custom CSS class to the rendered link when the current route matches the `href`.
 
+:::moniker range=">= aspnetcore-10.0"
+
 There are two <xref:Microsoft.AspNetCore.Components.Routing.NavLinkMatch> options that you can assign to the `Match` attribute of the `<NavLink>` element:
 
-* <xref:Microsoft.AspNetCore.Components.Routing.NavLinkMatch.All?displayProperty=nameWithType>: The <xref:Microsoft.AspNetCore.Components.Routing.NavLink> is active when it matches the entire current URL.
+* <xref:Microsoft.AspNetCore.Components.Routing.NavLinkMatch.All?displayProperty=nameWithType>: The <xref:Microsoft.AspNetCore.Components.Routing.NavLink> is active when it matches the current URL, ignoring the query string and fragment. To include matching on the query string/fragment, use the `Microsoft.AspNetCore.Components.Routing.NavLink.DisableMatchAllIgnoresLeftUriPart` [`AppContext` switch](/dotnet/fundamentals/runtime-libraries/system-appcontext).
 * <xref:Microsoft.AspNetCore.Components.Routing.NavLinkMatch.Prefix?displayProperty=nameWithType> (*default*): The <xref:Microsoft.AspNetCore.Components.Routing.NavLink> is active when it matches any prefix of the current URL.
 
+:::moniker-end
+
+:::moniker range="< aspnetcore-10.0"
+
+There are two <xref:Microsoft.AspNetCore.Components.Routing.NavLinkMatch> options that you can assign to the `Match` attribute of the `<NavLink>` element:
+
+* <xref:Microsoft.AspNetCore.Components.Routing.NavLinkMatch.All?displayProperty=nameWithType>: The <xref:Microsoft.AspNetCore.Components.Routing.NavLink> is active when it matches the entire current URL, including the query string and fragment.
+* <xref:Microsoft.AspNetCore.Components.Routing.NavLinkMatch.Prefix?displayProperty=nameWithType> (*default*): The <xref:Microsoft.AspNetCore.Components.Routing.NavLink> is active when it matches any prefix of the current URL.
+
+:::moniker-end
+
 In the preceding example, the Home <xref:Microsoft.AspNetCore.Components.Routing.NavLink> `href=""` matches the home URL and only receives the `active` CSS class at the app's default base path (`/`). The second <xref:Microsoft.AspNetCore.Components.Routing.NavLink> receives the `active` class when the user visits any URL with a `component` prefix (for example, `/component` and `/component/another-segment`).
 
+:::moniker range=">= aspnetcore-10.0"
+
+<!-- UPDATE 10.0 - API cross-link -->
+
+To adopt custom matching logic, subclass <xref:Microsoft.AspNetCore.Components.Routing.NavLink> and override its `ShouldMatch` method. Return `true` from the method when you want to apply the `active` CSS class:
+
+```csharp
+public class CustomNavLink : NavLink
+{
+    protected override bool ShouldMatch(string currentUriAbsolute)
+    {
+        // Custom matching logic
+    }
+}
+```
+
+:::moniker-end
+
 Additional <xref:Microsoft.AspNetCore.Components.Routing.NavLink> component attributes are passed through to the rendered anchor tag. In the following example, the <xref:Microsoft.AspNetCore.Components.Routing.NavLink> component includes the `target` attribute:
 
 ```razor

aspnetcore/fundamentals/map-static-files.md

@@ -0,0 +1,199 @@
+---
+title: Map static files in ASP.NET Core
+author: rick-anderson
+description: Learn how to serve and secure mapped static files and configure static file hosting middleware behaviors in an ASP.NET Core web app.
+monikerRange: '>= aspnetcore-8.0'
+ms.author: riande
+ms.custom: mvc
+ms.date: 3/18/2025
+uid: fundamentals/map-static-files
+---
+
+# Map static files in ASP.NET Core
+
+:::moniker range=">= aspnetcore-9.0"
+
+By [Rick Anderson](https://twitter.com/RickAndMSFT)
+
+Static files, such as HTML, CSS, images, and JavaScript, are assets an ASP.NET Core app serves directly to clients by default.
+
+For Blazor static files guidance, which adds to or supersedes the guidance in this article, see <xref:blazor/fundamentals/static-files>.
+
+## Serve static files
+
+Static files are stored within the project's [web root](xref:fundamentals/index#web-root) directory. The default directory is `{content root}/wwwroot`, but it can be changed with the <xref:Microsoft.AspNetCore.Hosting.HostingAbstractionsWebHostBuilderExtensions.UseWebRoot%2A> method. For more information, see [Content root](xref:fundamentals/index#content-root) and [Web root](xref:fundamentals/index#web-root).
+
+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,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:
+
+* `wwwroot`
+  * `css`
+  * `js`
+  * `lib`
+
+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
+
+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.
+
+<xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A>:
+* Integrates the information gathered about static web assets during the build and publish process with a runtime library that processes this information to optimize file serving to the browser.
+* Are routing endpoint conventions that optimize the delivery of static assets in an app. It's designed to work with all UI frameworks, including Blazor, Razor Pages, and MVC.
+
+### `MapStaticAssets` versus `UseStaticFiles`
+
+<xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A> is available in ASP.NET Core in .NET 9.0 and later. <xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A> must be used in versions prior to .NET 9.0.
+
+<xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A> serves static files, but it doesn't provide the same level of optimization as `MapStaticAssets`. `MapStaticAssets` is optimized for serving assets that the app has knowledge of at runtime. If the app serves assets from other locations, such as disk or embedded resources, `UseStaticFiles` should be used.
+
+The following features are supported in `UseStaticFiles` but not in `MapStaticAssets`:
+
+* [Serving files from disk or embedded resources, or other locations](xref:fundamentals/static-files#serve-files-from-multiple-locations)
+* [Serve files outside of web root](xref:fundamentals/static-files#serve-files-outside-of-web-root)
+* [Set HTTP response headers](xref:fundamentals/static-files#set-http-response-headers)
+* [Directory browsing](xref:fundamentals/static-files#directory-browsing)
+* [Serve default documents](xref:fundamentals/static-files#serve-default-documents)
+* [`FileExtensionContentTypeProvider`](xref:fundamentals/static-files#fileextensioncontenttypeprovider)
+* [Serve files from multiple locations](xref:fundamentals/static-files#serve-files-from-multiple-locations)
+* [Serving files from disk or embedded resources, or other locations](xref:fundamentals/static-files#serve-files-from-multiple-locations)
+* [Serve files outside of web root](xref:fundamentals/static-files#serve-files-outside-of-web-root)
+* [Set HTTP response headers](xref:fundamentals/static-files#set-http-response-headers)
+* [Directory browsing](xref:fundamentals/static-files#directory-browsing)
+* [Serve default documents](xref:fundamentals/static-files#serve-default-documents)
+* [`FileExtensionContentTypeProvider`](xref:fundamentals/static-files#fileextensioncontenttypeprovider)
+* [Serve files from multiple locations](xref:fundamentals/static-files#serve-files-from-multiple-locations)
+
+### Serve files in web root
+
+The default web app templates call the <xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A> 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)]
+
+The parameterless `MapStaticAssets` method overload marks the files in [web root](xref:fundamentals/index#web-root) as servable. The following markup references `wwwroot/images/MyImage.jpg`:
+
+```html
+<img src="~/images/MyImage.jpg" class="img" alt="My image" />
+```
+
+In the preceding markup, the tilde character `~` points to the [web root](xref:fundamentals/index#web-root).
+
+### Serve files outside of web root
+
+Consider a directory hierarchy in which the static files to be served reside outside of the [web root](xref:fundamentals/index#web-root):
+
+* `wwwroot`
+  * `css`
+  * `images`
+  * `js`
+* `MyStaticFiles`
+  * `images`
+    * `red-rose.jpg`
+
+A request can access the `red-rose.jpg` file by configuring the Static File Middleware as follows:
+
+[!code-csharp[](~/fundamentals/static-files/samples/9.x/StaticFilesSample/Program.cs?name=snippet_rr&highlight=1,18-23)]
+
+In the preceding code, the *MyStaticFiles* directory hierarchy is exposed publicly via the *StaticFiles* URI segment. A request to `https://<hostname>/StaticFiles/images/red-rose.jpg` serves the `red-rose.jpg` file.
+
+The following markup references `MyStaticFiles/images/red-rose.jpg`:
+<!-- zz test via /Home2/MyStaticFilesRR -->
+[!code-html[](~/fundamentals/static-files/samples/9.x/StaticFilesSample/Views/Home2/MyStaticFilesRR.cshtml?range=1)]
+
+To serve files from multiple locations, see [Serve files from multiple locations](xref:fundamentals/static-files#serve-files-from-multiple-locations).
+
+### Set HTTP response headers
+
+A <xref:Microsoft.AspNetCore.Builder.StaticFileOptions> object can be used to set HTTP response headers. In addition to configuring static file serving from the [web root](xref:fundamentals/index#web-root), the following code sets the [Cache-Control](https://developer.mozilla.org/docs/Web/HTTP/Headers/Cache-Control) header:
+
+[!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.
+
+## Static file authorization
+
+The ASP.NET Core templates call <xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A> before calling <xref:Microsoft.AspNetCore.Builder.AuthorizationAppBuilderExtensions.UseAuthorization%2A>. Most apps follow this pattern. When `MapStaticAssets` 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.
+  
+To serve static files based on authorization, see [Static file authorization](xref:fundamentals/static-files#static-file-authorization).
+
+## Serve files from multiple locations
+
+Consider the following Razor page which displays the `/MyStaticFiles/image3.png` file:
+
+[!code-cshtml[](~/fundamentals/static-files/samples/9.x/StaticFilesSample/Pages/Test.cshtml?highlight=5)]
+
+`UseStaticFiles` and `UseFileServer` default to the file provider pointing at `wwwroot`. Additional instances of `UseStaticFiles` and `UseFileServer` can be provided with other file providers to serve files from other locations. The following example calls `UseStaticFiles` twice to serve files from both `wwwroot` and `MyStaticFiles`:
+
+[!code-csharp[](~/fundamentals/static-files/samples/9.x/StaticFilesSample/Program.cs?name=snippet_mul)]
+
+Using the preceding code:
+
+* The `/MyStaticFiles/image3.png` file is displayed.
+* The [Image Tag Helpers](xref:mvc/views/tag-helpers/builtin-th/image-tag-helper) <xref:Microsoft.AspNetCore.Mvc.TagHelpers.ImageTagHelper.AppendVersion> is not applied because the Tag Helpers depend on <xref:Microsoft.AspNetCore.Hosting.IWebHostEnvironment.WebRootFileProvider>. `WebRootFileProvider` has not been updated to include the `MyStaticFiles` folder.
+
+The following code updates the `WebRootFileProvider`, which enables the Image Tag Helper to provide a version:
+
+[!code-csharp[](~/fundamentals/static-files/samples/9.x/StaticFilesSample/Program.cs?name=snippet_mult2)]
+
+> [!NOTE]
+> The preceding approach applies to Razor Pages and MVC apps. For guidance that applies to Blazor Web Apps, see <xref:blazor/fundamentals/static-files#serve-files-from-multiple-locations>.
+
+## Serve files outside wwwroot by updating IWebHostEnvironment.WebRootPath
+
+When <xref:Microsoft.AspNetCore.Hosting.IWebHostEnvironment.WebRootPath%2A?displayProperty=nameWithType> is set to a folder other than `wwwroot`:
+
+* In the development environment, static assets found in both `wwwroot` and the updated `IWebHostEnvironment.WebRootPath` are served from `wwwroot`.
+* In any environment other than development, duplicate static assets are served from the updated `IWebHostEnvironment.WebRootPath` folder.
+
+Consider a web app created with the empty web template:
+
+* Containing an `Index.html` file in `wwwroot` and `wwwroot-custom`.
+* With the following updated `Program.cs` file that sets `WebRootPath = "wwwroot-custom"`:
+
+  [!code-csharp[](~/fundamentals/static-files/samples/9.x/WebRoot/Program.cs?name=snippet1)]
+
+In the preceding code, requests to `/`:
+
+* In the development environment return `wwwroot/Index.html`
+* In any environment other than development return `wwwroot-custom/Index.html`
+
+To ensure assets from `wwwroot-custom` are returned, use one of the following approaches:
+
+* Delete duplicate named assets in `wwwroot`.
+* Set `"ASPNETCORE_ENVIRONMENT"` in `Properties/launchSettings.json` to any value other than `"Development"`.
+* Completely disable static web assets by setting `<StaticWebAssetsEnabled>false</StaticWebAssetsEnabled>` in the project file. ***WARNING, disabling static web assets disables [Razor Class Libraries](xref:razor-pages/ui-class)***.
+* Add the following XML to the project file:
+
+  ```xml
+  <ItemGroup>
+	  <Content Remove="wwwroot\**" />
+  </ItemGroup>
+  ```
+
+The following code updates `IWebHostEnvironment.WebRootPath` to a non development value, guaranteeing duplicate content is returned from `wwwroot-custom` rather than `wwwroot`:
+
+[!code-csharp[](~/fundamentals/static-files/samples/9.x/WebRoot/Program.cs?name=snippet2&highlight=5)]
+
+## Additional resources
+
+* [View or download sample code](https://github.com/dotnet/AspNetCore.Docs/tree/main/aspnetcore/fundamentals/static-files/samples) ([how to download](xref:index#how-to-download-a-sample))
+* [Middleware](xref:fundamentals/middleware/index)
+* [Introduction to ASP.NET Core](xref:index)
+* <xref:blazor/file-uploads>
+* <xref:blazor/file-downloads>
+
+:::moniker-end