Skip to content

Commit 1b4668e

Browse files
danroth27danroth27
authored
.NET 9 migration guidance edit suggestions for MapStaticAssets (#34032)
1 parent 1447385 commit 1b4668e

File tree

1 file changed

+29
-22
lines changed

1 file changed

+29
-22
lines changed

‎aspnetcore/migration/80-90.md‎

Lines changed: 29 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -72,38 +72,45 @@ In the project file, update each [`Microsoft.AspNetCore.*`](https://www.nuget.or
7272

7373
## Replace `UseStaticFiles` with `MapStaticAssets`
7474

75-
Blazor has different update instructions for implementing Map Static Assets routing endpoint conventions than ASP.NET Core Razor Pages and MVC.
75+
Optimize the handling of static files in your web apps by replacing <xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A> with <xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A> in the app's `Program` file:
76+
77+
```diff
78+
- app.UseStaticFiles();
79+
+ app.MapStaticAssets();
80+
```
81+
82+
In MVC & Razor Pages apps you additionally need to 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>.
83+
84+
ASP.NET Core automatically fingerprints and precompresses your static files at build and publish time, and then <xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A> surfaces the optimized files as endpoints using endpoint routing with appropriate caching headers.
7685

77-
### Blazor Web App implementation
7886

79-
* Replace <xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A> with <xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A> in the app's `Program` file:
8087

81-
```diff
82-
- app.UseStaticFiles();
83-
+ app.MapStaticAssets();
84-
```
88+
To resolve the fingerprinted file names from your app:
8589

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`):
90+
* In Blazor apps, use the <xref:Microsoft.AspNetCore.Components.ComponentBase.Assets?displayProperty=nameWithType> property. 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. Note that 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`):
8791

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-
```
92+
```razor
93+
<link rel="stylesheet" href="@Assets["bootstrap/bootstrap.min.css"]" />
94+
<link rel="stylesheet" href="@Assets["app.css"]" />
95+
<link rel="stylesheet" href="@Assets["BlazorSample.styles.css"]" />
96+
```
97+
98+
* In MVC & Razor Pages apps, the script and link tag helpers will automatically resolve the fingerprinted file names.
9399
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`):
100+
To resolve the fingerprinted file names when importing JavaScript modules, add a generated [import map](https://developer.mozilla.org/docs/Web/HTML/Element/script/type/importmap):
95101
96-
```razor
97-
<ImportMap />
98-
```
102+
* In Blazor apps, add the (<xref:Microsoft.AspNetCore.Components.ImportMap>) component to the `<head>` content of the app's root component, typically in the `App` component (`App.razor`):
99103
100-
For more information, see <xref:blazor/fundamentals/static-files>.
104+
```razor
105+
<ImportMap />
106+
```
101107

102-
### ASP.NET Core Razor Pages and MVC implementation
108+
* In MVC & Razor pages apps, add `<script type="importmap"></script>` to the head of the main layout file, which is updated by the Import Map Tag Helper.
109+
110+
For more information, see the following resources:
103111

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>.
106-
* Add `<script type="importmap"></script>` to the head of the main layout file.
112+
* <xref:aspnetcore-9#static-asset-delivery-optimization>
113+
* <xref:blazor/fundamentals/static-files>
107114

108115
## Blazor
109116

0 commit comments

Comments
 (0)