Skip to content

Commit 70cc81b

Browse files
guardrexguardrex
authored
Map Static Assets updates (#34009)
1 parent 39324ff commit 70cc81b

File tree

7 files changed

+58
-41
lines changed

7 files changed

+58
-41
lines changed

‎aspnetcore/blazor/file-downloads.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ Files can be downloaded from the app's own static assets or from any other locat
2020

2121
:::moniker range=">= aspnetcore-9.0"
2222

23-
* ASP.NET Core apps use Map Static Assets Middleware or Static File Middleware to serve files to clients of server-side apps. For more information, see <xref:blazor/fundamentals/static-files>.
23+
* ASP.NET Core apps use Map Static Assets routing endpoint conventions or Static File Middleware to serve files to clients of server-side apps. For more information, see <xref:blazor/fundamentals/static-files>.
2424
* The guidance in this article also applies to other types of file servers that don't use .NET, such as Content Delivery Networks (CDNs).
2525

2626
:::moniker-end

‎aspnetcore/blazor/fundamentals/static-files.md‎

Lines changed: 19 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -14,20 +14,18 @@ uid: blazor/fundamentals/static-files
1414

1515
This article describes Blazor app configuration for serving static files.
1616

17-
## Static asset middleware
18-
19-
*This section applies to server-side Blazor apps.*
17+
## Static asset delivery in server-side Blazor apps
2018

2119
:::moniker range=">= aspnetcore-9.0"
2220

23-
Serving static assets is managed by either of the two middlewares described in the following table.
21+
Serving static assets is managed by either routing endpoint conventions or a middleware described in the following table.
2422

25-
Middleware | API | .NET Version | Description
23+
Feature | API | .NET Version | Description
2624
--- | --- | :---: | ---
27-
Map Static Assets | <xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A> | .NET 9 or later | Optimizes the delivery of static assets to clients.
28-
Static Files | <xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A> | All .NET versions | Serves static assets to clients without the optimizations of Map Static Assets Middleware but useful for some tasks that Map Static Assets Middleware isn't capable of managing.
25+
Map Static Assets routing endpoint conventions | <xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A> | .NET 9 or later | Optimizes the delivery of static assets to clients.
26+
Static Files Middleware | <xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A> | All .NET versions | Serves static assets to clients without the optimizations of Map Static Assets but useful for some tasks that Map Static Assets isn't capable of managing.
2927

30-
Configure Map Static Assets Middleware by calling <xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A> in the app's request processing pipeline, which performs the following:
28+
Configure Map Static Assets by calling <xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A> in the app's request processing pipeline, which performs the following:
3129

3230
* Sets the [ETag](https://developer.mozilla.org/docs/Web/HTTP/Headers/ETag) and [Last-Modified](https://developer.mozilla.org/docs/Web/HTTP/Headers/Last-Modified) headers.
3331
* Sets [caching headers](https://developer.mozilla.org/docs/Web/HTTP/Headers/Cache-Control).
@@ -36,13 +34,13 @@ Configure Map Static Assets Middleware by calling <xref:Microsoft.AspNetCore.Bui
3634
* Works with a [Content Delivery Network (CDN)](https://developer.mozilla.org/docs/Glossary/CDN) (for example, [Azure CDN](https://azure.microsoft.com/services/cdn/)) to serve the app's static assets closer to the user.
3735
* [Fingerprinting assets](https://developer.mozilla.org/docs/Glossary/Fingerprinting) to prevent reusing old versions of files.
3836

39-
Map Static Assets Middleware operates by combining build and publish processes to collect information about the static assets in the app. This information is utilized by the runtime library to efficiently serve the static assets to browsers.
37+
Map Static Assets operates by combining build and publish processes to collect information about the static assets in the app. This information is utilized by the runtime library to efficiently serve the static assets to browsers.
4038

41-
Map Static Assets Middleware can replace <xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A> in most situations. However, Map Static Assets Middleware is optimized for serving the assets from known locations in the app at build and publish time. If the app serves assets from other locations, such as disk or embedded resources, <xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A> should be used.
39+
Map Static Assets can replace <xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A> in most situations. However, Map Static Assets is optimized for serving the assets from known locations in the app at build and publish time. If the app serves assets from other locations, such as disk or embedded resources, <xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A> should be used.
4240

43-
Map Static Assets Middleware (<xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A>) replaces calling <xref:Microsoft.AspNetCore.Builder.ComponentsWebAssemblyApplicationBuilderExtensions.UseBlazorFrameworkFiles%2A> in apps that serve Blazor WebAssembly framework files, and explicitly calling <xref:Microsoft.AspNetCore.Builder.ComponentsWebAssemblyApplicationBuilderExtensions.UseBlazorFrameworkFiles%2A> in a Blazor Web App isn't necessary because the API is automatically called when invoking <xref:Microsoft.Extensions.DependencyInjection.WebAssemblyRazorComponentsBuilderExtensions.AddInteractiveWebAssemblyComponents%2A>.
41+
Map Static Assets (<xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A>) replaces calling <xref:Microsoft.AspNetCore.Builder.ComponentsWebAssemblyApplicationBuilderExtensions.UseBlazorFrameworkFiles%2A> in apps that serve Blazor WebAssembly framework files, and explicitly calling <xref:Microsoft.AspNetCore.Builder.ComponentsWebAssemblyApplicationBuilderExtensions.UseBlazorFrameworkFiles%2A> in a Blazor Web App isn't necessary because the API is automatically called when invoking <xref:Microsoft.Extensions.DependencyInjection.WebAssemblyRazorComponentsBuilderExtensions.AddInteractiveWebAssemblyComponents%2A>.
4442

45-
Map Static Assets Middleware provides the following benefits that aren't available when calling <xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A>:
43+
Map Static Assets provides the following benefits that aren't available when calling <xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A>:
4644

4745
* Build-time compression for all the assets in the app, including JavaScript (JS) and stylesheets but excluding image and font assets that are already compressed. [Gzip](https://tools.ietf.org/html/rfc1952) (`Content-Encoding: gz`) compression is used during development. Gzip with [Brotli](https://tools.ietf.org/html/rfc7932) (`Content-Encoding: br`) compression is used during publish.
4846
* [Fingerprinting](https://developer.mozilla.org/docs/Glossary/Fingerprinting) for all assets at build time with a [Base64](https://developer.mozilla.org/docs/Glossary/Base64)-encoded string of the [SHA-256](xref:System.Security.Cryptography.SHA256) hash of each file's content. This prevents reusing an old version of a file, even if the old file is cached. Fingerprinted assets are cached using the [`immutable` directive](https://developer.mozilla.org/docs/Web/HTTP/Headers/Cache-Control#directives), which results in the browser never requesting the asset again until it changes. For browsers that don't support the `immutable` directive, a [`max-age` directive](https://developer.mozilla.org/docs/Web/HTTP/Headers/Cache-Control#directives) is added.
@@ -61,40 +59,40 @@ When [Interactive WebAssembly or Interactive Auto render modes](xref:blazor/fund
6159
* During WebAssembly boot, Blazor retrieves the URL, imports the module, and calls a function to retrieve the asset collection and reconstruct it in memory. The URL is specific to the content and cached forever, so this overhead cost is only paid once per user until the app is updated.
6260
* The resource collection is also exposed at a human-readable URL (`_framework/resource-collection.js`), so JS has access to the resource collection for [enhanced navigation](xref:blazor/fundamentals/routing#enhanced-navigation-and-form-handling) or to implement features of other frameworks and third-party components.
6361

64-
Map Static Assets Middleware doesn't provide features for minification or other file transformations. Minification is usually handled by custom code or [third-party tooling](xref:blazor/fundamentals/index#community-links-to-blazor-resources).
62+
Map Static Assets doesn't provide features for minification or other file transformations. Minification is usually handled by custom code or [third-party tooling](xref:blazor/fundamentals/index#community-links-to-blazor-resources).
6563

66-
Static File Middleware (<xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A>) is useful in the following situations that Map Static Assets Middleware (<xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A>) can't handle:
64+
Static File Middleware (<xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A>) is useful in the following situations that Map Static Assets (<xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A>) can't handle:
6765

6866
* Applying a path prefix to Blazor WebAssembly static asset files, which is covered in the [Prefix for Blazor WebAssembly assets](#prefix-for-blazor-webassembly-assets) section.
6967
* Configuring file mappings of extensions to specific content types and setting static file options, which is covered in the [File mappings and static file options](#file-mappings-and-static-file-options) section.
7068

7169
For more information, see <xref:fundamentals/static-files>.
7270

73-
## Consume assets with Map Static File Middleware
71+
## Deliver assets with Map Static Assets routing endpoint conventions
7472

7573
*This section applies to server-side Blazor apps.*
7674

7775
<!-- UPDATE 10.0 Compiler implementation for tilde/slash-based HREFs. -->
7876

79-
Assets are consumed via the `ComponentBase.Assets` property, which resolves the fingerprinted URL for a given asset. In the following example, Bootstrap, the Blazor project template app stylesheet (`app.css`), and the [CSS isolation stylesheet](xref:blazor/components/css-isolation) are linked in a root component, typically the `App` component (`Components/App.razor`):
77+
Assets are delivered via the <xref:Microsoft.AspNetCore.Components.ComponentBase.Assets?displayProperty=nameWithType> property, which resolves the fingerprinted URL for a given asset. In the following example, Bootstrap, the Blazor project template app stylesheet (`app.css`), and the [CSS isolation stylesheet](xref:blazor/components/css-isolation) (based on an app's namespace of `BlazorSample`) are linked in a root component, typically the `App` component (`Components/App.razor`):
8078

8179
```razor
8280
<link rel="stylesheet" href="@Assets["bootstrap/bootstrap.min.css"]" />
8381
<link rel="stylesheet" href="@Assets["app.css"]" />
84-
<link rel="stylesheet" href="@Assets["BlazorWeb-CSharp.styles.css"]" />
82+
<link rel="stylesheet" href="@Assets["BlazorSample.styles.css"]" />
8583
```
8684

8785
## Import maps
8886

8987
*This section applies to server-side Blazor apps.*
9088

91-
The `ImportMap` component represents an import map element (`<script type="importmap"></script>`) that defines the import map for module scripts. The `ImportMap` component is placed in `<head>` content of the root component, typically the `App` component (`Components/App.razor`).
89+
The Import Map component (<xref:Microsoft.AspNetCore.Components.ImportMap>) represents an import map element (`<script type="importmap"></script>`) that defines the import map for module scripts. The Import Map component is placed in `<head>` content of the root component, typically the `App` component (`Components/App.razor`).
9290

9391
```razor
9492
<ImportMap />
9593
```
9694

97-
If a custom `ImportMapDefinition` isn't assigned to an `ImportMap` component, the import map is generated based on the app's assets.
95+
If a custom <xref:Microsoft.AspNetCore.Components.ImportMapDefinition> isn't assigned to an Import Map component, the import map is generated based on the app's assets.
9896

9997
The following examples demonstrate custom import map definitions and the import maps that they create.
10098

@@ -175,9 +173,9 @@ The preceding code results in the following import map:
175173
}
176174
```
177175

178-
Combine import map definitions (`ImportMapDefinition`) with `ImportMapDefinition.Combine`.
176+
Combine import map definitions (<xref:Microsoft.AspNetCore.Components.ImportMapDefinition>) with <xref:Microsoft.AspNetCore.Components.ImportMapDefinition.Combine%2A?displayProperty=nameWithType>.
179177

180-
Import map created from a `ResourceAssetCollection` that maps static assets to their corresponding unique URLs:
178+
Import map created from a <xref:Microsoft.AspNetCore.Components.ResourceAssetCollection> that maps static assets to their corresponding unique URLs:
181179

182180
```csharp
183181
ImportMapDefinition.FromResourceCollection(

‎aspnetcore/blazor/tutorials/movie-database-app/part-1.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -331,7 +331,7 @@ app.UseAntiforgery();
331331

332332
:::moniker range=">= aspnetcore-9.0"
333333

334-
Map Static Assets Middleware (<xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A>) maps static files, such as images, scripts, and stylesheets, produced during the build as endpoints:
334+
Map Static Assets routing endpoint conventions (<xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A>) maps static files, such as images, scripts, and stylesheets, produced during the build as endpoints:
335335

336336
```csharp
337337
app.MapStaticAssets();

‎aspnetcore/fundamentals/static-files.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -49,14 +49,14 @@ Creating performant web apps requires optimizing asset delivery to the browser.
4949
* Use a [CDN](/microsoft-365/enterprise/content-delivery-networks?view=o365-worldwide&preserve-view=true) to serve the assets closer to the user.
5050
* Minimize the size of assets served to the browser. This optimization doesn't include minification.
5151

52-
[`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.
52+
<xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A> 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.
5353

5454
[`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
5555
](xref:aspnetcore-9#optimizing-static-web-asset-delivery).
5656

5757
### Serve files in web root
5858

59-
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:
59+
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:
6060

6161
[!code-csharp[](~/fundamentals/static-files/samples/9.x/StaticFilesSample/Program.cs?name=snippet&highlight=15)]
6262

@@ -102,7 +102,7 @@ The preceding code makes static files publicly available in the local cache for
102102

103103
## Static file authorization
104104

105-
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:
105+
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 the Static File Middleware is called before the authorization middleware:
106106

107107
* No authorization checks are performed on the static files.
108108
* Static files served by the Static File Middleware, such as those under `wwwroot`, are publicly accessible.

‎aspnetcore/migration/80-90.md‎

Lines changed: 28 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -70,20 +70,39 @@ In the project file, update each [`Microsoft.AspNetCore.*`](https://www.nuget.or
7070
</ItemGroup>
7171
```
7272

73-
## Replace UseStaticFiles with MapStaticAssets
73+
## Replace `UseStaticFiles` with `MapStaticAssets`
7474

75-
Blazor has different update instructions for `MapStaticAssets` than Razor Pages and ASP.NET Core MVC.
75+
Blazor has different update instructions for implementing Map Static Assets routing endpoint conventions than ASP.NET Core Razor Pages and MVC.
7676

77-
### Blazor web apps
77+
### Blazor Web App implementation
7878

79-
* Replace [UseStaticFiles](/dotnet/api/microsoft.aspnetcore.builder.staticfileextensions.usestaticfiles) with [MapStaticAssets](/dotnet/api/microsoft.aspnetcore.builder.staticassetsendpointroutebuilderextensions.mapstaticassets) in `Program.cs`
80-
* Update explicit references to static assets in `.razor` files to use the `@Assets["asset-path"]` API. This should ***NOT*** be done for the Blazor framework scripts (`*blazor.\*.js*`).
81-
* Update the root `App.razor` component to include the `<ImportMap />` component in the head.
79+
* Replace <xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A> with <xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A> in the app's `Program` file:
8280

83-
### Razor Pages and ASP.NET Core MVC based apps
81+
```diff
82+
- app.UseStaticFiles();
83+
+ app.MapStaticAssets();
84+
```
8485

85-
* Replace [UseStaticFiles](/dotnet/api/microsoft.aspnetcore.builder.staticfileextensions.usestaticfiles) with [MapStaticAssets](/dotnet/api/microsoft.aspnetcore.builder.staticassetsendpointroutebuilderextensions.mapstaticassets) in `Program.cs`
86-
* Chain a call to `.WithStaticAssets` after `MapRazorPages` or `MapControllerRoute` in `Program.cs`. For an example, see the <xref:fundamentals/static-files?view=aspnetcore-9.0&preserve-view=true>
86+
* Assets are delivered via the <xref:Microsoft.AspNetCore.Components.ComponentBase.Assets?displayProperty=nameWithType> property, which resolves the fingerprinted URL for a given asset. Update explicit references to static assets in Razor component files (`.razor`) to use `@Assets["{ASSET PATH}"]`, where the `{ASSET PATH}` placeholder is the path to the asset. This should ***NOT*** be done for the Blazor framework scripts (`blazor.*.js`). In the following example, Bootstrap, the Blazor project template app stylesheet (`app.css`), and the [CSS isolation stylesheet](xref:blazor/components/css-isolation) (based on an app's namespace of `BlazorSample`) are linked in a root component, typically the `App` component (`Components/App.razor`):
87+
88+
```razor
89+
<link rel="stylesheet" href="@Assets["bootstrap/bootstrap.min.css"]" />
90+
<link rel="stylesheet" href="@Assets["app.css"]" />
91+
<link rel="stylesheet" href="@Assets["BlazorSample.styles.css"]" />
92+
```
93+
94+
* Add the Import Map component (<xref:Microsoft.AspNetCore.Components.ImportMap>) to the `<head>` content of the app's root component, typically the `App` component (`App.razor`):
95+
96+
```razor
97+
<ImportMap />
98+
```
99+
100+
For more information, see <xref:blazor/fundamentals/static-files>.
101+
102+
### ASP.NET Core Razor Pages and MVC implementation
103+
104+
* Replace <xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A> with <xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A> in `Program.cs`.
105+
* Chain a call to `.WithStaticAssets` after `MapRazorPages` or `MapControllerRoute` in `Program.cs`. For an example, see the <xref:fundamentals/static-files?view=aspnetcore-9.0&preserve-view=true>.
87106
* Add `<script type="importmap"></script>` to the head of the main layout file.
88107

89108
## Blazor

0 commit comments

Comments
 (0)