Static Files and wwwroot

Level: Beginner to Intermediate

ℹ️ Where This Fits

Static files are files ASP.NET Core can serve directly, such as images, CSS, JavaScript, PDFs, and downloadable documents.

ℹ️ What You'll Learn

• Static files: CSS, JavaScript, images, PDFs that don't change (no server processing)
• wwwroot folder: Special folder where ASP.NET Core serves files directly (root = wwwroot/)
• app.UseStaticFiles(): Middleware that serves files from wwwroot/ (must add to Program.cs)
• File serving paths: wwwroot/css/style.css served as GET /css/style.css
• Directory structure in wwwroot: css/, js/, images/, lib/ (libraries like Bootstrap, jQuery)
• Serving images: Store PNG/JPG in wwwroot/images/, reference as <img src="/images/logo.png">
• Serving PDF downloads: Put students.pdf in wwwroot/, link as <a href="/students.pdf">Download</a>
• Default files: app.UseDefaultFiles() serves index.html for GET / automatically
• CSS/JS in HTML: <link href="/css/style.css"> or <script src="/js/app.js"></script>
• Built-in libraries: Bootstrap, jQuery, Popper added to wwwroot/lib/ via npm or CDN
• Performance: Static files served faster than processing requests (no code execution)
• Caching headers: Static files can cache 1 year (browser won't re-download), versioning with ?v=1
• School Management static assets: Logo in wwwroot/images/, CSS for portal styling, downloadable PDF reports
• Common mistake: Forgetting app.UseStaticFiles() (files won't serve), putting secrets in wwwroot (exposed!)
• Security mistakes to avoid: Never store config files/secrets in wwwroot, use .gitignore for wwwroot/node_modules, verify file permissions

What are Static Files?

Static files are files that do not need server-side C# logic for every request.

Examples:

• CSS files
• JavaScript files
• images
• PDFs
• logos
• icons
• downloadable forms

In a school portal:

school logo
student handbook PDF
admission form PDF
frontend CSS
dashboard JavaScript
teacher profile photo

What is wwwroot?

wwwroot is the public web root folder.

Files inside wwwroot can be served to browsers when static file middleware is enabled.

Example structure:

SchoolPortal/
  Program.cs
  Controllers/
  wwwroot/
    css/
      site.css
    js/
      app.js
    images/
      logo.png
    downloads/
      admission-form.pdf

Enable Static Files

💻 Try It — Console App

💡 Add UseStaticFiles before endpoint mapping.⌥ GitHub

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.UseStaticFiles();

app.MapGet("/", () => "School Portal");

app.Run();

Now this file:

wwwroot/images/logo.png

is available at:

/images/logo.png

Referencing Static Files

HTML:

<link rel="stylesheet" href="/css/site.css">
<script src="/js/app.js"></script>
<img src="/images/logo.png" alt="School logo">
<a href="/downloads/admission-form.pdf">Download admission form</a>

Notice that wwwroot is not part of the URL.

UseStaticFiles Order

Typical order:

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();

Static files are commonly served before authentication and controller routing.

Default Files

UseDefaultFiles() looks for default documents like index.html.

app.UseDefaultFiles();
app.UseStaticFiles();

Order matters:

UseDefaultFiles must come before UseStaticFiles.

If this file exists:

wwwroot/index.html

Then visiting:

/

can serve that file.

Static Files and APIs

For pure backend APIs, you may not need many static files.

For ASP.NET Core MVC, Razor Pages, or combined frontend/backend apps, static files are common.

For a separate React/Angular frontend, static files may be handled by that frontend build or CDN instead.

Serving Files Outside wwwroot

By default, ASP.NET Core serves only from wwwroot.

That is safer.

You can configure other folders, but do it carefully:

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(builder.Environment.ContentRootPath, "Uploads")),
    RequestPath = "/uploads"
});

Required namespace:

using Microsoft.Extensions.FileProviders;

This exposes files in Uploads as /uploads.

Caching Static Files

Static files can be cached by the browser to improve performance.

app.UseStaticFiles(new StaticFileOptions
{
    OnPrepareResponse = context =>
    {
        context.Context.Response.Headers.CacheControl =
            "public,max-age=604800";
    }
});

This tells browsers to cache files for 7 days.

Use caching carefully when files change often.

Security Rules

ℹ️ Important Static File Safety

Only put files in wwwroot that are safe for public access. Anything in wwwroot should be treated as visible to users.

Do not place these in wwwroot:

• appsettings.json
• database backups
• private reports
• user passwords
• source code files
• internal documents
• private student records

Uploaded Files

If users upload files, do not blindly serve them.

Safer approach:

• validate file type
• limit file size
• rename files safely
• store outside wwwroot when private
• serve through a controller after permission checks

Example:

Private student marksheet -> controller with authorization
Public school brochure -> wwwroot/downloads

Common Mistakes

Mistake	Better Approach
Forgetting UseStaticFiles()	Enable static file middleware
Using /wwwroot/images/logo.png in URLs	Use /images/logo.png
Putting private files in wwwroot	Store private files elsewhere
Forgetting UseDefaultFiles() order	Put it before UseStaticFiles()
No cache strategy for large assets	Add controlled caching
Serving uploads without validation	Validate and protect uploads

Practice Task

Create static file support:

1. Add wwwroot/images/logo.png.
2. Add wwwroot/downloads/admission-form.pdf.
3. Enable app.UseStaticFiles().
4. Confirm /images/logo.png works.
5. Add an index.html and enable UseDefaultFiles().

Quick Recap

Question	Answer
Public static folder?	wwwroot
Enable static files?	app.UseStaticFiles()
URL for wwwroot/css/site.css?	/css/site.css
Default file middleware?	UseDefaultFiles()
Private files in wwwroot?	No

🎯 Interview Favourite

Q: How do static files work in ASP.NET Core?

Good Answer: "Static files are files like CSS, JavaScript, images, and PDFs served directly to clients. In ASP.NET Core, public static files are usually placed inside the wwwroot folder and enabled with app.UseStaticFiles(). A file like wwwroot/css/site.css is accessed as /css/site.css. UseDefaultFiles() can serve files like index.html for folder requests and must run before UseStaticFiles(). Private files should not be placed in wwwroot."

🤖Use AI to Learn Faster

Use ChatGPT, Claude, or Copilot to go deeper on Static Files and wwwroot. Try these prompts:

• "Explain wwwroot in ASP.NET Core."
• "Why should private files not be placed in wwwroot?"
• "Show me how to enable static files and default files."
• "How should uploaded files be handled safely?"

💡 Tip: After reading this article, paste your own code into AI and ask "What could go wrong here and why?" — fastest way to find edge cases and deepen understanding.

Next Article

-> Session and Cookies