You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: aspnetcore/fundamentals/index.md
+5-5Lines changed: 5 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@ description: Learn the fundamental concepts for building ASP.NET Core apps, incl
5
5
monikerRange: '>= aspnetcore-3.1'
6
6
ms.author: tdykstra
7
7
ms.custom: mvc
8
-
ms.date: 08/01/2024
8
+
ms.date: 07/23/2025
9
9
uid: fundamentals/index
10
10
---
11
11
# ASP.NET Core fundamentals overview
@@ -210,9 +210,9 @@ The content root is the base path for:
210
210
* Razor files (`.cshtml`, `.razor`)
211
211
* Configuration files (`.json`, `.xml`)
212
212
* Data files (`.db`)
213
-
* The [Web root](#web-root), typically the *wwwroot* folder.
213
+
* The [Web root](#web-root), typically the `wwwroot` folder.
214
214
215
-
During development, the content root defaults to the project's root directory. This directory is also the base path for both the app's content files and the [Web root](#web-root). Specify a different content root by setting its path when [building the host](#host). For more information, see [Content root](xref:fundamentals/host/generic-host#contentroot).
215
+
During development, the content root defaults to the project's root directory. This directory is also the base path for both the app's content files and the [web root](#web-root). Specify a different content root by setting its path when [building the host](#host). For more information, see [Content root](xref:fundamentals/host/generic-host#contentroot).
216
216
217
217
## Web root
218
218
@@ -222,9 +222,9 @@ The web root is the base path for public, static resource files, such as:
222
222
* JavaScript (`.js`)
223
223
* Images (`.png`, `.jpg`)
224
224
225
-
By default, static files are served only from the web root directory and its sub-directories. The web root path defaults to *{content root}/wwwroot*. Specify a different web root by setting its path when [building the host](#host). For more information, see [Web root](xref:fundamentals/host/generic-host#webroot).
225
+
By default, static files are served only from the web root directory and its sub-directories. The web root path defaults to `{CONTENT ROOT}/wwwroot`, where the `{CONTENT ROOT}` placeholder is the content root. Specify a different web root by setting its path when [building the host](#host). For more information, see [Web root](xref:fundamentals/host/generic-host#webroot).
226
226
227
-
Prevent publishing files in *wwwroot* with the [\<Content> project item](/visualstudio/msbuild/common-msbuild-project-items#content) in the project file. The following example prevents publishing content in *wwwroot/local* and its sub-directories:
227
+
Prevent publishing files in `wwwroot` with the [`<Content>` project item](/visualstudio/msbuild/common-msbuild-project-items#content) in the project file. The following example prevents publishing content in `wwwroot/local` and its sub-directories:
By [Rick Anderson](https://twitter.com/RickAndMSFT)
20
-
21
19
Static files, such as HTML, CSS, images, and JavaScript, are assets an ASP.NET Core app serves directly to clients by default.
22
20
23
21
For Blazor static files guidance, which adds to or supersedes the guidance in this article, see <xref:blazor/fundamentals/static-files>.
24
22
25
-
## Serve static files
26
-
27
-
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).
28
-
29
-
The <xref:Microsoft.AspNetCore.Builder.WebApplication.CreateBuilder%2A> method sets the content root to the current directory:
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:
34
-
35
-
*`wwwroot`
36
-
*`css`
37
-
*`js`
38
-
*`lib`
39
-
40
-
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`
Creating performant web apps requires optimizing asset delivery to the browser. Possible optimizations with <xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A> include:
45
26
46
-
* 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) and [Last-Modified](https://developer.mozilla.org/docs/Web/HTTP/Headers/Last-Modified) headers.
47
-
* 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.
48
-
* Set up proper [caching headers](https://developer.mozilla.org/docs/Web/HTTP/Headers/Cache-Control).
27
+
* 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) and [Last-Modified](https://developer.mozilla.org/docs/Web/HTTP/Headers/Last-Modified) headers.
28
+
* 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.
29
+
* Set appropriate [caching headers](https://developer.mozilla.org/docs/Web/HTTP/Headers/Cache-Control) on the response.
49
30
* Use [Caching Middleware](xref:performance/caching/middleware).
50
31
* Serve [compressed](/aspnet/core/performance/response-compression) versions of the assets when possible. This optimization doesn't include minification.
51
32
* Use a [CDN](/microsoft-365/enterprise/content-delivery-networks?view=o365-worldwide&preserve-view=true) to serve the assets closer to the user.
52
-
*[Fingerprinting assets](https://en.wikipedia.org/wiki/Fingerprint_(computing)) to prevent reusing old versions of files.
33
+
*[Fingerprinting assets](https://wikipedia.org/wiki/Fingerprint_(computing)) to prevent reusing old versions of files.
53
34
54
35
`MapStaticAssets`:
55
36
@@ -78,13 +59,6 @@ Map Static Assets doesn't provide features for minification or other file transf
78
59
79
60
The following features are supported with `UseStaticFiles` but not with `MapStaticAssets`:
80
61
81
-
*[Serving files from disk or embedded resources, or other locations](xref:fundamentals/static-files#serve-files-from-multiple-locations)
82
-
*[Serve files outside of web root](xref:fundamentals/static-files#serve-files-outside-of-web-root)
@@ -95,21 +69,37 @@ The following features are supported with `UseStaticFiles` but not with `MapStat
95
69
96
70
### Serve files in web root
97
71
98
-
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:
72
+
In the app's `Program` file, <xref:Microsoft.AspNetCore.Builder.WebApplication.CreateBuilder%2A?displayProperty=nameWithType> sets the [content root](xref:fundamentals/index#content-root) to the current directory. Call <xref:Microsoft.AspNetCore.Builder.StaticAssetsEndpointRouteBuilderExtensions.MapStaticAssets%2A> method to enable serving static files. The parameterless overload results in serving the files from the app's [web root](xref:fundamentals/index#web-root). The default web root directory is `{CONTENT ROOT}/wwwroot`, where the `{CONTENT ROOT}` placeholder is the content root.
73
+
74
+
```csharp
75
+
varbuilder=WebApplication.CreateBuilder(args);
76
+
77
+
...
78
+
79
+
app.MapStaticAssets();
80
+
```
81
+
82
+
You can change the web root with the <xref:Microsoft.AspNetCore.Hosting.HostingAbstractionsWebHostBuilderExtensions.UseWebRoot%2A> method. For more information, see the [Content root](xref:fundamentals/index#content-root) and [Web root](xref:fundamentals/index#web-root) sections of the *ASP.NET Core fundamentals overview* article.
Static files are accessible via a path relative to the web root. For example, the Blazor Web App project template contains the `lib` folder within the `wwwroot` folder, which contains Bootstrap static assets.
101
85
102
-
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`:
86
+
If an app placed its images in an `images` folder in `wwwroot`, the following markup references `wwwroot/images/favicon.png`:
In Razor Pages and MVC apps (but not Blazor apps), the tilde character `~` points to the web root. In the following example, `~/images/icon.jpg` loads the icon image (`icon.jpg`) from the app's `wwwroot/images` folder:
93
+
94
+
```cshtml
95
+
<img src="~/images/icon.jpg" alt="Icon image" />
106
96
```
107
97
108
-
In the preceding markup, the tilde character `~` points to the [web root](xref:fundamentals/index#web-root).
98
+
The URL format for the preceding example is `https://{HOST}/images/{FILE NAME}`. The `{HOST}` placeholder is the host, and the `{FILE NAME}` placeholder is the file name. For the preceding example running at the app's localhost address on port 5001, the absolute URL is `https://localhost:5001/images/icon.jpg`.
109
99
110
100
### Serve files outside of web root
111
101
112
-
Consider a directory hierarchy in which the static files to be served reside outside of the [web root](xref:fundamentals/index#web-root):
102
+
Consider the following directory hierarchy with static files residing outside of the app's [web root](xref:fundamentals/index#web-root) in a folder named `MyStaticFiles`:
113
103
114
104
*`wwwroot`
115
105
*`css`
@@ -121,19 +111,19 @@ Consider a directory hierarchy in which the static files to be served reside out
121
111
122
112
A request can access the `red-rose.jpg` file by configuring the Static File Middleware as follows:
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.
116
+
In the preceding code, the `MyStaticFiles` directory hierarchy is exposed publicly via the `StaticFiles` URL segment. A request to `https://{HOST}/StaticFiles/images/red-rose.jpg`, where the `{HOST}` placeholder is the host, serves the `red-rose.jpg` file.
127
117
128
118
The following markup references `MyStaticFiles/images/red-rose.jpg`:
To serve files from multiple locations, see [Serve files from multiple locations](xref:fundamentals/static-files#serve-files-from-multiple-locations).
133
123
134
124
### Set HTTP response headers
135
125
136
-
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:
126
+
A <xref:Microsoft.AspNetCore.Builder.StaticFileOptions> object can be used to set HTTP response headers. In addition to configuring the middleware to serve static files 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:
@@ -143,9 +133,9 @@ The preceding code makes static files publicly available in the local cache for
143
133
144
134
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:
145
135
146
-
* No authorization checks are performed on the static files.
147
-
* Static files served by the Static File Middleware, such as those under `wwwroot`, are publicly accessible.
148
-
136
+
* No authorization checks are performed on the static files.
137
+
* Static files served by the Static File Middleware, such as those under `wwwroot`, are publicly accessible.
138
+
149
139
To serve static files based on authorization, see [Static file authorization](xref:fundamentals/static-files#static-file-authorization).
150
140
151
141
## Serve files from multiple locations
@@ -161,7 +151,7 @@ Consider the following Razor page which displays the `/MyStaticFiles/image3.png`
161
151
Using the preceding code:
162
152
163
153
* The `/MyStaticFiles/image3.png` file is displayed.
164
-
*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.
154
+
*[Image Tag Helpers](xref:mvc/views/tag-helpers/builtin-th/image-tag-helper)(<xref:Microsoft.AspNetCore.Mvc.TagHelpers.ImageTagHelper.AppendVersion>) aren't applied because Tag Helpers depend on <xref:Microsoft.AspNetCore.Hosting.IWebHostEnvironment.WebRootFileProvider>. `WebRootFileProvider`hasn't been updated to include the `MyStaticFiles` folder.
165
155
166
156
The following code updates the `WebRootFileProvider`, which enables the Image Tag Helper to provide a version:
167
157
@@ -170,7 +160,7 @@ The following code updates the `WebRootFileProvider`, which enables the Image Ta
170
160
> [!NOTE]
171
161
> 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>.
172
162
173
-
## Serve files outside wwwroot by updating IWebHostEnvironment.WebRootPath
163
+
## Serve files outside wwwroot by updating `IWebHostEnvironment.WebRootPath`
174
164
175
165
When <xref:Microsoft.AspNetCore.Hosting.IWebHostEnvironment.WebRootPath%2A?displayProperty=nameWithType> is set to a folder other than `wwwroot`:
176
166
@@ -186,8 +176,8 @@ Consider a web app created with the empty web template:
186
176
187
177
In the preceding code, requests to `/`:
188
178
189
-
* In the development environment return `wwwroot/Index.html`
190
-
* In any environment other than development return `wwwroot-custom/Index.html`
179
+
* In the development environment, return `wwwroot/Index.html`.
180
+
* In any environment other than development, return `wwwroot-custom/Index.html`.
191
181
192
182
To ensure assets from `wwwroot-custom` are returned, use one of the following approaches:
193
183
@@ -202,14 +192,15 @@ To ensure assets from `wwwroot-custom` are returned, use one of the following ap
202
192
</ItemGroup>
203
193
```
204
194
205
-
The following code updates `IWebHostEnvironment.WebRootPath` to a non development value, guaranteeing duplicate content is returned from `wwwroot-custom` rather than `wwwroot`:
195
+
The following code updates `IWebHostEnvironment.WebRootPath` to a non-Development value (Staging), guaranteeing duplicate content is returned from `wwwroot-custom` rather than `wwwroot`:
When developing a server-side Blazor app and testing locally, see <xref:blazor/fundamentals/static-files#static-files-in-non-development-environments>.
200
+
209
201
## Additional resources
210
202
211
203
*[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))
0 commit comments