Core

Contents
Introduction
What's new
What's new
What's new
Get started
Create a web app
Create a Web API
Tutorials
Create a Razor Pages web app
Get started with Razor Pages
Add a model
Scaffolded Razor Pages
SQL Server LocalDB
Update the pages
Add search
Add a new field
Add validation
Create a real-time SignalR web app
Create a SignalR web app with TypeScript
Create an MVC web app
Get started
Add a controller
Add a view
Add a model
Work with SQL Server LocalDB
Controller methods and views
Add search
Add a new field
Add validation
Examine the Details and Delete methods
Build Web APIs
Create a Web API in Visual Studio Code
Create a Web API in Visual Studio for Mac
Create a Web API in Visual Studio
Create backend services for native mobile apps
Help pages using Swagger
Get started with NSwag
Get started with Swashbuckle
Data access - with EF Core
Data access - with Razor Pages and EF Core
Get started
Create, Read, Update, and Delete operations
Sort, filter, page, and group
Migrations
Create a complex data model
Read related data
Update related data
Handle concurrency conflicts
Data access - MVC with EF Core
Get started
Migrations
Read related data
Update related data
Inheritance
Advanced topics
Cross platform tutorials
Razor Pages web app on macOS
Add a model
Work with SQLite
Update the pages
Add search
Razor Pages web app with VS Code
Add a model
Work with SQLite
Update the pages
Add search
MVC web app with Visual Studio for Mac
Get started
Add a controller
Add a view
Add a model
Work with SQLite
Add search
Add a new field
Add validation
MVC web app with Visual Studio Code on macOS or Linux
Get started
Add a controller
Add a view
Add a model
Work with SQLite
Add search
Add a new field
Add validation
Web API with Visual Studio for Mac
Web API with Visual Studio Code
Develop apps using a file watcher
Create backend services for mobile apps
Fundamentals
Application startup
Dependency injection (services)
Middleware
Middleware
Factory-based middleware
Factory-based middleware with third-party container
Static files
Routing
URL rewriting middleware
Use multiple environments
Configuration and options
Configuration
Options
Logging
Logging with LoggerMessage
Handle errors
Host
Web Host
Generic Host
Background tasks with hosted services
Enhance an app from an external assembly
Servers
Kestrel
ASP.NET Core Module
HTTP.sys
Session and app state
File Providers
Repository pattern
Globalization and localization
Configure Portable Object localization with Orchard Core
Initiate HTTP requests
Request Features
Access HttpContext
Primitives
Change tokens
Open Web Interface for .NET (OWIN)
WebSockets
Microsoft.AspNetCore.App metapackage
Microsoft.AspNetCore.All metapackage
Choose between .NET Core and .NET Framework
Choose between ASP.NET Core and ASP.NET
Razor Pages
Filter methods for Razor Pages
Create a Razor Class Library
Route and app conventions
Upload files to a Razor Page
Razor SDK
MVC
Model binding
Model validation
Views
Razor syntax
View compilation
Layout
Tag Helpers
Create Tag Helpers
Use Tag Helpers in forms
Tag Helper Components
Built-in Tag Helpers
Anchor Tag Helper
Cache Tag Helper
Distributed Cache Tag Helper
Environment Tag Helper
Form Tag Helper
Image Tag Helper
Input Tag Helper
Label Tag Helper
Partial Tag Helper
Select Tag Helper
Textarea Tag Helper
Validation Message Tag Helper
Validation Summary Tag Helper
Partial views
Dependency injection into views
View components
Controllers
Route to controller actions
File uploads
Dependency injection into controllers
Test controllers
Advanced
Work with the app model
Filters
Areas
Application parts
Custom model binding
Compatibility version
Web API
Controller action return types
Advanced
Custom formatters
Format response data
SignalR
Introduction
Get started
Server concepts
Supported platforms
Hubs
HubContext
Users and groups
Publish to Azure
Clients
.NET client
Java client
Java API reference
JavaScript client
JavaScript API reference
WebPack and TypeScript
Configuration
Authentication and authorization
Security considerations
MessagePack Hub Protocol
Streaming
Differences between SignalR versions
Test, debug, and troubleshoot
Unit testing
Integration tests
Razor Pages unit tests
Test controllers
Remote debugging
Snapshot debugging
Snapshot debugging in Visual Studio
Troubleshoot
Data access with EF Core
Get started with Razor Pages and EF Core using Visual Studio
Get started with ASP.NET Core and EF Core using Visual Studio
ASP.NET Core with EF Core - new database
ASP.NET Core with EF Core - existing database
Get started with ASP.NET Core and Entity Framework 6
Azure Storage
Add Azure Storage by using Visual Studio Connected Services
Get started with Blob storage and Visual Studio Connected Services
Get Started with Queue Storage and Visual Studio Connected Services
Get Started with Table Storage and Visual Studio Connected Services
Azure guidance
DevOps with ASP.NET Core and Azure
Introduction
Tools and downloads
Deploy to App Service
Continuous integration and deployment
Monitor and troubleshoot
Next steps
Client-side development
Use Gulp
Use Grunt
Use LibMan
LibMan CLI
LibMan in Visual Studio
Manage client-side packages with Bower
Build responsive sites with Bootstrap
Style apps with LESS, Sass, and Font Awesome
Bundle and minify
Use Browser Link
Use JavaScriptServices for SPAs
Use the SPA project templates
Angular project template
React project template
React with Redux project template
Mobile
Host and deploy
Host on Azure App Service
Publish to Azure with Visual Studio
Publish to Azure with CLI tools
Continuous deployment to Azure with Visual Studio and Git
Continuous deployment to Azure with Azure Pipelines
Troubleshoot ASP.NET Core on Azure App Service
Host on Windows with IIS
Troubleshoot ASP.NET Core on IIS
ASP.NET Core Module configuration reference
Development-time IIS support in Visual Studio for ASP.NET Core
IIS Modules with ASP.NET Core
Host in a Windows service
Host on Linux with Nginx
Host on Linux with Apache
Host in Docker
Build Docker images
Visual Studio Tools for Docker
Publish to a Docker image
Proxy and load balancer configuration
Host in a web farm
Visual Studio publish profiles
Directory structure
Common errors reference for Azure App Service and IIS
Security
Authentication
Authentication
Introduction to Identity
Scaffold Identity
Add custom user data to Identity
Customize Identity
Community OSS authentication options
Configure Identity
Configure Windows Authentication
Custom storage providers for Identity
External providers
Facebook authentication
Twitter authentication
Google authentication
Microsoft authentication
Other authentication providers
Additional claims
WS-Federation authentication
Account confirmation and password recovery
Enable QR code generation in Identity
Two-factor authentication with SMS
Use Cookie Authentication without Identity
Azure Active Directory
Integrate Azure AD Into an ASP.NET Core web app
Integrate Azure AD B2C into a customer-facing ASP.NET Core web app
Integrate Azure AD B2C into an ASP.NET Core web API
Call a ASP.NET Core Web API from a WPF app using Azure AD
Call a Web API in an ASP.NET Core web app using Azure AD
Secure ASP.NET Core apps with IdentityServer4
Secure ASP.NET Core apps with Azure App Service authentication (Easy Auth)
Individual user accounts
Authorization
Introduction
Create an app with user data protected by authorization
Razor Pages authorization
Simple authorization
Role-based authorization
Claims-based authorization
Policy-based authorization
Authorization policy providers
Dependency injection in requirement handlers
Resource-based authorization
View-based authorization
Limit identity by scheme
Data protection
Introduction to data protection
Get started with the Data Protection APIs
Consumer APIs
Consumer APIs overview
Purpose strings
Purpose hierarchy and multi-tenancy
Hash passwords
Limit the lifetime of protected payloads
Unprotect payloads whose keys have been revoked
Configuration
Configure data protection
Default settings
Machine-wide policy
Non-DI aware scenarios
Extensibility APIs
Core cryptography extensibility
Key management extensibility
Miscellaneous APIs
Implementation
Authenticated encryption details
Subkey derivation and authenticated encryption
Context headers
Key management
Key storage providers
Key encryption at rest
Key immutability and settings
Key storage format
Ephemeral data protection providers
Compatibility
Replace <machineKey> in ASP.NET
Enforce HTTPS
EU General Data Protection Regulation (GDPR) support
Safe storage of app secrets in development
Azure Key Vault configuration provider
Anti-request forgery
Prevent open redirect attacks
Prevent Cross-Site Scripting
Enable Cross-Origin Requests (CORS)
Share cookies among apps
IP safelist
Performance
Cache responses
Cache in-memory
Work with a distributed cache
Response caching
Response caching middleware
Response compression
Migration
ASP.NET Core 2.0 to 2.1
ASP.NET to ASP.NET Core
MVC
Web API
Configuration
Authentication and Identity
ClaimsPrincipal.Current
Membership to Identity
HTTP modules to middleware
ASP.NET Core 1.x to 2.0
Authentication and Identity
API reference
Contribute
Introduction to ASP.NET Core
9/20/2018 • 2 minutes to read • Edit Online
By Daniel Roth, Rick Anderson, and Shaun Luttin

ASP.NET Core is a cross-platform, high-performance, open-source framework for building modern, cloud-based,
Internet-connected applications. With ASP.NET Core, you can:
Build web apps and services, IoT apps, and mobile backends.
Use your favorite development tools on Windows, macOS, and Linux.
Deploy to the cloud or on-premises.
Run on .NET Core or .NET Framework.
Why use ASP.NET Core?

Millions of developers have used (and continue to use) ASP.NET 4.x to create web apps. ASP.NET Core is a
redesign of ASP.NET 4.x, with architectural changes that result in a leaner, more modular framework.
ASP.NET Core provides the following benefits:
A unified story for building web UI and web APIs.
Integration of modern, client-side frameworks and development workflows.
A cloud-ready, environment-based configuration system.
Built-in dependency injection.
A lightweight, high-performance, and modular HTTP request pipeline.
Ability to host on IIS, Nginx, Apache, Docker, or self-host in your own process.
Side-by-side app versioning when targeting .NET Core.
Tooling that simplifies modern web development.
Ability to build and run on Windows, macOS, and Linux.
Open-source and community-focused.
ASP.NET Core ships entirely as NuGet packages. Using NuGet packages allows you to optimize your app to
include only the necessary dependencies. In fact, ASP.NET Core 2.x apps targeting .NET Core only require a
single NuGet package. The benefits of a smaller app surface area include tighter security, reduced servicing, and
improved performance.
Build web APIs and web UI using ASP.NET Core MVC

ASP.NET Core MVC provides features to build web APIs and web apps:
The Model-View -Controller (MVC ) pattern helps make your web APIs and web apps testable.
Razor Pages (new in ASP.NET Core 2.0) is a page-based programming model that makes building web UI
easier and more productive.
Razor markup provides a productive syntax for Razor Pages and MVC views.
Tag Helpers enable server-side code to participate in creating and rendering HTML elements in Razor files.
Built-in support for multiple data formats and content negotiation lets your web APIs reach a broad range of
clients, including browsers and mobile devices.
Model binding automatically maps data from HTTP requests to action method parameters.
Model validation automatically performs client-side and server-side validation.
ASP.NET Core integrates seamlessly with popular client-side frameworks and libraries, including Angular, React,
and Bootstrap. For more information, see Client-side development.
ASP.NET Core targeting .NET Framework

ASP.NET Core can target .NET Core or .NET Framework. ASP.NET Core apps targeting .NET Framework aren't
cross-platform—they run on Windows only. There are no plans to remove support for targeting .NET Framework
in ASP.NET Core. Generally, ASP.NET Core is made up of .NET Standard libraries. Apps written with .NET
Standard 2.0 run anywhere that .NET Standard 2.0 is supported.
There are several advantages to targeting .NET Core, and these advantages increase with each release. Some
advantages of .NET Core over .NET Framework include:
Cross-platform. Runs on macOS, Linux, and Windows.
Improved performance
Side-by-side versioning
New APIs
Open source
We're working hard to close the API gap from .NET Framework to .NET Core. The Windows Compatibility Pack
made thousands of Windows-only APIs available in .NET Core. These APIs weren't available in .NET Core 1.x.
Next steps
For more information, see the following resources:
ASP.NET Core tutorials
Publish an ASP.NET Core app to Azure with Visual Studio
ASP.NET Core fundamentals
The weekly ASP.NET community standup covers the team's progress and plans. It features new blogs and
third-party software.
What's new in ASP.NET Core 2.1
This article highlights the most significant changes in ASP.NET Core 2.1, with links to relevant documentation.
SignalR
SignalR has been rewritten for ASP.NET Core 2.1. ASP.NET Core SignalR includes a number of improvements:
A simplified scale-out model.
A new JavaScript client with no jQuery dependency.
A new compact binary protocol based on MessagePack.
Support for custom protocols.
A new streaming response model.
Support for clients based on bare WebSockets.
For more information, see ASP.NET Core SignalR.
Razor class libraries

ASP.NET Core 2.1 makes it easier to build and include Razor-based UI in a library and share it across multiple
projects. The new Razor SDK enables building Razor files into a class library project that can be packaged into a
NuGet package. Views and pages in libraries are automatically discovered and can be overridden by the app. By
integrating Razor compilation into the build:
The app startup time is significantly faster.
Fast updates to Razor views and pages at runtime are still available as part of an iterative development
workflow.
For more information, see Create reusable UI using the Razor Class Library project.
Identity UI library & scaffolding

ASP.NET Core 2.1 provides ASP.NET Core Identity as a Razor Class Library. Apps that include Identity can apply
the new Identity scaffolder to selectively add the source code contained in the Identity Razor Class Library (RCL ).
You might want to generate source code so you can modify the code and change the behavior. For example, you
could instruct the scaffolder to generate the code used in registration. Generated code takes precedence over the
same code in the Identity RCL.
Apps that do not include authentication can apply the Identity scaffolder to add the RCL Identity package. You
have the option of selecting Identity code to be generated.
For more information, see Scaffold Identity in ASP.NET Core projects.
HTTPS
With the increased focus on security and privacy, enabling HTTPS for web apps is important. HTTPS enforcement
is becoming increasingly strict on the web. Sites that don’t use HTTPS are considered insecure. Browsers
(Chromium, Mozilla) are starting to enforce that web features must be used from a secure context. GDPR requires
the use of HTTPS to protect user privacy. While using HTTPS in production is critical, using HTTPS in development
can help prevent issues in deployment (for example, insecure links). ASP.NET Core 2.1 includes a number of
improvements that make it easier to use HTTPS in development and to configure HTTPS in production. For more
information, see Enforce HTTPS.
On by default
To facilitate secure website development, HTTPS is now enabled by default. Starting in 2.1, Kestrel listens on
https://localhost:5001 when a local development certificate is present. A development certificate is created:
As part of the .NET Core SDK first-run experience, when you use the SDK for the first time.
Manually using the new dev-certs tool.
Run dotnet dev-certs https --trust to trust the certificate.
HTTPS redirection and enforcement
Web apps typically need to listen on both HTTP and HTTPS, but then redirect all HTTP traffic to HTTPS. In 2.1,
specialized HTTPS redirection middleware that intelligently redirects based on the presence of configuration or
bound server ports has been introduced.
Use of HTTPS can be further enforced using HTTP Strict Transport Security Protocol (HSTS ). HSTS instructs
browsers to always access the site via HTTPS. ASP.NET Core 2.1 adds HSTS middleware that supports options for
max age, subdomains, and the HSTS preload list.
Configuration for production
In production, HTTPS must be explicitly configured. In 2.1, default configuration schema for configuring HTTPS for
Kestrel has been added. Apps can be configured to use:
Multiple endpoints including the URLs. For more information, see Kestrel web server implementation: Endpoint
configuration.
The certificate to use for HTTPS either from a file on disk or from a certificate store.
GDPR
ASP.NET Core provides APIs and templates to help meet some of the EU General Data Protection Regulation
(GDPR ) requirements. For more information, see GDPR support in ASP.NET Core. A sample app shows how to
use and lets you test most of the GDPR extension points and APIs added to the ASP.NET Core 2.1 templates.
Integration tests
A new package is introduced that streamlines test creation and execution. The Microsoft.AspNetCore.Mvc.Testing
package handles the following tasks:
Copies the dependency file (*.deps) from the tested app into the test project's bin folder.
Sets the content root to the tested app's project root so that static files and pages/views are found when the
tests are executed.
Provides the WebApplicationFactory class to streamline bootstrapping the tested app with TestServer.
The following test uses xUnit to check that the Index page loads with a success status code and with the correct
Content-Type header:
public class BasicTests
: IClassFixture<WebApplicationFactory<RazorPagesProject.Startup>>
{
private readonly HttpClient _client;
public BasicTests(WebApplicationFactory<RazorPagesProject.Startup> factory)

{
_client = factory.CreateClient();
}
[Fact]
public async Task GetHomePage()
{
// Act
var response = await _client.GetAsync("/");
// Assert
response.EnsureSuccessStatusCode(); // Status Code 200-299
Assert.Equal("text/html; charset=utf-8",
response.Content.Headers.ContentType.ToString());
}
}
For more information, see the Integration tests topic.
[ApiController], ActionResult<T>
ASP.NET Core 2.1 adds new programming conventions that make it easier to build clean and descriptive web
APIs. ActionResult<T> is a new type added to allow an app to return either a response type or any other action
result (similar to IActionResult), while still indicating the response type. The [ApiController] attribute has also
been added as the way to opt in to Web API-specific conventions and behaviors.
For more information, see Build Web APIs with ASP.NET Core.
IHttpClientFactory
ASP.NET Core 2.1 includes a new IHttpClientFactory service that makes it easier to configure and consume
instances of HttpClient in apps. HttpClient already has the concept of delegating handlers that could be linked
together for outgoing HTTP requests. The factory:
Makes registering of instances of HttpClient per named client more intuitive.
Implements a Polly handler that allows Polly policies to be used for Retry, CircuitBreakers, etc.
For more information, see Initiate HTTP Requests.
Kestrel transport configuration

With the release of ASP.NET Core 2.1, Kestrel's default transport is no longer based on Libuv but instead based on
managed sockets. For more information, see Kestrel web server implementation: Transport configuration.
Generic host builder

The Generic Host Builder ( HostBuilder ) has been introduced. This builder can be used for apps that don't process
HTTP requests (Messaging, background tasks, etc.).
For more information, see .NET Generic Host.
Updated SPA templates

The Single Page Application templates for Angular, React, and React with Redux are updated to use the standard
project structures and build systems for each framework.
The Angular template is based on the Angular CLI, and the React templates are based on create-react-app. For
more information, see Use the Single Page Application templates with ASP.NET Core.
Razor Pages search for Razor assets

In 2.1, Razor Pages search for Razor assets (such as layouts and partials) in the following directories in the listed
order:
1. Current Pages folder.
2. /Pages/Shared/
3. /Views/Shared/
Razor Pages in an area

Razor Pages now support areas. To see an example of areas, create a new Razor Pages web app with individual
user accounts. A Razor Pages web app with individual user accounts includes /Areas/Identity/Pages.
MVC compatibility version

The SetCompatibilityVersion method allows an app to opt-in or opt-out of potentially breaking behavior changes
introduced in ASP.NET Core MVC 2.1 or later.
For more information, see Compatibility version for ASP.NET Core MVC.
Migrate from 2.0 to 2.1

See Migrate from ASP.NET Core 2.0 to 2.1.
Additional information
For the complete list of changes, see the ASP.NET Core 2.1 Release Notes.
This article highlights the most significant changes in ASP.NET Core 2.0, with links to relevant documentation.
Razor Pages
Razor Pages is a new feature of ASP.NET Core MVC that makes coding page-focused scenarios easier and more
productive.
For more information, see the introduction and tutorial:
Introduction to Razor Pages
ASP.NET Core metapackage

A new ASP.NET Core metapackage includes all of the packages made and supported by the ASP.NET Core and
Entity Framework Core teams, along with their internal and 3rd-party dependencies. You no longer need to choose
individual ASP.NET Core features by package. All features are included in the Microsoft.AspNetCore.All package.
The default templates use this package.
For more information, see Microsoft.AspNetCore.All metapackage for ASP.NET Core 2.0.
Runtime Store
Applications that use the Microsoft.AspNetCore.All metapackage automatically take advantage of the new .NET
Core Runtime Store. The Store contains all the runtime assets needed to run ASP.NET Core 2.0 applications. When
you use the Microsoft.AspNetCore.All metapackage, no assets from the referenced ASP.NET Core NuGet
packages are deployed with the application because they already reside on the target system. The assets in the
Runtime Store are also precompiled to improve application startup time.
For more information, see Runtime store
.NET Standard 2.0

The ASP.NET Core 2.0 packages target .NET Standard 2.0. The packages can be referenced by other .NET Standard
2.0 libraries, and they can run on .NET Standard 2.0-compliant implementations of .NET, including .NET Core 2.0
and .NET Framework 4.6.1.
The Microsoft.AspNetCore.All metapackage targets .NET Core 2.0 only, because it's intended to be used with the
.NET Core 2.0 Runtime Store.
Configuration update
An IConfiguration instance is added to the services container by default in ASP.NET Core 2.0. IConfiguration in
the services container makes it easier for applications to retrieve configuration values from the container.
For information about the status of planned documentation, see the GitHub issue.
Logging update
In ASP.NET Core 2.0, logging is incorporated into the dependency injection (DI) system by default. You add
providers and configure filtering in the Program.cs file instead of in the Startup.cs file. And the default
ILoggerFactory supports filtering in a way that lets you use one flexible approach for both cross-provider filtering
and specific-provider filtering.
For more information, see Introduction to Logging.
Authentication update
A new authentication model makes it easier to configure authentication for an application using DI.
New templates are available for configuring authentication for web apps and web APIs using [Azure AD B2C ]
(https://azure.microsoft.com/services/active-directory-b2c/).
Identity update
We've made it easier to build secure web APIs using Identity in ASP.NET Core 2.0. You can acquire access tokens
for accessing your web APIs using the Microsoft Authentication Library (MSAL ).
For more information on authentication changes in 2.0, see the following resources:
Account confirmation and password recovery in ASP.NET Core
Enable QR Code generation for authenticator apps in ASP.NET Core
Migrate Authentication and Identity to ASP.NET Core 2.0
SPA templates
Single Page Application (SPA) project templates for Angular, Aurelia, Knockout.js, React.js, and React.js with Redux
are available. The Angular template has been updated to Angular 4. The Angular and React templates are available
by default; for information about how to get the other templates, see Create a new SPA project. For information
about how to build a SPA in ASP.NET Core, see Use JavaScriptServices for Creating Single Page Applications.
Kestrel improvements
The Kestrel web server has new features that make it more suitable as an Internet-facing server. A number of
server constraint configuration options are added in the KestrelServerOptions class's new Limits property. Add
limits for the following:
Maximum client connections
Maximum request body size
Minimum request body data rate
For more information, see Kestrel web server implementation in ASP.NET Core.
WebListener renamed to HTTP.sys

The packages Microsoft.AspNetCore.Server.WebListener and Microsoft.Net.Http.Server have been merged into a
new package Microsoft.AspNetCore.Server.HttpSys . The namespaces have been updated to match.
For more information, see HTTP.sys web server implementation in ASP.NET Core.
Enhanced HTTP header support

When using MVC to transmit a FileStreamResult or a FileContentResult , you now have the option to set an ETag
or a LastModified date on the content you transmit. You can set these values on the returned content with code
similar to the following:
var data = Encoding.UTF8.GetBytes("This is a sample text from a binary array");

var entityTag = new EntityTagHeaderValue("\"MyCalculatedEtagValue\"");
return File(data, "text/plain", "downloadName.txt", lastModified: DateTime.UtcNow.AddSeconds(-5), entityTag:
entityTag);
The file returned to your visitors will be decorated with the appropriate HTTP headers for the ETag and
LastModified values.
If an application visitor requests content with a Range Request header, ASP.NET Core recognizes the request and
handles the header. If the requested content can be partially delivered, ASP.NET Core appropriately skips and
returns just the requested set of bytes. You don't need to write any special handlers into your methods to adapt or
handle this feature; it's automatically handled for you.
Hosting startup and Application Insights

Hosting environments can now inject extra package dependencies and execute code during application startup,
without the application needing to explicitly take a dependency or call any methods. This feature can be used to
enable certain environments to "light-up" features unique to that environment without the application needing to
know ahead of time.
In ASP.NET Core 2.0, this feature is used to automatically enable Application Insights diagnostics when debugging
in Visual Studio and (after opting in) when running in Azure App Services. As a result, the project templates no
longer add Application Insights packages and code by default.
Automatic use of anti-forgery tokens

ASP.NET Core has always helped HTML -encode content by default, but with the new version an extra step is taken
to help prevent cross-site request forgery (XSRF ) attacks. ASP.NET Core will now emit anti-forgery tokens by
default and validate them on form POST actions and pages without extra configuration.
For more information, see Prevent Cross-Site Request Forgery (XSRF/CSRF ) attacks.
Automatic precompilation
Razor view pre-compilation is enabled during publish by default, reducing the publish output size and application
startup time.
For more information, see Razor view compilation and precompilation in ASP.NET Core.
Razor support for C# 7.1

The Razor view engine has been updated to work with the new Roslyn compiler. That includes support for C# 7.1
features like Default Expressions, Inferred Tuple Names, and Pattern-Matching with Generics. To use C# 7.1 in your
project, add the following property in your project file and then reload the solution:
<LangVersion>latest</LangVersion>
For information about the status of C# 7.1 features, see the Roslyn GitHub repository.
Other documentation updates for 2.0
Visual Studio publish profiles for ASP.NET Core app deployment
Key Management
Configure Facebook authentication
Configure Twitter authentication
Configure Google authentication
Configure Microsoft Account authentication
Migration guidance
For guidance on how to migrate ASP.NET Core 1.x applications to ASP.NET Core 2.0, see the following resources:
Migrate from ASP.NET Core 1.x to ASP.NET Core 2.0
Migrate Authentication and Identity to ASP.NET Core 2.0
Additional Information
For the complete list of changes, see the ASP.NET Core 2.0 Release Notes.
To connect with the ASP.NET Core development team's progress and plans, tune in to the ASP.NET Community
Standup.
ASP.NET Core 1.1 includes the following new features:

URL Rewriting Middleware
Response Caching Middleware
View Components as Tag Helpers
Middleware as MVC filters
Cookie-based TempData provider
Azure App Service logging provider
Azure and Redis Storage Data Protection Key Repositories
WebListener Server for Windows
WebSockets support
Choosing between versions 1.0 and 1.1 of ASP.NET Core

ASP.NET Core 1.1 has more features than 1.0. In general, we recommend you use the latest version.
Additional Information
ASP.NET Core 1.1.0 Release Notes
To connect with the ASP.NET Core development team's progress and plans, tune in to the ASP.NET
Community Standup.
Get started with ASP.NET Core
1. Install the .NET Core 2.1 SDK or later.

2. Create an ASP.NET Core project. Open a command shell and enter the following command:
dotnet new webapp -o aspnetcoreapp
3. Trust the HTTPS development certificate:

Windows
macOS
Linux
```console
dotnet dev-certs https --trust
```
The preceding command displays the following dialog:
Select Yes if you agree to trust the development certificate.

4. Run the app:
cd aspnetcoreapp
dotnet run
5. Browse to http://localhost:5001. Click Accept to accept the privacy and cookie policy. This app doesn't keep
personal information.
6. Open Pages/About.cshtml and modify the page with the following highlighted markup:
@page
@model AboutModel
@{
ViewData["Title"] = "About";
}
<h2>@ViewData["Title"]</h2>
<h3>@Model.Message</h3>
<p>Hello, world! The time on the server is @DateTime.Now</p>
7. Browse to http://localhost:5001/About and verify the changes are displayed.

Next steps
An ASP.NET Core app can use the .NET Core or .NET Framework Base Class Library and runtime. For more
information, see Choosing between .NET Core and .NET Framework.
Getting started tutorials
ASP.NET Core architecture and fundamentals.
1. Install the .NET Core SDK 2.0 or later.
2. Create a new ASP.NET Core project.
Open a command shell. Enter the following command:
dotnet new razor -o aspnetcoreapp
3. Run the app with the following commands:
cd aspnetcoreapp
dotnet run
4. Browse to http://localhost:5000.
5. Open Pages/About.cshtml and modify the page to display the message "Hello, world! The time on the
server is @DateTime.Now":
@page
@model AboutModel
@{
}
<p>Hello, world! The time on the server is @DateTime.Now</p>
6. Browse to http://localhost:5000/About and verify the changes.

Next steps
1. Install the .NET Core SDK Installer for SDK 1.0.4 from the .NET Core All Downloads page.
2. Create a folder for a new ASP.NET Core project.
Open a command shell. Enter the following commands:
mkdir aspnetcoreapp
cd aspnetcoreapp
3. If you have installed a later SDK version on your machine, create a global.json file to select the 1.0.4 SDK.
{
"sdk": { "version": "1.0.4" }
}
4. Create a new ASP.NET Core project.
dotnet new web
5. Restore the packages.
dotnet restore
6. Run the app.
dotnet run
The dotnet run command builds the app first, if needed.

7. Browse to http://localhost:5000 .
Next steps
Introduction to Razor Pages in ASP.NET Core
By Rick Anderson and Ryan Nowak

Razor Pages is a new aspect of ASP.NET Core MVC that makes coding page-focused scenarios easier and more
productive.
If you're looking for a tutorial that uses the Model-View -Controller approach, see Get started with ASP.NET Core
MVC.
This document provides an introduction to Razor Pages. It's not a step by step tutorial. If you find some of the
sections too advanced, see Get started with Razor Pages. For an overview of ASP.NET Core, see the Introduction to
ASP.NET Core.
Prerequisites
Install one of the following:
CLI tooling: Windows, Linux, or macOS: .NET Core SDK 2.0 or later
IDE/editor tooling
Windows: Visual Studio for Windows
ASP.NET and web development workload
.NET Core cross-platform development workload
Linux: Visual Studio Code
macOS: Visual Studio for Mac
Creating a Razor Pages project

Visual Studio
Visual Studio for Mac
Visual Studio Code
.NET Core CLI
See Get started with Razor Pages for detailed instructions on how to create a Razor Pages project using Visual
Studio.
Razor Pages
Razor Pages is enabled in Startup.cs:
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
// Includes support for Razor Pages and controllers.
services.AddMvc();
}
public void Configure(IApplicationBuilder app)

{
app.UseMvc();
}
}
Consider a basic page:
@page
<h1>Hello, world!</h1>
<h2>The time on the server is @DateTime.Now</h2>
The preceding code looks a lot like a Razor view file. What makes it different is the @page directive. @page makes
the file into an MVC action - which means that it handles requests directly, without going through a controller.
@page must be the first Razor directive on a page. @page affects the behavior of other Razor constructs.
A similar page, using a PageModel class, is shown in the following two files. The Pages/Index2.cshtml file:
@page
@using RazorPagesIntro.Pages
@model IndexModel2
<h2>Separate page model</h2>

<p>
@Model.Message
</p>
The Pages/Index2.cshtml.cs page model:
using Microsoft.AspNetCore.Mvc.RazorPages;
using System;
namespace RazorPagesIntro.Pages
{
public class IndexModel2 : PageModel
{
public string Message { get; private set; } = "PageModel in C#";
public void OnGet()

{
Message += $" Server time is { DateTime.Now }";
}
}
}
By convention, the PageModel class file has the same name as the Razor Page file with .cs appended. For example,
the previous Razor Page is Pages/Index2.cshtml. The file containing the PageModel class is named
Pages/Index2.cshtml.cs.
The associations of URL paths to pages are determined by the page's location in the file system. The following table
shows a Razor Page path and the matching URL:
FILE NAME AND PATH MATCHING URL
/Pages/Index.cshtml / or /Index
/Pages/Contact.cshtml /Contact
/Pages/Store/Contact.cshtml /Store/Contact
/Pages/Store/Index.cshtml /Store or /Store/Index
Notes:
The runtime looks for Razor Pages files in the Pages folder by default.
Index is the default page when a URL doesn't include a page.
Writing a basic form

Razor Pages is designed to make common patterns used with web browsers easy to implement when building an
app. Model binding, Tag Helpers, and HTML helpers all just work with the properties defined in a Razor Page class.
Consider a page that implements a basic "contact us" form for the Contact model:
For the samples in this document, the DbContext is initialized in the Startup.cs file.
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using RazorPagesContacts.Data;
namespace RazorPagesContacts
{
{
public IHostingEnvironment HostingEnvironment { get; }

{
services.AddDbContext<AppDbContext>(options =>
options.UseInMemoryDatabase("name"));
services.AddMvc();
}

{
app.UseMvc();
}
}
}
The data model:

using System.ComponentModel.DataAnnotations;
namespace RazorPagesContacts.Data
{
public class Customer
{
public int Id { get; set; }
[Required, StringLength(100)]
public string Name { get; set; }
}
}
The db context:
{
public class AppDbContext : DbContext
{
public AppDbContext(DbContextOptions options)
: base(options)
{
}
public DbSet<Customer> Customers { get; set; }

}
}
The Pages/Create.cshtml view file:
@page
@model RazorPagesContacts.Pages.CreateModel
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
<html>
<body>
<p>
Enter your name.
</p>
<div asp-validation-summary="All"></div>
<form method="POST">
<div>Name: <input asp-for="Customer.Name" /></div>
<input type="submit" />
</form>
</body>
</html>
The Pages/Create.cshtml.cs page model:

using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
namespace RazorPagesContacts.Pages
{
public class CreateModel : PageModel
{
private readonly AppDbContext _db;
public CreateModel(AppDbContext db)

{
_db = db;
}
[BindProperty]
public Customer Customer { get; set; }
public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}
_db.Customers.Add(Customer);
await _db.SaveChangesAsync();
return RedirectToPage("/Index");
}
}
}
By convention, the PageModel class is called <PageName>Model and is in the same namespace as the page.
The PageModel class allows separation of the logic of a page from its presentation. It defines page handlers for
requests sent to the page and the data used to render the page. This separation allows you to manage page
dependencies through dependency injection and to unit test the pages.
The page has an OnPostAsync handler method, which runs on POST requests (when a user posts the form). You can
add handler methods for any HTTP verb. The most common handlers are:
OnGet to initialize state needed for the page. OnGet sample.
OnPost to handle form submissions.
The Async naming suffix is optional but is often used by convention for asynchronous functions. The OnPostAsync
code in the preceding example looks similar to what you would normally write in a controller. The preceding code is
typical for Razor Pages. Most of the MVC primitives like model binding, validation, and action results are shared.
The previous OnPostAsync method:

{
{
return Page();
}
}
The basic flow of OnPostAsync :
Check for validation errors.
If there are no errors, save the data and redirect.
If there are errors, show the page again with validation messages. Client-side validation is identical to traditional
ASP.NET Core MVC applications. In many cases, validation errors would be detected on the client, and never
submitted to the server.
When the data is entered successfully, the OnPostAsync handler method calls the RedirectToPage helper method to
return an instance of RedirectToPageResult . RedirectToPage is a new action result, similar to RedirectToAction or
RedirectToRoute , but customized for pages. In the preceding sample, it redirects to the root Index page ( /Index ).
RedirectToPage is detailed in the URL generation for Pages section.
When the submitted form has validation errors (that are passed to the server), the OnPostAsync handler method
calls the Page helper method. Page returns an instance of PageResult . Returning Page is similar to how actions
in controllers return View . PageResult is the default return type for a handler method. A handler method that
returns void renders the page.
The Customer property uses [BindProperty] attribute to opt in to model binding.

{

{
_db = db;
}
[BindProperty]

{
{
return Page();
}
}
}
Razor Pages, by default, bind properties only with non-GET verbs. Binding to properties can reduce the amount of
code you have to write. Binding reduces code by using the same property to render form fields (
<input asp-for="Customer.Name" /> ) and accept the input.
NOTE
For security reasons, you must opt in to binding GET request data to page model properties. Verify user input before
mapping it to properties. Opting in to this behavior is useful when addressing scenarios which rely on query string or route
values.
To bind a property on GET requests, set the [BindProperty] attribute's SupportsGet property to true :
[BindProperty(SupportsGet = true)]
The home page (Index.cshtml):
@page
@model RazorPagesContacts.Pages.IndexModel
<h1>Contacts</h1>
<form method="post">
<table class="table">
<thead>
<tr>
<th>ID</th>
<th>Name</th>
</tr>
</thead>
<tbody>
@foreach (var contact in Model.Customers)
{
<tr>
<td>@contact.Id</td>
<td>@contact.Name</td>
<td>
<a asp-page="./Edit" asp-route-id="@contact.Id">edit</a>
<button type="submit" asp-page-handler="delete"
asp-route-id="@contact.Id">delete</button>
</td>
</tr>
}
</tbody>
</table>
<a asp-page="./Create">Create</a>
</form>
The associated PageModel class (Index.cshtml.cs):

using System.Collections.Generic;
{
public class IndexModel : PageModel
{
public IndexModel(AppDbContext db)

{
_db = db;
}
public IList<Customer> Customers { get; private set; }
public async Task OnGetAsync()

{
Customers = await _db.Customers.AsNoTracking().ToListAsync();
}
public async Task<IActionResult> OnPostDeleteAsync(int id)

{
var contact = await _db.Customers.FindAsync(id);
if (contact != null)
{
_db.Customers.Remove(contact);
}
return RedirectToPage();
}
}
}
The Index.cshtml file contains the following markup to create an edit link for each contact:
The Anchor Tag Helper used the asp-route-{value} attribute to generate a link to the Edit page. The link contains
route data with the contact ID. For example, http://localhost:5000/Edit/1 .
The Pages/Edit.cshtml file:
@page "{id:int}"
@model RazorPagesContacts.Pages.EditModel
@{
ViewData["Title"] = "Edit Customer";
}
<h1>Edit Customer - @Model.Customer.Id</h1>

<input asp-for="Customer.Id" type="hidden" />
<div>
<label asp-for="Customer.Name"></label>
<div>
<input asp-for="Customer.Name" />
<span asp-validation-for="Customer.Name" ></span>
</div>
</div>
<div>
<button type="submit">Save</button>
</div>
</form>
The first line contains the @page "{id:int}" directive. The routing constraint "{id:int}" tells the page to accept
requests to the page that contain int route data. If a request to the page doesn't contain route data that can be
converted to an int , the runtime returns an HTTP 404 (not found) error. To make the ID optional, append ? to
the route constraint:
@page "{id:int?}"
The Pages/Edit.cshtml.cs file:

using System;
{
public class EditModel : PageModel
{
public EditModel(AppDbContext db)

{
_db = db;
}
[BindProperty]
public async Task<IActionResult> OnGetAsync(int id)

{
Customer = await _db.Customers.FindAsync(id);
if (Customer == null)
{
}
return Page();
}

{
{
return Page();
}
_db.Attach(Customer).State = EntityState.Modified;
try
{
}
catch (DbUpdateConcurrencyException)
{
throw new Exception($"Customer {Customer.Id} not found!");
}
}
}
}
The Index.cshtml file also contains markup to create a delete button for each customer contact:

When the delete button is rendered in HTML, its formaction includes parameters for:
The customer contact ID specified by the asp-route-id attribute.
The handler specified by the asp-page-handler attribute.
Here is an example of a rendered delete button with a customer contact ID of 1 :
<button type="submit" formaction="/?id=1&handler=delete">delete</button>
When the button is selected, a form POST request is sent to the server. By convention, the name of the handler
method is selected based the value of the handler parameter according to the scheme OnPost[handler]Async .
Because the handler is delete in this example, the OnPostDeleteAsync handler method is used to process the
POST request. If the asp-page-handler is set to a different value, such as remove , a page handler method with the
name OnPostRemoveAsync is selected.

{
{
}
}
The OnPostDeleteAsync method:

Accepts the id from the query string.
Queries the database for the customer contact with FindAsync .
If the customer contact is found, they're removed from the list of customer contacts. The database is updated.
Calls RedirectToPage to redirect to the root Index page ( /Index ).
Mark page properties required

Properties on a PageModel can be decorated with the Required attribute:
namespace RazorPagesMovie.Pages.Movies
{
{
public IActionResult OnGet()
{
return Page();
}
[BindProperty]
[Required(ErrorMessage = "Color is required")]
public string Color { get; set; }
public IActionResult OnPostAsync()

{
{
return Page();
}
// Process color.
return RedirectToPage("./Index");
}
}
}
See Model validation for more information.
Manage HEAD requests with the OnGet handler

Ordinarily, a HEAD handler is created and called for HEAD requests:
public void OnHead()

{
HttpContext.Response.Headers.Add("HandledBy", "Handled by OnHead!");
}
If no HEAD handler ( OnHead ) is defined, Razor Pages falls back to calling the GET page handler ( OnGet ) in
ASP.NET Core 2.1 or later. Opt in to this behavior with the SetCompatibilityVersion method in Startup.Configure
for ASP.NET Core 2.1 to 2.x:
services.AddMvc()
.SetCompatibilityVersion(Microsoft.AspNetCore.Mvc.CompatibilityVersion.Version_2_1);
SetCompatibilityVersion effectively sets the Razor Pages option AllowMappingHeadRequestsToGetHandler to true .

Rather than opting into all 2.1 behaviors with SetCompatibilityVersion , you can explicitly opt-in to specific
behaviors. The following code opts into the mapping HEAD requests to the GET handler.
services.AddMvc()
.AddRazorPagesOptions(options =>
{
options.AllowMappingHeadRequestsToGetHandler = true;
});
XSRF/CSRF and Razor Pages
You don't have to write any code for antiforgery validation. Antiforgery token generation and validation are
automatically included in Razor Pages.
Using Layouts, partials, templates, and Tag Helpers with Razor Pages
Pages work with all the capabilities of the Razor view engine. Layouts, partials, templates, Tag Helpers,
_ViewStart.cshtml, _ViewImports.cshtml work in the same way they do for conventional Razor views.
Let's declutter this page by taking advantage of some of those capabilities.
Add a layout page to Pages/Shared/_Layout.cshtml:
Add a layout page to Pages/_Layout.cshtml:
<!DOCTYPE html>
<html>
<head>
<title>Razor Pages Sample</title>
</head>
<body>
<a asp-page="/Index">Home</a>
@RenderBody()
<a asp-page="/Customers/Create">Create</a> <br />
</body>
</html>
The Layout:
Controls the layout of each page (unless the page opts out of layout).
Imports HTML structures such as JavaScript and stylesheets.
See layout page for more information.
The Layout property is set in Pages/_ViewStart.cshtml:
@{
Layout = "_Layout";
}
The layout is in the Pages/Shared folder. Pages look for other views (layouts, templates, partials) hierarchically,
starting in the same folder as the current page. A layout in the Pages/Shared folder can be used from any Razor
page under the Pages folder.
The layout file should go in the Pages/Shared folder.
The layout is in the Pages folder. Pages look for other views (layouts, templates, partials) hierarchically, starting in
the same folder as the current page. A layout in the Pages folder can be used from any Razor page under the Pages
folder.
We recommend you not put the layout file in the Views/Shared folder. Views/Shared is an MVC views pattern.
Razor Pages are meant to rely on folder hierarchy, not path conventions.
View search from a Razor Page includes the Pages folder. The layouts, templates, and partials you're using with
MVC controllers and conventional Razor views just work.
Add a Pages/_ViewImports.cshtml file:
@namespace RazorPagesContacts.Pages
@namespace is explained later in the tutorial. The @addTagHelper directive brings in the built-in Tag Helpers to all the
pages in the Pages folder.
When the @namespace directive is used explicitly on a page:
@page
@namespace RazorPagesIntro.Pages.Customers
@model NameSpaceModel
<h2>Name space</h2>
<p>
@Model.Message
</p>
The directive sets the namespace for the page. The @model directive doesn't need to include the namespace.
When the @namespace directive is contained in _ViewImports.cshtml, the specified namespace supplies the prefix for
the generated namespace in the Page that imports the @namespace directive. The rest of the generated namespace
(the suffix portion) is the dot-separated relative path between the folder containing _ViewImports.cshtml and the
folder containing the page.
For example, the PageModel class Pages/Customers/Edit.cshtml.cs explicitly sets the namespace:
{
{

{
_db = db;
}
// Code removed for brevity.
The Pages/_ViewImports.cshtml file sets the following namespace:
The generated namespace for the Pages/Customers/Edit.cshtml Razor Page is the same as the PageModel class.
@namespace also works with conventional Razor views.
The original Pages/Create.cshtml view file:
@page
<html>
<body>
<p>
Enter your name.
</p>
</form>
</body>
</html>
The updated Pages/Create.cshtml view file:
@page
@model CreateModel
<html>
<body>
<p>
Enter your name.
</p>
</form>
</body>
</html>
The Razor Pages starter project contains the Pages/_ValidationScriptsPartial.cshtml, which hooks up client-side
validation.
For more information on partial views, see Partial views in ASP.NET Core.
URL generation for Pages

The Create page, shown previously, uses RedirectToPage :

{
{
return Page();
}
}
The app has the following file/folder structure:

/Pages
Index.cshtml
/Customers
Create.cshtml
Edit.cshtml
Index.cshtml
The Pages/Customers/Create.cshtml and Pages/Customers/Edit.cshtml pages redirect to Pages/Index.cshtml after
success. The string /Index is part of the URI to access the preceding page. The string /Index can be used to
generate URIs to the Pages/Index.cshtml page. For example:
Url.Page("/Index", ...)
<a asp-page="/Index">My Index Page</a>
RedirectToPage("/Index")
The page name is the path to the page from the root /Pages folder including a leading / (for example, /Index ).
The preceding URL generation samples offer enhanced options and functional capabilities over hardcoding a URL.
URL generation uses routing and can generate and encode parameters according to how the route is defined in the
destination path.
URL generation for pages supports relative names. The following table shows which Index page is selected with
different RedirectToPage parameters from Pages/Customers/Create.cshtml:
REDIRECTTOPAGE(X) PAGE
RedirectToPage("/Index") Pages/Index
RedirectToPage("./Index"); Pages/Customers/Index
RedirectToPage("../Index") Pages/Index
RedirectToPage("Index") Pages/Customers/Index
RedirectToPage("Index") , RedirectToPage("./Index") , and RedirectToPage("../Index") are relative names. The

RedirectToPage parameter is combined with the path of the current page to compute the name of the destination
page.
Relative name linking is useful when building sites with a complex structure. If you use relative names to link
between pages in a folder, you can rename that folder. All the links still work (because they didn't include the folder
name).
ViewData attribute
Data can be passed to a page with ViewDataAttribute. Properties on controllers or Razor Page models decorated
with [ViewData] have their values stored and loaded from the ViewDataDictionary.
In the following example, the AboutModel contains a Title property decorated with [ViewData] . The Title
property is set to the title of the About page:
public class AboutModel : PageModel
{
[ViewData]
public string Title { get; } = "About";
public void OnGet()

{
}
}
In the About page, access the Title property as a model property:
<h1>@Model.Title</h1>
In the layout, the title is read from the ViewData dictionary:
<!DOCTYPE html>
<html lang="en">
<head>
<title>@ViewData["Title"] - WebApplication</title>
...
TempData
ASP.NET Core exposes the TempData property on a controller. This property stores data until it's read. The Keep
and Peek methods can be used to examine the data without deletion. TempData is useful for redirection, when data
is needed for more than a single request.
The [TempData] attribute is new in ASP.NET Core 2.0 and is supported on controllers and pages.
The following code sets the value of Message using TempData :
public class CreateDotModel : PageModel
{
public CreateDotModel(AppDbContext db)

{
_db = db;
}
[TempData]
public string Message { get; set; }
[BindProperty]

{
{
return Page();
}
Message = $"Customer {Customer.Name} added";
}
}
The following markup in the Pages/Customers/Index.cshtml file displays the value of Message using TempData .
<h3>Msg: @Model.Message</h3>
The Pages/Customers/Index.cshtml.cs page model applies the [TempData] attribute to the Message property.
[TempData]
See TempData for more information.
Multiple handlers per page

The following page generates markup for two page handlers using the asp-page-handler Tag Helper:
@page
@model CreateFATHModel
<html>
<body>
<p>
Enter your name.
</p>
<input type="submit" asp-page-handler="JoinList" value="Join" />
<input type="submit" asp-page-handler="JoinListUC" value="JOIN UC" />
</form>
</body>
</html>
The form in the preceding example has two submit buttons, each using the FormActionTagHelper to submit to a
different URL. The asp-page-handler attribute is a companion to asp-page . asp-page-handler generates URLs that
submit to each of the handler methods defined by a page. asp-page isn't specified because the sample is linking to
the current page.
The page model:
namespace RazorPagesContacts.Pages.Customers
{
public class CreateFATHModel : PageModel
{
public CreateFATHModel(AppDbContext db)

{
_db = db;
}
[BindProperty]
public async Task<IActionResult> OnPostJoinListAsync()

{
{
return Page();
}
}
public async Task<IActionResult> OnPostJoinListUCAsync()

{
{
return Page();
}
Customer.Name = Customer.Name?.ToUpper();
return await OnPostJoinListAsync();
}
}
}
The preceding code uses named handler methods. Named handler methods are created by taking the text in the
name after On<HTTP Verb> and before Async (if present). In the preceding example, the page methods are
OnPostJoinListAsync and OnPostJoinListUCAsync. With OnPost and Async removed, the handler names are
JoinList and JoinListUC .

Using the preceding code, the URL path that submits to is

OnPostJoinListAsync
http://localhost:5000/Customers/CreateFATH?handler=JoinList . The URL path that submits to
OnPostJoinListUCAsync is http://localhost:5000/Customers/CreateFATH?handler=JoinListUC .
Custom routes
Use the @page directive to:
Specify a custom route to a page. For example, the route to the About page can be set to /Some/Other/Path with
@page "/Some/Other/Path" .
Append segments to a page's default route. For example, an "item" segment can be added to a page's default
route with @page "item" .
Append parameters to a page's default route. For example, an ID parameter, id , can be required for a page with
@page "{id}" .
A root-relative path designated by a tilde ( ~ ) at the beginning of the path is supported. For example,
@page "~/Some/Other/Path" is the same as @page "/Some/Other/Path" .
You can change the query string ?handler=JoinList in the URL to a route segment /JoinList by specifying the
route template @page "{handler?}" .
If you don't like the query string ?handler=JoinList in the URL, you can change the route to put the handler name
in the path portion of the URL. You can customize the route by adding a route template enclosed in double quotes
after the @page directive.
@page "{handler?}"
@model CreateRouteModel
<html>
<body>
<p>
Enter your name.
</p>
</form>
</body>
</html>
Using the preceding code, the URL path that submits to OnPostJoinListAsync is
http://localhost:5000/Customers/CreateFATH/JoinList . The URL path that submits to OnPostJoinListUCAsync is
http://localhost:5000/Customers/CreateFATH/JoinListUC .
The ? following handler means the route parameter is optional.
Configuration and settings

To configure advanced options, use the extension method AddRazorPagesOptions on the MVC builder:

{
services.AddMvc()
{
options.RootDirectory = "/MyPages";
options.Conventions.AuthorizeFolder("/MyPages/Admin");
});
}
Currently you can use the RazorPagesOptions to set the root directory for pages, or add application model
conventions for pages. We'll enable more extensibility this way in the future.
To precompile views, see Razor view compilation .
Download or view sample code.
See Get started with Razor Pages, which builds on this introduction.
Specify that Razor Pages are at the content root
By default, Razor Pages are rooted in the /Pages directory. Add WithRazorPagesAtContentRoot to AddMvc to
specify that your Razor Pages are at the content root (ContentRootPath) of the app:
services.AddMvc()
{
...
})
.WithRazorPagesAtContentRoot();
Specify that Razor Pages are at a custom root directory

Add WithRazorPagesRoot to AddMvc to specify that your Razor Pages are at a custom root directory in the app
(provide a relative path):
services.AddMvc()
{
...
})
.WithRazorPagesRoot("/path/to/razor/pages");
Additional resources
Razor syntax reference for ASP.NET Core
Get started with Razor Pages in ASP.NET Core
Razor Pages authorization conventions in ASP.NET Core
Razor Pages route and app conventions in ASP.NET Core
Razor Pages unit tests in ASP.NET Core
Partial views in ASP.NET Core
Create a Web API with ASP.NET Core and Visual
Studio
By Rick Anderson and Mike Wasson

This tutorial builds a web API for managing a list of "to-do" items. A user interface (UI) isn't created.
There are three versions of this tutorial:
Windows: Web API with Visual Studio on Windows (This tutorial)
macOS: Web API with Visual Studio for Mac
macOS, Linux, Windows: Web API with Visual Studio Code
Overview
This tutorial creates the following API:
API DESCRIPTION REQUEST BODY RESPONSE BODY
GET /api/todo Get all to-do items None Array of to-do items
GET /api/todo/{id} Get an item by ID None To-do item
POST /api/todo Add a new item To-do item To-do item
PUT /api/todo/{id} Update an existing item To-do item None
DELETE /api/todo/{id} Delete an item None None
The following diagram shows the basic design of the app.
The client is whatever consumes the web API (mobile app, browser, etc.). This tutorial doesn't create a client.
Postman or curl is used as the client to test the app.
A model is an object that represents the data in the app. In this case, the only model is a to-do item. Models
are represented as C# classes, also known as Plain Old CLR Object (POCOs).
A controller is an object that handles HTTP requests and creates the HTTP response. This app has a single
controller.
To keep the tutorial simple, the app doesn't use a persistent database. The sample app stores to-do items in
an in-memory database.
Prerequisites
Visual Studio 2017 version 15.7.3 or later with the following workloads:
ASP.NET and web development
.NET Core cross-platform development
.NET Core 2.1 SDK or later
Create the project

Follow these steps in Visual Studio:
From the File menu, select New > Project.
Select the ASP.NET Core Web Application template. Name the project TodoApi and click OK.
In the New ASP.NET Core Web Application - TodoApi dialog, choose the ASP.NET Core version. Select the
API template and click OK. Do not select Enable Docker Support.
Launch the app
In Visual Studio, press CTRL+F5 to launch the app. Visual Studio launches a browser and navigates to
http://localhost:<port>/api/values , where <port> is a randomly chosen port number. Chrome, Microsoft Edge,
and Firefox display the following output:
["value1","value2"]
If using Internet Explorer, you'll be prompted to save a values.json file.

Add a model class
A model is an object representing the data in the app. In this case, the only model is a to-do item.
In Solution Explorer, right-click the project. Select Add > New Folder. Name the folder Models.
NOTE
The model classes can go anywhere in the project. The Models folder is used by convention for model classes.
In Solution Explorer, right-click the Models folder and select Add > Class. Name the class TodoItem and click Add.
Update the TodoItem class with the following code:
namespace TodoApi.Models
{
public class TodoItem
{
public long Id { get; set; }
public bool IsComplete { get; set; }
}
}
The database generates the Id when a TodoItem is created.
Create the database context
The database context is the main class that coordinates Entity Framework functionality for a given data model. This
class is created by deriving from the Microsoft.EntityFrameworkCore.DbContext class.
In Solution Explorer, right-click the Models folder and select Add > Class. Name the class TodoContext and click
Add.
Replace the class with the following code:
{
public class TodoContext : DbContext
{
public TodoContext(DbContextOptions<TodoContext> options)
: base(options)
{
}
public DbSet<TodoItem> TodoItems { get; set; }

}
}
Register the database context

In this step, the database context is registered with the dependency injection container. Services (such as the DB
context) that are registered with the dependency injection (DI) container are available to the controllers.
Register the DB context with the service container using the built-in support for dependency injection. Replace the
contents of the Startup.cs file with the following code:
using TodoApi.Models;
namespace TodoApi
{
{
{
services.AddDbContext<TodoContext>(opt =>
opt.UseInMemoryDatabase("TodoList"));
services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
}

{
app.UseMvc();
}
}
}
namespace TodoApi
{
{
{
services.AddMvc();
}

{
app.UseMvc();
}
}
}
The preceding code:

Removes the unused code.
Specifies an in-memory database is injected into the service container.
Add a controller
In Solution Explorer, right-click the Controllers folder. Select Add > New Item. In the Add New Item dialog,
select the API Controller Class template. Name the class TodoController, and click Add.

using System.Linq;
namespace TodoApi.Controllers
{
[Route("api/[controller]")]
public class TodoController : ControllerBase
{
private readonly TodoContext _context;
public TodoController(TodoContext context)

{
_context = context;
if (_context.TodoItems.Count() == 0)
{
_context.TodoItems.Add(new TodoItem { Name = "Item1" });
_context.SaveChanges();
}
}
}
}
The preceding code defines an API controller class without methods. In the next sections, methods are added to
implement the API.
using System.Linq;
{
[ApiController]
{

{
_context = context;
{
// Create a new TodoItem if collection is empty,
// which means you can't delete all TodoItems.
}
}
}
}
The preceding code:

Defines an API controller class without methods.
Creates a new Todo item when TodoItems is empty. You won't be able to delete all the Todo items because the
constructor creates a new one if TodoItems is empty.
In the next sections, methods are added to implement the API. The class is annotated with an [ApiController]
attribute to enable some convenient features. For information on features enabled by the attribute, see Annotate
class with ApiControllerAttribute.
The controller's constructor uses Dependency Injection to inject the database context ( TodoContext ) into the
controller. The database context is used in each of the CRUD methods in the controller. The constructor adds an
item to the in-memory database if one doesn't exist.
Get to-do items

To get to-do items, add the following methods to the TodoController class:
[HttpGet]
public List<TodoItem> GetAll()
{
return _context.TodoItems.ToList();
}
[HttpGet("{id}", Name = "GetTodo")]

public IActionResult GetById(long id)
{
var item = _context.TodoItems.Find(id);
if (item == null)
{
return NotFound();
}
return Ok(item);
}
[HttpGet]
public ActionResult<List<TodoItem>> GetAll()
{
}

public ActionResult<TodoItem> GetById(long id)
{
if (item == null)
{
return NotFound();
}
return item;
}
These methods implement the two GET methods:

GET /api/todo
GET /api/todo/{id}
Here's a sample HTTP response for the GetAll method:
[
{
"id": 1,
"name": "Item1",
"isComplete": false
}
]
Later in the tutorial, I'll show how the HTTP response can be viewed with Postman or curl.
Routing and URL paths
The [HttpGet] attribute denotes a method that responds to an HTTP GET request. The URL path for each method
is constructed as follows:
Take the template string in the controller's Route attribute:
{
{
{
[ApiController]
{
Replace [controller] with the name of the controller, which is the controller class name minus the "Controller"
suffix. For this sample, the controller class name is TodoController and the root name is "todo". ASP.NET Core
routing is case insensitive.
If the [HttpGet] attribute has a route template (such as [HttpGet("/products")] , append that to the path. This
sample doesn't use a template. For more information, see Attribute routing with Http[Verb] attributes.
In the following GetById method, "{id}" is a placeholder variable for the unique identifier of the to-do item.
When GetById is invoked, it assigns the value of "{id}" in the URL to the method's id parameter.

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}

{
if (item == null)
{
return NotFound();
}
return item;
}
Name = "GetTodo" creates a named route. Named routes:

Enable the app to create an HTTP link using the route name.
Are explained later in the tutorial.
Return values
The GetAll method returns a collection of TodoItem objects. MVC automatically serializes the object to JSON and
writes the JSON into the body of the response message. The response code for this method is 200, assuming there
are no unhandled exceptions. Unhandled exceptions are translated into 5xx errors.
In contrast, the GetById method returns the more general IActionResult type, which represents a wide range of
return types. GetById has two different return types:
If no item matches the requested ID, the method returns a 404 error. Returning NotFound returns an HTTP 404
response.
Otherwise, the method returns 200 with a JSON response body. Returning Ok results in an HTTP 200 response.
In contrast, the GetById method returns the ActionResult<T> type, which represents a wide range of return types.
GetById has two different return types:
response.
Otherwise, the method returns 200 with a JSON response body. Returning item results in an HTTP 200
response.
Launch the app
http://localhost:<port>/api/values , where <port> is a randomly chosen port number. Navigate to the Todo
controller at http://localhost:<port>/api/todo .
Implement the other CRUD operations

In the following sections, Create , Update , and Delete methods are added to the controller.
Create
Add the following Create method:
[HttpPost]
public IActionResult Create([FromBody] TodoItem item)
{
if (item == null)
{
return BadRequest();
}
_context.TodoItems.Add(item);
return CreatedAtRoute("GetTodo", new { id = item.Id }, item);

}
The preceding code is an HTTP POST method, as indicated by the [HttpPost] attribute. The [FromBody] attribute
tells MVC to get the value of the to-do item from the body of the HTTP request.
[HttpPost]
public IActionResult Create(TodoItem item)
{

}
The preceding code is an HTTP POST method, as indicated by the [HttpPost] attribute. MVC gets the value of the
to-do item from the body of the HTTP request.
The CreatedAtRoute method:
Returns a 201 response. HTTP 201 is the standard response for an HTTP POST method that creates a new
resource on the server.
Adds a Location header to the response. The Location header specifies the URI of the newly created to-do item.
See 10.2.2 201 Created.
Uses the "GetTodo" named route to create the URL. The "GetTodo" named route is defined in GetById :

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}

{
if (item == null)
{
return NotFound();
}
return item;
}
Use Postman to send a Create request

Start the app.
Open Postman.
Update the port number in the localhost URL.
Set the HTTP method to POST.
Click the Body tab.
Select the raw radio button.
Set the type to JSON (application/json).
Enter a request body with a to-do item resembling the following JSON:
{
"name":"walk dog",
"isComplete":true
}
Click the Send button.
TIP
If no response displays after clicking Send, disable the SSL certification verification option. This is found under File >
Settings. Click the Send button again after disabling the setting.
Click the Headers tab in the Response pane and copy the Location header value:
The Location header URI can be used to access the new item.
Update
Add the following Update method:
[HttpPut("{id}")]
public IActionResult Update(long id, [FromBody] TodoItem item)
{
if (item == null || item.Id != id)
{
}
var todo = _context.TodoItems.Find(id);

if (todo == null)
{
return NotFound();
}
todo.IsComplete = item.IsComplete;
todo.Name = item.Name;
_context.TodoItems.Update(todo);
return NoContent();
}
[HttpPut("{id}")]
public IActionResult Update(long id, TodoItem item)
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}
Update is similar to Create , except it uses HTTP PUT. The response is 204 (No Content). According to the HTTP
specification, a PUT request requires the client to send the entire updated entity, not just the deltas. To support
partial updates, use HTTP PATCH.
Use Postman to update the to-do item's name to "walk cat":
Delete
Add the following Delete method:
[HttpDelete("{id}")]
public IActionResult Delete(long id)
{
if (todo == null)
{
return NotFound();
}
_context.TodoItems.Remove(todo);
return NoContent();
}
The Delete response is 204 (No Content).

Use Postman to delete the to-do item:
Call the Web API with jQuery

In this section, an HTML page is added that uses jQuery to call the Web API. jQuery initiates the request and
updates the page with the details from the API's response.
Configure the project to serve static files and to enable default file mapping. This is accomplished by invoking the
UseStaticFiles and UseDefaultFiles extension methods in Startup.Configure. For more information, see Static files.
{
app.UseDefaultFiles();
app.UseStaticFiles();
app.UseMvc();
}
Add an HTML file, named index.html, to the project's wwwroot directory. Replace its contents with the following
markup:
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>To-do CRUD</title>
<style>
input[type='submit'], button, [aria-label] {
cursor: pointer;
}
#spoiler {
display: none;
}
table {
font-family: Arial, sans-serif;
border: 1px solid;
border-collapse: collapse;
}
th {
background-color: #0066CC;
color: white;
}
td {
border: 1px solid;
padding: 5px;
}
</style>
</head>
<body>
<h1>To-do CRUD</h1>
<h3>Add</h3>
<form action="javascript:void(0);" method="POST" onsubmit="addItem()">
<input type="text" id="add-name" placeholder="New to-do">
<input type="submit" value="Add">
</form>
<div id="spoiler">
<h3>Edit</h3>
<form class="my-form">
<input type="hidden" id="edit-id">
<input type="checkbox" id="edit-isComplete">
<input type="text" id="edit-name">
<input type="submit" value="Edit">
<a onclick="closeInput()" aria-label="Close">✖</a>
</form>
</div>
<p id="counter"></p>
<table>
<tr>
<th>Is Complete</th>
<th>Name</th>
<th>Name</th>
<th></th>
<th></th>
</tr>
<tbody id="todos"></tbody>
</table>
<script src="https://code.jquery.com/jquery-3.3.1.min.js"
integrity="sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8="
crossorigin="anonymous"></script>
<script src="site.js"></script>
</body>
</html>
Add a JavaScript file, named site.js, to the project's wwwroot directory. Replace its contents with the following code:
const uri = 'api/todo';

let todos = null;
function getCount(data) {
const el = $('#counter');
let name = 'to-do';
if (data) {
if (data > 1) {
name = 'to-dos';
}
el.text(data + ' ' + name);
} else {
el.html('No ' + name);
}
}
$(document).ready(function () {
getData();
});
function getData() {
$.ajax({
type: 'GET',
url: uri,
success: function (data) {
$('#todos').empty();
getCount(data.length);
$.each(data, function (key, item) {
const checked = item.isComplete ? 'checked' : '';
$('<tr><td><input disabled="true" type="checkbox" ' + checked + '></td>' +

'<td>' + item.name + '</td>' +
'<td><button onclick="editItem(' + item.id + ')">Edit</button></td>' +
'<td><button onclick="deleteItem(' + item.id + ')">Delete</button></td>' +
'</tr>').appendTo($('#todos'));
});
todos = data;
}
});
}
function addItem() {
const item = {
'name': $('#add-name').val(),
'isComplete': false
};
$.ajax({
type: 'POST',
accepts: 'application/json',
url: uri,
contentType: 'application/json',
data: JSON.stringify(item),
error: function (jqXHR, textStatus, errorThrown) {
alert('here');
},
success: function (result) {
getData();
$('#add-name').val('');
}
});
}
function deleteItem(id) {
$.ajax({
url: uri + '/' + id,
type: 'DELETE',
getData();
}
});
}
function editItem(id) {
$.each(todos, function (key, item) {
if (item.id === id) {
$('#edit-name').val(item.name);
$('#edit-id').val(item.id);
$('#edit-isComplete')[0].checked = item.isComplete;
}
});
$('#spoiler').css({ 'display': 'block' });
}
$('.my-form').on('submit', function () {
const item = {
'name': $('#edit-name').val(),
'isComplete': $('#edit-isComplete').is(':checked'),
'id': $('#edit-id').val()
};
$.ajax({
url: uri + '/' + $('#edit-id').val(),
type: 'PUT',
getData();
}
});
closeInput();
return false;
});
function closeInput() {
$('#spoiler').css({ 'display': 'none' });
}
A change to the ASP.NET Core project's launch settings may be required to test the HTML page locally. Open
launchSettings.json in the Properties directory of the project. Remove the launchUrl property to force the app to
open at index.html—the project's default file.
There are several ways to get jQuery. In the preceding snippet, the library is loaded from a CDN. This sample is a
complete CRUD example of calling the API with jQuery. There are additional features in this sample to make the
experience richer. Below are explanations around the calls to the API.
Get a list of to -do items
To get a list of to-do items, send an HTTP GET request to /api/todo.
The jQuery ajax function sends an AJAX request to the API, which returns JSON representing an object or array.
This function can handle all forms of HTTP interaction, sending an HTTP request to the specified url . GET is used
as the type . The success callback function is invoked if the request succeeds. In the callback, the DOM is updated
with the to-do information.
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}
Add a to -do item

To add a to-do item, send an HTTP POST request to /api/todo/. The request body should contain a to-do object.
The ajax function is using POST to call the API. For POST and PUT requests, the request body represents the data
sent to the API. The API is expecting a JSON request body. The accepts and contentType options are set to
application/json to classify the media type being received and sent, respectively. The data is converted to a JSON
object using JSON.stringify . When the API returns a successful status code, the getData function is invoked to
update the HTML table.
const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
alert('here');
},
getData();
}
});
}
Update a to -do item

Updating a to-do item is very similar to adding one, since both rely on a request body. The only real difference
between the two in this case is that the url changes to add the unique identifier of the item, and the type is PUT .
$.ajax({
type: 'PUT',
getData();
}
});
Delete a to -do item

Deleting a to-do item is accomplished by setting the type on the AJAX call to DELETE and specifing the item's
unique identifier in the URL.
$.ajax({
type: 'DELETE',
getData();
}
});
Next steps
For information on using a persistent database, see:
Create a Razor Pages web app with ASP.NET Core
Work with data in ASP.NET Core
ASP.NET Core Web API help pages using Swagger
Routing to controller actions
Build web APIs with ASP.NET Core
For information about deploying an API, including to Azure App Service, see Host and deploy.
View or download sample code. See how to download.
The following step-by-step guides for developing ASP.NET Core applications are available:
Build web apps

Razor Pages is the recommended approach to create a new Web UI app with ASP.NET Core 2.0.
Razor Pages on Windows
Razor Pages on macOS
Razor Pages with VS Code
Create a real-time SignalR web app
Create a SignalR web app with TypeScript
Create an ASP.NET Core MVC web app
Web app with Visual Studio for Windows
Web app with Visual Studio for Mac
Web app with Visual Studio Code on macOS or Linux
Get started with ASP.NET Core and Entity Framework Core using Visual Studio
Create Tag Helpers
Create a simple view component
Develop apps using a file watcher
Build Web APIs

Create a Web API with ASP.NET Core
Web API with Visual Studio for Windows
Create backend web services for native mobile apps
Data access and storage

Get started with Razor Pages and EF Core using Visual Studio
Get started with ASP.NET Core MVC and EF Core using Visual Studio
ASP.NET Core MVC with EF Core - new database
ASP.NET Core MVC with EF Core - existing database
Enable authentication using Facebook, Google, and other external providers
Use Gulp
Use Grunt
Test
Unit testing in .NET Core using dotnet test
Host and deploy

Deploy an ASP.NET Core web app to Azure using Visual Studio
Deploy an ASP.NET Core web app to Azure using the command line
Publish to an Azure Web App with continuous deployment
Deploy an ASP.NET container to a remote Docker host
ASP.NET Core and Azure Service Fabric
How to download a sample

1. Download the ASP.NET repository zip file.
2. Unzip the Docs-master.zip file.
3. Use the URL in the sample link to help you navigate to the sample directory.
This series explains the basics of building a Razor Pages web app with ASP.NET Core using Visual Studio. Other
versions of this series include a macOS version and a Visual Studio Code version.
1. Get started with Razor Pages
2. Add a model to a Razor Pages app
3. Scaffolded Razor Pages
4. Work with SQL Server LocalDB
5. Updating the pages
6. Add search
7. Add a new field
8. Add validation
After the tutorial to add a file upload capability to the sample app, see Upload files to a Razor Page in ASP.NET
Core.
Tutorial: Get started with Razor Pages in ASP.NET
Core
By Rick Anderson
We recommend you follow the ASP.NET Core 2.1 version of this tutorial. It's much easier to follow and
covers more features. Select ASP.NET Core 2.1 in the version selector.
This tutorial teaches the basics of building an ASP.NET Core Razor Pages web app. Razor Pages is the
recommended way to build UI for web apps in ASP.NET Core.
Windows: This tutorial
MacOS: Get started with Razor Pages with Visual Studio for Mac
macOS, Linux, and Windows: Get started with ASP.NET Core Razor Pages in Visual Studio Code
View or download sample code (how to download)
Prerequisites
Create a Razor web app

From the Visual Studio File menu, select New > Project.
Create a new ASP.NET Core Web Application. Name the project RazorPagesMovie. It's important to
name the project RazorPagesMovie so the namespaces will match when you copy/paste code.
Select ASP.NET Core 2.1 in the dropdown, and then select Web Application.
The Visual Studio template creates a starter project:

Press F5 to run the app in debug mode or Ctrl-F5 to run without attaching the debugger. Select Accept to
consent to tracking. This app doesn't track personal information. The template generated code includes assets
to help meet General Data Protection Regulation (GDPR ).
The following image shows the app after accepting tracking:

Visual Studio starts IIS Express and runs the app. The address bar shows localhost:port# and not
something like example.com . That's because localhost is the standard hostname for your local computer.
Localhost only serves web requests from the local computer. When Visual Studio creates a web project, a
random port is used for the web server. In the preceding image, the port number is 5001. When you run
the app, you'll see a different port number.
Launching the app with Ctrl+F5 (non-debug mode) allows you to make code changes, save the file, refresh
the browser, and see the code changes. Many developers prefer to use non-debug mode to quickly launch
the app and view changes.
The default template creates RazorPagesMovie, Home, About and Contact links and pages. Depending on
the size of your browser window, you might need to click the navigation icon to show the links.
Test the links. The RazorPagesMovie and Home links go to the Index page. The About and Contact links
go to the About and Contact pages, respectively.
Project files and folders

The following table lists the files and folders in the project. For this tutorial, the Startup.cs file is the most
important to understand. You don't need to review each link provided below. The links are provided as a
reference when you need more information on a file or folder in the project.
FILE OR FOLDER PURPOSE
wwwroot Contains static assets. See Static files.
Pages Folder for Razor Pages.
appsettings.json Configuration
Program.cs Configures the host of the ASP.NET Core app.
Startup.cs Configures services and the request pipeline. See Startup.
The Pages/Shared folder

The _Layout.cshtml file contains common HTML elements (script and stylesheet links) and sets the layout for
the app. For example when you select RazorPagesMovie, Home, About or Contact, a common set of
elements appears in the webpage. The common elements include the navigation menu at the top and the
header at the bottom of the window. For more information, see Layout.
The _ValidationScriptsPartial.cshtml file provides a reference to jQuery validation scripts. When the Create
and Edit pages are added later in the tutorial, the _ValidationScriptsPartial.cshtml file is used.
The _CookieConsentPartial.cshtml file provides a navigation bar and content to summarize the privacy and
cookie use policy. For more information on the GDPR assets included in the project, see EU General Data
Protection Regulation (GDPR ) support in ASP.NET Core).
The Pages folder
The _ViewStart.cshtml sets the Razor Pages Layout property to use the _Layout.cshtml file. See Layout for
more information.
The _ViewImports.cshtml file contains Razor directives that are imported into each Razor Page. See Importing
Shared Directives for more information.
The About , Contact and Index pages are basic pages you can use to start an app. The Error page is used
to display error information.
Use F7 to toggle between a Razor Page and the PageModel

To enable F7 toggling between a Razor Page (*.cshtml file) and the C# file (*.cshtml.cs):
Select Tools > Options > Environment > Keyboard
Enter ToggleRazorView in Show commands containing.
Select EditorContextMenus.CodeWindow.ToggleRazorView
In the Press shortcut keys entry box, press F7.
Select Assign > OK
Prerequisites

Create a new ASP.NET Core Web Application. Name the project RazorPagesMovie. It's important to
name the project RazorPagesMovie so the namespaces will match when you copy/paste code.
NOTE
To use ASP.NET Core with .NET Framework, you must first select .NET Framework from the leftmost drop-
down in the dialog, then you can select the desired ASP.NET Core version.
The Visual Studio template creates a starter project:

Press F5 to run the app in debug mode or Ctrl-F5 to run without attaching the debugger
Visual Studio starts IIS Express and runs your app. The address bar shows localhost:port# and not
something like example.com . That's because localhost is the standard hostname for your local computer.
Localhost only serves web requests from the local computer. When Visual Studio creates a web project, a
random port is used for the web server. In the preceding image, the port number is 5000. When you run
the app, you'll see a different port number.
the browser, and see the code changes. Many developers prefer to use non-debug mode to quickly launch
the app and view changes.
The default template creates RazorPagesMovie, Home, About and Contact links and pages. Depending on
the size of your browser window, you might need to click the navigation icon to show the links.
Test the links. The RazorPagesMovie and Home links go to the Index page. The About and Contact links
go to the About and Contact pages, respectively.

important to understand. You don't need to review each link provided below. The links are provided as a
reference when you need more information on a file or folder in the project.
wwwroot Contains static files. See Static files.
Program.cs Hosts the ASP.NET Core app.
The Pages folder

The _Layout.cshtml file contains common HTML elements (scripts and stylesheets) and sets the layout for the
application. For example, when you click on RazorPagesMovie, Home, About or Contact, you see the same
elements. The common elements include the navigation menu on the top and the header on the bottom of the
window. See Layout for more information.
The _ViewStart.cshtml sets the Razor Pages Layout property to use the _Layout.cshtml file. See Layout for
more information.
The _ValidationScriptsPartial.cshtml file provides a reference to jQuery validation scripts. When we add
Create and Edit pages later in the tutorial, the _ValidationScriptsPartial.cshtml file will be used.
The About , Contact and Index pages are basic pages you can use to start an app. The Error page is used
to display error information.
N E X T: A D D IN G A
M ODEL
Add a model to a Razor Pages app in ASP.NET Core
By Rick Anderson
In this section, you add classes for managing movies in a database. You use these classes with Entity Framework
Core (EF Core) to work with a database. EF Core is an object-relational mapping (ORM ) framework that simplifies
the data access code that you have to write.
The model classes you create are known as POCO classes (from "plain-old CLR objects") because they don't have
any dependency on EF Core. They define the properties of the data that are stored in the database.
In this tutorial, you write the model classes first, and EF Core creates the database. An alternate approach not
covered here is to generate model classes from an existing database.
View or download sample.
Add a data model

In Solution Explorer, right-click the RazorPagesMovie project > Add > New Folder. Name the folder Models.
Right click the Models folder. Select Add > Class. Name the class Movie and add the following properties:
Replace the contents of the Movie class with the following code:
using System;
using System.ComponentModel.DataAnnotations.Schema;
namespace RazorPagesMovie.Models
{
public class Movie
{
public int ID { get; set; }
public string Title { get; set; }
public DateTime ReleaseDate { get; set; }
public string Genre { get; set; }
public decimal Price { get; set; }
}
}
Scaffold the movie model

In this section, the movie model is scaffolded. That is, the scaffolding tool produces pages for Create, Read,
Update, and Delete (CRUD ) operations for the movie model.
Create a Pages/Movies folder:
In Solution Explorer, right click on the Pages folder > Add > New Folder.
Name the folder Movies
In Solution Explorer, right click on the Pages/Movies folder > Add > New Scaffolded Item.
In the Add Scaffold dialog, select Razor Pages using Entity Framework (CRUD ) > ADD.
Complete the Add Razor Pages using Entity Framework (CRUD ) dialog:
In the Model class drop down, select Movie (RazorPagesMovie.Models).
In the Data context class row, select the + (plus) sign and accept the generated name
RazorPagesMovie.Models.RazorPagesMovieContext.
In the Data context class drop down, select RazorPagesMovie.Models.RazorPagesMovieContext
Select Add.
The scaffold process created and changed the following files:

Files created
Pages/Movies Create, Delete, Details, Edit, Index. These pages are detailed in the next tutorial.
Data/RazorPagesMovieContext.cs
Files updates
Startup.cs: Changes to this file are detailed in the next section.
appsettings.json: The connection string used to connect to a local database is added.
Examine the context registered with dependency injection

ASP.NET Core is built with dependency injection. Services (such as the EF Core DB context) are registered with
dependency injection during application startup. Components that require these services (such as Razor Pages)
are provided these services via constructor parameters. The constructor code that gets a DB context instance is
shown later in the tutorial.
The scaffolding tool automatically created a DB context and registered it with the dependency injection container.
Examine the Startup.ConfigureServices method. The highlighted line was added by the scaffolder:

{
services.Configure<CookiePolicyOptions>(options =>
{
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
services.AddDbContext<RazorPagesMovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("RazorPagesMovieContext")));
}
The main class that coordinates EF Core functionality for a given data model is the DB context class. The data
context is derived from Microsoft.EntityFrameworkCore.DbContext. The data context specifies which entities are
included in the data model. In this project, the class is named RazorPagesMovieContext .
using System;
using System.Linq;
{
public class RazorPagesMovieContext : DbContext
{
public RazorPagesMovieContext (DbContextOptions<RazorPagesMovieContext> options)
: base(options)
{
}
public DbSet<RazorPagesMovie.Models.Movie> Movie { get; set; }

}
}
The preceding code creates a DbSet<Movie> property for the entity set. In Entity Framework terminology, an
entity set typically corresponds to a database table. An entity corresponds to a row in the table.
The name of the connection string is passed in to the context by calling a method on a DbContextOptions object.
For local development, the ASP.NET Core configuration system reads the connection string from the
appsettings.json file.
Perform initial migration

In this section, you use the Package Manager Console (PMC ) to:
Add an initial migration.
Update the database with the initial migration.
From the Tools menu, select NuGet Package Manager > Package Manager Console.
In the PMC, enter the following commands:

Add-Migration Initial
Update-Database
Alternatively, the following .NET Core CLI commands can be used from the project folder:
dotnet ef migrations add Initial

dotnet ef database update
Ignore the following warning message, you fix that in a a later tutorial:
Microsoft.EntityFrameworkCore.Model.Validation[30000]
*No type was specified for the decimal column 'Price' on entity type 'Movie'. This will cause values to be
silently truncated if they do not fit in the default precision and scale. Explicitly specify the SQL server
column type that can accommodate all the values using 'ForHasColumnType()'.*
The Add-Migration command generates code to create the initial database schema. The schema is based on the
model specified in the RazorPagesMovieContext (In the Data/RazorPagesMovieContext.cs file). The Initial
argument is used to name the migrations. You can use any name, but by convention you choose a name that
describes the migration. See Introduction to migrations for more information.
The Update-Database command runs the Up method in the Migrations/{time-stamp }_InitialCreate.cs file, which
creates the database.
If you get the error:
SqlException: Cannot open database "RazorPagesMovieContext-GUID" requested by the login. The login failed.
Login failed for user 'User-name'.
You missed the migrations step.
By Rick Anderson
Add a data model

In Solution Explorer, right-click the RazorPagesMovie project > Add > New Folder. Name the folder Models.
Right click the Models folder. Select Add > Class. Name the class Movie and add the following properties:
Add the following properties to the Movie class:
using System;
{
public class Movie
{
}
}
The ID field is required by the database for the primary key.

Add a database context class
Add the following MovieContext.cs class to the Models folder:
{
public class MovieContext : DbContext
{
public MovieContext(DbContextOptions<MovieContext> options)
: base(options)
{
}
public DbSet<Movie> Movie { get; set; }

}
}
The preceding code creates a DbSet property for the entity set. In Entity Framework terminology, an entity set
typically corresponds to a database table, and an entity corresponds to a row in the table.
Add a database connection string
Add a connection string to the appsettings.json file.
{
"Logging": {
"IncludeScopes": false,
"LogLevel": {
"Default": "Warning"
}
},
"ConnectionStrings": {
"MovieContext": "Server=(localdb)\\mssqllocaldb;Database=Movie-
1;Trusted_Connection=True;MultipleActiveResultSets=true"
}
}

Register the database context with the dependency injection container in the ConfigureServices method of the
Startup class (Startup.cs):
{
// requires
// using RazorPagesMovie.Models;
// using Microsoft.EntityFrameworkCore;
services.AddDbContext<MovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("MovieContext")));
services.AddMvc();
}
Build the project to verify you don't have any errors.
Add scaffold tooling and perform initial migration

In this section, you use the Package Manager Console (PMC ) to:
Add the Visual Studio web code generation package. This package is required to run the scaffolding engine.
Install-Package Microsoft.VisualStudio.Web.CodeGeneration.Design -Version 2.0.3

Update-Database
Alternatively, the following .NET Core CLI commands can be used:
dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design

Ignore the following message:

`Microsoft.EntityFrameworkCore.Model.Validation[30000]`
*No type was specified for the decimal column 'Price' on entity type 'Movie'. This will cause values to be
silently truncated if they do not fit in the default precision and scale. Explicitly specify the SQL server
column type that can accommodate all the values using 'ForHasColumnType()'*
You fix that in the next tutorial.

The Install-Package command installs the tooling required to run the scaffolding engine.
The Add-Migration command generates code to create the initial database schema. The schema is based on the
model specified in the DbContext (In the Models/MovieContext.cs file). The Initial argument is used to name the
migrations. You can use any name, but by convention you choose a name that describes the migration. See
Introduction to migrations for more information.
The Update-Database command runs the Up method in the Migrations/{time-stamp }_InitialCreate.cs file, which
creates the database.
Scaffold the Movie model
Run the following from the command line (in the project directory that contains the Program.cs, Startup.cs,
and .csproj files):
dotnet restore
dotnet aspnet-codegenerator razorpage -m Movie -dc MovieContext -udl -outDir Pages\Movies --
referenceScriptLibraries
No executable found matching command "dotnet-aspnet-codegenerator"
The preceeding error happens when you are in the wrong directory. Open a command shell to the project
directory (The directory that contains the Program.cs, Startup.cs, and .csproj files), and then run the preceeding
command.
The process cannot access the file

'RazorPagesMovie/bin/Debug/netcoreapp2.0/RazorPagesMovie.dll'
because it is being used by another process.
Exit Visual Studio and run the command again.

The following table details the ASP.NET Core code generators` parameters:
PARAMETER DESCRIPTION
-m The name of the model.
-dc The data context.
-udl Use the default layout.
-outDir The relative output folder path to create the views.

--referenceScriptLibraries Adds _ValidationScriptsPartial to Edit and Create pages
Use the h switch to get help on the aspnet-codegenerator razorpage command:
dotnet aspnet-codegenerator razorpage -h
Test the app

Run the app and append /Movies to the URL in the browser ( http://localhost:port/movies ).
Test the Create link.
Test the Edit, Details, and Delete links.

If you get a SQL exception, verify you have run migrations and updated the database.
The next tutorial explains the files created by scaffolding.
P R E V IO U S : G E T N E X T: S C A F F O L D E D R A Z O R
STA RTE D PAGES
Scaffolded Razor Pages in ASP.NET Core
By Rick Anderson
This tutorial examines the Razor Pages created by scaffolding in the previous tutorial.
The Create, Delete, Details, and Edit pages.

Examine the Pages/Movies/Index.cshtml.cs Page Model:
using RazorPagesMovie.Models;
{
{
private readonly RazorPagesMovie.Models.MovieContext _context;
public IndexModel(RazorPagesMovie.Models.MovieContext context)

{
_context = context;
}
public IList<Movie> Movie { get;set; }

{
Movie = await _context.Movie.ToListAsync();
}
}
}
{
{
private readonly RazorPagesMovie.Models.RazorPagesMovieContext _context;
public IndexModel(RazorPagesMovie.Models.RazorPagesMovieContext context)

{
_context = context;
}
public IList<Movie> Movie { get; set; }

{
}
}
}
Razor Pages are derived from PageModel . By convention, the PageModel -derived class is called <PageName>Model .
The constructor uses dependency injection to add the MovieContext to the page. All the scaffolded pages follow
this pattern. See Asynchronous code for more information on asynchronous programing with Entity Framework.
When a request is made for the page, the OnGetAsync method returns a list of movies to the Razor Page.
OnGetAsync or OnGet is called on a Razor Page to initialize the state for the page. In this case, OnGetAsync gets a
list of movies and displays them.
When OnGet returns void or OnGetAsync returns Task , no return method is used. When the return type is
IActionResult or Task<IActionResult> , a return statement must be provided. For example, the
Pages/Movies/Create.cshtml.cs OnPostAsync method:

{
{
return Page();
}
_context.Movie.Add(Movie);
await _context.SaveChangesAsync();
}
Examine the Pages/Movies/Index.cshtml Razor Page:

@page
@model RazorPagesMovie.Pages.Movies.IndexModel
@{
ViewData["Title"] = "Index";
}
<h2>Index</h2>
<p>
<a asp-page="Create">Create New</a>
</p>
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.Movie[0].Title)
</th>
<th>
@Html.DisplayNameFor(model => model.Movie[0].ReleaseDate)
</th>
<th>
@Html.DisplayNameFor(model => model.Movie[0].Genre)
</th>
<th>
@Html.DisplayNameFor(model => model.Movie[0].Price)
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Movie) {
<tr>
<td>
@Html.DisplayFor(modelItem => item.Title)
</td>
<td>
@Html.DisplayFor(modelItem => item.ReleaseDate)
</td>
<td>
@Html.DisplayFor(modelItem => item.Genre)
</td>
<td>
@Html.DisplayFor(modelItem => item.Price)
</td>
<td>
<a asp-page="./Edit" asp-route-id="@item.ID">Edit</a> |
<a asp-page="./Details" asp-route-id="@item.ID">Details</a> |
<a asp-page="./Delete" asp-route-id="@item.ID">Delete</a>
</td>
</tr>
}
</tbody>
</table>
Razor can transition from HTML into C# or into Razor-specific markup. When an @ symbol is followed by a
Razor reserved keyword, it transitions into Razor-specific markup, otherwise it transitions into C#.
The @page Razor directive makes the file into an MVC action — which means that it can handle requests. @page
must be the first Razor directive on a page. @page is an example of transitioning into Razor-specific markup. See
Razor syntax for more information.
Examine the lambda expression used in the following HTML Helper:
@Html.DisplayNameFor(model => model.Movie[0].Title))
The DisplayNameFor HTML Helper inspects the Title property referenced in the lambda expression to determine
the display name. The lambda expression is inspected rather than evaluated. That means there is no access
violation when model , model.Movie , or model.Movie[0] are null or empty. When the lambda expression is
evaluated (for example, with @Html.DisplayFor(modelItem => item.Title) ), the model's property values are
evaluated.
The @model directive
@page
The directive specifies the type of the model passed to the Razor Page. In the preceding example, the
@model
@model line makes the PageModel -derived class available to the Razor Page. The model is used in the
@Html.DisplayNameFor and @Html.DisplayName HTML Helpers on the page.
ViewData and layout

Consider the following code:
@page
@{
}
The preceding highlighted code is an example of Razor transitioning into C#. The { and } characters enclose a
block of C# code.
The PageModel base class has a ViewData dictionary property that can be used to add data that you want to pass
to a View. You add objects into the ViewData dictionary using a key/value pattern. In the preceding sample, the
"Title" property is added to the ViewData dictionary.
The "Title" property is used in the Pages/Shared/_Layout.cshtml file. The following markup shows the first few
lines of the Pages/Shared/_Layout.cshtml file.
lines of the _Layout.cshtml file.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@ViewData["Title"] - RazorPagesMovie</title>
@*Markup removed for brevity.*@
The line @*Markup removed for brevity.*@ is a Razor comment. Unlike HTML comments (  ), Razor
comments are not sent to the client.
Run the app and test the links in the project (Home, About, Contact, Create, Edit, and Delete). Each page sets
the title, which you can see in the browser tab. When you bookmark a page, the title is used for the bookmark.
Pages/Index.cshtml and Pages/Movies/Index.cshtml currently have the same title, but you can modify them to
have different values.
NOTE
You may not be able to enter decimal commas in the Price field. To support jQuery validation for non-English locales that
use a comma (",") for a decimal point, and non US-English date formats, you must take steps to globalize your app. This
GitHub issue 4076 for instructions on adding decimal comma.
The Layout property is set in the Pages/_ViewStart.cshtml file:
@{
Layout = "_Layout";
}
The preceding markup sets the layout file to Pages/Shared/_Layout.cshtml for all Razor files under the Pages
folder. See Layout for more information.
Update the layout
Change the <title> element in the Pages/Shared/_Layout.cshtml file to use a shorter string.
<!DOCTYPE html>
<html>
<head>
<title>@ViewData["Title"] - Movie</title>
Find the following anchor element in the Pages/_Layout.cshtml file.
<a asp-page="/Index" class="navbar-brand">RazorPagesMovie</a>
Replace the preceding element with the following markup.
<a asp-page="/Movies/Index" class="navbar-brand">RpMovie</a>
The preceding anchor element is a Tag Helper. In this case, it's the Anchor Tag Helper. The
asp-page="/Movies/Index" Tag Helper attribute and value creates a link to the /Movies/Index Razor Page.
Save your changes, and test the app by clicking on the RpMovie link. See the _Layout.cshtml file in GitHub.
The Create page model
Examine the Pages/Movies/Create.cshtml.cs page model:
// Unused usings removed.
{
{
public CreateModel(RazorPagesMovie.Models.MovieContext context)

{
_context = context;
}

{
return Page();
}
[BindProperty]
public Movie Movie { get; set; }

{
{
return Page();
}
}
}
}
{
{
public CreateModel(RazorPagesMovie.Models.RazorPagesMovieContext context)

{
_context = context;
}

{
return Page();
}
[BindProperty]

{
{
return Page();
}
}
}
}
The method initializes any state needed for the page. The Create page doesn't have any state to initialize, so
OnGet
Page is returned. Later in the tutorial you see OnGet method initialize state. The Page method creates a
PageResult object that renders the Create.cshtml page.
The Movie property uses the [BindProperty] attribute to opt-in to model binding. When the Create form posts
the form values, the ASP.NET Core runtime binds the posted values to the Movie model.
The OnPostAsync method is run when the page posts form data:

{
{
return Page();
}
}
If there are any model errors, the form is redisplayed, along with any form data posted. Most model errors can be
caught on the client-side before the form is posted. An example of a model error is posting a value for the date
field that cannot be converted to a date. We'll talk more about client-side validation and model validation later in
the tutorial.
If there are no model errors, the data is saved, and the browser is redirected to the Index page.
The Create Razor Page
Examine the Pages/Movies/Create.cshtml Razor Page file:
@page
@model RazorPagesMovie.Pages.Movies.CreateModel
@{
ViewData["Title"] = "Create";
}
<h2>Create</h2>
<h4>Movie</h4>
<hr />
<div class="row">
<div class="col-md-4">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<div class="form-group">
<label asp-for="Movie.Title" class="control-label"></label>
<input asp-for="Movie.Title" class="form-control" />
<span asp-validation-for="Movie.Title" class="text-danger"></span>
</div>
<label asp-for="Movie.ReleaseDate" class="control-label"></label>
<input asp-for="Movie.ReleaseDate" class="form-control" />
<span asp-validation-for="Movie.ReleaseDate" class="text-danger"></span>
</div>
<label asp-for="Movie.Genre" class="control-label"></label>
<input asp-for="Movie.Genre" class="form-control" />
<span asp-validation-for="Movie.Genre" class="text-danger"></span>
</div>
<label asp-for="Movie.Price" class="control-label"></label>
<input asp-for="Movie.Price" class="form-control" />
<span asp-validation-for="Movie.Price" class="text-danger"></span>
</div>
<input type="submit" value="Create" class="btn btn-default" />
</div>
</form>
</div>
</div>
<div>
<a asp-page="Index">Back to List</a>
</div>
@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}
Visual Studio displays the <form method="post"> tag in a distinctive font used for Tag Helpers:
The <form method="post"> element is a Form Tag Helper. The Form Tag Helper automatically includes an
antiforgery token.
The scaffolding engine creates Razor markup for each field in the model (except the ID ) similar to the following:

</div>
The Validation Tag Helpers ( <div asp-validation-summary and <span asp-validation-for ) display validation errors.
Validation is covered in more detail later in this series.
The Label Tag Helper ( <label asp-for="Movie.Title" class="control-label"></label> ) generates the label caption
and for attribute for the Title property.
The Input Tag Helper ( <input asp-for="Movie.Title" class="form-control" /> ) uses the DataAnnotations attributes
and produces HTML attributes needed for jQuery Validation on the client-side.
The next tutorial explains SQL Server LocalDB and seeding the database.
P R E V IO U S : A D D IN G A N E X T: S Q L S E R V E R
M ODEL LOCA LDB
Work with SQL Server LocalDB and ASP.NET Core
By Rick Anderson and Joe Audette

The MovieContext object handles the task of connecting to the database and mapping Movie objects to database
records. The database context is registered with the Dependency Injection container in the ConfigureServices
method in the Startup.cs file:

{
// requires
options.UseSqlServer(Configuration.GetConnectionString("MovieContext")));
services.AddMvc();
}

{
{
});
services.AddDbContext<RazorPagesMovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("RazorPagesMovieContext")));
}
For more information on the methods used in ConfigureServices , see:

EU General Data Protection Regulation (GDPR ) support in ASP.NET Core for CookiePolicyOptions .
SetCompatibilityVersion
The ASP.NET Core Configuration system reads the ConnectionString . For local development, it gets the
connection string from the appsettings.json file. The name value for the database ( Database={Database name} ) will
be different for your generated code. The name value is arbitrary.
"MovieContext": "Server=(localdb)\\mssqllocaldb;Database=Movie-
}
When you deploy the app to a test or production server, you can use an environment variable or another approach
to set the connection string to a real SQL Server. See Configuration for more information.
SQL Server Express LocalDB

LocalDB is a lightweight version of the SQL Server Express Database Engine that's targeted for program
development. LocalDB starts on demand and runs in user mode, so there's no complex configuration. By default,
LocalDB database creates "*.mdf" files in the C:/Users/<user> directory.
From the View menu, open SQL Server Object Explorer (SSOX).
Right click on the Movie table and select View Designer:

Note the key icon next to ID . By default, EF creates a property named ID for the primary key.
Right click on the Movie table and select View Data:
Seed the database

Create a new class named SeedData in the Models folder. Replace the generated code with the following:
using System;
using System.Linq;
{
public static class SeedData
{
public static void Initialize(IServiceProvider serviceProvider)
{
using (var context = new MovieContext(
serviceProvider.GetRequiredService<DbContextOptions<MovieContext>>()))
{
// Look for any movies.
if (context.Movie.Any())
{
return; // DB has been seeded
}
context.Movie.AddRange(
new Movie
{
Title = "When Harry Met Sally",
ReleaseDate = DateTime.Parse("1989-2-12"),
Genre = "Romantic Comedy",
Price = 7.99M
},
new Movie
{
Title = "Ghostbusters",
Genre = "Comedy",
Price = 8.99M
},
new Movie
{
Title = "Ghostbusters 2",
Genre = "Comedy",
Price = 9.99M
},
new Movie
{
Title = "Rio Bravo",
Genre = "Western",
Price = 3.99M
}
);
context.SaveChanges();
}
}
}
}
using System;
using System.Linq;
{
{
{
using (var context = new RazorPagesMovieContext(
serviceProvider.GetRequiredService<DbContextOptions<RazorPagesMovieContext>>()))
{
{
}
new Movie
{
Price = 7.99M
},
new Movie
{
Title = "Ghostbusters ",
Genre = "Comedy",
Price = 8.99M
},
new Movie
{
Genre = "Comedy",
Price = 9.99M
},
new Movie
{
Genre = "Western",
Price = 3.99M
}
);
}
}
}
}
If there are any movies in the DB, the seed initializer returns and no movies are added.
{
return; // DB has been seeded.
}
Add the seed initializer

In Program.cs, modify the Main method to do the following:
Get a DB context instance from the dependency injection container.
Call the seed method, passing to it the context.
Dispose the context when the seed method completes.
The following code shows the updated Program.cs file.

using Microsoft.AspNetCore;
using Microsoft.Extensions.Logging;
using System;
namespace RazorPagesMovie
{
public class Program
{
public static void Main(string[] args)
{
var host = BuildWebHost(args);
using (var scope = host.Services.CreateScope())

{
var services = scope.ServiceProvider;
try
{
var context = services.GetRequiredService<MovieContext>();
// requires using Microsoft.EntityFrameworkCore;
context.Database.Migrate();
// Requires using RazorPagesMovie.Models;
SeedData.Initialize(services);
}
catch (Exception ex)
{
var logger = services.GetRequiredService<ILogger<Program>>();
logger.LogError(ex, "An error occurred seeding the DB.");
}
}
host.Run();
}
public static IWebHost BuildWebHost(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.Build();
}
}
using System;
{
{
{
var host = CreateWebHostBuilder(args).Build();

{
try
{
var context = services.GetRequiredService<RazorPagesMovieContext>();
}
{
}
}
host.Run();
}
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

.UseStartup<Startup>();
}
}
A production app would not call Database.Migrate . It's added to the preceding code to prevent the following
exception when Update-Database has not been run:
SqlException: Cannot open database "RazorPagesMovieContext-21" requested by the login. The login failed.
Login failed for user 'user name'.
Test the app
Delete all the records in the DB. You can do this with the delete links in the browser or from SSOX
Force the app to initialize (call the methods in the Startup class) so the seed method runs. To force
initialization, IIS Express must be stopped and restarted. You can do this with any of the following
approaches:
Right click the IIS Express system tray icon in the notification area and tap Exit or Stop Site:
If you were running VS in non-debug mode, press F5 to run in debug mode.
If you were running VS in debug mode, stop the debugger and press F5.
The app shows the seeded data:
The next tutorial will clean up the presentation of the data.
P R E V IO U S : S C A F F O L D E D R A Z O R N E X T: U P D A T IN G T H E
PAGES PAGES
Update the generated pages in an ASP.NET Core app
By Rick Anderson
We have a good start to the movie app, but the presentation isn't ideal. We don't want to see the time (12:00:00
AM in the image below ) and ReleaseDate should be Release Date (two words).
Update the generated code

Open the Models/Movie.cs file and add the highlighted lines shown in the following code:
using System;
{
public class Movie
{
[Display(Name = "Release Date")]

[DataType(DataType.Date)]
}
}
using System;
{
public class Movie
{

[Column(TypeName = "decimal(18, 2)")]

}
}
Right click on a red squiggly line > Quick Actions and Refactorings.
Select using System.ComponentModel.DataAnnotations;
Visual studio adds using System.ComponentModel.DataAnnotations; .

Right click on a red squiggly line > Quick Actions and Refactorings on the [Column] atribute and select
The [Column(TypeName = "decimal(18, 2)")] data annotation is required so Entity Framework Core can correctly
map Price to currency in the database. For more information, see Data Types.
The completed model:
using System;
{
public class Movie
{


}
}
We'll cover DataAnnotations in the next tutorial. The Display attribute specifies what to display for the name of a
field (in this case "Release Date" instead of "ReleaseDate"). The DataType attribute specifies the type of the data
(Date), so the time information stored in the field isn't displayed.
Browse to Pages/Movies and hover over an Edit link to see the target URL.
The Edit, Details, and Delete links are generated by the Anchor Tag Helper in the Pages/Movies/Index.cshtml file.
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
Tag Helpers enable server-side code to participate in creating and rendering HTML elements in Razor files. In the
preceding code, the AnchorTagHelper dynamically generates the HTML href attribute value from the Razor Page
(the route is relative), the asp-page , and the route id ( asp-route-id ). See URL generation for Pages for more
information.
Use View Source from your favorite browser to examine the generated markup. A portion of the generated
HTML is shown below:
<td>
<a href="/Movies/Edit?id=1">Edit</a> |
<a href="/Movies/Details?id=1">Details</a> |
<a href="/Movies/Delete?id=1">Delete</a>
</td>
The dynamically-generated links pass the movie ID with a query string (for example,
http://localhost:5000/Movies/Details?id=2 ).
Update the Edit, Details, and Delete Razor Pages to use the "{id:int}" route template. Change the page directive for
each of these pages from @page to @page "{id:int}" . Run the app and then view source. The generated HTML
adds the ID to the path portion of the URL:
<td>
<a href="/Movies/Edit/1">Edit</a> |
<a href="/Movies/Details/1">Details</a> |
<a href="/Movies/Delete/1">Delete</a>
</td>
A request to the page with the "{id:int}" route template that does not include the integer will return an HTTP 404
(not found) error. For example, http://localhost:5000/Movies/Details will return a 404 error. To make the ID
optional, append ? to the route constraint:
@page "{id:int?}"
Update concurrency exception handling

Update the OnPostAsync method in the Pages/Movies/Edit.cshtml.cs file. The following highlighted code shows the
changes:

{
{
return Page();
}
_context.Attach(Movie).State = EntityState.Modified;
try
{
}
{
if (!_context.Movie.Any(e => e.ID == Movie.ID))
{
return NotFound();
}
else
{
throw;
}
}
}
The previous code only detects concurrency exceptions when the first concurrent client deletes the movie, and the
second concurrent client posts changes to the movie.
To test the catch block:
Set a breakpoint on catch (DbUpdateConcurrencyException)
Edit a movie.
In another browser window, select the Delete link for the same movie, and then delete the movie.
In the previous browser window, post changes to the movie.
Production code would generally detect concurrency conflicts when two or more clients concurrently updated a
record. See Handle concurrency conflicts for more information.
Posting and binding review
Examine the Pages/Movies/Edit.cshtml.cs file:
{
public EditModel(RazorPagesMovie.Models.MovieContext context)

{
_context = context;
}
[BindProperty]
public async Task<IActionResult> OnGetAsync(int? id)

{
if (id == null)
{
return NotFound();
}
Movie = await _context.Movie.SingleOrDefaultAsync(m => m.ID == id);
if (Movie == null)
{
return NotFound();
}
return Page();
}

{
{
return Page();
}
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
}
{
public EditModel(RazorPagesMovie.Models.RazorPagesMovieContext context)

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}
if (Movie == null)
{
return NotFound();
}
return Page();
}

{
{
return Page();
}
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
}
When an HTTP GET request is made to the Movies/Edit page (for example, http://localhost:5000/Movies/Edit/2 ):
The OnGetAsync method fetches the movie from the database and returns the Page method.
The Page method renders the Pages/Movies/Edit.cshtml Razor Page. The Pages/Movies/Edit.cshtml file
contains the model directive ( @model RazorPagesMovie.Pages.Movies.EditModel ), which makes the movie model
available on the page.
The Edit form is displayed with the values from the movie.
When the Movies/Edit page is posted:
The form values on the page are bound to the Movie property. The [BindProperty] attribute enables
Model binding.
[BindProperty]
If there are errors in the model state (for example, ReleaseDate cannot be converted to a date), the form is
posted again with the submitted values.
If there are no model errors, the movie is saved.
The HTTP GET methods in the Index, Create, and Delete Razor pages follow a similar pattern. The HTTP POST
OnPostAsync method in the Create Razor Page follows a similar pattern to the OnPostAsync method in the Edit
Razor Page.
Search is added in the next tutorial.
P R E V IO U S : W O R K IN G W IT H S Q L S E R V E R ADD
LOCA LDB SE A RCH
Add search to ASP.NET Core Razor Pages
By Rick Anderson
In this document, search capability is added to the Index page that enables searching movies by genre or name.
Update the Index page's OnGetAsync method with the following code:
public async Task OnGetAsync(string searchString)

{
var movies = from m in _context.Movie
select m;
if (!String.IsNullOrEmpty(searchString))
{
movies = movies.Where(s => s.Title.Contains(searchString));
}
Movie = await movies.ToListAsync();

}
The first line of the OnGetAsync method creates a LINQ query to select the movies:

select m;
The query is only defined at this point, it has not been run against the database.
If the searchString parameter contains a string, the movies query is modified to filter on the search string:
{
}
The s => s.Title.Contains() code is a Lambda Expression. Lambdas are used in method-based LINQ queries as
arguments to standard query operator methods such as the Where method or Contains (used in the preceding
code). LINQ queries are not executed when they're defined or when they're modified by calling a method (such as
Where , Contains or OrderBy ). Rather, query execution is deferred. That means the evaluation of an expression is
delayed until its realized value is iterated over or the ToListAsync method is called. See Query Execution for more
information.
Note: The Contains method is run on the database, not in the C# code. The case sensitivity on the query depends
on the database and the collation. On SQL Server, Contains maps to SQL LIKE, which is case insensitive. In
SQLite, with the default collation, it's case sensitive.
Navigate to the Movies page and append a query string such as ?searchString=Ghost to the URL (for example,
http://localhost:5000/Movies?searchString=Ghost ). The filtered movies are displayed.
If the following route template is added to the Index page, the search string can be passed as a URL segment (for
example, http://localhost:5000/Movies/Ghost ).
@page "{searchString?}"
The preceding route constraint allows searching the title as route data (a URL segment) instead of as a query
string value. The ? in "{searchString?}" means this is an optional route parameter.
However, you can't expect users to modify the URL to search for a movie. In this step, UI is added to filter movies.
If you added the route constraint "{searchString?}" , remove it.
Open the Pages/Movies/Index.cshtml file, and add the <form> markup highlighted in the following code:
@page
@{
}
<h2>Index</h2>
<p>
</p>
<form>
<p>
Title: <input type="text" name="SearchString">
<input type="submit" value="Filter" />
</p>
</form>
The HTML <form> tag uses the Form Tag Helper. When the form is submitted, the filter string is sent to the
Pages/Movies/Index page. Save the changes and test the filter.
Search by genre
Add the following highlighted properties to Pages/Movies/Index.cshtml.cs:
{

{
_context = context;
}

public SelectList Genres { get; set; }
public string MovieGenre { get; set; }

{

{
_context = context;
}

The SelectList Genres contains the list of genres. This allows the user to select a genre from the list.
The MovieGenre property contains the specific genre the user selects (for example, "Western").
Update the OnGetAsync method with the following code:
// Requires using Microsoft.AspNetCore.Mvc.Rendering;

public async Task OnGetAsync(string movieGenre, string searchString)
{
// Use LINQ to get list of genres.
IQueryable<string> genreQuery = from m in _context.Movie
orderby m.Genre
select m.Genre;

select m;
{
}
if (!String.IsNullOrEmpty(movieGenre))
{
movies = movies.Where(x => x.Genre == movieGenre);
}
Genres = new SelectList(await genreQuery.Distinct().ToListAsync());
}
The following code is a LINQ query that retrieves all the genres from the database.
orderby m.Genre
select m.Genre;
The SelectList of genres is created by projecting the distinct genres.
Adding search by genre

Update Index.cshtml as follows:
@page
@{
}
<h2>Index</h2>
<p>
</p>
<form>
<p>
<select asp-for="MovieGenre" asp-items="Model.Genres">
<option value="">All</option>
</select>

</p>
</form>
<thead>
Test the app by searching by genre, by movie title, and by both.
P R E V IO U S : U P D A T IN G T H E N E X T: A D D IN G A N E W
PAGES F IE L D
Add a new field to a Razor Page in ASP.NET Core
By Rick Anderson
In this section you use Entity Framework Code First Migrations to add a new field to the model and migrate that
change to the database.
When using EF Code First to automatically create a database, Code First:
Adds a table to the database to track whether the schema of the database is in sync with the model classes it
was generated from.
If the model classes aren't in sync with the DB, EF throws an exception.
Automatic verification of schema/model in sync makes it easier to find inconsistent database/code issues.
Adding a Rating Property to the Movie Model

Open the Models/Movie.cs file and add a Rating property:
public class Movie

{

public string Rating { get; set; }
}
public class Movie

{


}
Build the app (Ctrl+Shift+B ).

Edit Pages/Movies/Index.cshtml, and add a Rating field:
@page
@{
}
<h2>Index</h2>
<p>
</p>
<form>
<p>
</select>

</p>
</form>
<thead>
<tr>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
@Html.DisplayNameFor(model => model.Movie[0].Rating)
</th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
@Html.DisplayFor(modelItem => item.Rating)
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
Add the Rating field to the Delete and Details pages.
Update Create.cshtml with a Rating field. You can copy/paste the previous <div> element and let intelliSense
help you update the fields. IntelliSense works with Tag Helpers.
The following code shows Create.cshtml with a Rating field:

@page
@{
}
<h2>Create</h2>
<h4>Movie</h4>
<hr />
<div class="row">
</div>
</div>
</div>
</div>
<label asp-for="Movie.Rating" class="control-label"></label>
<input asp-for="Movie.Rating" class="form-control" />
<span asp-validation-for="Movie.Rating" class="text-danger"></span>
</div>
</div>
</form>
</div>
</div>
<div>
</div>
@section Scripts {
}
Add the Rating field to the Edit Page.

The app won't work until the DB is updated to include the new field. If run now, the app throws a SqlException :
SqlException: Invalid column name 'Rating'.
This error is caused by the updated Movie model class being different than the schema of the Movie table of the
database. (There's no Rating column in the database table.)
There are a few approaches to resolving the error:
1. Have the Entity Framework automatically drop and re-create the database using the new model class
schema. This approach is convenient early in the development cycle; it allows you to quickly evolve the
model and database schema together. The downside is that you lose existing data in the database. You don't
want to use this approach on a production database! Dropping the DB on schema changes and using an
initializer to automatically seed the database with test data is often a productive way to develop an app.
2. Explicitly modify the schema of the existing database so that it matches the model classes. The advantage
of this approach is that you keep your data. You can make this change either manually or by creating a
database change script.
3. Use Code First Migrations to update the database schema.
For this tutorial, use Code First Migrations.
Update the SeedData class so that it provides a value for the new column. A sample change is shown below, but
you'll want to make this change for each new Movie block.
new Movie
{
Price = 7.99M,
Rating = "R"
},
See the completed SeedData.cs file.

See the completed SeedData.cs file.
Build the solution.
From the Tools menu, select NuGet Package Manager > Package Manager Console. In the PMC, enter the
following commands:
Add-Migration Rating
Update-Database
The Add-Migration command tells the framework to:

Compare the Movie model with the Movie DB schema.
Create code to migrate the DB schema to the new model.
The name "Rating" is arbitrary and is used to name the migration file. It's helpful to use a meaningful name for
the migration file.
If you delete all the records in the DB, the initializer will seed the DB and include the Rating field. You can do this
with the delete links in the browser or from Sql Server Object Explorer (SSOX). To delete the database from
SSOX:
Select the database in SSOX.
Right click on the database, and select Delete.
Check Close existing connections.
Select OK.
In the PMC, update the database:
Update-Database
Run the app and verify you can create/edit/display movies with a Rating field. If the database isn't seeded, stop
IIS Express, and then run the app.
P R E V IO U S : A D D IN G N E X T: A D D IN G
SE A RCH V A L ID A T IO N
Add validation to an ASP.NET Core Razor Page
By Rick Anderson
In this section, validation logic is added to the Movie model. The validation rules are enforced any time a user
creates or edits a movie.
Validation
A key tenet of software development is called DRY ("Don't Repeat Yourself"). Razor Pages encourages
development where functionality is specified once, and it's reflected throughout the app. DRY can help reduce the
amount of code in an app. DRY makes the code less error prone, and easier to test and maintain.
The validation support provided by Razor Pages and Entity Framework is a good example of the DRY principle.
Validation rules are declaratively specified in one place (in the model class), and the rules are enforced everywhere
in the app.
Adding validation rules to the movie model
Open the Movie.cs file. DataAnnotations provides a built-in set of validation attributes that are applied
declaratively to a class or property. DataAnnotations also contains formatting attributes like DataType that help
with formatting and don't provide validation.
Update the Movie class to take advantage of the Required , StringLength , RegularExpression , and Range
validation attributes.
public class Movie

{
[StringLength(60, MinimumLength = 3)]

[Required]

[Range(1, 100)]
[DataType(DataType.Currency)]
[RegularExpression(@"^[A-Z]+[a-zA-Z""'\s-]*$")]
[Required]
[StringLength(30)]
[RegularExpression(@"^[A-Z]+[a-zA-Z0-9""'\s-]*$")]
[StringLength(5)]
[Required]
}
public class Movie
{

[Required]

[Range(1, 100)]
[Required]
[StringLength(30)]
[StringLength(5)]
[Required]
}
Validation attributes specify behavior that's enforced on model properties:

The Required and MinimumLength attributes indicate that a property must have a value. However, nothing
prevents a user from entering whitespace to satisfy the validation constraint for a nullable type. Non-nullable
value types (such as decimal , int , float , and DateTime ) are inherently required and don't need the
Required attribute.
The RegularExpression attribute limits the characters that the user can enter. In the preceding code, Genre
must start with one or more capital letters and follow with zero or more letters, single or double quotes,
whitespace characters, or dashes. Rating must start with one or more capital letters and follow with zero or
more letters, numbers, single or double quotes, whitespace characters, or dashes.
The Range attribute constrains a value to a specified range.
The StringLength attribute sets the maximum length of a string, and optionally the minimum length.
Having validation rules automatically enforced by ASP.NET Core helps make an app more robust. Automatic
validation on models helps protect the app because you don't have to remember to apply them when new code is
added.
Validation Error UI in Razor Pages
Run the app and navigate to Pages/Movies.
Select the Create New link. Complete the form with some invalid values. When jQuery client-side validation
detects the error, it displays an error message.
NOTE
You may not be able to enter decimal points or commas in the Price field. To support jQuery validation in non-English
locales that use a comma (",") for a decimal point, and non US-English date formats, you must take steps to globalize your
app. See Additional resources for more information. For now, just enter whole numbers like 10.
Notice how the form has automatically rendered a validation error message in each field containing an invalid
value. The errors are enforced both client-side (using JavaScript and jQuery) and server-side (when a user has
JavaScript disabled).
A significant benefit is that no code changes were necessary in the Create or Edit pages. Once DataAnnotations
were applied to the model, the validation UI was enabled. The Razor Pages created in this tutorial automatically
picked up the validation rules (using validation attributes on the properties of the Movie model class). Test
validation using the Edit page, the same validation is applied.
The form data isn't posted to the server until there are no client-side validation errors. Verify form data isn't
posted by one or more of the following approaches:
Put a break point in the OnPostAsync method. Submit the form (select Create or Save). The break point is
never hit.
Use the Fiddler tool.
Use the browser developer tools to monitor network traffic.
Server-side validation
When JavaScript is disabled in the browser, submitting the form with errors will post to the server.
Optional, test server-side validation:
Disable JavaScript in the browser. If you can't disable JavaScript in the browser, try another browser.
Set a break point in the OnPostAsync method of the Create or Edit page.
Submit a form with validation errors.
Verify the model state is invalid:
{
return Page();
}
The following code shows a portion of the Create.cshtml page that you scaffolded earlier in the tutorial. It's used
by the Create and Edit pages to display the initial form and to redisplay the form in the event of an error.
</div>
The Input Tag Helper uses the DataAnnotations attributes and produces HTML attributes needed for jQuery
Validation on the client-side. The Validation Tag Helper displays validation errors. See Validation for more
information.
The Create and Edit pages have no validation rules in them. The validation rules and the error strings are specified
only in the Movie class. These validation rules are automatically applied to Razor Pages that edit the Movie
model.
When validation logic needs to change, it's done only in the model. Validation is applied consistently throughout
the application (validation logic is defined in one place). Validation in one place helps keep the code clean, and
makes it easier to maintain and update.
Using DataType Attributes

Examine the Movie class. The System.ComponentModel.DataAnnotations namespace provides formatting attributes
in addition to the built-in set of validation attributes. The DataType attribute is applied to the ReleaseDate and
Price properties.
[Range(1, 100)]
The DataType attributes only provide hints for the view engine to format the data (and supplies attributes such as
<a> for URL's and <a href="mailto:EmailAddress.com"> for email). Use the RegularExpression attribute to
validate the format of the data. The DataType attribute is used to specify a data type that's more specific than the
database intrinsic type. DataType attributes are not validation attributes. In the sample application, only the date is
displayed, without time.
The DataType Enumeration provides for many data types, such as Date, Time, PhoneNumber, Currency,
EmailAddress, and more. The DataType attribute can also enable the application to automatically provide type-
specific features. For example, a mailto: link can be created for DataType.EmailAddress . A date selector can be
provided for DataType.Date in browsers that support HTML5. The DataType attributes emits HTML 5 data-
(pronounced data dash) attributes that HTML 5 browsers consume. The DataType attributes do not provide any
validation.
DataType.Date doesn't specify the format of the date that's displayed. By default, the data field is displayed
according to the default formats based on the server's CultureInfo .
The DisplayFormat attribute is used to explicitly specify the date format:
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]

The ApplyFormatInEditMode setting specifies that the formatting should be applied when the value is displayed for
editing. You might not want that behavior for some fields. For example, in currency values, you probably don't
want the currency symbol in the edit UI.
The DisplayFormat attribute can be used by itself, but it's generally a good idea to use the DataType attribute. The
DataType attribute conveys the semantics of the data as opposed to how to render it on a screen, and provides the
following benefits that you don't get with DisplayFormat:
The browser can enable HTML5 features (for example to show a calendar control, the locale-appropriate
currency symbol, email links, etc.)
By default, the browser will render data using the correct format based on your locale.
The DataType attribute can enable the ASP.NET Core framework to choose the right field template to render
the data. The DisplayFormat if used by itself uses the string template.
Note: jQuery validation doesn't work with the Range attribute and DateTime . For example, the following code will
always display a client-side validation error, even when the date is in the specified range:
[Range(typeof(DateTime), "1/1/1966", "1/1/2020")]
It's generally not a good practice to compile hard dates in your models, so using the Range attribute and
DateTime is discouraged.
The following code shows combining attributes on one line:
public class Movie

{

[Display(Name = "Release Date"), DataType(DataType.Date)]

[RegularExpression(@"^[A-Z]+[a-zA-Z""'\s-]*$"), Required, StringLength(30)]

[Range(1, 100), DataType(DataType.Currency)]

[RegularExpression(@"^[A-Z]+[a-zA-Z0-9""'\s-]*$"), StringLength(5)]
}
public class Movie

{




}
Get started with Razor Pages and EF Core shows advanced EF Core operations with Razor Pages.
Publish to Azure
For information on deploying to Azure, See Tutorial: Build an ASP.NET app in Azure with SQL Database. The
instruction are for an ASP.NET app, not an ASP.NET Core app, but the steps are the same.
Thanks for completing this introduction to Razor Pages. We appreciate feedback. Get started with Razor Pages
and EF Core is an excellent follow up to this tutorial.
Working with Forms
Introduction to Tag Helpers
Author Tag Helpers
P R E V IO U S : A D D IN G A N E W
F IE L D
Tutorial: Get started with SignalR on ASP.NET Core
This tutorial teaches the basics of building a real-time app using SignalR. You learn how to:
Create a web app that uses SignalR on ASP.NET Core.
Create a SignalR hub on the server.
Connect to the SignalR hub from JavaScript clients.
Use the hub to send messages from any client to all connected clients.
At the end, you'll have a working chat app:
View or download sample code (how to download).
Prerequisites
Visual Studio
Visual Studio Code
Visual Studio 2017 version 15.8 or later with the ASP.NET and web development workload
.NET Core SDK 2.1 or later
Create the project

Visual Studio
Visual Studio Code
From the menu, select File > New Project.
In the New Project dialog, select Installed > Visual C# > Web > ASP.NET Core Web Application.
Name the project SignalRChat.
Select Web Application to create a project that uses Razor Pages.
Select a target framework of .NET Core, select ASP.NET Core 2.1, and click OK.
Add the SignalR client library

The SignalR server library is included in the Microsoft.AspNetCore.App metapackage. The JavaScript client library
isn't automatically included in the project. For this tutorial, you use Library Manager (LibMan) to get the client
library from unpkg. unpkg is a content delivery network that can deliver anything found in npm, the Node.js
package manager.
Visual Studio
Visual Studio Code
In Solution Explorer, right-click the project, and select Add > Client-Side Library.
In the Add Client-Side Library dialog, for Provider select unpkg.
For Library, enter _@aspnet/signalr@1_, and select the latest version that isn't preview.
Select Choose specific files, expand the dist/browser folder, and select signalr.js and signalr.min.js.
Set Target Location to wwwroot/lib/signalr/, and select Install.
LibMan creates a wwwroot/lib/signalr folder and copies the selected files to it.
Create the SignalR hub

A hub is a class that serves as a high-level pipeline that handles client-server communication.
In the SignalRChat project folder, create a Hubs folder.
In the Hubs folder, create a ChatHub.cs file with the following code:
using Microsoft.AspNetCore.SignalR;
namespace SignalRChat.Hubs
{
public class ChatHub : Hub
{
public async Task SendMessage(string user, string message)
{
await Clients.All.SendAsync("ReceiveMessage", user, message);
}
}
}
The ChatHub class inherits from the SignalR Hub class. The Hub class manages connections, groups, and
messaging.
The SendMessage method can be called by any connected client. It sends the received message to all clients.
SignalR code is asynchronous to provide maximum scalability.
Configure the project to use SignalR

The SignalR server must be configured to pass SignalR requests to SignalR.
Add the following highlighted code to the Startup.cs file.
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Configuration;
using SignalRChat.Hubs;
namespace SignalRChat
{
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
public IConfiguration Configuration { get; }
// This method gets called by the runtime. Use this method to add services to the container.
{
{
// This lambda determines whether user consent for non-essential cookies is needed for a
given request.
});
services.AddSignalR();
}
// This method gets called by the runtime. Use this method to configure the HTTP request
pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseCookiePolicy();
app.UseSignalR(routes =>
{
routes.MapHub<ChatHub>("/chatHub");
});
app.UseMvc();
}
}
}
These changes add SignalR to the dependency injection system and the middleware pipeline.
Create the SignalR client code

Replace the content in Pages\Index.cshtml with the following code:
@page
<div class="container">
<div class="row"> </div>
<div class="row">
<div class="col-6"> </div>
<div class="col-6">
User..........<input type="text" id="userInput" />
<br />
Message...<input type="text" id="messageInput" />
<input type="button" id="sendButton" value="Send Message" />
</div>
</div>
<div class="row">
<div class="col-12">
<hr />
</div>
</div>
<div class="row">
<div class="col-6">
<ul id="messagesList"></ul>
</div>
</div>
</div>
<script src="~/lib/signalr/dist/browser/signalr.js"></script>
<script src="~/js/chat.js"></script>
The preceding code:

Creates text boxes for name and message text, and a submit button.
Creates a list with id="messagesList" for displaying messages that are received from the SignalR hub.
Includes script references to SignalR and the chat.js application code that you create in the next step.
In the wwwroot/js folder, create a chat.js file with the following code:
"use strict";
var connection = new signalR.HubConnectionBuilder().withUrl("/chatHub").build();
connection.on("ReceiveMessage", function (user, message) {

var msg = message.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">");
var encodedMsg = user + " says " + msg;
var li = document.createElement("li");
li.textContent = encodedMsg;
document.getElementById("messagesList").appendChild(li);
});
connection.start().catch(function (err) {
return console.error(err.toString());
});
document.getElementById("sendButton").addEventListener("click", function (event) {

var user = document.getElementById("userInput").value;
var message = document.getElementById("messageInput").value;
connection.invoke("SendMessage", user, message).catch(function (err) {
});
event.preventDefault();
});
The preceding code:

Creates and starts a connection.
Adds to the submit button a handler that sends messages to the hub.
Adds to the connection object a handler that receives messages from the hub and adds them to the list.
Run the app

Visual Studio
Visual Studio Code
Press CTRL+F5 to run the app without debugging.
Copy the URL from the address bar, open another browser instance or tab, and paste the URL in the address
bar.
Choose either browser, enter a name and message, and select the Send button.
The name and message are displayed on both pages instantly.
TIP
If the app doesn't work, open your browser developer tools (F12) and go to the console. You might see errors related to your
HTML and JavaScript code. For example, suppose you put signalr.js in a different folder than directed. In that case the
reference to that file won't work and you'll see a 404 error in the console.
Next steps
If you want clients to connect to a SignalR app from different domains, you have to enable Cross-Origin Resource
Sharing (CORS ). For more information, see Cross-origin resource sharing.
To learn more about SignalR, hubs, and JavaScript clients, see these resources:
Introduction to SignalR for ASP.NET Core
Use hubs in SignalR for ASP.NET Core
ASP.NET Core SignalR JavaScript client
Use ASP.NET Core SignalR with TypeScript and
Webpack
By Sébastien Sougnez and Scott Addie

Webpack enables developers to bundle and build the client-side resources of a web app. This tutorial demonstrates
using Webpack in an ASP.NET Core SignalR web app whose client is written in TypeScript.
In this tutorial, you learn how to:
Scaffold a starter ASP.NET Core SignalR app
Configure the SignalR TypeScript client
Configure a build pipeline using Webpack
Configure the SignalR server
Enable communication between client and server
Prerequisites
Install the following software:
Visual Studio
.NET Core CLI
Node.js with npm
Visual Studio 2017 version 15.7.3 or later with the ASP.NET and web development workload
Create the ASP.NET Core web app

Visual Studio
.NET Core CLI
Configure Visual Studio to look for npm in the PATH environment variable. By default, Visual Studio uses the
version of npm found in its installation directory. Follow these instructions in Visual Studio:
1. Navigate to Tools > Options > Projects and solutions > Web Package Management > External Web
Tools.
2. Select the $ (PATH ) entry from the list. Click the up arrow to move the entry to the second position in the list.
As an aside, the first entry refers to the project's local packages.
Visual Studio configuration is completed. It's time to create the project.
1. Use the File > New > Project menu option and choose the ASP.NET Core Web Application template.
2. Name the project SignalRWebPack, and click the OK button.
3. Select .NET Core from the target framework drop-down, and select ASP.NET Core 2.1 from the framework
selector drop-down. Select the Empty template, and click the OK button.
Configure Webpack and TypeScript

The following steps configure the conversion of TypeScript to JavaScript and the bundling of client-side resources.
1. Execute the following command in the project root to create a package.json file:
npm init -y
2. Add the highlighted property to the package.json file:
{
"name": "SignalRWebPack",
"version": "1.0.0",
"private": true,
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC"
}
Setting the private property to true prevents package installation warnings in the next step.
3. Install the required npm packages. Execute the following command from the project root:
npm install -D -E [email protected] [email protected] [email protected] mini-css-
[email protected] [email protected] [email protected] [email protected] [email protected]
Some command details to note:

A version number follows the @ sign for each package name. npm installs those specific package
versions.
The -E option disables npm's default behavior of writing semantic versioning range operators to
package.json. For example, "webpack": "4.12.0" is used instead of "webpack": "^4.12.0" . This option
prevents unintended upgrades to newer package versions.
See the official npm-install docs for more detail.
4. Replace the scripts property of the package.json file with the following snippet:
"scripts": {
"build": "webpack --mode=development --watch",
"release": "webpack --mode=production",
"publish": "npm run release && dotnet publish -c Release"
},
Some explanation of the scripts:

build : Bundles your client-side resources in development mode and watches for file changes. The file
watcher causes the bundle to regenerate each time a project file changes. The mode option disables
production optimizations, such as tree shaking and minification. Only use build in development.
release : Bundles your client-side resources in production mode.
publish : Runs the release script to bundle the client-side resources in production mode. It calls the
.NET Core CLI's publish command to publish the app.
5. Create a file named webpack.config.js, in the project root, with the following content:
const path = require("path");
const HtmlWebpackPlugin = require("html-webpack-plugin");
const CleanWebpackPlugin = require("clean-webpack-plugin");
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
entry: "./src/index.ts",
output: {
path: path.resolve(__dirname, "wwwroot"),
filename: "[name].[chunkhash].js",
publicPath: "/"
},
resolve: {
extensions: [".js", ".ts"]
},
module: {
rules: [
{
test: /\.ts$/,
use: "ts-loader"
},
{
test: /\.css$/,
use: [MiniCssExtractPlugin.loader, "css-loader"]
}
]
},
plugins: [
new CleanWebpackPlugin(["wwwroot/*"]),
new HtmlWebpackPlugin({
template: "./src/index.html"
}),
new MiniCssExtractPlugin({
filename: "css/[name].[chunkhash].css"
})
]
};
The preceding file configures the Webpack compilation. Some configuration details to note:
The output property overrides the default value of dist. The bundle is instead emitted in the wwwroot
directory.
The resolve.extensions array includes .js to import the SignalR client JavaScript.
6. Create a new src directory in the project root. Its purpose is to store the project's client-side assets.
7. Create src/index.html with the following content.
<!DOCTYPE html>
<html>
<head>
<title>ASP.NET Core SignalR</title>
</head>
<body>
<div id="divMessages" class="messages">
</div>
<div class="input-zone">
<label id="lblMessage" for="tbMessage">Message:</label>
<input id="tbMessage" class="input-zone-input" type="text" />
<button id="btnSend">Send</button>
</div>
</body>
</html>
The preceding HTML defines the homepage's boilerplate markup.
8. Create a new src/css directory. Its purpose is to store the project's .css files.
9. Create src/css/main.css with the following content:
*, *::before, *::after {
box-sizing: border-box;
}
html, body {
margin: 0;
padding: 0;
}
.input-zone {
align-items: center;
display: flex;
flex-direction: row;
margin: 10px;
}
.input-zone-input {
flex: 1;
margin-right: 10px;
}
.message-author {
font-weight: bold;
}
.messages {
border: 1px solid #000;
margin: 10px;
max-height: 300px;
min-height: 300px;
overflow-y: auto;
padding: 5px;
}
The preceding main.css file styles the app.

10. Create src/tsconfig.json with the following content:
{
"compilerOptions": {
"target": "es5"
}
}
The preceding code configures the TypeScript compiler to produce ECMAScript 5-compatible JavaScript.
11. Create src/index.ts with the following content:
import "./css/main.css";
const divMessages: HTMLDivElement = document.querySelector("#divMessages");

const tbMessage: HTMLInputElement = document.querySelector("#tbMessage");
const btnSend: HTMLButtonElement = document.querySelector("#btnSend");
const username = new Date().getTime();
tbMessage.addEventListener("keyup", (e: KeyboardEvent) => {

if (e.keyCode === 13) {
send();
}
});
btnSend.addEventListener("click", send);
function send() {
}
The preceding TypeScript retrieves references to DOM elements and attaches two event handlers:
keyup : This event fires when the user types something in the textbox identified as tbMessage . The send
function is called when the user presses the Enter key.
click : This event fires when the user clicks the Send button. The send function is called.
Configure the ASP.NET Core app

1. The code provided in the Startup.Configure method displays Hello World!. Replace the app.Run method
call with calls to UseDefaultFiles and UseStaticFiles.
The preceding code allows the server to locate and serve the index.html file, whether the user enters its full
URL or the root URL of the web app.
2. Call AddSignalR in the Startup.ConfigureServices method. It adds the SignalR services to your project.
3. Map a /hub route to the ChatHub hub. Add the following lines at the end of the Startup.Configure method:
app.UseSignalR(options =>
{
options.MapHub<ChatHub>("/hub");
});
4. Create a new directory, called Hubs, in the project root. Its purpose is to store the SignalR hub, which is
created in the next step.
5. Create hub Hubs/ChatHub.cs with the following code:
namespace SignalRWebPack.Hubs
{
{
}
}
6. Add the following code at the top of the Startup.cs file to resolve the ChatHub reference:
using SignalRWebPack.Hubs;
Enable client and server communication

The app currently displays a simple form to send messages. Nothing happens when you try to do so. The server is
listening to a specific route but does nothing with sent messages.
1. Execute the following command at the project root:
npm install @aspnet/signalr
The preceding command installs the SignalR TypeScript client, which allows the client to send messages to
the server.
2. Add the highlighted code to the src/index.ts file:
import * as signalR from "@aspnet/signalr";

const connection = new signalR.HubConnectionBuilder()

.withUrl("/hub")
.build();
connection.start().catch(err => document.write(err));
connection.on("messageReceived", (username: string, message: string) => {

let m = document.createElement("div");
m.innerHTML =
`<div class="message__author">${username}</div><div>${message}</div>`;
divMessages.appendChild(m);
divMessages.scrollTop = divMessages.scrollHeight;
});

send();
}
});
function send() {
}
The preceding code supports receiving messages from the server. The HubConnectionBuilder class creates a
new builder for configuring the server connection. The withUrl function configures the hub URL.
SignalR enables the exchange of messages between a client and a server. Each message has a specific name.
For example, you can have messages with the name messageReceived that execute the logic responsible for
displaying the new message in the messages zone. Listening to a specific message can be done via the on
function. You can listen to any number of message names. It's also possible to pass parameters to the
message, such as the author's name and the content of the message received. Once the client receives a
message, a new div element is created with the author's name and the message content in its innerHTML
attribute. It's added to the main div element displaying the messages.
3. Now that the client can receive a message, configure it to send messages. Add the highlighted code to the
src/index.ts file:


.withUrl("/hub")
.build();

let messageContainer = document.createElement("div");
messageContainer.innerHTML =
`<div class="message-author">${username}</div><div>${message}</div>`;
divMessages.appendChild(messageContainer);
});

send();
}
});
function send() {
connection.send("newMessage", username, tbMessage.value)
.then(() => tbMessage.value = "");
}
Sending a message through the WebSockets connection requires calling the send method. The method's
first parameter is the message name. The message data inhabits the other parameters. In this example, a
message identified as newMessage is sent to the server. The message consists of the username and the user
input from a text box. If the send works, the text box value is cleared.
4. Add the highlighted method to the ChatHub class:
{
{
public async Task NewMessage(string username, string message)
{
await Clients.All.SendAsync("messageReceived", username, message);
}
}
}
The preceding code broadcasts received messages to all connected users once the server receives them. It's
unnecessary to have a generic on method to receive all the messages. A method named after the message
name suffices.
In this example, the TypeScript client sends a message identified as newMessage . The C# NewMessage method
expects the data sent by the client. A call is made to the SendAsync method on Clients.All. The received
messages are sent to all clients connected to the hub.
Test the app

Confirm that the app works with the following steps.
Visual Studio
.NET Core CLI
1. Run Webpack in release mode. Using the Package Manager Console window, execute the following
command in the project root:
npm run release
This command yields the client-side assets to be served when running the app. The assets are placed in the
wwwroot folder.
Webpack completed the following tasks:
Purged the contents of the wwwroot directory.
Converted the TypeScript to JavaScript—a process known as transpilation.
Mangled the generated JavaScript to reduce file size—a process known as minification.
Copied the processed JavaScript, CSS, and HTML files from src to the wwwroot directory.
Injected the following elements into the wwwroot/index.html file:
A <link> tag, referencing the wwwroot/main.<hash>.css file. This tag is placed immediately
before the closing </head> tag.
A <script> tag, referencing the minified wwwroot/main.<hash>.js file. This tag is placed
immediately before the closing </body> tag.
2. Select Debug > Start without debugging to launch the app in a browser without attaching the debugger.
The wwwroot/index.html file is served at http://localhost:<port_number> .
3. Open another browser instance (any browser). Paste the URL in the address bar.
4. Choose either browser, type something in the Message text box, and click the Send button. The unique user
name and message are displayed on both pages instantly.
Use hubs in ASP.NET Core SignalR
Create a web app with ASP.NET Core MVC on
Windows with Visual Studio
This tutorial teaches ASP.NET Core MVC web development with controllers and views. Razor Pages is a feature of
the ASP.NET Core MVC framework that makes building and testing web UI easier and more productive. You can
use Razor pages alongside controllers and views in the same project.
We recommend you try the Razor Pages tutorial before the MVC/Controller/Views version. The Razor Pages
tutorial:
Is the preferred approach for new application development.
Is easier to follow.
Covers more features.
If you choose this tutorial over the Razor Pages version, let us know why in this GitHub issue.
There are 3 versions of this tutorial:
Windows: This series
macOS: Create an ASP.NET Core MVC app with Visual Studio for Mac
macOS, Linux, and Windows: Create an ASP.NET Core MVC app with Visual Studio Code
The tutorial series includes the following:
1. Get started
2. Add a controller
3. Add a view
4. Add a model
5. Work with SQL Server LocalDB
6. Controller methods and views
7. Add search
8. Add a new field
9. Add validation
10. Examine the Details and Delete methods
Get started with ASP.NET Core MVC and Visual
Studio
By Rick Anderson
This tutorial teaches ASP.NET Core MVC web development with controllers and views. Razor Pages is a feature
of the ASP.NET Core MVC framework that makes building and testing web UI easier and more productive. You
can use Razor pages alongside controllers and views in the same project.
tutorial:
Windows: Create an ASP.NET Core MVC app with Visual Studio
Install Visual Studio and .NET Core

Create a web app

From Visual Studio, select File > New > Project.
Complete the New Project dialog:
In the left pane, tap .NET Core
In the center pane, tap ASP.NET Core Web Application (.NET Core)
Name the project "MvcMovie" (It's important to name the project "MvcMovie" so when you copy code, the
namespace will match.)
Tap OK
Complete the New ASP.NET Core Web Application (.NET Core) - MvcMovie dialog:
In the version selector drop-down box select ASP.NET Core 2.1
Select Web Application(Model-View-Controller)
Tap OK.
Visual Studio used a default template for the MVC project you just created. You have a working app right now by
entering a project name and selecting a few options. This is a basic starter project, and it's a good place to start,
Tap F5 to run the app in debug mode or Ctrl-F5 in non-debug mode.
Visual Studio starts IIS Express and runs your app. Notice that the address bar shows localhost:port# and
not something like example.com . That's because localhost is the standard hostname for your local computer.
When Visual Studio creates a web project, a random port is used for the web server. In the image above, the
port number is 5000. The URL in the browser shows localhost:5000 . When you run the app, you'll see a
different port number.
the browser, and see the code changes. Many developers prefer to use non-debug mode to quickly launch the
app and view changes.
You can launch the app in debug or non-debug mode from the Debug menu item:
You can debug the app by tapping the IIS Express button
The default template gives you working Home, About and Contact links. The browser image above doesn't
show these links. Depending on the size of your browser, you might need to click the navigation icon to show
them.
If you were running in debug mode, tap Shift-F5 to stop debugging.
In the next part of this tutorial, we'll learn about MVC and start writing some code.
ASP.NET Core 2.x
ASP.NET Core 1.x
IDE/editor tooling
Create a web app

From Visual Studio, select File > New > Project.
In the left pane, tap .NET Core
In the center pane, tap ASP.NET Core Web Application (.NET Core)
Name the project "MvcMovie" (It's important to name the project "MvcMovie" so when you copy code, the
namespace will match.)
Tap OK
ASP.NET Core 2.x

ASP.NET Core 1.x
Complete the New ASP.NET Core Web Application (.NET Core) - MvcMovie dialog:
In the version selector drop-down box select ASP.NET Core 2.-
Select Web Application(Model-View-Controller)
Tap OK.
Visual Studio used a default template for the MVC project you just created. You have a working app right now by
entering a project name and selecting a few options. This is a basic starter project, and it's a good place to start,
Tap F5 to run the app in debug mode or Ctrl-F5 in non-debug mode.
Visual Studio starts IIS Express and runs your app. Notice that the address bar shows localhost:port# and
When Visual Studio creates a web project, a random port is used for the web server. In the image above, the
port number is 5000. The URL in the browser shows localhost:5000 . When you run the app, you'll see a
different port number.
the browser, and see the code changes. Many developers prefer to use non-debug mode to quickly launch the
app and view changes.
You can launch the app in debug or non-debug mode from the Debug menu item:
You can debug the app by tapping the IIS Express button
them.
If you were running in debug mode, tap Shift-F5 to stop debugging.
NEXT
Add a controller to an ASP.NET Core MVC app
By Rick Anderson
The Model-View -Controller (MVC ) architectural pattern separates an app into three main components: Model,
View, and Controller. The MVC pattern helps you create apps that are more testable and easier to update than
traditional monolithic apps. MVC -based apps contain:
Models: Classes that represent the data of the app. The model classes use validation logic to enforce
business rules for that data. Typically, model objects retrieve and store model state in a database. In this
tutorial, a Movie model retrieves movie data from a database, provides it to the view or updates it. Updated
data is written to a database.
Views: Views are the components that display the app's user interface (UI). Generally, this UI displays the
model data.
Controllers: Classes that handle browser requests. They retrieve model data and call view templates that
return a response. In an MVC app, the view only displays information; the controller handles and responds
to user input and interaction. For example, the controller handles route data and query-string values, and
passes these values to the model. The model might use these values to query the database. For example,
http://localhost:1234/Home/About has route data of Home (the controller ) and About (the action method to
call on the home controller). http://localhost:1234/Movies/Edit/5 is a request to edit the movie with ID=5
using the movie controller. We'll talk about route data later in the tutorial.
The MVC pattern helps you create apps that separate the different aspects of the app (input logic, business logic,
and UI logic), while providing a loose coupling between these elements. The pattern specifies where each kind of
logic should be located in the app. The UI logic belongs in the view. Input logic belongs in the controller. Business
logic belongs in the model. This separation helps you manage complexity when you build an app, because it
enables you to work on one aspect of the implementation at a time without impacting the code of another. For
example, you can work on the view code without depending on the business logic code.
We cover these concepts in this tutorial series and show you how to use them to build a movie app. The MVC
project contains folders for the Controllers and Views.
In Solution Explorer, right-click Controllers > Add > New Item
Select Controller Class
In the Add New Item dialog, enter HelloWorldController.
Replace the contents of Controllers/HelloWorldController.cs with the following:

using System.Text.Encodings.Web;
namespace MvcMovie.Controllers
{
public class HelloWorldController : Controller
{
//
// GET: /HelloWorld/
public string Index()

{
return "This is my default action...";
}
//
// GET: /HelloWorld/Welcome/
public string Welcome()

{
return "This is the Welcome action method...";
}
}
}
Every public method in a controller is callable as an HTTP endpoint. In the sample above, both methods return a
string. Note the comments preceding each method.
An HTTP endpoint is a targetable URL in the web application, such as http://localhost:1234/HelloWorld , and
combines the protocol used: HTTP , the network location of the web server (including the TCP port):
localhost:1234 and the target URI HelloWorld .
The first comment states this is an HTTP GET method that's invoked by appending "/HelloWorld/" to the base
URL. The second comment specifies an HTTP GET method that's invoked by appending "/HelloWorld/Welcome/"
to the URL. Later on in the tutorial you'll use the scaffolding engine to generate HTTP POST methods.
Run the app in non-debug mode and append "HelloWorld" to the path in the address bar. The Index method
returns a string.
MVC invokes controller classes (and the action methods within them) depending on the incoming URL. The
default URL routing logic used by MVC uses a format like this to determine what code to invoke:
/[Controller]/[ActionName]/[Parameters]
You set the format for routing in the Configure method in Startup.cs file.
app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});
When you run the app and don't supply any URL segments, it defaults to the "Home" controller and the "Index"
method specified in the template line highlighted above.
The first URL segment determines the controller class to run. So localhost:xxxx/HelloWorld maps to the
HelloWorldController class. The second part of the URL segment determines the action method on the class. So
localhost:xxxx/HelloWorld/Index would cause the Index method of the HelloWorldController class to run. Notice
that you only had to browse to localhost:xxxx/HelloWorld and the Index method was called by default. This is
because Index is the default method that will be called on a controller if a method name isn't explicitly specified.
The third part of the URL segment ( id ) is for route data. You'll see route data later on in this tutorial.
Browse to http://localhost:xxxx/HelloWorld/Welcome . The Welcome method runs and returns the string "This is the
Welcome action method...". For this URL, the controller is HelloWorld and Welcome is the action method. You
haven't used the [Parameters] part of the URL yet.
Modify the code to pass some parameter information from the URL to the controller. For example,
/HelloWorld/Welcome?name=Rick&numtimes=4 . Change the Welcome method to include two parameters as shown in
the following code.
// Requires using System.Text.Encodings.Web;
public string Welcome(string name, int numTimes = 1)
{
return HtmlEncoder.Default.Encode($"Hello {name}, NumTimes is: {numTimes}");
}
The preceding code:

Uses the C# optional-parameter feature to indicate that the numTimes parameter defaults to 1 if no value is
passed for that parameter.
Uses HtmlEncoder.Default.Encode to protect the app from malicious input (namely JavaScript).
Uses Interpolated Strings.
Run your app and browse to:
http://localhost:xxxx/HelloWorld/Welcome?name=Rick&numtimes=4
(Replace xxxx with your port number.) You can try different values for name and numtimes in the URL. The MVC
model binding system automatically maps the named parameters from the query string in the address bar to
parameters in your method. See Model Binding for more information.
In the image above, the URL segment ( Parameters ) isn't used, the name and numTimes parameters are passed as
query strings. The ? (question mark) in the above URL is a separator, and the query strings follow. The &
character separates query strings.
Replace the Welcome method with the following code:
public string Welcome(string name, int ID = 1)

{
return HtmlEncoder.Default.Encode($"Hello {name}, ID: {ID}");
}
Run the app and enter the following URL: http://localhost:xxx/HelloWorld/Welcome/3?name=Rick
This time the third URL segment matched the route parameter id . The Welcome method contains a parameter
id that matched the URL template in the MapRoute method. The trailing ? (in id? ) indicates the id parameter
is optional.
{
routes.MapRoute(
name: "default",
});
In these examples the controller has been doing the "VC" portion of MVC - that is, the view and controller work.
The controller is returning HTML directly. Generally you don't want controllers returning HTML directly, since that
becomes very cumbersome to code and maintain. Instead you typically use a separate Razor view template file to
help generate the HTML response. You do that in the next tutorial.
In Visual Studio, in non-debug mode (Ctrl+F5), you don't need to build the app after changing code. Just save the
file, refresh your browser and you can see the changes.
P R E V IO U S NEXT
Add a view to an ASP.NET Core MVC app
By Rick Anderson
In this section you modify the HelloWorldController class to use Razor view template files to cleanly encapsulate
the process of generating HTML responses to a client.
You create a view template file using Razor. Razor-based view templates have a .cshtml file extension. They
provide an elegant way to create HTML output using C#.
Currently the method returns a string with a message that's hard-coded in the controller class. In the
Index
HelloWorldController class, replace the Index method with the following code:
public IActionResult Index()

{
return View();
}
The preceding code returns a View object. It uses a view template to generate an HTML response to the browser.
Controller methods (also known as action methods) such as the Index method above, generally return an
IActionResult (or a class derived from ActionResult ), not a type like string.
Right click on the Views folder, and then Add > New Folder and name the folder HelloWorld.
Right click on the Views/HelloWorld folder, and then Add > New Item.
In the Add New Item - MvcMovie dialog
In the search box in the upper-right, enter view
Tap Razor View
In the Name box, change the name if necessary to Index.cshtml.
Tap Add
Replace the contents of the Views/HelloWorld/Index.cshtml Razor view file with the following:
@{
}
<h2>Index</h2>
<p>Hello from our View Template!</p>
Navigate to http://localhost:xxxx/HelloWorld . The Index method in the HelloWorldController didn't do much; it

ran the statement return View(); , which specified that the method should use a view template file to render a
response to the browser. Because you didn't explicitly specify the name of the view template file, MVC defaulted to
using the Index.cshtml view file in the /Views/HelloWorld folder. The image below shows the string "Hello from
our View Template!" hard-coded in the view.
If your browser window is small (for example on a mobile device), you might need to toggle (tap) the Bootstrap
navigation button in the upper right to see the Home, About, and Contact links.
Changing views and layout pages
Tap the menu links (MvcMovie, Home, About). Each page shows the same menu layout. The menu layout is
implemented in the Views/Shared/_Layout.cshtml file. Open the Views/Shared/_Layout.cshtml file.
Layout templates allow you to specify the HTML container layout of your site in one place and then apply it across
multiple pages in your site. Find the @RenderBody() line. RenderBody is a placeholder where all the view -specific
pages you create show up, wrapped in the layout page. For example, if you select the About link, the
Views/Home/About.cshtml view is rendered inside the RenderBody method.
Change the title and menu link in the layout file

In the title element, change MvcMovie to Movie App . Change the anchor text in the layout template from MvcMovie
to Movie App and the controller from Home to Movies as highlighted below:
@inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet

<!DOCTYPE html>
<html>
<head>
<title>@ViewData["Title"] - Movie App</title>
<environment names="Development">
<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
<link rel="stylesheet" href="~/css/site.css" />
</environment>
<environment names="Staging,Production">
<link rel="stylesheet" href="https://ajax.aspnetcdn.com/ajax/bootstrap/3.3.7/css/bootstrap.min.css"
asp-fallback-href="~/lib/bootstrap/dist/css/bootstrap.min.css"
asp-fallback-test-class="sr-only" asp-fallback-test-property="position" asp-fallback-test-
value="absolute" />
<link rel="stylesheet" href="~/css/site.min.css" asp-append-version="true" />
</environment>
@Html.Raw(JavaScriptSnippet.FullScript)
</head>
<body>
<nav class="navbar navbar-inverse navbar-fixed-top">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-
collapse">
collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
</button>
<a asp-area="" asp-controller="Movies" asp-action="Index" class="navbar-brand">Movie App</a>
</div>
<div class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li><a asp-area="" asp-controller="Home" asp-action="Index">Home</a></li>
<li><a asp-area="" asp-controller="Home" asp-action="About">About</a></li>
<li><a asp-area="" asp-controller="Home" asp-action="Contact">Contact</a></li>
</ul>
</div>
</div>
</nav>
<div class="container body-content">
@RenderBody()
<hr />
<footer>
<p>© 2017 - MvcMovie</p>
</footer>
</div>
<script src="~/lib/jquery/dist/jquery.js"></script>
<script src="~/lib/bootstrap/dist/js/bootstrap.js"></script>
<script src="~/js/site.js" asp-append-version="true"></script>
</environment>
<script src="https://ajax.aspnetcdn.com/ajax/jquery/jquery-2.2.0.min.js"
asp-fallback-src="~/lib/jquery/dist/jquery.min.js"
asp-fallback-test="window.jQuery"
crossorigin="anonymous"
integrity="sha384-K+ctZQ+LL8q6tP7I94W+qzQsfRV2a+AfHIi9k8z8l9ggpc8X+Ytst4yBo/hH+8Fk">
</script>
<script src="https://ajax.aspnetcdn.com/ajax/bootstrap/3.3.7/bootstrap.min.js"
asp-fallback-src="~/lib/bootstrap/dist/js/bootstrap.min.js"
asp-fallback-test="window.jQuery && window.jQuery.fn && window.jQuery.fn.modal"
integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa">
</script>
<script src="~/js/site.min.js" asp-append-version="true"></script>
</environment>
@RenderSection("Scripts", required: false)

</body>
</html>

<!DOCTYPE html>
<html>
<head>
</environment>
value="absolute" />
</environment>
</head>
<body>
collapse">
</button>
</div>
</ul>
</div>
</div>
</nav>
@RenderBody()
<hr />
<footer>
</footer>
</div>
</environment>
</script>
</script>
</environment>

</body>
</html>
WARNING
We haven't implemented the Movies controller yet, so if you click on that link, you'll get a 404 (Not found) error.
Save your changes and tap the About link. Notice how the title on the browser tab now displays About - Movie
App instead of About - Mvc Movie:
Tap the Contact link and notice that the title and anchor text also display Movie App. We were able to make the
change once in the layout template and have all pages on the site reflect the new link text and new title.
Examine the Views/_ViewStart.cshtml file:
@{
Layout = "_Layout";
}
The Views/_ViewStart.cshtml file brings in the Views/Shared/_Layout.cshtml file to each view. You can use the
Layout property to set a different layout view, or set it to null so no layout file will be used.
Change the title of the Index view.

Open Views/HelloWorld/Index.cshtml. There are two places to make a change:
The text that appears in the title of the browser.
The secondary header ( <h2> element).
You'll make them slightly different so you can see which bit of code changes which part of the app.
@{
ViewData["Title"] = "Movie List";
}
<h2>My Movie List</h2>
ViewData["Title"] = "Movie List"; in the code above sets the Title property of the ViewData dictionary to
"Movie List". The Title property is used in the <title> HTML element in the layout page:
Save your change and navigate to http://localhost:xxxx/HelloWorld . Notice that the browser title, the primary
heading, and the secondary headings have changed. (If you don't see changes in the browser, you might be
viewing cached content. Press Ctrl+F5 in your browser to force the response from the server to be loaded.) The
browser title is created with ViewData["Title"] we set in the Index.cshtml view template and the additional "-
Movie App" added in the layout file.
Also notice how the content in the Index.cshtml view template was merged with the Views/Shared/_Layout.cshtml
view template and a single HTML response was sent to the browser. Layout templates make it really easy to make
changes that apply across all of the pages in your application. To learn more see Layout.
Our little bit of "data" (in this case the "Hello from our View Template!" message) is hard-coded, though. The MVC
application has a "V" (view ) and you've got a "C" (controller), but no "M" (model) yet.
Passing Data from the Controller to the View

Controller actions are invoked in response to an incoming URL request. A controller class is where you write the
code that handles the incoming browser requests. The controller retrieves data from a data source and decides
what type of response to send back to the browser. View templates can be used from a controller to generate and
format an HTML response to the browser.
Controllers are responsible for providing the data required in order for a view template to render a response. A
best practice: View templates should not perform business logic or interact with a database directly. Rather, a view
template should work only with the data that's provided to it by the controller. Maintaining this "separation of
concerns" helps keep your code clean, testable, and maintainable.
Currently, the Welcome method in the HelloWorldController class takes a name and a ID parameter and then
outputs the values directly to the browser. Rather than have the controller render this response as a string, change
the controller to use a view template instead. The view template generates a dynamic response, which means that
appropriate bits of data must be passed from the controller to the view in order to generate the response. Do this
by having the controller put the dynamic data (parameters) that the view template needs in a ViewData dictionary
that the view template can then access.
Return to the HelloWorldController.cs file and change the Welcome method to add a Message and NumTimes value
to the ViewData dictionary. The ViewData dictionary is a dynamic object, which means you can put whatever you
want in to it; the ViewData object has no defined properties until you put something inside it. The MVC model
binding system automatically maps the named parameters ( name and numTimes ) from the query string in the
address bar to parameters in your method. The complete HelloWorldController.cs file looks like this:
{
{
{
return View();
}
public IActionResult Welcome(string name, int numTimes = 1)

{
ViewData["Message"] = "Hello " + name;
ViewData["NumTimes"] = numTimes;
return View();
}
}
}
The ViewData dictionary object contains data that will be passed to the view.
Create a Welcome view template named Views/HelloWorld/Welcome.cshtml.
You'll create a loop in the Welcome.cshtml view template that displays "Hello" NumTimes . Replace the contents of
Views/HelloWorld/Welcome.cshtml with the following:
@{
ViewData["Title"] = "Welcome";
}
<h2>Welcome</h2>
<ul>
@for (int i = 0; i < (int)ViewData["NumTimes"]; i++)
{
<li>@ViewData["Message"]</li>
}
</ul>
Save your changes and browse to the following URL:

Data is taken from the URL and passed to the controller using the MVC model binder . The controller packages
the data into a ViewData dictionary and passes that object to the view. The view then renders the data as HTML to
the browser.
In the sample above, we used the ViewData dictionary to pass data from the controller to a view. Later in the
tutorial, we will use a view model to pass data from a controller to a view. The view model approach to passing
data is generally much preferred over the ViewData dictionary approach. See ViewModel vs ViewData vs
ViewBag vs TempData vs Session in MVC for more information.
Well, that was a kind of an "M" for model, but not the database kind. Let's take what we've learned and create a
database of movies.
P R E V IO U S NEXT
Add a model to an ASP.NET Core MVC app
By Rick Anderson and Tom Dykstra

In this section, you'll add some classes for managing movies in a database. These classes will be the "Model" part
of the MVC app.
You use these classes with Entity Framework Core (EF Core) to work with a database. EF Core is an object-
relational mapping (ORM ) framework that simplifies the data access code that you have to write. EF Core
supports many database engines.
The model classes you'll create are known as POCO classes (from "plain-old CLR objects") because they don't
have any dependency on EF Core. They just define the properties of the data that will be stored in the database.
In this tutorial you'll write the model classes first, and EF Core will create the database. An alternate approach not
covered here is to generate model classes from an already-existing database. For information about that approach,
see ASP.NET Core - Existing Database.
Add a data model class

Right-click the Models folder > Add > Class. Name the class Movie and add the following properties:
using System;
namespace MvcMovie.Models
{
public class Movie
{
}
}

Build the project to verify you don't have any errors. You now have a Model in your MVC app.
Scaffolding a controller
In Solution Explorer, right-click the Controllers folder > Add > New Scaffolded Item.
In the Add Scaffold dialog, tap MVC Controller with views, using Entity Framework > Add.
In Solution Explorer, right-click the Controllers folder > Add > Controller.
If the Add MVC Dependencies dialog appears:
Update Visual Studio to the latest version. Visual Studio versions prior to 15.5 show this dialog.
If you can't update, select ADD, and then follow the add controller steps again.
In the Add Scaffold dialog, tap MVC Controller with views, using Entity Framework > Add.
Complete the Add Controller dialog:

Model class: Movie (MvcMovie.Models)
Data context class: Select the + icon and add the default MvcMovie.Models.MvcMovieContext
Views: Keep the default of each option checked
Controller name: Keep the default MoviesController
Tap Add
Visual Studio creates:

An Entity Framework Core database context class (Data/MvcMovieContext.cs)
A movies controller (Controllers/MoviesController.cs)
Razor view files for Create, Delete, Details, Edit, and Index pages (Views/Movies/*.cshtml)
The automatic creation of the database context and CRUD (create, read, update, and delete) action methods and
views is known as scaffolding. You'll soon have a fully functional web application that lets you manage a movie
database.
If you run the app and click on the Mvc Movie link, you get an error similar to the following:
An unhandled exception occurred while processing the request.
SqlException: Cannot open database "MvcMovieContext-<GUID removed>" requested by the login. The login failed.
Login failed for user 'Rick'.
System.Data.SqlClient.SqlInternalConnectionTds..ctor(DbConnectionPoolIdentity identity, SqlConnectionString
You need to create the database, and you'll use the EF Core Migrations feature to do that. Migrations lets you
create a database that matches your data model and update the database schema when your data model changes.
Add EF tooling and perform initial migration

In this section you'll use the Package Manager Console (PMC ) to:
Add the Entity Framework Core Tools package. This package is required to add migrations and update the
database.
Update-Database
Ignore the following error message, we fix it in the next tutorial:

Microsoft.EntityFrameworkCore.Model.Validation[30000 ]
No type was specified for the decimal column 'Price' on entity type 'Movie'. This will cause values to be silently
truncated if they do not fit in the default precision and scale. Explicitly specify the SQL server column type that can
accommodate all the values using 'ForHasColumnType()'.
Install-Package Microsoft.EntityFrameworkCore.Tools
Update-Database
Note: If you receive an error with the Install-Package command, open NuGet Package Manager and search for
the Microsoft.EntityFrameworkCore.Tools package. This allows you to install the package or check if it's already
installed. Alternatively, see the CLI approach if you have problems with the PMC.
The Add-Migration command creates code to create the initial database schema. The schema is based on the
model specified in the DbContext (In the Data/MvcMovieContext.cs file). The Initial argument is used to name
the migrations. You can use any name, but by convention you choose a name that describes the migration. See
Introduction to migrations for more information.
The Update-Database command runs the Up method in the Migrations/<time-stamp>_Initial.cs file, which creates
the database.
You can perform the preceeding steps using the command-line interface (CLI) rather than the PMC:
Add EF Core tooling to the .csproj file.
Run the following commands from the console (in the project directory):

If you run the app and get the error:
SqlException: Cannot open database "Movie" requested by the login.

The login failed.
You probably have not run dotnet ef database update .
Test the app

Run the app and tap the Mvc Movie link.
Tap the Create New link and create a movie.
You may not be able to enter decimal points or commas in the Price field. To support jQuery validation for
non-English locales that use a comma (",") for a decimal point, and non US -English date formats, you must
take steps to globalize your app. See https://github.com/aspnet/Docs/issues/4076 and Additional resources
for more information. For now, just enter whole numbers like 10.
In some locales you need to specify the date format. See the highlighted code below.
using System;
{
public class Movie
{
}
}
We'll talk about DataAnnotations later in the tutorial.

Tapping Create causes the form to be posted to the server, where the movie information is saved in a database.
The app redirects to the /Movies URL, where the newly created movie information is displayed.
Create a couple more movie entries. Try the Edit, Details, and Delete links, which are all functional.

{
{
// This lambda determines whether user consent for non-essential cookies is needed for a given
request.
});
services.AddDbContext<MvcMovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("MvcMovieContext")));
}

{
// Add framework services.
services.AddMvc();
}
The highlighted code above shows the movie database context being added to the Dependency Injection container
(In the Startup.cs file). services.AddDbContext<MvcMovieContext>(options => specifies the database to use and the
connection string. => is a lambda operator.
Open the Controllers/MoviesController.cs file and examine the constructor:
public class MoviesController : Controller
{
private readonly MvcMovieContext _context;
public MoviesController(MvcMovieContext context)

{
_context = context;
}
The constructor uses Dependency Injection to inject the database context ( MvcMovieContext ) into the controller.
The database context is used in each of the CRUD methods in the controller.
Strongly typed models and the @model keyword

Earlier in this tutorial, you saw how a controller can pass data or objects to a view using the ViewData dictionary.
The ViewData dictionary is a dynamic object that provides a convenient late-bound way to pass information to a
view.
MVC also provides the ability to pass strongly typed model objects to a view. This strongly typed approach
enables better compile-time checking of your code. The scaffolding mechanism used this approach (that is,
passing a strongly typed model) with the MoviesController class and views when it created the methods and
views.
Examine the generated Details method in the Controllers/MoviesController.cs file:
// GET: Movies/Details/5
public async Task<IActionResult> Details(int? id)
{
if (id == null)
{
return NotFound();
}
var movie = await _context.Movie

.FirstOrDefaultAsync(m => m.ID == id);
if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
if (id == null)
{
return NotFound();
}

.SingleOrDefaultAsync(m => m.ID == id);
if (movie == null)
{
return NotFound();
}
return View(movie);
}
The id parameter is generally passed as route data. For example http://localhost:5000/movies/details/1 sets:
The controller to the movies controller (the first URL segment).
The action to details (the second URL segment).
The id to 1 (the last URL segment).
You can also pass in the id with a query string as follows:
http://localhost:1234/movies/details?id=1
The id parameter is defined as a nullable type ( int? ) in case an ID value isn't provided.
A lambda expression is passed in to FirstOrDefaultAsync to select movie entities that match the route data or
query string value.

A lambda expression is passed in to SingleOrDefaultAsync to select movie entities that match the route data or
query string value.

If a movie is found, an instance of the Movie model is passed to the Details view:
return View(movie);
Examine the contents of the Views/Movies/Details.cshtml file:

@model MvcMovie.Models.Movie
@{
ViewData["Title"] = "Details";
}
<h2>Details</h2>
<div>
<h4>Movie</h4>
<hr />
<dl class="dl-horizontal">
<dt>
@Html.DisplayNameFor(model => model.Title)
</dt>
<dd>
@Html.DisplayFor(model => model.Title)
</dd>
<dt>
@Html.DisplayNameFor(model => model.ReleaseDate)
</dt>
<dd>
@Html.DisplayFor(model => model.ReleaseDate)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Genre)
</dt>
<dd>
@Html.DisplayFor(model => model.Genre)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Price)
</dt>
<dd>
@Html.DisplayFor(model => model.Price)
</dd>
</dl>
</div>
<div>
<a asp-action="Edit" asp-route-id="@Model.ID">Edit</a> |
<a asp-action="Index">Back to List</a>
</div>
By including a @model statement at the top of the view file, you can specify the type of object that the view expects.
When you created the movie controller, Visual Studio automatically included the following @model statement at
the top of the Details.cshtml file:
This @model directive allows you to access the movie that the controller passed to the view by using a Model
object that's strongly typed. For example, in the Details.cshtml view, the code passes each movie field to the
DisplayNameFor and DisplayFor HTML Helpers with the strongly typed Model object. The Create and Edit
methods and views also pass a Movie model object.
Examine the Index.cshtml view and the Index method in the Movies controller. Notice how the code creates a
List object when it calls the View method. The code passes this Movies list from the Index action method to
the view:
// GET: Movies
public async Task<IActionResult> Index()
{
return View(await _context.Movie.ToListAsync());
}
When you created the movies controller, scaffolding automatically included the following @model statement at the
top of the Index.cshtml file:
@model IEnumerable<MvcMovie.Models.Movie>
The @modeldirective allows you to access the list of movies that the controller passed to the view by using a
Model object that's strongly typed. For example, in the Index.cshtml view, the code loops through the movies with
a foreach statement over the strongly typed Model object:
@model IEnumerable<MvcMovie.Models.Movie>
@{
}
<h2>Index</h2>
<p>
<a asp-action="Create">Create New</a>
</p>
<thead>
<tr>
<th>
</th>
<th>
@Html.DisplayNameFor(model => model.ReleaseDate)
</th>
<th>
@Html.DisplayNameFor(model => model.Genre)
</th>
<th>
@Html.DisplayNameFor(model => model.Price)
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model) {
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
<a asp-action="Edit" asp-route-id="@item.ID">Edit</a> |
<a asp-action="Details" asp-route-id="@item.ID">Details</a> |
<a asp-action="Delete" asp-route-id="@item.ID">Delete</a>
</td>
</tr>
}
</tbody>
</table>
Because the Model object is strongly typed (as an IEnumerable<Movie> object), each item in the loop is typed as
Movie . Among other benefits, this means that you get compile-time checking of the code:
Tag Helpers
P R E V IO U S A D D IN G A N E X T W O R K IN G W IT H
V IE W SQL
Work with SQL Server LocalDB in ASP.NET Core
By Rick Anderson
The MvcMovieContext object handles the task of connecting to the database and mapping Movie objects to
database records. The database context is registered with the Dependency Injection container in the
ConfigureServices method in the Startup.cs file:

{
{
request.
});
}

{
services.AddMvc();
}
The ASP.NET Core Configuration system reads the ConnectionString . For local development, it gets the
connection string from the appsettings.json file:
"MvcMovieContext": "Server=(localdb)\\mssqllocaldb;Database=MvcMovieContext-
}
When you deploy the app to a test or production server, you can use an environment variable or another approach
to set the connection string to a real SQL Server. See Configuration for more information.

LocalDB is a lightweight version of the SQL Server Express Database Engine that's targeted for program
development. LocalDB starts on demand and runs in user mode, so there's no complex configuration. By default,
LocalDB database creates "*.mdf" files in the C:/Users/<user> directory.
From the View menu, open SQL Server Object Explorer (SSOX).
Right click on the Movie table > View Designer
Note the key icon next to ID . By default, EF will make a property named ID the primary key.
Right click on the Movie table > View Data
Seed the database
using System;
using System.Linq;
{
{
{
using (var context = new MvcMovieContext(
serviceProvider.GetRequiredService<DbContextOptions<MvcMovieContext>>()))
{
{
}
new Movie
{
Price = 7.99M
},
new Movie
{
Genre = "Comedy",
Price = 8.99M
},
new Movie
{
Genre = "Comedy",
Price = 9.99M
},
new Movie
{
Genre = "Western",
Price = 3.99M
}
);
}
}
}
}
If there are any movies in the DB, the seed initializer returns and no movies are added.
{
}

Replace the contents of Program.cs with the following code:
using System;
using MvcMovie.Models;
using MvcMovie;
namespace MvcMovie
{
{
{

{
try
{
var context = services.GetRequiredService<MvcMovieContext>();
}
{
}
}
host.Run();
}

}
}
ASP.NET Core 2.x

ASP.NET Core 1.x
Add the seed initializer to the Main method in the Program.cs file:
using System;
namespace MvcMovie
{
{
{

{
try
{
// Requires using MvcMovie.Models;
}
{
}
}
host.Run();
}

.Build();
}
}
Test the app

Delete all the records in the DB. You can do this with the delete links in the browser or from SSOX.
Force the app to initialize (call the methods in the Startup class) so the seed method runs. To force
initialization, IIS Express must be stopped and restarted. You can do this with any of the following
approaches:
Right click the IIS Express system tray icon in the notification area and tap Exit or Stop Site
If you were running VS in non-debug mode, press F5 to run in debug mode
If you were running VS in debug mode, stop the debugger and press F5
The app shows the seeded data.
P R E V IO U S NEXT
Controller methods and views in ASP.NET Core
By Rick Anderson
AM in the image below ) and ReleaseDate should be two words.
Open the Models/Movie.cs file and add the highlighted lines shown below:
using System;
{
public class Movie
{


}
}
using System;
using System.Linq;
{
public class Movie
{

}
}
We cover DataAnnotations in the next tutorial. The Display attribute specifies what to display for the name of a
Browse to the Movies controller and hold the mouse pointer over an Edit link to see the target URL.
The Edit, Details, and Delete links are generated by the Core MVC Anchor Tag Helper in the
Views/Movies/Index.cshtml file.
</td>
</tr>
code above, the AnchorTagHelper dynamically generates the HTML href attribute value from the controller action
method and route id. You use View Source from your favorite browser or use the developer tools to examine the
generated markup. A portion of the generated HTML is shown below:
<td>
<a href="/Movies/Edit/4"> Edit </a> |
<a href="/Movies/Details/4"> Details </a> |
<a href="/Movies/Delete/4"> Delete </a>
</td>
Recall the format for routing set in the Startup.cs file:
{
routes.MapRoute(
name: "default",
});
ASP.NET Core translates http://localhost:1234/Movies/Edit/4 into a request to the Edit action method of the
Movies controller with the parameter Id of 4. ( Controller methods are also known as action methods.)
Tag Helpers are one of the most popular new features in ASP.NET Core. See Additional resources for more
information.
Open the Movies controller and examine the two Edit action methods. The following code shows the
HTTP GET Edit method, which fetches the movie and populates the edit form generated by the Edit.cshtml Razor
file.
// GET: Movies/Edit/5
public async Task<IActionResult> Edit(int? id)
{
if (id == null)
{
return NotFound();
}
var movie = await _context.Movie.FindAsync(id);

if (movie == null)
{
return NotFound();
}
return View(movie);
}
The following code shows the HTTP POST Edit method, which processes the posted movie values:
// POST: Movies/Edit/5
// To protect from overposting attacks, please enable the specific properties you want to bind to, for
// more details see http://go.microsoft.com/fwlink/?LinkId=317598.
[HttpPost]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Edit(int id, [Bind("ID,Title,ReleaseDate,Genre,Price")] Movie movie)
{
if (id != movie.ID)
{
return NotFound();
}
if (ModelState.IsValid)
{
try
{
_context.Update(movie);
}
{
if (!MovieExists(movie.ID))
{
return NotFound();
}
else
{
throw;
}
}
return RedirectToAction("Index");
}
return View(movie);
}
{
if (id == null)
{
return NotFound();
}
var movie = await _context.Movie.SingleOrDefaultAsync(m => m.ID == id);

if (movie == null)
{
return NotFound();
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
The [Bind] attribute is one way to protect against over-posting. You should only include properties in the [Bind]
attribute that you want to change. See Protect your controller from over-posting for more information.
ViewModels provide an alternative approach to prevent over-posting.
Notice the second Edit action method is preceded by the [HttpPost] attribute.
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
return RedirectToAction(nameof(Index));
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
The HttpPost attribute specifies that this Edit method can be invoked only for POST requests. You could apply
the [HttpGet] attribute to the first edit method, but that's not necessary because [HttpGet] is the default.
The ValidateAntiForgeryToken attribute is used to prevent forgery of a request and is paired up with an anti-
forgery token generated in the edit view file (Views/Movies/Edit.cshtml). The edit view file generates the anti-
forgery token with the Form Tag Helper.
<form asp-action="Edit">
The Form Tag Helper generates a hidden anti-forgery token that must match the [ValidateAntiForgeryToken]
generated anti-forgery token in the Edit method of the Movies controller. For more information, see Anti-
Request Forgery.
The method takes the movie ID parameter, looks up the movie using the Entity Framework
HttpGet Edit
SingleOrDefaultAsync method, and returns the selected movie to the Edit view. If a movie cannot be found,
NotFound ( HTTP 404 ) is returned.
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
When the scaffolding system created the Edit view, it examined the Movie class and created code to render
<label> and <input> elements for each property of the class. The following example shows the Edit view that
was generated by the Visual Studio scaffolding system:
@{
ViewData["Title"] = "Edit";
}
<h2>Edit</h2>
<div class="form-horizontal">
<h4>Movie</h4>
<hr />
<input type="hidden" asp-for="ID" />
<label asp-for="Title" class="col-md-2 control-label"></label>
<input asp-for="Title" class="form-control" />
<span asp-validation-for="Title" class="text-danger"></span>
</div>
</div>
<label asp-for="ReleaseDate" class="col-md-2 control-label"></label>
<input asp-for="ReleaseDate" class="form-control" />
<span asp-validation-for="ReleaseDate" class="text-danger"></span>
</div>
</div>
<label asp-for="Genre" class="col-md-2 control-label"></label>
<input asp-for="Genre" class="form-control" />
<span asp-validation-for="Genre" class="text-danger"></span>
</div>
</div>
<label asp-for="Price" class="col-md-2 control-label"></label>
<input asp-for="Price" class="form-control" />
<span asp-validation-for="Price" class="text-danger"></span>
</div>
</div>
<div class="col-md-offset-2 col-md-10">
<input type="submit" value="Save" class="btn btn-default" />
</div>
</div>
</div>
</form>
<div>
</div>
@section Scripts {
}
Notice how the view template has a @model MvcMovie.Models.Movie statement at the top of the file.
@model MvcMovie.Models.Movie specifies that the view expects the model for the view template to be of type Movie .
The scaffolded code uses several Tag Helper methods to streamline the HTML markup. The - Label Tag Helper
displays the name of the field ("Title", "ReleaseDate", "Genre", or "Price"). The Input Tag Helper renders an HTML
<input> element. The Validation Tag Helper displays any validation messages associated with that property.
Run the application and navigate to the /Movies URL. Click an Edit link. In the browser, view the source for the
page. The generated HTML for the <form> element is shown below.
<form action="/Movies/Edit/7" method="post">

<h4>Movie</h4>
<hr />
<div class="text-danger" />
<input type="hidden" data-val="true" data-val-required="The ID field is required." id="ID" name="ID"
value="7" />
<label class="control-label col-md-2" for="Genre" />
<input class="form-control" type="text" id="Genre" name="Genre" value="Western" />
<span class="text-danger field-validation-valid" data-valmsg-for="Genre" data-valmsg-
replace="true"></span>
</div>
</div>
<label class="control-label col-md-2" for="Price" />
<input class="form-control" type="text" data-val="true" data-val-number="The field Price must
be a number." data-val-required="The Price field is required." id="Price" name="Price" value="3.99" />
<span class="text-danger field-validation-valid" data-valmsg-for="Price" data-valmsg-
</div>
</div>

</div>
</div>
</div>
<input name="__RequestVerificationToken" type="hidden"
value="CfDJ8Inyxgp63fRFqUePGvuI5jGZsloJu1L7X9le1gy7NCIlSduCRx9jDQClrV9pOTTmqUyXnJBXhmrjcUVDJyDUMm7-
MF_9rK8aAZdRdlOri7FmKVkRe_2v5LIHGKFcTjPrWPYnc9AdSbomkiOSaTEg7RU" />
</form>
The <input> elements are in an HTML <form> element whose action attribute is set to post to the
/Movies/Edit/id URL. The form data will be posted to the server when the Save button is clicked. The last line
before the closing </form> element shows the hidden XSRF token generated by the Form Tag Helper.
Processing the POST Request

The following listing shows the [HttpPost] version of the Edit action method.
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
The [ValidateAntiForgeryToken] attribute validates the hidden XSRF token generated by the anti-forgery token
generator in the Form Tag Helper
The model binding system takes the posted form values and creates a Movie object that's passed as the movie
parameter. The ModelState.IsValid method verifies that the data submitted in the form can be used to modify
(edit or update) a Movie object. If the data is valid it's saved. The updated (edited) movie data is saved to the
database by calling the SaveChangesAsync method of database context. After saving the data, the code redirects the
user to the Index action method of the MoviesController class, which displays the movie collection, including the
changes just made.
Before the form is posted to the server, client side validation checks any validation rules on the fields. If there are
any validation errors, an error message is displayed and the form isn't posted. If JavaScript is disabled, you won't
have client side validation but the server will detect the posted values that are not valid, and the form values will
be redisplayed with error messages. Later in the tutorial we examine Model Validation in more detail. The
Validation Tag Helper in the Views/Movies/Edit.cshtml view template takes care of displaying appropriate error
messages.
All the HttpGet methods in the movie controller follow a similar pattern. They get a movie object (or list of
objects, in the case of Index ), and pass the object (model) to the view. The Create method passes an empty
movie object to the Create view. All the methods that create, edit, delete, or otherwise modify data do so in the
[HttpPost] overload of the method. Modifying data in an HTTP GET method is a security risk. Modifying data in
an HTTP GET method also violates HTTP best practices and the architectural REST pattern, which specifies that
GET requests shouldn't change the state of your application. In other words, performing a GET operation should
be a safe operation that has no side effects and doesn't modify your persisted data.
Author Tag Helpers
Anti-Request Forgery
Protect your controller from over-posting
ViewModels
Form Tag Helper
Input Tag Helper
Label Tag Helper
Select Tag Helper
Validation Tag Helper
P R E V IO U S NEXT
Add search to an ASP.NET Core MVC app
By Rick Anderson
In this section you add search capability to the Index action method that lets you search movies by genre or
name.
Update the Index method with the following code:
public async Task<IActionResult> Index(string searchString)

{
select m;
{
}
return View(await movies.ToListAsync());

}
The first line of the Index action method creates a LINQ query to select the movies:

select m;
If the searchString parameter contains a string, the movies query is modified to filter on the value of the search
string:
{
}
The s => s.Title.Contains() code above is a Lambda Expression. Lambdas are used in method-based LINQ
queries as arguments to standard query operator methods such as the Where method or Contains (used in the
code above). LINQ queries are not executed when they're defined or when they're modified by calling a method
such as Where , Contains or OrderBy . Rather, query execution is deferred. That means that the evaluation of an
expression is delayed until its realized value is actually iterated over or the ToListAsync method is called. For more
information about deferred query execution, see Query Execution.
Note: The Contains method is run on the database, not in the c# code shown above. The case sensitivity on the
query depends on the database and the collation. On SQL Server, Contains maps to SQL LIKE, which is case
insensitive. In SQLlite, with the default collation, it's case sensitive.
Navigate to /Movies/Index . Append a query string such as ?searchString=Ghost to the URL. The filtered movies
are displayed.
If you change the signature of the Index method to have a parameter named id , the id parameter will match
the optional {id} placeholder for the default routes set in Startup.cs.
{
routes.MapRoute(
name: "default",
});
You can quickly rename the searchString parameter to id with the rename command. Right click on
searchString > Rename.
The rename targets are highlighted.
Change the parameter to id and all occurrences of searchString change to id .
The previous Index method:

{
select m;
{
}

}
The updated Index method with id parameter:
public async Task<IActionResult> Index(string id)

{
select m;
if (!String.IsNullOrEmpty(id))
{
movies = movies.Where(s => s.Title.Contains(id));
}

}
You can now pass the search title as route data (a URL segment) instead of as a query string value.
However, you can't expect users to modify the URL every time they want to search for a movie. So now you'll add
UI elements to help them filter movies. If you changed the signature of the Index method to test how to pass the
route-bound ID parameter, change it back so that it takes a parameter named searchString :
{
select m;
{
}

}
Open the Views/Movies/Index.cshtml file, and add the <form> markup highlighted below:
}
<h2>Index</h2>
<p>
</p>
<form asp-controller="Movies" asp-action="Index">

<p>
</p>
</form>
<thead>
The HTML <form> tag uses the Form Tag Helper, so when you submit the form, the filter string is posted to the
Index action of the movies controller. Save your changes and then test the filter.
There's no [HttpPost] overload of the Index method as you might expect. You don't need it, because the method
isn't changing the state of the app, just filtering data.
You could add the following [HttpPost] Index method.
[HttpPost]
public string Index(string searchString, bool notUsed)
{
return "From [HttpPost]Index: filter on " + searchString;
}
The notUsed parameter is used to create an overload for the Index method. We'll talk about that later in the
tutorial.
If you add this method, the action invoker would match the [HttpPost] Index method, and the [HttpPost] Index
method would run as shown in the image below.
However, even if you add this [HttpPost] version of the Index method, there's a limitation in how this has all
been implemented. Imagine that you want to bookmark a particular search or you want to send a link to friends
that they can click in order to see the same filtered list of movies. Notice that the URL for the HTTP POST request
is the same as the URL for the GET request (localhost:xxxxx/Movies/Index) -- there's no search information in the
URL. The search string information is sent to the server as a form field value. You can verify that with the browser
Developer tools or the excellent Fiddler tool. The image below shows the Chrome browser Developer tools:
You can see the search parameter and XSRF token in the request body. Note, as mentioned in the previous
tutorial, the Form Tag Helper generates an XSRF anti-forgery token. We're not modifying data, so we don't need
to validate the token in the controller method.
Because the search parameter is in the request body and not the URL, you can't capture that search information to
bookmark or share with others. We'll fix this by specifying the request should be HTTP GET .
Notice how intelliSense helps us update the markup.
Notice the distinctive font in the <form> tag. That distinctive font indicates the tag is supported by Tag Helpers.
Now when you submit a search, the URL contains the search query string. Searching will also go to the
HttpGet Index action method, even if you have a HttpPost Index method.
The following markup shows the change to the form tag:
<form asp-controller="Movies" asp-action="Index" method="get">
Adding Search by genre

Add the following MovieGenreViewModel class to the Models folder:
using Microsoft.AspNetCore.Mvc.Rendering;
{
public class MovieGenreViewModel
{
public List<Movie> movies;
public SelectList genres;
public string movieGenre { get; set; }
}
}
The movie-genre view model will contain:

A list of movies.
A SelectList containing the list of genres. This will allow the user to select a genre from the list.
movieGenre , which contains the selected genre.
Replace the Index method in MoviesController.cs with the following code:

public async Task<IActionResult> Index(string movieGenre, string searchString)
{
orderby m.Genre
select m.Genre;

select m;
{
}
{
}
var movieGenreVM = new MovieGenreViewModel();

movieGenreVM.genres = new SelectList(await genreQuery.Distinct().ToListAsync());
movieGenreVM.movies = await movies.ToListAsync();
return View(movieGenreVM);
}

orderby m.Genre
select m.Genre;
The SelectList of genres is created by projecting the distinct genres (we don't want our select list to have
duplicate genres).
movieGenreVM.genres = new SelectList(await genreQuery.Distinct().ToListAsync())
Adding search by genre to the Index view

@model MvcMovie.Models.MovieGenreViewModel
@{
}
<h2>Index</h2>
<p>
</p>

<p>
<select asp-for="movieGenre" asp-items="Model.genres">
</select>

</p>
</form>
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.movies[0].Title)
</th>
<th>
@Html.DisplayNameFor(model => model.movies[0].ReleaseDate)
</th>
<th>
@Html.DisplayNameFor(model => model.movies[0].Genre)
</th>
<th>
@Html.DisplayNameFor(model => model.movies[0].Price)
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.movies)
{
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
In the preceding code, the DisplayNameFor HTML Helper inspects the Title property referenced in the lambda
expression to determine the display name. Since the lambda expression is inspected rather than evaluated, you
don't receive an access violation when model , model.movies , or model.movies[0] are null or empty. When the
lambda expression is evaluated (for example, @Html.DisplayFor(modelItem => item.Title) ), the model's property
values are evaluated.
P R E V IO U S NEXT
Add a new field to an ASP.NET Core MVC app
By Rick Anderson
In this section you'll use Entity Framework Code First Migrations to add a new field to the model and migrate that
change to the database.
When you use EF Code First to automatically create a database, Code First adds a table to the database to help
track whether the schema of the database is in sync with the model classes it was generated from. If they aren't in
sync, EF throws an exception. This makes it easier to find inconsistent database/code issues.

public class Movie

{


}
public class Movie

{

}
Build the app (Ctrl+Shift+B ).

Because you've added a new field to the Movie class, you also need to update the binding white list so this new
property will be included. In MoviesController.cs, update the [Bind] attribute for both the Create and Edit
action methods to include the Rating property:
[Bind("ID,Title,ReleaseDate,Genre,Price,Rating")]
You also need to update the view templates in order to display, create and edit the new Rating property in the
browser view.
Edit the /Views/Movies/Index.cshtml file and add a Rating field:
<thead>
<tr>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
@Html.DisplayNameFor(model => model.movies[0].Rating)
</th>
<th></th>
</tr>
</thead>
<tbody>
{
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
Update the /Views/Movies/Create.cshtml with a Rating field. You can copy/paste the previous "form group" and
let intelliSense help you update the fields. IntelliSense works with Tag Helpers. Note: In the RTM verison of Visual
Studio 2017 you need to install the Razor Language Services for Razor intelliSense. This will be fixed in the next
release.
The app won't work until we update the DB to include the new field. If you run it now, you'll get the following
SqlException :
SqlException: Invalid column name 'Rating'.
You're seeing this error because the updated Movie model class is different than the schema of the Movie table of
the existing database. (There's no Rating column in the database table.)
1. Have the Entity Framework automatically drop and re-create the database based on the new model class
schema. This approach is very convenient early in the development cycle when you are doing active
development on a test database; it allows you to quickly evolve the model and database schema together.
The downside, though, is that you lose existing data in the database — so you don't want to use this
approach on a production database! Using an initializer to automatically seed a database with test data is
often a productive way to develop an application.
2. Explicitly modify the schema of the existing database so that it matches the model classes. The advantage of
this approach is that you keep your data. You can make this change either manually or by creating a
For this tutorial, we'll use Code First Migrations.
you'll want to make this change for each new Movie .
new Movie
{
Rating = "R",
Price = 7.99M
},
Build the solution.

Add-Migration Rating
Update-Database
The Add-Migration command tells the migration framework to examine the current Movie model with the current
Movie DB schema and create the necessary code to migrate the DB to the new model. The name "Rating" is
arbitrary and is used to name the migration file. It's helpful to use a meaningful name for the migration file.
If you delete all the records in the DB, the initialize will seed the DB and include the Rating field. You can do this
with the delete links in the browser or from SSOX.
Run the app and verify you can create/edit/display movies with a Rating field. You should also add the Rating
field to the Edit , Details , and Delete view templates.
P R E V IO U S NEXT
Add validation to an ASP.NET Core MVC app
By Rick Anderson
In this section you'll add validation logic to the Movie model, and you'll ensure that the validation rules are
enforced any time a user creates or edits a movie.
Keeping things DRY

One of the design tenets of MVC is DRY ("Don't Repeat Yourself"). ASP.NET Core MVC encourages you to specify
functionality or behavior only once, and then have it be reflected everywhere in an app. This reduces the amount
of code you need to write and makes the code you do write less error prone, easier to test, and easier to maintain.
The validation support provided by MVC and Entity Framework Core Code First is a good example of the DRY
principle in action. You can declaratively specify validation rules in one place (in the model class) and the rules are
enforced everywhere in the app.

Open the Movie.cs file. DataAnnotations provides a built-in set of validation attributes that you apply declaratively
to any class or property. (It also contains formatting attributes like DataType that help with formatting and don't
provide any validation.)
Update the Movie class to take advantage of the built-in Required , StringLength , RegularExpression , and Range
public class Movie

{

[Required]

[Range(1, 100)]
[Required]
[StringLength(30)]
[StringLength(5)]
[Required]
}
public class Movie
{

[Required]

[Range(1, 100)]
[Required]
[StringLength(30)]
[StringLength(5)]
[Required]
}
The validation attributes specify behavior that you want to enforce on the model properties they're applied to. The
Required and MinimumLength attributes indicates that a property must have a value; but nothing prevents a user
from entering white space to satisfy this validation. The RegularExpression attribute is used to limit what
characters can be input. In the code above, Genre and Rating must use only letters (First letter uppercase, white
space, numbers and special characters are not allowed). The Range attribute constrains a value to within a
specified range. The StringLength attribute lets you set the maximum length of a string property, and optionally
its minimum length. Value types (such as decimal , int , float , DateTime ) are inherently required and don't need
the [Required] attribute.
Having validation rules automatically enforced by ASP.NET Core helps make your app more robust. It also
ensures that you can't forget to validate something and inadvertently let bad data into the database.
Validation Error UI in MVC

Run the app and navigate to the Movies controller.
Tap the Create New link to add a new movie. Fill out the form with some invalid values. As soon as jQuery client
side validation detects the error, it displays an error message.
NOTE
Notice how the form has automatically rendered an appropriate validation error message in each field containing
an invalid value. The errors are enforced both client-side (using JavaScript and jQuery) and server-side (in case a
user has JavaScript disabled).
A significant benefit is that you didn't need to change a single line of code in the MoviesController class or in the
Create.cshtml view in order to enable this validation UI. The controller and views you created earlier in this tutorial
automatically picked up the validation rules that you specified by using validation attributes on the properties of
the Movie model class. Test validation using the Edit action method, and the same validation is applied.
The form data isn't sent to the server until there are no client side validation errors. You can verify this by putting a
break point in the HTTP Post method, by using the Fiddler tool , or the F12 Developer tools.
How validation works

You might wonder how the validation UI was generated without any updates to the code in the controller or views.
The following code shows the two Create methods.
// GET: Movies/Create
public IActionResult Create()
{
return View();
}
// POST: Movies/Create
[HttpPost]
public async Task<IActionResult> Create(
[Bind("ID,Title,ReleaseDate,Genre,Price, Rating")] Movie movie)
{
{
_context.Add(movie);
}
return View(movie);
}
The first (HTTP GET) Create action method displays the initial Create form. The second ( [HttpPost] ) version
handles the form post. The second Create method (The [HttpPost] version) calls ModelState.IsValid to check
whether the movie has any validation errors. Calling this method evaluates any validation attributes that have
been applied to the object. If the object has validation errors, the Create method re-displays the form. If there are
no errors, the method saves the new movie in the database. In our movie example, the form isn't posted to the
server when there are validation errors detected on the client side; the second Create method is never called
when there are client side validation errors. If you disable JavaScript in your browser, client validation is disabled
and you can test the HTTP POST Create method ModelState.IsValid detecting any validation errors.
You can set a break point in the [HttpPost] Create method and verify the method is never called, client side
validation won't submit the form data when validation errors are detected. If you disable JavaScript in your
browser, then submit the form with errors, the break point will be hit. You still get full validation without
JavaScript.
The following image shows how to disable JavaScript in the FireFox browser.
The following image shows how to disable JavaScript in the Chrome browser.
After you disable JavaScript, post invalid data and step through the debugger.
Below is portion of the Create.cshtml view template that you scaffolded earlier in the tutorial. It's used by the
action methods shown above both to display the initial form and to redisplay it in the event of an error.
<form asp-action="Create">
<h4>Movie</h4>
<hr />

</div>
</div>

</div>
</form>
Validation on the client side. The Validation Tag Helper displays validation errors. See Validation for more
information.
What's really nice about this approach is that neither the controller nor the Create view template knows anything
about the actual validation rules being enforced or about the specific error messages displayed. The validation
rules and the error strings are specified only in the Movie class. These same validation rules are automatically
applied to the Edit view and any other views templates you might create that edit your model.
When you need to change validation logic, you can do so in exactly one place by adding validation attributes to the
model (in this example, the Movie class). You won't have to worry about different parts of the application being
inconsistent with how the rules are enforced — all validation logic will be defined in one place and used
everywhere. This keeps the code very clean, and makes it easy to maintain and evolve. And it means that you'll be
fully honoring the DRY principle.

Open the Movie.cs file and examine the Movie class. The System.ComponentModel.DataAnnotations namespace
provides formatting attributes in addition to the built-in set of validation attributes. We've already applied a
DataType enumeration value to the release date and to the price fields. The following code shows the
ReleaseDate and Price properties with the appropriate DataType attribute.
[Range(1, 100)]
The DataType attributes only provide hints for the view engine to format the data (and supplies
elements/attributes such as <a> for URL's and <a href="mailto:EmailAddress.com"> for email. You can use the
RegularExpression attribute to validate the format of the data. The DataType attribute is used to specify a data
type that's more specific than the database intrinsic type, they're not validation attributes. In this case we only want
to keep track of the date, not the time. The DataType Enumeration provides for many data types, such as Date,
Time, PhoneNumber, Currency, EmailAddress and more. The DataType attribute can also enable the application
to automatically provide type-specific features. For example, a mailto: link can be created for
DataType.EmailAddress , and a date selector can be provided for DataType.Date in browsers that support HTML5.
The DataType attributes emit HTML 5 data- (pronounced data dash) attributes that HTML 5 browsers can
understand. The DataType attributes do not provide any validation.

The ApplyFormatInEditMode setting specifies that the formatting should also be applied when the value is displayed
in a text box for editing. (You might not want that for some fields — for example, for currency values, you probably
don't want the currency symbol in the text box for editing.)
You can use the DisplayFormat attribute by itself, but it's generally a good idea to use the DataType attribute. The
The DataType attribute can enable MVC to choose the right field template to render the data (the
DisplayFormat if used by itself uses the string template).
NOTE
jQuery validation doesn't work with the Range attribute and DateTime . For example, the following code will always display
a client side validation error, even when the date is in the specified range:
You will need to disable jQuery date validation to use the Range attribute with DateTime . It's generally not a good
practice to compile hard dates in your models, so using the Range attribute and DateTime is discouraged.
public class Movie
{




}
public class Movie

{
[StringLength(60, MinimumLength = 3), Required]




[RegularExpression(@"^[A-Z]+[a-zA-Z0-9""'\s-]*$"), Required, StringLength(5)]

}
In the next part of the series, we'll review the application and make some improvements to the automatically
generated Details and Delete methods.
Working with Forms
Author Tag Helpers
P R E V IO U S NEXT
Examine the Details and Delete methods of an
ASP.NET Core app
By Rick Anderson
Open the Movie controller and examine the Details method:
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
The MVC scaffolding engine that created this action method adds a comment showing an HTTP request that
invokes the method. In this case it's a GET request with three URL segments, the Movies controller, the Details
method and an id value. Recall these segments are defined in Startup.cs.
{
routes.MapRoute(
name: "default",
});
EF makes it easy to search for data using the SingleOrDefaultAsync method. An important security feature built
into the method is that the code verifies that the search method has found a movie before it tries to do anything
with it. For example, a hacker could introduce errors into the site by changing the URL created by the links from
http://localhost:xxxx/Movies/Details/1 to something like http://localhost:xxxx/Movies/Details/12345 (or some
other value that doesn't represent an actual movie). If you didn't check for a null movie, the app would throw an
exception.
Examine the Delete and DeleteConfirmed methods.
// GET: Movies/Delete/5
public async Task<IActionResult> Delete(int? id)
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
// POST: Movies/Delete/5
[HttpPost, ActionName("Delete")]
public async Task<IActionResult> DeleteConfirmed(int id)
{
_context.Movie.Remove(movie);
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
}
Note that the HTTP GET Delete method doesn't delete the specified movie, it returns a view of the movie where you
can submit (HttpPost) the deletion. Performing a delete operation in response to a GET request (or for that matter,
performing an edit operation, create operation, or any other operation that changes data) opens up a security hole.
The [HttpPost] method that deletes the data is named DeleteConfirmed to give the HTTP POST method a unique
signature or name. The two method signatures are shown below:
{
{
The common language runtime (CLR ) requires overloaded methods to have a unique parameter signature (same
method name but different list of parameters). However, here you need two Delete methods -- one for GET and
one for POST -- that both have the same parameter signature. (They both need to accept a single integer as a
parameter.)
There are two approaches to this problem, one is to give the methods different names. That's what the scaffolding
mechanism did in the preceding example. However, this introduces a small problem: ASP.NET maps segments of a
URL to action methods by name, and if you rename a method, routing normally wouldn't be able to find that
method. The solution is what you see in the example, which is to add the ActionName("Delete") attribute to the
DeleteConfirmed method. That attribute performs mapping for the routing system so that a URL that includes
/Delete/ for a POST request will find the DeleteConfirmed method.
Another common work around for methods that have identical names and signatures is to artificially change the
signature of the POST method to include an extra (unused) parameter. That's what we did in a previous post when
we added the notUsed parameter. You could do the same thing here for the [HttpPost] Delete method:
public async Task<IActionResult> Delete(int id, bool notUsed)
Publish to Azure
P R E V IO U S
By Scott Addie
This document explains how to build a web API in ASP.NET Core and when it's most appropriate to use each
feature.
Derive class from ControllerBase

Inherit from the ControllerBase class in a controller that's intended to serve as a web API. For example:
[Produces("application/json")]
public class PetsController : ControllerBase
{
private readonly PetsRepository _repository;
public PetsController(PetsRepository repository)

{
_repository = repository;
}
[HttpGet]
public async Task<ActionResult<List<Pet>>> GetAllAsync()
{
return await _repository.GetPetsAsync();
}
[HttpGet("{id}")]
[ProducesResponseType(404)]
public async Task<ActionResult<Pet>> GetByIdAsync(int id)
{
var pet = await _repository.GetPetAsync(id);
if (pet == null)
{
return NotFound();
}
return pet;
}
[HttpPost]
public async Task<ActionResult<Pet>> CreateAsync(Pet pet)
{
{
return BadRequest(ModelState);
}
await _repository.AddPetAsync(pet);
return CreatedAtAction(nameof(GetByIdAsync),
new { id = pet.Id }, pet);
}
}
{

{
}
[HttpGet]
[ProducesResponseType(typeof(IEnumerable<Pet>), 200)]
public async Task<IActionResult> GetAllAsync()
{
var pets = await _repository.GetPetsAsync();
return Ok(pets);
}
[HttpGet("{id}")]
[ProducesResponseType(typeof(Pet), 200)]
public async Task<IActionResult> GetByIdAsync(int id)
{
if (pet == null)
{
return NotFound();
}
return Ok(pet);
}
[HttpPost]
public async Task<IActionResult> CreateAsync([FromBody] Pet pet)
{
{
}
}
}
The ControllerBase class provides access to several properties and methods. In the preceding code, examples
include BadRequest(ModelStateDictionary) and CreatedAtAction(String, Object, Object). These methods are called
within action methods to return HTTP 400 and 201 status codes, respectively. The ModelState property, also
provided by ControllerBase , is accessed to handle request model validation.
Annotate class with ApiControllerAttribute

ASP.NET Core 2.1 introduces the [ApiController] attribute to denote a web API controller class. For example:
[ApiController]
public class ProductsController : ControllerBase
A compatibility version of 2.1 or later, set via SetCompatibilityVersion, is required to use this attribute. For example,
the highlighted code in Startup.ConfigureServices sets the 2.1 compatibility flag:
services.AddMvc()
The [ApiController] attribute is commonly coupled with ControllerBase to enable REST-specific behavior for
controllers. ControllerBase provides access to methods such as NotFound and File.
Another approach is to create a custom base controller class annotated with the [ApiController] attribute:
[ApiController]
public class MyBaseController
{
}
The following sections describe convenience features added by the attribute.

Automatic HTTP 400 responses
Validation errors automatically trigger an HTTP 400 response. The following code becomes unnecessary in your
actions:
{
}
The default behavior is disabled when the SuppressModelStateInvalidFilter property is set to true . Add the
following code in Startup.ConfigureServices after
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1); :
services.Configure<ApiBehaviorOptions>(options =>
{
options.SuppressConsumesConstraintForFormFileParameters = true;
options.SuppressInferBindingSourcesForParameters = true;
options.SuppressModelStateInvalidFilter = true;
});
Binding source parameter inference

A binding source attribute defines the location at which an action parameter's value is found. The following binding
source attributes exist:
ATTRIBUTE BINDING SOURCE
[FromBody] Request body
[FromForm] Form data in the request body

[FromHeader] Request header
[FromQuery] Request query string parameter
[FromRoute] Route data from the current request
[FromServices] The request service injected as an action parameter
WARNING
Don't use [FromRoute] when values might contain %2f (that is / ). %2f won't be unescaped to / . Use [FromQuery] if
the value might contain %2f .
Without the [ApiController] attribute, binding source attributes are explicitly defined. In the following example,
the [FromQuery] attribute indicates that the discontinuedOnly parameter value is provided in the request URL's
query string:
[HttpGet]
public async Task<ActionResult<List<Product>>> GetAsync(
[FromQuery] bool discontinuedOnly = false)
{
List<Product> products = null;
if (discontinuedOnly)
{
products = await _repository.GetDiscontinuedProductsAsync();
}
else
{
products = await _repository.GetProductsAsync();
}
return products;
}
Inference rules are applied for the default data sources of action parameters. These rules configure the binding
sources you're otherwise likely to manually apply to the action parameters. The binding source attributes behave as
follows:
[FromBody] is inferred for complex type parameters. An exception to this rule is any complex, built-in type with
a special meaning, such as IFormCollection and CancellationToken. The binding source inference code ignores
those special types. [FromBody] isn't inferred for simple types such as string or int . Therefore, the
[FromBody] attribute should be used for simple types when that functionality is desired. When an action has
more than one parameter explicitly specified (via [FromBody] ) or inferred as bound from the request body, an
exception is thrown. For example, the following action signatures cause an exception:
// Don't do this. All of the following actions result in an exception.
[HttpPost]
public IActionResult Action1(Product product,
Order order) => null;
[HttpPost]
[FromBody] Order order) => null;
[HttpPost]
public IActionResult Action3([FromBody] Product product,
[FromForm ] is inferred for action parameters of type IFormFile and IFormFileCollection. It's not inferred for
any simple or user-defined types.
[FromRoute] is inferred for any action parameter name matching a parameter in the route template. When
more than one route matches an action parameter, any route value is considered [FromRoute] .
[FromQuery] is inferred for any other action parameters.
The default inference rules are disabled when the SuppressInferBindingSourcesForParameters property is set to
true . Add the following code in Startup.ConfigureServices after
{
});
Multipart/form-data request inference

When an action parameter is annotated with the [FromForm] attribute, the multipart/form-data request content
type is inferred.
The default behavior is disabled when the SuppressConsumesConstraintForFormFileParameters property is set to
{
});
Attribute routing requirement

Attribute routing becomes a requirement. For example:
[ApiController]
Actions are inaccessible via conventional routes defined in UseMvc or by UseMvcWithDefaultRoute in

Startup.Configure.
Controller action return types in ASP.NET Core Web API
Custom formatters in ASP.NET Core Web API
Format response data in ASP.NET Core Web API
ASP.NET Core Web API help pages with Swagger / OpenAPI
Routing to controller actions in ASP.NET Core
Studio Code

In this tutorial, build a web API for managing a list of "to-do" items. A UI isn't constructed.
macOS, Linux, Windows: Web API with Visual Studio Code (This tutorial)
Windows: Web API with Visual Studio for Windows
Overview
controller.
Prerequisites
Install the following:
Visual Studio Code
C# for Visual Studio Code
Visual Studio Code
Create the project

From a console, run the following commands:
dotnet new webapi -o TodoApi

code TodoApi
The TodoApi folder opens in Visual Studio Code (VS Code). Select the Startup.cs file.
Select Yes to the Warn message "Required assets to build and debug are missing from 'TodoApi'. Add them?"
Select Restore to the Info message "There are unresolved dependencies".
Press Debug (F5) to build and run the program. In a browser, navigate to http://localhost:5000/api/values. The
following output is displayed:
["value1","value2"]
See Visual Studio Code help for tips on using VS Code.
Add support for Entity Framework Core

Creating a new project in ASP.NET Core 2.1 or later adds the Microsoft.AspNetCore.App package reference to the
TodoApi.csproj file. Add the Version attribute, if not already specified.
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.App" Version="2.1.4" />
</ItemGroup>
Creating a new project in ASP.NET Core 2.0 adds the Microsoft.AspNetCore.All package reference to the
TodoApi.csproj file:
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.All" Version="2.1.4" />
</ItemGroup>
There's no need to install the Entity Framework Core InMemory database provider separately. This database
provider allows Entity Framework Core to be used with an in-memory database.
Add a model class

A model is an object representing the data in your app. In this case, the only model is a to-do item.
Add a folder named Models. You can put model classes anywhere in your project, but the Models folder is used by
convention.
Add a TodoItem class with the following code:
{
{
}
}

The database context is the main class that coordinates Entity Framework functionality for a given data model. You
create this class by deriving from the Microsoft.EntityFrameworkCore.DbContext class.
Add a TodoContext class in the Models folder:
{
{
: base(options)
{
}

}
}

namespace TodoApi
{
{
{
services.AddMvc()
}

{
app.UseMvc();
}
}
}
namespace TodoApi
{
{
{
services.AddMvc();
}

{
app.UseMvc();
}
}
}
The preceding code:

Add a controller
In the Controllers folder, create a class named TodoController . Replace its contents with the following code:
using System.Linq;
{
{

{
_context = context;
{
}
}
}
}
implement the API.
using System.Linq;
{
[ApiController]
{

{
_context = context;
{
}
}
}
}
The preceding code:

Get to-do items

[HttpGet]
{
}

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}
[HttpGet]
{
}

{
if (item == null)
{
return NotFound();
}
return item;
}

GET /api/todo
GET /api/todo/{id}
[
{
"id": 1,
"name": "Item1",
"isComplete": false
}
]
{
{
{
[ApiController]
{

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}

{
if (item == null)
{
return NotFound();
}
return item;
}

Return values
response.
response.
response.
Launch the app
In VS Code, press F5 to launch the app. Navigate to http://localhost:5000/api/todo (the Todo controller we
created).


{
app.UseMvc();
}
markup:
<!DOCTYPE html>
<html>
<head>
<style>
cursor: pointer;
}
#spoiler {
display: none;
}
table {
border: 1px solid;
}
th {
color: white;
}
td {
border: 1px solid;
padding: 5px;
}
</style>
</head>
<body>
<h1>To-do CRUD</h1>
<h3>Add</h3>
</form>
<div id="spoiler">
<h3>Edit</h3>
</form>
</div>
<table>
<tr>
<th>Name</th>
<th></th>
<th></th>
</tr>
</table>
</body>
</html>

let todos = null;
let name = 'to-do';
if (data) {
if (data > 1) {
name = 'to-dos';
}
} else {
}
}
getData();
});
$.ajax({
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}
const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
alert('here');
},
getData();
}
});
}
$.ajax({
type: 'DELETE',
getData();
}
});
}
}
});
}
const item = {
};
};
$.ajax({
type: 'PUT',
getData();
}
});
closeInput();
return false;
});
}
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}
Add a to -do item
const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
alert('here');
},
getData();
}
});
}

$.ajax({
type: 'PUT',
getData();
}
});

$.ajax({
type: 'DELETE',
getData();
}
});
Create
[HttpPost]
{
if (item == null)
{
}

}
[HttpPost]
{

}
Adds a Location header to the response. The Location header specifies the URI of the newly created to-do item.
See 10.2.2 201 Created.

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}
{
if (item == null)
{
return NotFound();
}
return item;
}

Start the app.
Open Postman.

Click the Body tab.
{
"name":"walk dog",
"isComplete":true
}
TIP
Update
[HttpPut("{id}")]
{
{
}

if (todo == null)
{
return NotFound();
}
return NoContent();
}
[HttpPut("{id}")]
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}
Delete
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}

Visual Studio Code help
Getting started
Debugging
Integrated terminal
Keyboard shortcuts
macOS keyboard shortcuts
Linux keyboard shortcuts
Windows keyboard shortcuts
Next steps
Studio for Mac

In this tutorial, build a web API for managing a list of "to-do" items. The UI isn't constructed.
macOS: Web API with Visual Studio for Mac (This tutorial)
Overview
controller.
See Introduction to ASP.NET Core MVC on macOS or Linux for an example that uses a persistent database.
Prerequisites
Create the project

From Visual Studio, select File > New Solution.
Select .NET Core App > ASP.NET Core Web API > Next.
Enter TodoApi for the Project Name, and then click Create.
Launch the app

In Visual Studio, select Run > Start With Debugging to launch the app. Visual Studio launches a browser and
navigates to http://localhost:5000 . You get an HTTP 404 (Not Found) error. Change the URL to
http://localhost:<port>/api/values . The ValuesController data is displayed:
["value1","value2"]

Install the Entity Framework Core InMemory database provider. This database provider allows Entity Framework
Core to be used with an in-memory database.
From the Project menu, select Add NuGet Packages.
Alternatively, you can right-click Dependencies, and then select Add Packages.
Enter EntityFrameworkCore.InMemory in the search box.
Select Microsoft.EntityFrameworkCore.InMemory , and then select Add Package.
Add a model class
NOTE
You can put model classes anywhere in your project, but the Models folder is used by convention.
Right-click the Models folder, and select Add > New File > General > Empty Class. Name the class TodoItem,
and then click New.
Replace the generated code with:
{
{
}
}

The database context is the main class that coordinates Entity Framework functionality for a given data model. You
create this class by deriving from the Microsoft.EntityFrameworkCore.DbContext class.
Add a TodoContext class to the Models folder.
{
{
: base(options)
{
}

}
}

namespace TodoApi
{
{
{
services.AddMvc()
}

{
app.UseMvc();
}
}
}
namespace TodoApi
{
{
{
services.AddMvc();
}

{
app.UseMvc();
}
}
}
The preceding code:

Add a controller
In Solution Explorer, in the Controllers folder, add the class TodoController .
Replace the generated code with the following:
using System.Linq;
{
{

{
_context = context;
{
}
}
}
}
implement the API.
using System.Linq;
{
[ApiController]
{

{
_context = context;
{
}
}
}
}
The preceding code:

Get to-do items

[HttpGet]
{
}

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}
[HttpGet]
{
}

{
if (item == null)
{
return NotFound();
}
return item;
}

GET /api/todo
GET /api/todo/{id}
[
{
"id": 1,
"name": "Item1",
"isComplete": false
}
]
{
{
{
[ApiController]
{

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}

{
if (item == null)
{
return NotFound();
}
return item;
}

Return values
response.
response.
response.
Launch the app
navigates to http://localhost:<port> , where <port> is a randomly chosen port number. You get an HTTP 404
(Not Found) error. Change the URL to http://localhost:<port>/api/values . The ValuesController data is
displayed:
["value1","value2"]
Navigate to the Todo controller at http://localhost:<port>/api/todo . The following JSON is returned:
[{"key":1,"name":"Item1","isComplete":false}]

We'll add Create , Update , and Delete methods to the controller. These methods are variations on a theme, so I'll
just show the code and highlight the main differences. Build the project after adding or changing code.
Create
[HttpPost]
{
if (item == null)
{
}

}
The preceding method responds to an HTTP POST, as indicated by the [HttpPost] attribute. The [FromBody]
attribute tells MVC to get the value of the to-do item from the body of the HTTP request.
[HttpPost]
{

}
The preceding method responds to an HTTP POST, as indicated by the [HttpPost] attribute. MVC gets the value of
the to-do item from the body of the HTTP request.
The CreatedAtRoute method returns a 201 response. It's the standard response for an HTTP POST method that
creates a new resource on the server. CreatedAtRoute also adds a Location header to the response. The Location
header specifies the URI of the newly created to-do item. See 10.2.2 201 Created.
Start the app (Run > Start With Debugging).
Open Postman.

Click the Body tab.
{
"name":"walk dog",
"isComplete":true
}
TIP
You can use the Location header URI to access the resource you created. The Create method returns
CreatedAtRoute. The first parameter passed to CreatedAtRoute represents the named route to use for generating
the URL. Recall that the GetById method created the "GetTodo" named route:

Update
[HttpPut("{id}")]
{
{
}

if (todo == null)
{
return NotFound();
}
return NoContent();
}
[HttpPut("{id}")]
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}
Update is similar to Create , but uses HTTP PUT. The response is 204 (No Content). According to the HTTP spec, a
PUT request requires the client to send the entire updated entity, not just the deltas. To support partial updates, use
HTTP PATCH.
{
"key": 1,
"name": "walk dog",
"isComplete": true
}
Delete
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}
The response is 204 (No Content).


{
app.UseMvc();
}
markup:
<!DOCTYPE html>
<html>
<head>
<style>
cursor: pointer;
}
#spoiler {
display: none;
}
table {
border: 1px solid;
}
th {
color: white;
}
td {
border: 1px solid;
padding: 5px;
}
</style>
</head>
<body>
<h1>To-do CRUD</h1>
<h3>Add</h3>
</form>
<div id="spoiler">
<h3>Edit</h3>
</form>
</div>
<table>
<tr>
<th>Name</th>
<th></th>
<th></th>
</tr>
</table>
</body>
</html>

let todos = null;
let name = 'to-do';
if (data) {
if (data > 1) {
if (data > 1) {
name = 'to-dos';
}
} else {
}
}
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}
const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
alert('here');
},
getData();
}
});
}
$.ajax({
type: 'DELETE',
getData();
}
});
}
}
});
}
const item = {
};
$.ajax({
type: 'PUT',
getData();
}
});
closeInput();
return false;
});
}
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}
Add a to -do item

const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
alert('here');
},
getData();
}
});
}

$.ajax({
type: 'PUT',
getData();
}
});

$.ajax({
type: 'DELETE',
getData();
}
});
Next steps
Studio

This tutorial builds a web API for managing a list of "to-do" items. A user interface (UI) isn't created.
Windows: Web API with Visual Studio on Windows (This tutorial)
Overview
The client is whatever consumes the web API (mobile app, browser, etc.). This tutorial doesn't create a
client. Postman or curl is used as the client to test the app.
A model is an object that represents the data in the app. In this case, the only model is a to-do item.
Models are represented as C# classes, also known as Plain Old CLR Object (POCOs).
controller.
To keep the tutorial simple, the app doesn't use a persistent database. The sample app stores to-do items
in an in-memory database.
Prerequisites
Create the project

Follow these steps in Visual Studio:
Select the ASP.NET Core Web Application template. Name the project TodoApi and click OK.
In the New ASP.NET Core Web Application - TodoApi dialog, choose the ASP.NET Core version. Select
the API template and click OK. Do not select Enable Docker Support.
Launch the app
http://localhost:<port>/api/values , where <port> is a randomly chosen port number. Chrome, Microsoft Edge,
and Firefox display the following output:
["value1","value2"]
If using Internet Explorer, you'll be prompted to save a values.json file.

Add a model class
A model is an object representing the data in the app. In this case, the only model is a to-do item.
NOTE
The model classes can go anywhere in the project. The Models folder is used by convention for model classes.
In Solution Explorer, right-click the Models folder and select Add > Class. Name the class TodoItem and click
Add.
Update the TodoItem class with the following code:
{
{
}
}

The database context is the main class that coordinates Entity Framework functionality for a given data model.
This class is created by deriving from the Microsoft.EntityFrameworkCore.DbContext class.
In Solution Explorer, right-click the Models folder and select Add > Class. Name the class TodoContext and click
Add.
{
{
: base(options)
{
}

}
}

Register the DB context with the service container using the built-in support for dependency injection. Replace
the contents of the Startup.cs file with the following code:
namespace TodoApi
{
{
{
services.AddMvc()
}

{
app.UseMvc();
}
}
}
namespace TodoApi
{
{
{
services.AddMvc();
}

{
app.UseMvc();
}
}
}
The preceding code:

Add a controller
In Solution Explorer, right-click the Controllers folder. Select Add > New Item. In the Add New Item dialog,
select the API Controller Class template. Name the class TodoController, and click Add.
using System.Linq;
{
{

{
_context = context;
{
}
}
}
}
implement the API.
using System.Linq;
{
[ApiController]
{

{
_context = context;
{
}
}
}
}
The preceding code:

Get to-do items

[HttpGet]
{
}

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}
[HttpGet]
{
}

{
if (item == null)
{
return NotFound();
}
return item;
}

GET /api/todo
GET /api/todo/{id}
[
{
"id": 1,
"name": "Item1",
"isComplete": false
}
]
The [HttpGet] attribute denotes a method that responds to an HTTP GET request. The URL path for each
method is constructed as follows:
{
{
{
[ApiController]
{
Replace [controller] with the name of the controller, which is the controller class name minus the
"Controller" suffix. For this sample, the controller class name is TodoController and the root name is "todo".
ASP.NET Core routing is case insensitive.

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}

{
if (item == null)
{
return NotFound();
}
return item;
}

Return values
The GetAll method returns a collection of TodoItem objects. MVC automatically serializes the object to JSON
and writes the JSON into the body of the response message. The response code for this method is 200,
assuming there are no unhandled exceptions. Unhandled exceptions are translated into 5xx errors.
If no item matches the requested ID, the method returns a 404 error. Returning NotFound returns an HTTP
404 response.
Otherwise, the method returns 200 with a JSON response body. Returning Ok results in an HTTP 200
response.
In contrast, the GetById method returns the ActionResult<T> type, which represents a wide range of return
types. GetById has two different return types:
404 response.
response.
Launch the app
http://localhost:<port>/api/values , where <port> is a randomly chosen port number. Navigate to the Todo
controller at http://localhost:<port>/api/todo .

Create
[HttpPost]
{
if (item == null)
{
}

}
[HttpPost]
{

}
Adds a Location header to the response. The Location header specifies the URI of the newly created to-do
item. See 10.2.2 201 Created.

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}

{
if (item == null)
{
return NotFound();
}
return item;
}

Start the app.
Open Postman.
Click the Body tab.
{
"name":"walk dog",
"isComplete":true
}
TIP
Update
[HttpPut("{id}")]
{
{
}

if (todo == null)
{
return NotFound();
}
return NoContent();
}
[HttpPut("{id}")]
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}
Delete
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}


UseStaticFiles and UseDefaultFiles extension methods in Startup.Configure. For more information, see Static
files.
{
app.UseMvc();
}
markup:
<!DOCTYPE html>
<html>
<head>
<style>
cursor: pointer;
}
#spoiler {
display: none;
}
table {
border: 1px solid;
}
th {
color: white;
}
td {
border: 1px solid;
padding: 5px;
}
</style>
</head>
<body>
<h1>To-do CRUD</h1>
<h3>Add</h3>
</form>
<div id="spoiler">
<h3>Edit</h3>
</form>
</div>
<table>
<tr>
<th>Name</th>
<th>Name</th>
<th></th>
<th></th>
</tr>
</table>
</body>
</html>
Add a JavaScript file, named site.js, to the project's wwwroot directory. Replace its contents with the following
code:

let todos = null;
let name = 'to-do';
if (data) {
if (data > 1) {
name = 'to-dos';
}
} else {
}
}
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}
const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
url: uri,
alert('here');
},
getData();
}
});
}
$.ajax({
type: 'DELETE',
getData();
}
});
}
}
});
}
const item = {
};
$.ajax({
type: 'PUT',
getData();
}
});
closeInput();
return false;
});
}
This function can handle all forms of HTTP interaction, sending an HTTP request to the specified url . GET is
used as the type . The success callback function is invoked if the request succeeds. In the callback, the DOM is
updated with the to-do information.
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}
Add a to -do item

The ajax function is using POST to call the API. For POST and PUT requests, the request body represents the
data sent to the API. The API is expecting a JSON request body. The accepts and contentType options are set to
application/json to classify the media type being received and sent, respectively. The data is converted to a
JSON object using JSON.stringify . When the API returns a successful status code, the getData function is
invoked to update the HTML table.
const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
alert('here');
},
getData();
}
});
}

between the two in this case is that the url changes to add the unique identifier of the item, and the type is
PUT .
$.ajax({
type: 'PUT',
getData();
}
});

$.ajax({
type: 'DELETE',
getData();
}
});
Next steps
Create backend services for native mobile apps with
ASP.NET Core
By Steve Smith
Mobile apps can easily communicate with ASP.NET Core backend services.
View or download sample backend services code
The Sample Native Mobile App

This tutorial demonstrates how to create backend services using ASP.NET Core MVC to support native mobile
apps. It uses the Xamarin Forms ToDoRest app as its native client, which includes separate native clients for
Android, iOS, Windows Universal, and Window Phone devices. You can follow the linked tutorial to create the
native app (and install the necessary free Xamarin tools), as well as download the Xamarin sample solution. The
Xamarin sample includes an ASP.NET Web API 2 services project, which this article's ASP.NET Core app replaces
(with no changes required by the client).
Features
The ToDoRest app supports listing, adding, deleting, and updating To-Do items. Each item has an ID, a Name,
Notes, and a property indicating whether it's been Done yet.
The main view of the items, as shown above, lists each item's name and indicates if it's done with a checkmark.
Tapping the + icon opens an add item dialog:
Tapping an item on the main list screen opens up an edit dialog where the item's Name, Notes, and Done settings
can be modified, or the item can be deleted:
This sample is configured by default to use backend services hosted at developer.xamarin.com, which allow read-
only operations. To test it out yourself against the ASP.NET Core app created in the next section running on your
computer, you'll need to update the app's RestUrl constant. Navigate to the ToDoREST project and open the
Constants.cs file. Replace the RestUrl with a URL that includes your machine's IP address (not localhost or
127.0.0.1, since this address is used from the device emulator, not from your machine). Include the port number as
well (5000). In order to test that your services work with a device, ensure you don't have an active firewall blocking
access to this port.
// URL of REST service (Xamarin ReadOnly Service)

//public static string RestUrl = "http://developer.xamarin.com:8081/api/todoitems{0}";
// use your machine's IP address

public static string RestUrl = "http://192.168.1.207:5000/api/todoitems/{0}";
Creating the ASP.NET Core Project

Create a new ASP.NET Core Web Application in Visual Studio. Choose the Web API template and No
Authentication. Name the project ToDoApi.
The application should respond to all requests made to port 5000. Update Program.cs to include
.UseUrls("http://*:5000") to achieve this:
var host = new WebHostBuilder()

.UseKestrel()
.UseUrls("http://*:5000")
.UseContentRoot(Directory.GetCurrentDirectory())
.UseIISIntegration()
.Build();
NOTE
Make sure you run the application directly, rather than behind IIS Express, which ignores non-local requests by default. Run
dotnet run from a command prompt, or choose the application name profile from the Debug Target dropdown in the Visual
Studio toolbar.
Add a model class to represent To-Do items. Mark required fields using the [Required] attribute:
namespace ToDoApi.Models
{
public class ToDoItem
{
[Required]
public string ID { get; set; }
[Required]
[Required]
public string Notes { get; set; }
public bool Done { get; set; }

}
}
The API methods require some way to work with data. Use the same IToDoRepository interface the original
Xamarin sample uses:
using ToDoApi.Models;
namespace ToDoApi.Interfaces
{
public interface IToDoRepository
{
bool DoesItemExist(string id);
IEnumerable<ToDoItem> All { get; }
ToDoItem Find(string id);
void Insert(ToDoItem item);
void Update(ToDoItem item);
void Delete(string id);
}
}
For this sample, the implementation just uses a private collection of items:
using System.Linq;
using ToDoApi.Interfaces;
namespace ToDoApi.Services
{
public class ToDoRepository : IToDoRepository
{
private List<ToDoItem> _toDoList;
public ToDoRepository()
{
InitializeData();
}
public IEnumerable<ToDoItem> All

{
get { return _toDoList; }
}
public bool DoesItemExist(string id)

{
return _toDoList.Any(item => item.ID == id);
}
public ToDoItem Find(string id)

{
return _toDoList.FirstOrDefault(item => item.ID == id);
}
public void Insert(ToDoItem item)

{
_toDoList.Add(item);
}
public void Update(ToDoItem item)

{
var todoItem = this.Find(item.ID);
var index = _toDoList.IndexOf(todoItem);
_toDoList.RemoveAt(index);
_toDoList.Insert(index, item);
}
public void Delete(string id)

{
_toDoList.Remove(this.Find(id));
}
private void InitializeData()

{
_toDoList = new List<ToDoItem>();
var todoItem1 = new ToDoItem

{
ID = "6bb8a868-dba1-4f1a-93b7-24ebce87e243",
Name = "Learn app development",
Notes = "Attend Xamarin University",
Done = true
};

{
ID = "b94afb54-a1cb-4313-8af3-b7511551b33b",
Name = "Develop apps",
Notes = "Use Xamarin Studio/Visual Studio",
Done = false
};

{
ID = "ecfa6f80-3671-4911-aabe-63cc442c1ecf",
Name = "Publish apps",
Notes = "All app stores",
Done = false,
};
_toDoList.Add(todoItem1);
}
}
}
Configure the implementation in Startup.cs:

{
services.AddMvc();
services.AddSingleton<IToDoRepository,ToDoRepository>();
}
At this point, you're ready to create the ToDoItemsController.
TIP
Learn more about creating web APIs in Build your first Web API with ASP.NET Core MVC and Visual Studio.
Creating the Controller

Add a new controller to the project, ToDoItemsController. It should inherit from
Microsoft.AspNetCore.Mvc.Controller. Add a Route attribute to indicate that the controller will handle requests
made to paths starting with api/todoitems . The [controller] token in the route is replaced by the name of the
controller (omitting the Controller suffix), and is especially helpful for global routes. Learn more about routing.
The controller requires an IToDoRepository to function; request an instance of this type through the controller's
constructor. At runtime, this instance will be provided using the framework's support for dependency injection.
using System;
namespace ToDoApi.Controllers
{
public class ToDoItemsController : Controller
{
private readonly IToDoRepository _toDoRepository;
public ToDoItemsController(IToDoRepository toDoRepository)

{
_toDoRepository = toDoRepository;
}
This API supports four different HTTP verbs to perform CRUD (Create, Read, Update, Delete) operations on the
data source. The simplest of these is the Read operation, which corresponds to an HTTP GET request.
Reading Items
Requesting a list of items is done with a GET request to the List method. The [HttpGet] attribute on the List
method indicates that this action should only handle GET requests. The route for this action is the route specified
on the controller. You don't necessarily need to use the action name as part of the route. You just need to ensure
each action has a unique and unambiguous route. Routing attributes can be applied at both the controller and
method levels to build up specific routes.
[HttpGet]
public IActionResult List()
{
return Ok(_toDoRepository.All);
}
The List method returns a 200 OK response code and all of the ToDo items, serialized as JSON.
You can test your new API method using a variety of tools, such as Postman, shown here:
Creating Items
By convention, creating new data items is mapped to the HTTP POST verb. The Create method has an
[HttpPost] attribute applied to it, and accepts a ToDoItem instance. Since the item argument will be passed in the
body of the POST, this parameter is decorated with the [FromBody] attribute.
Inside the method, the item is checked for validity and prior existence in the data store, and if no issues occur, it's
added using the repository. Checking ModelState.IsValid performs model validation, and should be done in every
API method that accepts user input.
[HttpPost]
public IActionResult Create([FromBody] ToDoItem item)
{
try
{
if (item == null || !ModelState.IsValid)
{
return BadRequest(ErrorCode.TodoItemNameAndNotesRequired.ToString());
}
bool itemExists = _toDoRepository.DoesItemExist(item.ID);
if (itemExists)
{
return StatusCode(StatusCodes.Status409Conflict, ErrorCode.TodoItemIDInUse.ToString());
}
_toDoRepository.Insert(item);
}
catch (Exception)
{
return BadRequest(ErrorCode.CouldNotCreateItem.ToString());
}
return Ok(item);
}
The sample uses an enum containing error codes that are passed to the mobile client:
public enum ErrorCode

{
TodoItemNameAndNotesRequired,
TodoItemIDInUse,
RecordNotFound,
CouldNotCreateItem,
CouldNotUpdateItem,
CouldNotDeleteItem
}
Test adding new items using Postman by choosing the POST verb providing the new object in JSON format in the
Body of the request. You should also add a request header specifying a Content-Type of application/json .
The method returns the newly created item in the response.
Updating Items
Modifying records is done using HTTP PUT requests. Other than this change, the Edit method is almost identical
to Create . Note that if the record isn't found, the Edit action will return a NotFound (404) response.
[HttpPut]
public IActionResult Edit([FromBody] ToDoItem item)
{
try
{
{
}
var existingItem = _toDoRepository.Find(item.ID);
if (existingItem == null)
{
return NotFound(ErrorCode.RecordNotFound.ToString());
}
_toDoRepository.Update(item);
}
catch (Exception)
{
return BadRequest(ErrorCode.CouldNotUpdateItem.ToString());
}
return NoContent();
}
To test with Postman, change the verb to PUT. Specify the updated object data in the Body of the request.
This method returns a NoContent (204) response when successful, for consistency with the pre-existing API.
Deleting Items
Deleting records is accomplished by making DELETE requests to the service, and passing the ID of the item to be
deleted. As with updates, requests for items that don't exist will receive NotFound responses. Otherwise, a
successful request will get a NoContent (204) response.
public IActionResult Delete(string id)
{
try
{
var item = _toDoRepository.Find(id);
if (item == null)
{
}
_toDoRepository.Delete(id);
}
catch (Exception)
{
return BadRequest(ErrorCode.CouldNotDeleteItem.ToString());
}
return NoContent();
}
Note that when testing the delete functionality, nothing is required in the Body of the request.
Common Web API Conventions

As you develop the backend services for your app, you will want to come up with a consistent set of conventions or
policies for handling cross-cutting concerns. For example, in the service shown above, requests for specific records
that weren't found received a NotFound response, rather than a BadRequest response. Similarly, commands made
to this service that passed in model bound types always checked ModelState.IsValid and returned a BadRequest
for invalid model types.
Once you've identified a common policy for your APIs, you can usually encapsulate it in a filter. Learn more about
how to encapsulate common API policies in ASP.NET Core MVC applications.
Authentication and Authorization
ASP.NET Core Web API help pages with Swagger /
OpenAPI
By Christoph Nienaber and Rico Suter

When consuming a Web API, understanding its various methods can be challenging for a developer. Swagger,
also known as OpenAPI, solves the problem of generating useful documentation and help pages for Web APIs. It
provides benefits such as interactive documentation, client SDK generation, and API discoverability.
In this article, the Swashbuckle.AspNetCore and NSwag .NET Swagger implementations are showcased:
Swashbuckle.AspNetCore is an open source project for generating Swagger documents for ASP.NET
Core Web APIs.
NSwag is another open source project for generating Swagger documents and integrating Swagger UI or
ReDoc into ASP.NET Core web APIs. Additionally, NSwag offers approaches to generate C# and
TypeScript client code for your API.
What is Swagger / OpenAPI?

Swagger is a language-agnostic specification for describing REST APIs. The Swagger project was donated to the
OpenAPI Initiative, where it's now referred to as OpenAPI. Both names are used interchangeably; however,
OpenAPI is preferred. It allows both computers and humans to understand the capabilities of a service without
any direct access to the implementation (source code, network access, documentation). One goal is to minimize
the amount of work needed to connect disassociated services. Another goal is to reduce the amount of time
needed to accurately document a service.
Swagger specification (swagger.json)

The core to the Swagger flow is the Swagger specification—by default, a document named swagger.json. It's
generated by the Swagger tool chain (or third-party implementations of it) based on your service. It describes
the capabilities of your API and how to access it with HTTP. It drives the Swagger UI and is used by the tool
chain to enable discovery and client code generation. Here's an example of a Swagger specification, reduced for
brevity:
{
"swagger": "2.0",
"info": {
"version": "v1",
"title": "API V1"
},
"basePath": "/",
"paths": {
"/api/Todo": {
"get": {
"tags": [
"Todo"
],
"operationId": "ApiTodoGet",
"consumes": [],
"produces": [
"text/plain",
"application/json",
"text/json"
],
"responses": {
"200": {
"description": "Success",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/TodoItem"
}
}
}
}
},
"post": {
...
}
},
"/api/Todo/{id}": {
"get": {
...
},
"put": {
...
},
"delete": {
...
},
"definitions": {
"TodoItem": {
"type": "object",
"properties": {
"id": {
"format": "int64",
"type": "integer"
},
"name": {
"type": "string"
},
"isComplete": {
"default": false,
"type": "boolean"
}
}
}
},
"securityDefinitions": {}
}
Swagger UI
Swagger UI offers a web-based UI that provides information about the service, using the generated Swagger
specification. Both Swashbuckle and NSwag include an embedded version of Swagger UI, so that it can be
hosted in your ASP.NET Core app using a middleware registration call. The web UI looks like this:
Each public action method in your controllers can be tested from the UI. Click a method name to expand the
section. Add any necessary parameters, and click Try it out!.
NOTE
The Swagger UI version used for the screenshots is version 2. For a version 3 example, see Petstore example.
Next steps
Get started with NSwag and ASP.NET Core
By Christoph Nienaber and Rico Suter

Register the NSwag middlewares to:
Generate the Swagger specification for the implemented web API.
Serve the Swagger UI to browse and test the web API.
To use the NSwag ASP.NET Core middlewares, install the NSwag.AspNetCore NuGet package. This package
contains the middlewares to generate and serve the Swagger specification, Swagger UI (v2 and v3), and ReDoc UI.
Additionally, it's highly recommended to make use of NSwag's code generation capabilities. Choose one of the
following options to use the code generation capabilities:
Use NSwagStudio, a Windows desktop app for generating client code in C# and TypeScript for your API.
Use the NSwag.CodeGeneration.CSharp or NSwag.CodeGeneration.TypeScript NuGet packages to do code
generation inside your project.
Use NSwag from the command line.
Use the NSwag.MSBuild NuGet package.
Features
The main reason to use NSwag is the ability to not only introduce the Swagger UI and Swagger generator, but to
also make use of the flexible code generation capabilities. You don't need an existing API—you can use third-party
APIs that incorporate Swagger and let NSwag generate a client implementation. Either way, the development cycle
is expedited and you can more easily adapt to API changes.
Package installation
The NSwag NuGet package can be added with the following approaches:
Visual Studio
Visual Studio Code
.NET Core CLI
From the Package Manager Console window:
Go to View > Other Windows > Package Manager Console
Navigate to the directory in which the TodoApi.csproj file exists
Execute the following command:
Install-Package NSwag.AspNetCore
From the Manage NuGet Packages dialog:

Right-click the project in Solution Explorer > Manage NuGet Packages
Set the Package source to "nuget.org"
Enter "NSwag.AspNetCore" in the search box
Select the "NSwag.AspNetCore" package from the Browse tab and click Install
Add and configure Swagger middleware

Import the following namespaces in the Startup class:
using NJsonSchema;
using NSwag.AspNetCore;
using System.Reflection;
In the Startup.ConfigureServices method, register the required Swagger services:

{
services.AddMvc();
// Register the Swagger services

services.AddSwagger();
}
In the Startup.Configure method, enable the middleware for serving the generated Swagger specification and the
Swagger UI v3:

{
// Register the Swagger generator and the Swagger UI middlewares

app.UseSwaggerUi3WithApiExplorer(settings =>
{
settings.GeneratorSettings.DefaultPropertyNameHandling =
PropertyNameHandling.CamelCase;
});
app.UseMvc();
}
Launch the app. Navigate to http://localhost:<port>/swagger to view the Swagger UI. Navigate to
http://localhost:<port>/swagger/v1/swagger.json to view the Swagger specification.
Code generation
Via NSwagStudio
Install NSwagStudio from the official GitHub repository.
Launch NSwagStudio. Enter the swagger.json file URL in the Swagger Specification URL textbox, and click the
Create local Copy button.
Select the CSharp Client client output type. Other options include TypeScript Client and CSharp Web API
Controller. Using a Web API Controller is basically a reverse generation. It uses a specification of a service to
rebuild the service.
Click the Generate Outputs button. A complete C# client implementation of the TodoApi.NSwag project is
produced. Click the CSharp Client tab of the Outputs section to see the generated client code:
//----------------------
// <auto-generated>
// Generated using the NSwag toolchain v11.17.3.0 (NJsonSchema v9.10.46.0 (Newtonsoft.Json v9.0.0.0))
(http://NSwag.org)
// </auto-generated>
//----------------------
namespace MyNamespace
{
#pragma warning disable // Disable all warnings
[System.CodeDom.Compiler.GeneratedCode("NSwag",
"11.17.3.0 (NJsonSchema v9.10.46.0 (Newtonsoft.Json v9.0.0.0))")]
public partial class TodoClient
{
private string _baseUrl = "http://localhost:50499";
private System.Lazy<Newtonsoft.Json.JsonSerializerSettings> _settings;
public TodoClient()
{
_settings = new System.Lazy
<Newtonsoft.Json.JsonSerializerSettings>(() =>
{
var settings = new Newtonsoft.Json.JsonSerializerSettings();
UpdateJsonSerializerSettings(settings);
return settings;
});
}
public string BaseUrl

{
get { return _baseUrl; }
set { _baseUrl = value; }
}
// code omitted for brevity
TIP
The C# client code is generated based on settings defined in the Settings tab of the CSharp Client tab. Modify the settings
to perform tasks such as default namespace renaming and synchronous method generation.
Copy the generated C# code into a file in a client project (for example, a Xamarin.Forms app).
Start consuming the web API:
var todoClient = new TodoClient();
// Gets all to-dos from the API

var allTodos = await todoClient.GetAllAsync();
// Create a new TodoItem, and save it in the API

var createdTodo = await todoClient.CreateAsync(new TodoItem());
// Get a single to-do by ID

var foundTodo = await todoClient.GetByIdAsync(1);
NOTE
You can inject a base URL and/or a HTTP client into the API client. The best practice is to always reuse the HttpClient.
Other ways to generate client code

You can generate the client code in other ways, more suited to your workflow:
MSBuild
In code
T4 templates
Customize
Swagger provides options for documenting the object model to ease consumption of the web API.
API info and description
In the Startup.Configure method, a configuration action passed to the UseSwagger method adds information such
as the author, license, and description:
// Register the Swagger generator middleware

app.UseSwaggerWithApiExplorer(settings =>
{
settings.PostProcess = document =>
{
document.Info.Version = "v1";
document.Info.Title = "ToDo API";
document.Info.Description = "A simple ASP.NET Core web API";
document.Info.TermsOfService = "None";
document.Info.Contact = new NSwag.SwaggerContact
{
Name = "Shayne Boyer",
Email = string.Empty,
Url = "https://twitter.com/spboyer"
};
document.Info.License = new NSwag.SwaggerLicense
{
Name = "Use under LICX",
Url = "https://example.com/license"
};
};
});
The Swagger UI displays the version's information:

XML comments
XML comments are enabled with the following approaches:
Visual Studio
Visual Studio Code
Right-click the project in Solution Explorer and select Edit <project_name>.csproj.
Manually add the highlighted lines to the .csproj file:
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
Right-click the project in Solution Explorer and select Properties

Check the XML documentation file box under the Output section of the Build tab
Data annotations
NSwag uses Reflection, and the recommended return type for web API actions is IActionResult. Consequently,
NSwag can't infer what your action is doing and what it returns. Consider the following example:
[HttpPost]
{
if (item == null)
{
}

}
The preceding action returns IActionResult , but inside the action it's returning either CreatedAtRoute or
BadRequest. Data annotations are used to tell clients which HTTP status codes this action is known to return.
Decorate the action with the following attributes:
[ProducesResponseType(typeof(TodoItem), 201)] // Created
[ProducesResponseType(400)] // BadRequest
NSwag uses Reflection, and the recommended return type for web API actions is ActionResult<T>. Consequently,
NSwag can only infer the return type defined by T . Other possible return types in the action cannot be inferred.
Consider the following example:
[HttpPost]
public ActionResult<TodoItem> Create(TodoItem item)
{

}
The preceding action returns ActionResult<T> , but inside the action it's returning either CreatedAtRoute. Since the
controller is decorated with the [ApiController] attribute, a BadRequest response is possible too. See Automatic
HTTP 400 responses for more info. Data annotations are used to tell clients which HTTP status codes this action is
known to return. Decorate the action with the following attributes:
[ProducesResponseType(201)] // Created
[ProducesResponseType(400)] // BadRequest
The Swagger generator can now accurately describe this action, and generated clients know what they receive
when calling the endpoint. Decorating all actions with these attributes is highly recommended. For guidelines on
what HTTP responses your API actions should return, see the RFC 7231 specification.
Get started with Swashbuckle and ASP.NET Core
By Shayne Boyer and Scott Addie

There are three main components to Swashbuckle:
Swashbuckle.AspNetCore.Swagger: a Swagger object model and middleware to expose SwaggerDocument
objects as JSON endpoints.
Swashbuckle.AspNetCore.SwaggerGen: a Swagger generator that builds SwaggerDocument objects directly
from your routes, controllers, and models. It's typically combined with the Swagger endpoint middleware to
automatically expose Swagger JSON.
Swashbuckle.AspNetCore.SwaggerUI: an embedded version of the Swagger UI tool. It interprets Swagger
JSON to build a rich, customizable experience for describing the Web API functionality. It includes built-in
test harnesses for the public methods.
Swashbuckle can be added with the following approaches:
Visual Studio
Visual Studio Code
.NET Core CLI
From the Package Manager Console window:
Go to View > Other Windows > Package Manager Console
Navigate to the directory in which the TodoApi.csproj file exists
Execute the following command:
Install-Package Swashbuckle.AspNetCore
From the Manage NuGet Packages dialog:

Right-click the project in Solution Explorer > Manage NuGet Packages
Set the Package source to "nuget.org"
Enter "Swashbuckle.AspNetCore" in the search box
Select the "Swashbuckle.AspNetCore" package from the Browse tab and click Install
Add and configure Swagger middleware

Add the Swagger generator to the services collection in the Startup.ConfigureServices method:
{
services.AddMvc();
// Register the Swagger generator, defining 1 or more Swagger documents

services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});
}

{
services.AddMvc()

{
c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});
}
Import the following namespace to use the Info class:
using Swashbuckle.AspNetCore.Swagger;
In the Startup.Configure method, enable the middleware for serving the generated JSON document and the
Swagger UI:

{
// Enable middleware to serve generated Swagger as a JSON endpoint.
app.UseSwagger();
// Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),

// specifying the Swagger JSON endpoint.
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
app.UseMvc();
}
The preceding UseSwaggerUI method call enables the Static Files Middleware. If targeting .NET Framework or
.NET Core 1.x, add the Microsoft.AspNetCore.StaticFiles NuGet package to the project.
Launch the app, and navigate to http://localhost:<port>/swagger/v1/swagger.json . The generated document
describing the endpoints appears as shown in Swagger specification (swagger.json).
The Swagger UI can be found at http://localhost:<port>/swagger . Explore the API via Swagger UI and
incorporate it in other programs.
TIP
To serve the Swagger UI at the app's root ( http://localhost:<port>/ ), set the RoutePrefix property to an empty
string:
{
c.RoutePrefix = string.Empty;
});
Customize and extend

Swagger provides options for documenting the object model and customizing the UI to match your theme.
API info and description
The configuration action passed to the AddSwaggerGen method adds information such as the author, license, and
description:

{
c.SwaggerDoc("v1", new Info
{
Version = "v1",
Title = "ToDo API",
Description = "A simple example ASP.NET Core Web API",
TermsOfService = "None",
Contact = new Contact
{
},
License = new License
{
}
});
});
The Swagger UI displays the version's information:

XML comments
XML comments can be enabled with the following approaches:
Visual Studio
Visual Studio Code
Right-click the project in Solution Explorer and select Edit <project_name>.csproj.
Manually add the highlighted lines to the .csproj file:
<PropertyGroup>
</PropertyGroup>
Right-click the project in Solution Explorer and select Properties.

Check the XML documentation file box under the Output section of the Build tab.
Enabling XML comments provides debug information for undocumented public types and members.
Undocumented types and members are indicated by the warning message. For example, the following message
indicates a violation of warning code 1591:
warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'
To suppress warnings project-wide, define a semicolon-delimited list of warning codes to ignore in the project file.
Appending the warning codes to $(NoWarn); applies the C# default values too.
<PropertyGroup>
</PropertyGroup>
<PropertyGroup>
<DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
</PropertyGroup>
To suppress warnings only for specific members, enclose the code in #pragma warning preprocessor directives.
This approach is useful for code that shouldn't be exposed via the API docs. In the following example, warning
code CS1591 is ignored for the entire Program class. Enforcement of the warning code is restored at the close of
the class definition. Specify multiple warning codes with a comma-delimited list.
namespace TodoApi
{
#pragma warning disable CS1591
{
public static void Main(string[] args) =>
BuildWebHost(args).Run();

.Build();
}
#pragma warning restore CS1591
}
Configure Swagger to use the generated XML file. For Linux or non-Windows operating systems, file names and
paths can be case-sensitive. For example, a TodoApi.XML file is valid on Windows but not CentOS.

{
services.AddMvc()

{
{
Version = "v1",
Title = "ToDo API",
{
},
{
}
});
// Set the comments path for the Swagger JSON and UI.
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
});
}
{
services.AddMvc();

{
{
Version = "v1",
Title = "ToDo API",
{
},
{
}
});
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
});
}
{
services.AddMvc();

{
{
Version = "v1",
Title = "ToDo API",
{
},
{
}
});
var xmlFile = $"{Assembly.GetEntryAssembly().GetName().Name}.xml";
});
}
In the preceding code, Reflection is used to build an XML file name matching that of the Web API project. The
AppContext.BaseDirectory property is used to construct a path to the XML file.
Adding triple-slash comments to an action enhances the Swagger UI by adding the description to the section
header. Add a <summary> element above the Delete action:
/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
/// <param name="id"></param>
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}
The Swagger UI displays the inner text of the preceding code's <summary> element:
The UI is driven by the generated JSON schema:
"delete": {
"tags": [
"Todo"
],
"summary": "Deletes a specific TodoItem.",
"operationId": "ApiTodoByIdDelete",
"consumes": [],
"produces": [],
"parameters": [
{
"name": "id",
"in": "path",
"description": "",
"required": true,
"type": "integer",
"format": "int64"
}
],
"responses": {
"200": {
"description": "Success"
}
}
}
Add a <remarks> element to the Create action method documentation. It supplements information specified in
the <summary> element and provides a more robust Swagger UI. The <remarks> element content can consist of
text, JSON, or XML.
/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
/// POST /Todo
/// {
/// "id": 1,
/// "name": "Item1",
/// "isComplete": true
/// }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(typeof(TodoItem), 201)]
{
if (item == null)
{
}

}
/// <summary>
/// </summary>
/// <remarks>
/// Sample request:
///
/// POST /Todo
/// {
/// "id": 1,
/// }
///
/// </remarks>
[HttpPost]
{

}
Notice the UI enhancements with these additional comments:

Data annotations
Decorate the model with attributes, found in the System.ComponentModel.DataAnnotations namespace, to help
drive the Swagger UI components.
Add the [Required] attribute to the Name property of the TodoItem class:
using System.ComponentModel;
{
{
[Required]
[DefaultValue(false)]
}
}
The presence of this attribute changes the UI behavior and alters the underlying JSON schema:
"definitions": {
"TodoItem": {
"required": [
"name"
],
"type": "object",
"properties": {
"id": {
"format": "int64",
"type": "integer"
},
"name": {
"type": "string"
},
"isComplete": {
"default": false,
"type": "boolean"
}
}
}
},
Add the [Produces("application/json")] attribute to the API controller. Its purpose is to declare that the
controller's actions support a response content type of application/json:
{
[ApiController]
{
The Response Content Type drop-down selects this content type as the default for the controller's GET actions:
As the usage of data annotations in the Web API increases, the UI and API help pages become more descriptive
and useful.
Describe response types
Consuming developers are most concerned with what's returned—specifically response types and error codes (if
not standard). The response types and error codes are denoted in the XML comments and data annotations.
The Create action returns an HTTP 201 status code on success. An HTTP 400 status code is returned when the
posted request body is null. Without proper documentation in the Swagger UI, the consumer lacks knowledge of
these expected outcomes. Fix that problem by adding the highlighted lines in the following example:
/// <summary>
/// </summary>
/// <remarks>
/// Sample request:
///
/// POST /Todo
/// {
/// "id": 1,
/// }
///
/// </remarks>
[HttpPost]
[ProducesResponseType(typeof(TodoItem), 201)]
{
if (item == null)
{
}

}
/// <summary>
/// </summary>
/// <remarks>
/// Sample request:
///
/// POST /Todo
/// {
/// "id": 1,
/// }
///
/// </remarks>
[HttpPost]
{

}
The Swagger UI now clearly documents the expected HTTP response codes:
Customize the UI
The stock UI is both functional and presentable. However, API documentation pages should represent your brand
or theme. Branding the Swashbuckle components requires adding the resources to serve static files and building
the folder structure to host those files.
If targeting .NET Framework or .NET Core 1.x, add the Microsoft.AspNetCore.StaticFiles NuGet package to the
project:
<PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.0.0" />
The preceding NuGet package is already installed if targeting .NET Core 2.x and using the metapackage.
Enable the static files middleware:

{
// Enable middleware to serve generated Swagger as a JSON endpoint.

app.UseSwagger();
// Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),

// specifying the Swagger JSON endpoint.
{
});
app.UseMvc();
}
Acquire the contents of the dist folder from the Swagger UI GitHub repository. This folder contains the necessary
assets for the Swagger UI page.
Create a wwwroot/swagger/ui folder, and copy into it the contents of the dist folder.
Create a custom.css file, in wwwroot/swagger/ui, with the following CSS to customize the page header:
.swagger-ui .topbar {
background-color: #000;
border-bottom: 3px solid #547f00;
}
Reference custom.css in the index.html file, after any other CSS files:
<link href="https://fonts.googleapis.com/css?
family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700" rel="stylesheet">
<link rel="stylesheet" type="text/css" href="./swagger-ui.css">
<link rel="stylesheet" type="text/css" href="custom.css">
Browse to the index.html page at http://localhost:<port>/swagger/ui/index.html . Enter

http://localhost:<port>/swagger/v1/swagger.json in the header's textbox, and click the Explore button. The
resulting page looks as follows:
There's much more you can do with the page. See the full capabilities for the UI resources at the Swagger UI
GitHub repository.
Get started with Razor Pages and Entity Framework Core using Visual Studio
Get started with Razor Pages and EF
Migrations
Read related data
Update related data
Get started with ASP.NET Core MVC and Entity Framework Core using Visual Studio
Get started
Migrations
Read related data
Update related data
Inheritance
Advanced topics
ASP.NET Core with EF Core - new database (Entity Framework Core documentation site)
ASP.NET Core with EF Core - existing database (Entity Framework Core documentation site)
Azure Storage
Get started with Azure Blob storage and Visual Studio Connected Services
Get started with Queue Storage and Visual Studio Connected Services
Get started with Azure Table Storage and Visual Studio Connected Services
ASP.NET Core Razor Pages with EF Core - tutorial
series
This series of tutorials teaches how to create ASP.NET Core Razor Pages web apps that use Entity Framework (EF )
Core for data access.
1. Get started
2. Create, Read, Update, and Delete operations
3. Sorting, filtering, paging, and grouping
4. Migrations
5. Create a complex data model
6. Reading related data
7. Updating related data
8. Handle concurrency conflicts
Razor Pages with Entity Framework Core in ASP.NET
Core - Tutorial 1 of 8
The ASP.NET Core 2.0 version of this tutorial can be found in this PDF file.
The ASP.NET Core 2.1 version of this tutorial has many improvements over the 2.0 version.
By Tom Dykstra and Rick Anderson
The Contoso University sample web app demonstrates how to create an ASP.NET Core Razor Pages app using
Entity Framework (EF ) Core.
The sample app is a web site for a fictional Contoso University. It includes functionality such as student admission,
course creation, and instructor assignments. This page is the first in a series of tutorials that explain how to build
the Contoso University sample app.
Download or view the completed app. Download instructions.
Prerequisites
Visual Studio
.NET Core CLI
Familiarity with Razor Pages. New programmers should complete Get started with Razor Pages before starting this
series.
Troubleshooting
If you run into a problem you can't resolve, you can generally find the solution by comparing your code to the
completed project. A good way to get help is by posting a question to StackOverflow.com for ASP.NET Core or EF
Core.
The Contoso University web app

The app built in these tutorials is a basic university web site.
Users can view and update student, course, and instructor information. Here are a few of the screens created in the
tutorial.
The UI style of this site is close to what's generated by the built-in templates. The tutorial focus is on EF Core with
Razor Pages, not the UI.
Create the ContosoUniversity Razor Pages web app

Visual Studio
.NET Core CLI
Create a new ASP.NET Core Web Application. Name the project ContosoUniversity. It's important to name
the project ContosoUniversity so the namespaces match when code is copy/pasted.
For images of the preceding steps, see Create a Razor web app. Run the app.
Set up the site style

A few changes set up the site menu, layout, and home page. Update Pages/Shared/_Layout.cshtml with the
following changes:
Change each occurrence of "ContosoUniversity" to "Contoso University". There are three occurrences.
Add menu entries for Students, Courses, Instructors, and Departments, and delete the Contact menu
entry.
The changes are highlighted. (All the markup is not displayed.)
<!DOCTYPE html>
<html>
<head>
<title>@ViewData["Title"] : Contoso University</title>
<environment include="Development">
</environment>
<environment exclude="Development">
value="absolute" />
</environment>
</head>
<body>
collapse">
</button>
<a asp-page="/Index" class="navbar-brand">Contoso University</a>
</div>
<li><a asp-page="/Index">Home</a></li>
<li><a asp-page="/About">About</a></li>
<li><a asp-page="/Students/Index">Students</a></li>
<li><a asp-page="/Courses/Index">Courses</a></li>
<li><a asp-page="/Instructors/Index">Instructors</a></li>
<li><a asp-page="/Departments/Index">Departments</a></li>
</ul>
</div>
</div>
</nav>
<partial name="_CookieConsentPartial" />

@RenderBody()
<hr />
<footer>
<p>© 2018 : Contoso University</p>
</footer>
</div>
@*Remaining markup not shown for brevity.*@
In Pages/Index.cshtml, replace the contents of the file with the following code to replace the text about ASP.NET
and MVC with text about this app:
@page
@model IndexModel
@{
ViewData["Title"] = "Home page";
}
<div class="jumbotron">
<h1>Contoso University</h1>
</div>
<div class="row">
<h2>Welcome to Contoso University</h2>
<p>
Contoso University is a sample application that
demonstrates how to use Entity Framework Core in an
ASP.NET Core Razor Pages web app.
</p>
</div>
<h2>Build it from scratch</h2>
<p>You can build the application by following the steps in a series of tutorials.</p>
<p>
<a class="btn btn-default"
href="https://docs.microsoft.com/aspnet/core/data/ef-rp/intro">
See the tutorial »
</a>
</p>
</div>
<h2>Download it</h2>
<p>You can download the completed project from GitHub.</p>
<p>
href="https://github.com/aspnet/Docs/tree/master/aspnetcore/data/ef-rp/intro/samples/cu-final">
See project source code »
</a>
</p>
</div>
</div>
Create the data model

Create entity classes for the Contoso University app. Start with the following three entities:
There's a one-to-many relationship between Student and Enrollment entities. There's a one-to-many relationship
between Course and Enrollment entities. A student can enroll in any number of courses. A course can have any
number of students enrolled in it.
In the following sections, a class for each one of these entities is created.
The Student entity
Create a Models folder. In the Models folder, create a class file named Student.cs with the following code:
using System;
namespace ContosoUniversity.Models
{
public class Student
{
public string LastName { get; set; }
public string FirstMidName { get; set; }
public DateTime EnrollmentDate { get; set; }
public ICollection<Enrollment> Enrollments { get; set; }

}
}
The ID property becomes the primary key column of the database (DB ) table that corresponds to this class. By
default, EF Core interprets a property that's named ID or classnameID as the primary key. In classnameID ,
classname is the name of the class. The alternative automatically recognized primary key is StudentID in the
preceding example.
The Enrollments property is a navigation property. Navigation properties link to other entities that are related to
this entity. In this case, the Enrollments property of a Student entity holds all of the Enrollment entities that are
related to that Student . For example, if a Student row in the DB has two related Enrollment rows, the Enrollments
navigation property contains those two Enrollment entities. A related Enrollment row is a row that contains that
student's primary key value in the StudentID column. For example, suppose the student with ID=1 has two rows in
the Enrollment table. The Enrollment table has two rows with StudentID = 1. StudentID is a foreign key in the
Enrollment table that specifies the student in the Student table.
If a navigation property can hold multiple entities, the navigation property must be a list type, such as
ICollection<T> . ICollection<T> can be specified, or a type such as List<T> or HashSet<T> . When ICollection<T>
is used, EF Core creates a HashSet<T> collection by default. Navigation properties that hold multiple entities come
from many-to-many and one-to-many relationships.
The Enrollment entity
In the Models folder, create Enrollment.cs with the following code:

{
public enum Grade
{
A, B, C, D, F
}
public class Enrollment

{
public int EnrollmentID { get; set; }
public int CourseID { get; set; }
public int StudentID { get; set; }
public Grade? Grade { get; set; }
public Course Course { get; set; }

public Student Student { get; set; }
}
}
The EnrollmentIDproperty is the primary key. This entity uses the classnameID pattern instead of ID like the
Student entity. Typically developers choose one pattern and use it throughout the data model. In a later tutorial,
using ID without classname is shown to make it easier to implement inheritance in the data model.
The Grade property is an enum . The question mark after the Grade type declaration indicates that the Grade
property is nullable. A grade that's null is different from a zero grade -- null means a grade isn't known or hasn't
been assigned yet.
The StudentID property is a foreign key, and the corresponding navigation property is Student . An Enrollment
entity is associated with one Student entity, so the property contains a single Student entity. The Student entity
differs from the Student.Enrollments navigation property, which contains multiple Enrollment entities.
The CourseID property is a foreign key, and the corresponding navigation property is Course . An Enrollment
entity is associated with one Course entity.
EF Core interprets a property as a foreign key if it's named <navigation property name><primary key property name> .
For example, StudentID for the Student navigation property, since the Student entity's primary key is ID .
Foreign key properties can also be named <primary key property name> . For example, CourseID since the Course
entity's primary key is CourseID .
The Course entity
In the Models folder, create Course.cs with the following code:

{
public class Course
{
[DatabaseGenerated(DatabaseGeneratedOption.None)]
public int Credits { get; set; }

}
}
The Enrollments property is a navigation property. A Course entity can be related to any number of Enrollment
entities.
The DatabaseGenerated attribute allows the app to specify the primary key rather than having the DB generate it.
Scaffold the student model

In this section, the student model is scaffolded. That is, the scaffolding tool produces pages for Create, Read,
Update, and Delete (CRUD ) operations for the student model.
Build the project.
Create the Pages/Students folder.
Visual Studio
.NET Core CLI
In Solution Explorer, right click on the Pages/Students folder > Add > New Scaffolded Item.
In the Model class drop-down, select Student (ContosoUniversity.Models).
In the Data context class row, select the + (plus) sign and change the generated name to
ContosoUniversity.Models.SchoolContext.
In the Data context class drop-down, select ContosoUniversity.Models.SchoolContext
Select Add.
See Scaffold the movie model if you have a problem with the preceding step.
Files created
Pages/Students Create, Delete, Details, Edit, Index.
Data/SchoolContext.cs
Files updates
Startup.cs : Changes to this file in are detailed the next section.
appsettings.json : The connection string used to connect to a local database is added.

ASP.NET Core is built with dependency injection. Services (such as the EF Core DB context) are registered with
dependency injection during application startup. Components that require these services (such as Razor Pages) are
provided these services via constructor parameters. The constructor code that gets a db context instance is shown
later in the tutorial.
The scaffolding tool automatically created a DB Context and registered it with the dependency injection container.
Examine the ConfigureServices method in Startup.cs. The highlighted line was added by the scaffolder:
{
{
// This lambda determines whether user consent for
//non -essential cookies is needed for a given request.
});
services.AddDbContext<SchoolContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("SchoolContext")));
}
The name of the connection string is passed in to the context by calling a method on a DbContextOptions object.
For local development, the ASP.NET Core configuration system reads the connection string from the
Update main
Call the EnsureCreated.
Dispose the context when the EnsureCreated method completes.

using ContosoUniversity.Models; // SchoolContext
using Microsoft.Extensions.DependencyInjection; // CreateScope
using System;
namespace ContosoUniversity
{
{
{

{
try
{
var context = services.GetRequiredService<SchoolContext>();
context.Database.EnsureCreated();
}
{
logger.LogError(ex, "An error occurred creating the DB.");
}
}
host.Run();
}

}
}
EnsureCreated ensures that the database for the context exists. If it exists, no action is taken. If it does not exist, then
the database and all its schema are created. EnsureCreated does not use migrations to create the database. A
database that is created with EnsureCreated cannot be later updated using migrations.
EnsureCreated is called on app start, which allows the following work flow:
Delete the DB.
Change the DB schema (for example, add an EmailAddress field).
Run the app.
EnsureCreated creates a DB with the EmailAddress column.
EnsureCreated is convenient early in development when the schema is rapidly evolving. Later in the tutorial the DB
is deleted and migrations are used.
Test the app
Run the app and accept the cookie policy. This app doesn't keep personal information. You can read about the
cookie policy at EU General Data Protection Regulation (GDPR ) support.
Select the Students link and then Create New.
Examine the SchoolContext DB context
The main class that coordinates EF Core functionality for a given data model is the DB context class. The data
context is derived from Microsoft.EntityFrameworkCore.DbContext. The data context specifies which entities are
included in the data model. In this project, the class is named SchoolContext .
Update SchoolContext.cs with the following code:
{
public class SchoolContext : DbContext
{
public SchoolContext(DbContextOptions<SchoolContext> options)
: base(options)
{
}
public DbSet<Student> Student { get; set; }

public DbSet<Enrollment> Enrollment { get; set; }
public DbSet<Course> Course { get; set; }
}
}
The highlighted code creates a DbSet<TEntity> property for each entity set. In EF Core terminology:
An entity set typically corresponds to a DB table.
An entity corresponds to a row in the table.
DbSet<Enrollment> and DbSet<Course> could be omitted. EF Core includes them implicitly because the Student
entity references the Enrollment entity, and the Enrollment entity references the Course entity. For this tutorial,
keep DbSet<Enrollment> and DbSet<Course> in the SchoolContext .
The connection string specifies SQL Server LocalDB. LocalDB is a lightweight version of the SQL Server Express
Database Engine and is intended for app development, not production use. LocalDB starts on demand and runs in
user mode, so there's no complex configuration. By default, LocalDB creates .mdf DB files in the C:/Users/<user>
directory.
Add code to initialize the DB with test data

EF Core creates an empty DB. In this section, an Initialize method is written to populate it with test data.
In the Data folder, create a new class file named DbInitializer.cs and add the following code:
using ContosoUniversity.Models;
using System;
using System.Linq;
namespace ContosoUniversity.Data
{
public static class DbInitializer
{
public static void Initialize(SchoolContext context)
{
// context.Database.EnsureCreated();
// Look for any students.

if (context.Student.Any())
{
{
}
var students = new Student[]

{
new Student{FirstMidName="Carson",LastName="Alexander",EnrollmentDate=DateTime.Parse("2005-09-
01")},
new Student{FirstMidName="Meredith",LastName="Alonso",EnrollmentDate=DateTime.Parse("2002-09-01")},
new Student{FirstMidName="Arturo",LastName="Anand",EnrollmentDate=DateTime.Parse("2003-09-01")},
new Student{FirstMidName="Gytis",LastName="Barzdukas",EnrollmentDate=DateTime.Parse("2002-09-01")},
new Student{FirstMidName="Yan",LastName="Li",EnrollmentDate=DateTime.Parse("2002-09-01")},
new Student{FirstMidName="Peggy",LastName="Justice",EnrollmentDate=DateTime.Parse("2001-09-01")},
new Student{FirstMidName="Laura",LastName="Norman",EnrollmentDate=DateTime.Parse("2003-09-01")},
new Student{FirstMidName="Nino",LastName="Olivetto",EnrollmentDate=DateTime.Parse("2005-09-01")}
};
foreach (Student s in students)
{
context.Student.Add(s);
}
var courses = new Course[]

{
new Course{CourseID=1050,Title="Chemistry",Credits=3},
new Course{CourseID=4022,Title="Microeconomics",Credits=3},
new Course{CourseID=4041,Title="Macroeconomics",Credits=3},
new Course{CourseID=1045,Title="Calculus",Credits=4},
new Course{CourseID=3141,Title="Trigonometry",Credits=4},
new Course{CourseID=2021,Title="Composition",Credits=3},
new Course{CourseID=2042,Title="Literature",Credits=4}
};
foreach (Course c in courses)
{
context.Course.Add(c);
}
var enrollments = new Enrollment[]

{
new Enrollment{StudentID=1,CourseID=1050,Grade=Grade.A},
new Enrollment{StudentID=1,CourseID=4022,Grade=Grade.C},
new Enrollment{StudentID=1,CourseID=4041,Grade=Grade.B},
new Enrollment{StudentID=2,CourseID=3141,Grade=Grade.F},
new Enrollment{StudentID=3,CourseID=1050},
};
foreach (Enrollment e in enrollments)
{
context.Enrollment.Add(e);
}
}
}
}
The code checks if there are any students in the DB. If there are no students in the DB, the DB is initialized with test
data. It loads test data into arrays rather than List<T> collections to optimize performance.
The EnsureCreated method automatically creates the DB for the DB context. If the DB exists, EnsureCreated returns
without modifying the DB.
In Program.cs, modify the Main method to call Initialize :

{
{

{
try
{
// using ContosoUniversity.Data;
DbInitializer.Initialize(context);
}
{
}
}
host.Run();
}

}
Delete any student records and restart the app. If the DB is not initialized, set a break point in Initialize to
diagnose the problem.
View the DB
Open SQL Server Object Explorer (SSOX) from the View menu in Visual Studio. In SSOX, click
(localdb)\MSSQLLocalDB > Databases > ContosoUniversity1.
Expand the Tables node.
Right-click the Student table and click View Data to see the columns created and the rows inserted into the table.
Asynchronous code
Asynchronous programming is the default mode for ASP.NET Core and EF Core.
A web server has a limited number of threads available, and in high load situations all of the available threads
might be in use. When that happens, the server can't process new requests until the threads are freed up. With
synchronous code, many threads may be tied up while they aren't actually doing any work because they're waiting
for I/O to complete. With asynchronous code, when a process is waiting for I/O to complete, its thread is freed up
for the server to use for processing other requests. As a result, asynchronous code enables server resources to be
used more efficiently, and the server is enabled to handle more traffic without delays.
Asynchronous code does introduce a small amount of overhead at run time. For low traffic situations, the
performance hit is negligible, while for high traffic situations, the potential performance improvement is substantial.
In the following code, the async keyword, Task<T> return value, await keyword, and ToListAsync method make
the code execute asynchronously.
{
Student = await _context.Student.ToListAsync();
}
The async keyword tells the compiler to:

Generate callbacks for parts of the method body.
Automatically create the Task object that's returned. For more information, see Task Return Type.
The implicit return type Task represents ongoing work.
The await keyword causes the compiler to split the method into two parts. The first part ends with the
operation that's started asynchronously. The second part is put into a callback method that's called when the
operation completes.
ToListAsync is the asynchronous version of the ToList extension method.
Some things to be aware of when writing asynchronous code that uses EF Core:
Only statements that cause queries or commands to be sent to the DB are executed asynchronously. That
includes, ToListAsync , SingleOrDefaultAsync , FirstOrDefaultAsync , and SaveChangesAsync . It doesn't include
statements that just change an IQueryable , such as
var students = context.Students.Where(s => s.LastName == "Davolio") .
An EF Core context isn't thread safe: don't try to do multiple operations in parallel.
To take advantage of the performance benefits of async code, verify that library packages (such as for paging)
use async if they call EF Core methods that send queries to the DB.
For more information about asynchronous programming in .NET, see Async Overview and Asynchronous
programming with async and await.
In the next tutorial, basic CRUD (create, read, update, delete) operations are examined.
NEXT
Razor Pages with EF Core in ASP.NET Core - CRUD -
2 of 8
By Tom Dykstra, Jon P Smith, and Rick Anderson
The Contoso University web app demonstrates how to create Razor Pages web apps using EF Core and Visual
Studio. For information about the tutorial series, see the first tutorial.
In this tutorial, the scaffolded CRUD (create, read, update, delete) code is reviewed and customized.
To minimize complexity and keep these tutorials focused on EF Core, EF Core code is used in the page models.
Some developers use a service layer or repository pattern in to create an abstraction layer between the UI (Razor
Pages) and the data access layer.
In this tutorial, the Create, Edit, Delete, and Details Razor Pages in the Student folder are examined.
The scaffolded code uses the following pattern for Create, Edit, and Delete pages:
Get and display the requested data with the HTTP GET method OnGetAsync .
Save changes to the data with the HTTP POST method OnPostAsync .
The Index and Details pages get and display the requested data with the HTTP GET method OnGetAsync
SingleOrDefaultAsync vs FirstOrDefaultAsync
The generated code uses FirstOrDefaultAsync, which is generally preferred over SingleOrDefaultAsync.
FirstOrDefaultAsync is more efficient than SingleOrDefaultAsync at fetching one entity:
Unless the code needs to verify that there's not more than one entity returned from the query.
SingleOrDefaultAsync fetches more data and does unnecessary work.
SingleOrDefaultAsync throws an exception if there's more than one entity that fits the filter part.
FirstOrDefaultAsync doesn't throw if there's more than one entity that fits the filter part.
FindAsync
In much of the scaffolded code, FindAsync can be used in place of FirstOrDefaultAsync .
FindAsync :
Finds an entity with the primary key (PK). If an entity with the PK is being tracked by the context, it's returned
without a request to the DB.
Is simple and concise.
Is optimized to look up a single entity.
Can have perf benefits in some situations, but they rarely happens for typical web apps.
Implicitly uses FirstAsync instead of SingleAsync.
But if you want to Include other entities, then FindAsync is no longer appropriate. This means that you may
need to abandon FindAsync and move to a query as your app progresses.
Customize the Details page
Browse to Pages/Students page. The Edit, Details, and Delete links are generated by the Anchor Tag Helper in
the Pages/Students/Index.cshtml file.
<td>
</td>
Run the app and select a Details link. The URL is of the form http://localhost:5000/Students/Details?id=2 . The
Student ID is passed using a query string ( ?id=2 ).
Update the Edit, Details, and Delete Razor Pages to use the "{id:int}" route template. Change the page directive
for each of these pages from @page to @page "{id:int}" .
A request to the page with the "{id:int}" route template that does not include a integer route value returns an
HTTP 404 (not found) error. For example, http://localhost:5000/Students/Details returns a 404 error. To make
the ID optional, append ? to the route constraint:
@page "{id:int?}"
Run the app, click on a Details link, and verify the URL is passing the ID as route data (
http://localhost:5000/Students/Details/2 ).
Don't globally change @page to @page "{id:int}" , doing so breaks the links to the Home and Create pages.
Add related data
The scaffolded code for the Students Index page doesn't include the Enrollments property. In this section, the
contents of the Enrollments collection is displayed in the Details page.
The OnGetAsync method of Pages/Students/Details.cshtml.cs uses the FirstOrDefaultAsync method to retrieve a
single Student entity. Add the following highlighted code:

{
if (id == null)
{
return NotFound();
}
Student = await _context.Student

.Include(s => s.Enrollments)
.ThenInclude(e => e.Course)
.AsNoTracking()
if (Student == null)
{
return NotFound();
}
return Page();
}
The Include and ThenInclude methods cause the context to load the Student.Enrollments navigation property,
and within each enrollment the Enrollment.Course navigation property. These methods are examined in detail in
the reading-related data tutorial.
The AsNoTracking method improves performance in scenarios when the entities returned are not updated in the
current context. AsNoTracking is discussed later in this tutorial.
Display related enrollments on the Details page
Open Pages/Students/Details.cshtml. Add the following highlighted code to display a list of enrollments:
@page "{id:int}"
@model ContosoUniversity.Pages.Students.DetailsModel
@{
}
<h2>Details</h2>
<div>
<h4>Student</h4>
<hr />
<dt>
@Html.DisplayNameFor(model => model.Student.LastName)
</dt>
<dd>
@Html.DisplayFor(model => model.Student.LastName)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Student.FirstMidName)
</dt>
<dd>
@Html.DisplayFor(model => model.Student.FirstMidName)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Student.EnrollmentDate)
</dt>
<dd>
@Html.DisplayFor(model => model.Student.EnrollmentDate)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Student.Enrollments)
</dt>
<dd>
<tr>
<th>Course Title</th>
<th>Grade</th>
</tr>
@foreach (var item in Model.Student.Enrollments)
{
<tr>
<td>
@Html.DisplayFor(modelItem => item.Course.Title)
</td>
<td>
@Html.DisplayFor(modelItem => item.Grade)
</td>
</tr>
}
</table>
</dd>
</dl>
</div>
<div>
<a asp-page="./Edit" asp-route-id="@Model.Student.ID">Edit</a> |
<a asp-page="./Index">Back to List</a>
</div>
If code indentation is wrong after the code is pasted, press CTRL -K-D to correct it.
The preceding code loops through the entities in the Enrollments navigation property. For each enrollment, it
displays the course title and the grade. The course title is retrieved from the Course entity that's stored in the
Course navigation property of the Enrollments entity.
Run the app, select the Students tab, and click the Details link for a student. The list of courses and grades for the
selected student is displayed.
Update the Create page

Update the OnPostAsync method in Pages/Students/Create.cshtml.cs with the following code:

{
{
return Page();
}
var emptyStudent = new Student();
if (await TryUpdateModelAsync<Student>(
emptyStudent,
"student", // Prefix for form value.
s => s.FirstMidName, s => s.LastName, s => s.EnrollmentDate))
{
_context.Student.Add(emptyStudent);
}
return null;
}
TryUpdateModelAsync
Examine the TryUpdateModelAsync code:
var emptyStudent = new Student();
emptyStudent,
"student", // Prefix for form value.
{
In the preceding code, TryUpdateModelAsync<Student> tries to update the emptyStudent object using the posted
form values from the PageContext property in the PageModel. TryUpdateModelAsync only updates the properties
listed ( s => s.FirstMidName, s => s.LastName, s => s.EnrollmentDate ).
In the preceding sample:
The second argument ( "student", // Prefix ) is the prefix uses to look up values. It's not case sensitive.
The posted form values are converted to the types in the Student model using model binding.
Overposting
Using TryUpdateModel to update fields with posted values is a security best practice because it prevents
overposting. For example, suppose the Student entity includes a Secret property that this web page shouldn't
update or add:
{
public string Secret { get; set; }
}
Even if the app doesn't have a Secret field on the create/update Razor Page, a hacker could set the Secret value
by overposting. A hacker could use a tool such as Fiddler, or write some JavaScript, to post a Secret form value.
The original code doesn't limit the fields that the model binder uses when it creates a Student instance.
Whatever value the hacker specified for the Secret form field is updated in the DB. The following image shows
the Fiddler tool adding the Secret field (with the value "OverPost") to the posted form values.
The value "OverPost" is successfully added to the Secret property of the inserted row. The app designer never
intended the Secret property to be set with the Create page.
View model
A view model typically contains a subset of the properties included in the model used by the application. The
application model is often called the domain model. The domain model typically contains all the properties
required by the corresponding entity in the DB. The view model contains only the properties needed for the UI
layer (for example, the Create page). In addition to the view model, some apps use a binding model or input
model to pass data between the Razor Pages page model class and the browser. Consider the following Student
view model:
using System;
{
public class StudentVM
{
}
}
View models provide an alternative way to prevent overposting. The view model contains only the properties to
view (display) or update.
The following code uses the StudentVM view model to create a new student:
[BindProperty]
public StudentVM StudentVM { get; set; }

{
{
return Page();
}
var entry = _context.Add(new Student());

entry.CurrentValues.SetValues(StudentVM);
}
The SetValues method sets the values of this object by reading values from another PropertyValues object.
SetValues uses property name matching. The view model type doesn't need to be related to the model type, it
just needs to have properties that match.
Using StudentVM requires CreateVM.cshtml be updated to use StudentVM rather than Student .
In Razor Pages, the PageModel derived class is the view model.
Update the Edit page

Update the page model for the Edit page. The major changes are highlighted:
{
private readonly SchoolContext _context;
public EditModel(SchoolContext context)

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}
Student = await _context.Student.FindAsync(id);
{
return NotFound();
}
return Page();
}
public async Task<IActionResult> OnPostAsync(int? id)

{
{
return Page();
}
var studentToUpdate = await _context.Student.FindAsync(id);
studentToUpdate,
"student",
{
}
return Page();
}
}
The code changes are similar to the Create page with a few exceptions:
OnPostAsync has an optional id parameter.
The current student is fetched from the DB, rather than creating an empty student.
FirstOrDefaultAsync has been replaced with FindAsync. FindAsync is a good choice when selecting an entity
from the primary key. See FindAsync for more information.
Test the Edit and Create pages
Create and edit a few student entities.
Entity States
The DB context keeps track of whether entities in memory are in sync with their corresponding rows in the DB.
The DB context sync information determines what happens when SaveChangesAsync is called. For example,
when a new entity is passed to the AddAsync method, that entity's state is set to Added. When SaveChangesAsync
is called, the DB context issues a SQL INSERT command.
An entity may be in one of the following states:
Added : The entity doesn't yet exist in the DB. The SaveChanges method issues an INSERT statement.
Unchanged : No changes need to be saved with this entity. An entity has this status when it's read from the
DB.
: Some or all of the entity's property values have been modified. The
Modified SaveChanges method issues
an UPDATE statement.
Deleted : The entity has been marked for deletion. The SaveChanges method issues a DELETE statement.
Detached : The entity isn't being tracked by the DB context.
In a desktop app, state changes are typically set automatically. An entity is read, changes are made, and the entity
state to automatically be changed to Modified . Calling SaveChanges generates a SQL UPDATE statement that
updates only the changed properties.
In a web app, the DbContext that reads an entity and displays the data is disposed after a page is rendered. When
a page's OnPostAsync method is called, a new web request is made and with a new instance of the DbContext . Re-
reading the entity in that new context simulates desktop processing.
Update the Delete page

In this section, code is added to implement a custom error message when the call to SaveChanges fails. Add a
string to contain possible error messages:
public class DeleteModel : PageModel

{
public DeleteModel(SchoolContext context)

{
_context = context;
}
[BindProperty]
public string ErrorMessage { get; set; }
Replace the OnGetAsync method with the following code:

public async Task<IActionResult> OnGetAsync(int? id, bool? saveChangesError = false)
{
if (id == null)
{
return NotFound();
}
Student = await _context.Student

.AsNoTracking()
{
return NotFound();
}
if (saveChangesError.GetValueOrDefault())
{
ErrorMessage = "Delete failed. Try again";
}
return Page();
}
The preceding code contains the optional parameter saveChangesError . saveChangesError indicates whether the
method was called after a failure to delete the student object. The delete operation might fail because of transient
network problems. Transient network errors are more likely in the cloud. saveChangesError is false when the
Delete page OnGetAsync is called from the UI. When OnGetAsync is called by OnPostAsync (because the delete
operation failed), the saveChangesError parameter is true.
The Delete pages OnPostAsync method
Replace the OnPostAsync with the following code:

{
if (id == null)
{
return NotFound();
}
var student = await _context.Student

.AsNoTracking()
if (student == null)
{
return NotFound();
}
try
{
_context.Student.Remove(student);
}
catch (DbUpdateException /* ex */)
{
//Log the error (uncomment ex variable name and write a log.)
return RedirectToAction("./Delete",
new { id, saveChangesError = true });
}
}
The preceding code retrieves the selected entity, then calls the Remove method to set the entity's status to
Deleted . When SaveChanges is called, a SQL DELETE command is generated. If Remove fails:
The DB exception is caught.

The Delete pages OnGetAsync method is called with saveChangesError=true .
Update the Delete Razor Page
Add the following highlighted error message to the Delete Razor Page.
@page "{id:int}"
@model ContosoUniversity.Pages.Students.DeleteModel
@{
ViewData["Title"] = "Delete";
}
<h2>Delete</h2>
<p class="text-danger">@Model.ErrorMessage</p>
<h3>Are you sure you want to delete this?</h3>

<div>
Test Delete.
Common errors
Student/Index or other links don't work:
Verify the Razor Page contains the correct @page directive. For example, The Student/Index Razor Page should
not contain a route template:
@page "{id:int}"
Each Razor Page must include the @page directive.
P R E V IO U S NEXT
Razor Pages with EF Core in ASP.NET Core - Sort,
Filter, Paging - 3 of 8
By Tom Dykstra, Rick Anderson, and Jon P Smith
In this tutorial, sorting, filtering, grouping, and paging, functionality is added.
The following illustration shows a completed page. The column headings are clickable links to sort the column.
Clicking a column heading repeatedly switches between ascending and descending sort order.
If you run into problems you can't solve, download the completed app.
Add sorting to the Index page

Add strings to the Students/Index.cshtml.cs PageModel to contain the sorting parameters:
{
public IndexModel(SchoolContext context)

{
_context = context;
}
public string NameSort { get; set; }

public string DateSort { get; set; }
public string CurrentFilter { get; set; }
public string CurrentSort { get; set; }
Update the Students/Index.cshtml.cs OnGetAsync with the following code:
public async Task OnGetAsync(string sortOrder)

{
NameSort = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";
DateSort = sortOrder == "Date" ? "date_desc" : "Date";
IQueryable<Student> studentIQ = from s in _context.Student

select s;
switch (sortOrder)
{
case "name_desc":
studentIQ = studentIQ.OrderByDescending(s => s.LastName);
break;
case "Date":
studentIQ = studentIQ.OrderBy(s => s.EnrollmentDate);
break;
case "date_desc":
studentIQ = studentIQ.OrderByDescending(s => s.EnrollmentDate);
break;
default:
studentIQ = studentIQ.OrderBy(s => s.LastName);
break;
}
Student = await studentIQ.AsNoTracking().ToListAsync();

}
The preceding code receives a sortOrder parameter from the query string in the URL. The URL (including the
query string) is generated by the Anchor Tag Helper
The sortOrder parameter is either "Name" or "Date." The sortOrder parameter is optionally followed by "_desc"
to specify descending order. The default sort order is ascending.
When the Index page is requested from the Students link, there's no query string. The students are displayed in
ascending order by last name. Ascending order by last name is the default (fall-through case) in the switch
statement. When the user clicks a column heading link, the appropriate sortOrder value is provided in the query
string value.
NameSort and DateSort are used by the Razor Page to configure the column heading hyperlinks with the
appropriate query string values:
{

select s;
switch (sortOrder)
{
case "name_desc":
break;
case "Date":
break;
case "date_desc":
break;
default:
break;
}

}
The following code contains the C# conditional ?: operator:

The first line specifies that when sortOrder is null or empty, NameSort is set to "name_desc." If sortOrder is not
null or empty, NameSort is set to an empty string.
The ?: operator is also known as the ternary operator.
These two statements enable the page to set the column heading hyperlinks as follows:
CURRENT SORT ORDER LAST NAME HYPERLINK DATE HYPERLINK
Last Name ascending descending ascending
Last Name descending ascending ascending
Date ascending ascending descending
Date descending ascending ascending
The method uses LINQ to Entities to specify the column to sort by. The code initializes an IQueryable<Student>
before the switch statement, and modifies it in the switch statement:
{

select s;
switch (sortOrder)
{
case "name_desc":
break;
case "Date":
break;
case "date_desc":
break;
default:
break;
}

}
When an IQueryable is created or modified, no query is sent to the database. The query isn't executed until the
IQueryable object is converted into a collection. IQueryable are converted to a collection by calling a method
such as ToListAsync . Therefore, the IQueryable code results in a single query that's not executed until the
following statement:
OnGetAsync could get verbose with a large number of sortable columns.

Add column heading hyperlinks to the Student Index page
Replace the code in Students/Index.cshtml, with the following highlighted code:
@page
@model ContosoUniversity.Pages.Students.IndexModel
@{
}
<h2>Index</h2>
<p>
</p>
<thead>
<tr>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.NameSort">
@Html.DisplayNameFor(model => model.Student[0].LastName)
</a>
</th>
<th>
@Html.DisplayNameFor(model => model.Student[0].FirstMidName)
</th>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.DateSort">
@Html.DisplayNameFor(model => model.Student[0].EnrollmentDate)
</a>
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Student)
{
<tr>
<td>
@Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
@Html.DisplayFor(modelItem => item.FirstMidName)
</td>
<td>
@Html.DisplayFor(modelItem => item.EnrollmentDate)
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
The preceding code:

Adds hyperlinks to the LastName and EnrollmentDate column headings.
Uses the information in NameSort and DateSort to set up hyperlinks with the current sort order values.
To verify that sorting works:
Run the app and select the Students tab.
Click Last Name.
Click Enrollment Date.
To get a better understanding of the code:
In Student/Index.cshtml.cs, set a breakpoint on switch (sortOrder) .
Add a watch for NameSort and DateSort .
In Student/Index.cshtml, set a breakpoint on @Html.DisplayNameFor(model => model.Student[0].LastName) .
Step through the debugger.
Add a Search Box to the Students Index page

To add filtering to the Students Index page:
A text box and a submit button is added to the Razor Page. The text box supplies a search string on the first or
last name.
The page model is updated to use the text box value.
Add filtering functionality to the Index method
public async Task OnGetAsync(string sortOrder, string searchString)

{
CurrentFilter = searchString;

select s;
{
studentIQ = studentIQ.Where(s => s.LastName.Contains(searchString)
|| s.FirstMidName.Contains(searchString));
}
switch (sortOrder)
{
case "name_desc":
break;
case "Date":
break;
case "date_desc":
break;
default:
break;
}

}
The preceding code:

Adds the searchString parameter to the OnGetAsync method. The search string value is received from a text
box that's added in the next section.
Added to the LINQ statement a Where clause. The Where clause selects only students whose first name or last
name contains the search string. The LINQ statement is executed only if there's a value to search for.
Note: The preceding code calls the Where method on an IQueryable object, and the filter is processed on the
server. In some scenarios, the app might be calling the Where method as an extension method on an in-memory
collection. For example, suppose _context.Students changes from EF Core DbSet to a repository method that
returns an IEnumerable collection. The result would normally be the same but in some cases may be different.
For example, the .NET Framework implementation of Contains performs a case-sensitive comparison by default.
In SQL Server, Contains case-sensitivity is determined by the collation setting of the SQL Server instance. SQL
Server defaults to case-insensitive. ToUpper could be called to make the test explicitly case-insensitive:
Where(s => s.LastName.ToUpper().Contains(searchString.ToUpper())
The preceding code would ensure that results are case-insensitive if the code changes to use IEnumerable . When
Contains is called on an IEnumerable collection, the .NET Core implementation is used. When Contains is called
on an IQueryable object, the database implementation is used. Returning an IEnumerable from a repository can
have a significant performance penality:
1. All the rows are returned from the DB server.
2. The filter is applied to all the returned rows in the application.
There's a performance penalty for calling ToUpper . The ToUpper code adds a function in the WHERE clause of the
TSQL SELECT statement. The added function prevents the optimizer from using an index. Given that SQL is
installed as case-insensitive, it's best to avoid the ToUpper call when it's not needed.
Add a Search Box to the Student Index page
In Pages/Students/Index.cshtml, add the following highlighted code to create a Search button and assorted
chrome.
@page
@{
}
<h2>Index</h2>
<p>
</p>
<form asp-page="./Index" method="get">

<div class="form-actions no-color">
<p>
Find by name:
<input type="text" name="SearchString" value="@Model.CurrentFilter" />
<input type="submit" value="Search" class="btn btn-default" /> |
<a asp-page="./Index">Back to full List</a>
</p>
</div>
</form>
The preceding code uses the <form> tag helper to add the search text box and button. By default, the <form> tag
helper submits form data with a POST. With POST, the parameters are passed in the HTTP message body and
not in the URL. When HTTP GET is used, the form data is passed in the URL as query strings. Passing the data
with query strings enables users to bookmark the URL. The W3C guidelines recommend that GET should be used
when the action doesn't result in an update.
Test the app:
Select the Students tab and enter a search string.
Select Search.
Notice that the URL contains the search string.
http://localhost:5000/Students?SearchString=an
If the page is bookmarked, the bookmark contains the URL to the page and the SearchString query string. The
method="get" in the form tag is what caused the query string to be generated.
Currently, when a column heading sort link is selected, the filter value from the Search box is lost. The lost filter
value is fixed in the next section.
Add paging functionality to the Students Index page

In this section, a PaginatedList class is created to support paging. The PaginatedList class uses Skip and Take
statements to filter data on the server instead of retrieving all rows of the table. The following illustration shows
the paging buttons.
In the project folder, create PaginatedList.cs with the following code:

using System;
using System.Linq;
{
public class PaginatedList<T> : List<T>
{
public int PageIndex { get; private set; }
public int TotalPages { get; private set; }
public PaginatedList(List<T> items, int count, int pageIndex, int pageSize)

{
PageIndex = pageIndex;
TotalPages = (int)Math.Ceiling(count / (double)pageSize);
this.AddRange(items);
}
public bool HasPreviousPage

{
get
{
return (PageIndex > 1);
}
}
public bool HasNextPage

{
get
{
return (PageIndex < TotalPages);
}
}
public static async Task<PaginatedList<T>> CreateAsync(

IQueryable<T> source, int pageIndex, int pageSize)
{
var count = await source.CountAsync();
var items = await source.Skip(
(pageIndex - 1) * pageSize)
.Take(pageSize).ToListAsync();
return new PaginatedList<T>(items, count, pageIndex, pageSize);
}
}
}
The CreateAsyncmethod in the preceding code takes page size and page number and applies the appropriate
Skip and Take statements to the IQueryable . When ToListAsync is called on the IQueryable , it returns a List
containing only the requested page. The properties HasPreviousPage and HasNextPage are used to enable or
disable Previous and Next paging buttons.
The CreateAsync method is used to create the PaginatedList<T> . A constructor can't create the PaginatedList<T>
object, constructors can't run asynchronous code.
Add paging functionality to the Index method

In Students/Index.cshtml.cs, update the type of Student from IList<Student> to PaginatedList<Student> :
public PaginatedList<Student> Student { get; set; }

public async Task OnGetAsync(string sortOrder,

string currentFilter, string searchString, int? pageIndex)
{
CurrentSort = sortOrder;
if (searchString != null)
{
pageIndex = 1;
}
else
{
searchString = currentFilter;
}
CurrentFilter = searchString;

select s;
{
studentIQ = studentIQ.Where(s => s.LastName.Contains(searchString)
}
switch (sortOrder)
{
case "name_desc":
break;
case "Date":
break;
case "date_desc":
break;
default:
break;
}
int pageSize = 3;
Student = await PaginatedList<Student>.CreateAsync(
studentIQ.AsNoTracking(), pageIndex ?? 1, pageSize);
}
The preceding code adds the page index, the current sortOrder , and the currentFilter to the method signature.
public async Task OnGetAsync(string sortOrder,

string currentFilter, string searchString, int? pageIndex)
All the parameters are null when:

The page is called from the Students link.
The user hasn't clicked a paging or sorting link.
When a paging link is clicked, the page index variable contains the page number to display.
CurrentSort provides the Razor Page with the current sort order. The current sort order must be included in the
paging links to keep the sort order while paging.
CurrentFilter provides the Razor Page with the current filter string. The CurrentFilter value:
Must be included in the paging links in order to maintain the filter settings during paging.
Must be restored to the text box when the page is redisplayed.
If the search string is changed while paging, the page is reset to 1. The page has to be reset to 1 because the new
filter can result in different data to display. When a search value is entered and Submit is selected:
The search string is changed.
The searchString parameter isn't null.
{
pageIndex = 1;
}
else
{
}
The PaginatedList.CreateAsync method converts the student query to a single page of students in a collection
type that supports paging. That single page of students is passed to the Razor Page.
Student = await PaginatedList<Student>.CreateAsync(

studentIQ.AsNoTracking(), pageIndex ?? 1, pageSize);
The two question marks in PaginatedList.CreateAsync represent the null-coalescing operator. The null-coalescing
operator defines a default value for a nullable type. The expression (pageIndex ?? 1) means return the value of
pageIndex if it has a value. If pageIndex doesn't have a value, return 1.
Add paging links to the student Razor Page

Update the markup in Students/Index.cshtml. The changes are highlighted:
@page
@{
}
<h2>Index</h2>
<p>
</p>
<form asp-page="./Index" method="get">

<p>
Find by name: <input type="text" name="SearchString" value="@Model.CurrentFilter" />
<a asp-page="./Index">Back to full List</a>
</p>
</div>
</form>
<thead>
<tr>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.NameSort"
asp-route-currentFilter="@Model.CurrentFilter">
</a>
</th>
<th>
@Html.DisplayNameFor(model => model.Student[0].FirstMidName)
</th>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.DateSort"
@Html.DisplayNameFor(model => model.Student[0].EnrollmentDate)
</a>
</th>
<th></th>
</tr>
</thead>
<tbody>
{
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
@{
var prevDisabled = !Model.Student.HasPreviousPage ? "disabled" : "";
var nextDisabled = !Model.Student.HasNextPage ? "disabled" : "";
}
<a asp-page="./Index"
asp-route-sortOrder="@Model.CurrentSort"
asp-route-pageIndex="@(Model.Student.PageIndex - 1)"
asp-route-currentFilter="@Model.CurrentFilter"
class="btn btn-default @prevDisabled">
Previous
</a>
asp-route-pageIndex="@(Model.Student.PageIndex + 1)"
class="btn btn-default @nextDisabled">
Next
</a>
The column header links use the query string to pass the current search string to the OnGetAsync method so that
the user can sort within filter results:
<a asp-page="./Index" asp-route-sortOrder="@Model.NameSort"

</a>
The paging buttons are displayed by tag helpers:
asp-route-pageIndex="@(Model.Student.PageIndex - 1)"
Previous
</a>
asp-route-pageIndex="@(Model.Student.PageIndex + 1)"
Next
</a>
Run the app and navigate to the students page.

To make sure paging works, click the paging links in different sort orders.
To verify that paging works correctly with sorting and filtering, enter a search string and try paging.
To get a better understanding of the code:

In Student/Index.cshtml.cs, set a breakpoint on switch (sortOrder) .
Add a watch for NameSort , DateSort , CurrentSort , and Model.Student.PageIndex .
In Student/Index.cshtml, set a breakpoint on @Html.DisplayNameFor(model => model.Student[0].LastName) .
Step through the debugger.
Update the About page to show student statistics

In this step, Pages/About.cshtml is updated to display how many students have enrolled for each enrollment date.
The update uses grouping and includes the following steps:
Create a view model for the data used by the About Page.
Update the About page to use the view model.
Create the view model
Create a SchoolViewModels folder in the Models folder.
In the SchoolViewModels folder, add a EnrollmentDateGroup.cs with the following code:
using System;
namespace ContosoUniversity.Models.SchoolViewModels
{
public class EnrollmentDateGroup
{
public DateTime? EnrollmentDate { get; set; }
public int StudentCount { get; set; }

}
}
Update the About page model

Update the Pages/About.cshtml.cs file with the following code:
using ContosoUniversity.Models.SchoolViewModels;
using System.Linq;
using ContosoUniversity.Data;
namespace ContosoUniversity.Pages
{
{
public AboutModel(SchoolContext context)

{
_context = context;
}
public IList<EnrollmentDateGroup> Student { get; set; }

{
IQueryable<EnrollmentDateGroup> data =
from student in _context.Student
group student by student.EnrollmentDate into dateGroup
select new EnrollmentDateGroup()
{
EnrollmentDate = dateGroup.Key,
StudentCount = dateGroup.Count()
};
Student = await data.AsNoTracking().ToListAsync();

}
}
}
The LINQ statement groups the student entities by enrollment date, calculates the number of entities in each
group, and stores the results in a collection of EnrollmentDateGroup view model objects.
Modify the About Razor Page
Replace the code in the Pages/About.cshtml file with the following code:
@page
@model ContosoUniversity.Pages.AboutModel
@{
ViewData["Title"] = "Student Body Statistics";
}
<h2>Student Body Statistics</h2>
<table>
<tr>
<th>
Enrollment Date
</th>
<th>
Students
</th>
</tr>

{
<tr>
<td>
</td>
<td>
@item.StudentCount
</td>
</tr>
}
</table>
Run the app and navigate to the About page. The count of students for each enrollment date is displayed in a
table.
If you run into problems you can't solve, download the completed app for this stage.
Debugging ASP.NET Core 2.x source
In the next tutorial, the app uses migrations to update the data model.
P R E V IO U S NEXT
Razor Pages with EF Core in ASP.NET Core -
Migrations - 4 of 8
In this tutorial, the EF Core migrations feature for managing data model changes is used.
When a new app is developed, the data model changes frequently. Each time the model changes, the model gets
out of sync with the database. This tutorial started by configuring the Entity Framework to create the database if it
doesn't exist. Each time the data model changes:
The DB is dropped.
EF creates a new one that matches the model.
The app seeds the DB with test data.
This approach to keeping the DB in sync with the data model works well until you deploy the app to production.
When the app is running in production, it's usually storing data that needs to be maintained. The app can't start
with a test DB each time a change is made (such as adding a new column). The EF Core Migrations feature solves
this problem by enabling EF Core to update the DB schema instead of creating a new DB.
Rather than dropping and recreating the DB when the data model changes, migrations updates the schema and
retains existing data.
Drop the database

Use SQL Server Object Explorer (SSOX) or the database drop command:
Visual Studio
.NET Core CLI
In the Package Manager Console (PMC ), run the following command:
Drop-Database
Run Get-Help about_EntityFrameworkCore from the PMC to get help information.
Create an initial migration and update the DB

Build the project and create the first migration.
Visual Studio
.NET Core CLI
Add-Migration InitialCreate
Update-Database
Examine the Up and Down methods

The EF Core migrations add command generated code to create the DB. This migrations code is in the
Migrations<timestamp>_InitialCreate.cs file. The Up method of the InitialCreate class creates the DB tables
that correspond to the data model entity sets. The Down method deletes them, as shown in the following example:
public partial class InitialCreate : Migration

{
protected override void Up(MigrationBuilder migrationBuilder)
{
migrationBuilder.CreateTable(
name: "Course",
columns: table => new
{
CourseID = table.Column<int>(nullable: false),
Title = table.Column<string>(nullable: true),
Credits = table.Column<int>(nullable: false)
},
constraints: table =>
{
table.PrimaryKey("PK_Course", x => x.CourseID);
});
protected override void Down(MigrationBuilder migrationBuilder)
{
migrationBuilder.DropTable(
name: "Enrollment");
name: "Course");
name: "Student");
}
}
Migrations calls the Up method to implement the data model changes for a migration. When you enter a
command to roll back the update, migrations calls the Down method.
The preceding code is for the initial migration. That code was created when the migrations add InitialCreate
command was run. The migration name parameter ("InitialCreate" in the example) is used for the file name. The
migration name can be any valid file name. It's best to choose a word or phrase that summarizes what is being
done in the migration. For example, a migration that added a department table might be called
"AddDepartmentTable."
If the initial migration is created and the DB exists:
The DB creation code is generated.
The DB creation code doesn't need to run because the DB already matches the data model. If the DB creation
code is run, it doesn't make any changes because the DB already matches the data model.
When the app is deployed to a new environment, the DB creation code must be run to create the DB.
Previously the DB was dropped and doesn't exist, so migrations creates the new DB.
The data model snapshot
Migrations create a snapshot of the current database schema in Migrations/SchoolContextModelSnapshot.cs.
When you add a migration, EF determines what changed by comparing the data model to the snapshot file.
To delete a migration, use the following command:
Visual Studio
.NET Core CLI
Remove-Migration
The remove migrations command deletes the migration and ensures the snapshot is correctly reset.
Remove EnsureCreated and test the app
For early development, EnsureCreated was used. In this tutorial, migrations are used. EnsureCreated has the
following limitations:
Bypasses migrations and creates the DB and schema.
Doesn't create a migrations table.
Can not be used with migrations.
Is designed for testing or rapid prototyping where the DB is dropped and re-created frequently.
Remove the following line from DbInitializer :
Run the app and verify the DB is seeded.

Inspect the database
Use SQL Server Object Explorer to inspect the DB. Notice the addition of an __EFMigrationsHistory table. The
__EFMigrationsHistory table keeps track of which migrations have been applied to the DB. View the data in the
__EFMigrationsHistory table, it shows one row for the first migration. The last log in the preceding CLI output
example shows the INSERT statement that creates this row.
Run the app and verify that everything works.
Applying migrations in production

We recommend production apps should not call Database.Migrate at application startup. Migrate shouldn't be
called from an app in server farm. For example, if the app has been cloud deployed with scale-out (multiple
instances of the app are running).
Database migration should be done as part of deployment, and in a controlled way. Production database
migration approaches include:
Using migrations to create SQL scripts and using the SQL scripts in deployment.
Running dotnet ef database update from a controlled environment.
EF Core uses the __MigrationsHistory table to see if any migrations need to run. If the DB is up-to-date, no
migration is run.
Troubleshooting
Download the completed app.
The app generates the following exception:
SqlException: Cannot open database "ContosoUniversity" requested by the login.
The login failed.
Solution: Run dotnet ef database update
.NET Core CLI.
Package Manager Console (Visual Studio)
P R E V IO U S NEXT
Razor Pages with EF Core in ASP.NET Core - Data
Model - 5 of 8
The previous tutorials worked with a basic data model that was composed of three entities. In this tutorial:
More entities and relationships are added.
The data model is customized by specifying formatting, validation, and database mapping rules.
The entity classes for the completed data model is shown in the following illustration:
Customize the data model with attributes

In this section, the data model is customized using attributes.
The DataType attribute
The student pages currently displays the time of the enrollment date. Typically, date fields show only the date and
not the time.
Update Models/Student.cs with the following highlighted code:
using System;
{
{

}
}
The DataType attribute specifies a data type that's more specific than the database intrinsic type. In this case only
the date should be displayed, not the date and time. The DataType Enumeration provides for many data types,
such as Date, Time, PhoneNumber, Currency, EmailAddress, etc. The DataType attribute can also enable the app
to automatically provide type-specific features. For example:
The mailto: link is automatically created for DataType.EmailAddress .
The date selector is provided for DataType.Date in most browsers.
The DataType attribute emits HTML 5 data- (pronounced data dash) attributes that HTML 5 browsers consume.
The DataType attributes don't provide validation.
DataType.Date doesn't specify the format of the date that's displayed. By default, the date field is displayed
according to the default formats based on the server's CultureInfo.
The ApplyFormatInEditMode setting specifies that the formatting should also be applied to the edit UI. Some fields
shouldn't use ApplyFormatInEditMode . For example, the currency symbol should generally not be displayed in an
edit text box.
The DisplayFormatattribute can be used by itself. It's generally a good idea to use the DataType attribute with the
DisplayFormat attribute. The DataType attribute conveys the semantics of the data as opposed to how to render it
on a screen. The DataType attribute provides the following benefits that are not available in DisplayFormat :
The browser can enable HTML5 features. For example, show a calendar control, the locale-appropriate
currency symbol, email links, client-side input validation, etc.
By default, the browser renders data using the correct format based on the locale.
For more information, see the <input> Tag Helper documentation.
Run the app. Navigate to the Students Index page. Times are no longer displayed. Every view that uses the
Student model displays the date without time.
The StringLength attribute
Data validation rules and validation error messages can be specified with attributes. The StringLength attribute
specifies the minimum and maximum length of characters that are allowed in a data field. The StringLength
attribute also provides client-side and server-side validation. The minimum value has no impact on the database
schema.
Update the Student model with the following code:
using System;
{
{
[StringLength(50)]
[StringLength(50, ErrorMessage = "First name cannot be longer than 50 characters.")]

}
}
The preceding code limits names to no more than 50 characters. The StringLength attribute doesn't prevent a
user from entering white space for a name. The RegularExpression attribute is used to apply restrictions to the
input. For example, the following code requires the first character to be upper case and the remaining characters
to be alphabetical:
Run the app:

Navigate to the Students page.
Select Create New, and enter a name longer than 50 characters.
Select Create, client-side validation shows an error message.
In SQL Server Object Explorer (SSOX), open the Student table designer by double-clicking the Student table.
The preceding image shows the schema for the Student table. The name fields have type nvarchar(MAX) because
migrations has not been run on the DB. When migrations are run later in this tutorial, the name fields become
nvarchar(50) .
The Column attribute
Attributes can control how classes and properties are mapped to the database. In this section, the Column
attribute is used to map the name of the FirstMidName property to "FirstName" in the DB.
When the DB is created, property names on the model are used for column names (except when the Column
attribute is used).
The Student model uses FirstMidName for the first-name field because the field might also contain a middle
name.
Update the Student.cs file with the following highlighted code:
using System;
{
{
[StringLength(50)]
[Column("FirstName")]

}
}
With the preceding change, Student.FirstMidName in the app maps to the FirstName column of the Student table.
The addition of the Column attribute changes the model backing the SchoolContext . The model backing the
SchoolContext no longer matches the database. If the app is run before applying migrations, the following
exception is generated:
SqlException: Invalid column name 'FirstName'.
To update the DB:

Build the project.
Open a command window in the project folder. Enter the following commands to create a new migration and
update the DB:
Visual Studio
.NET Core CLI
Add-Migration ColumnFirstName
Update-Database
The migrations add ColumnFirstName command generates the following warning message:
An operation was scaffolded that may result in the loss of data.
Please review the migration for accuracy.
The warning is generated because the name fields are now limited to 50 characters. If a name in the DB had more
than 50 characters, the 51 to last character would be lost.
Test the app.
Open the Student table in SSOX:
Before migration was applied, the name columns were of type nvarchar(MAX). The name columns are now
nvarchar(50) . The column name has changed from FirstMidName to FirstName .
NOTE
In the following section, building the app at some stages generates compiler errors. The instructions specify when to build
the app.
Student entity update
Update Models/Student.cs with the following code:

using System;
{
{
[Required]
[StringLength(50)]
[Display(Name = "Last Name")]
[Required]
[Display(Name = "First Name")]
[Display(Name = "Enrollment Date")]
[Display(Name = "Full Name")]
public string FullName
{
get
{
return LastName + ", " + FirstMidName;
}
}

}
}
The Required attribute

The Required attribute makes the name properties required fields. The Required attribute isn't needed for non-
nullable types such as value types ( DateTime , int , double , etc.). Types that can't be null are automatically treated
as required fields.
The Required attribute could be replaced with a minimum length parameter in the StringLength attribute:

[StringLength(50, MinimumLength=1)]
The Display attribute

The Display attribute specifies that the caption for the text boxes should be "First Name", "Last Name", "Full
Name", and "Enrollment Date." The default captions had no space dividing the words, for example "Lastname."
The FullName calculated property
FullName is a calculated property that returns a value that's created by concatenating two other properties.
FullName cannot be set, it has only a get accessor. No FullName column is created in the database.
Create the Instructor Entity

Create Models/Instructor.cs with the following code:
using System;
{
public class Instructor
{
[Required]
[StringLength(50)]
[Required]
[StringLength(50)]
[Display(Name = "Hire Date")]
public DateTime HireDate { get; set; }

{
get { return LastName + ", " + FirstMidName; }
}
public ICollection<CourseAssignment> CourseAssignments { get; set; }

public OfficeAssignment OfficeAssignment { get; set; }
}
}
Multiple attributes can be on one line. The HireDate attributes could be written as follows:
[DataType(DataType.Date),Display(Name = "Hire Date"),DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}",

ApplyFormatInEditMode = true)]
The CourseAssignments and OfficeAssignment navigation properties

The CourseAssignments and OfficeAssignment properties are navigation properties.
An instructor can teach any number of courses, so CourseAssignments is defined as a collection.
If a navigation property holds multiple entities:

It must be a list type where the entries can be added, deleted, and updated.
Navigation property types include:
ICollection<T>
List<T>
HashSet<T>
If ICollection<T> is specified, EF Core creates a HashSet<T> collection by default.

The CourseAssignment entity is explained in the section on many-to-many relationships.
Contoso University business rules state that an instructor can have at most one office. The OfficeAssignment
property holds a single OfficeAssignment entity. OfficeAssignment is null if no office is assigned.
Create the OfficeAssignment entity
Create Models/OfficeAssignment.cs with the following code:
{
public class OfficeAssignment
{
[Key]
public int InstructorID { get; set; }
[StringLength(50)]
[Display(Name = "Office Location")]
public string Location { get; set; }
public Instructor Instructor { get; set; }

}
}
The Key attribute

The [Key] attribute is used to identify a property as the primary key (PK) when the property name is something
other than classnameID or ID.
There's a one-to-zero-or-one relationship between the Instructor and OfficeAssignment entities. An office
assignment only exists in relation to the instructor it's assigned to. The OfficeAssignment PK is also its foreign key
(FK) to the Instructor entity. EF Core can't automatically recognize InstructorID as the PK of OfficeAssignment
because:
InstructorID doesn't follow the ID or classnameID naming convention.
Therefore, the Key attribute is used to identify InstructorID as the PK:
[Key]
By default, EF Core treats the key as non-database-generated because the column is for an identifying
relationship.
The Instructor navigation property
The OfficeAssignment navigation property for the Instructor entity is nullable because:
Reference types (such as classes are nullable).
An instructor might not have an office assignment.
The OfficeAssignment entity has a non-nullable Instructor navigation property because:
InstructorIDis non-nullable.
An office assignment can't exist without an instructor.
When an Instructor entity has a related OfficeAssignment entity, each entity has a reference to the other one in
its navigation property.
The [Required] attribute could be applied to the Instructor navigation property:
[Required]
The preceding code specifies that there must be a related instructor. The preceding code is unnecessary because
the InstructorID foreign key (which is also the PK) is non-nullable.
Modify the Course Entity
Update Models/Course.cs with the following code:

{
public class Course
{
[Display(Name = "Number")]

[Range(0, 5)]
public int DepartmentID { get; set; }
public Department Department { get; set; }

}
}
The Course entity has a foreign key (FK) property DepartmentID . DepartmentID points to the related Department
entity. The Course entity has a Department navigation property.
EF Core doesn't require a FK property for a data model when the model has a navigation property for a related
entity.
EF Core automatically creates FKs in the database wherever they're needed. EF Core creates shadow properties
for automatically created FKs. Having the FK in the data model can make updates simpler and more efficient. For
example, consider a model where the FK property DepartmentID is not included. When a course entity is fetched
to edit:
The Department entity is null if it's not explicitly loaded.
To update the course entity, the Department entity must first be fetched.
When the FK property DepartmentID is included in the data model, there's no need to fetch the Department entity
before an update.
The DatabaseGenerated attribute
The [DatabaseGenerated(DatabaseGeneratedOption.None)] attribute specifies that the PK is provided by the
application rather than generated by the database.
By default, EF Core assumes that PK values are generated by the DB. DB generated PK values is generally the best
approach. For Course entities, the user specifies the PK. For example, a course number such as a 1000 series for
the math department, a 2000 series for the English department.
The DatabaseGenerated attribute can also be used to generate default values. For example, the DB can
automatically generate a date field to record the date a row was created or updated. For more information, see
Generated Properties.
Foreign key and navigation properties
The foreign key (FK) properties and navigation properties in the Course entity reflect the following relationships:
A course is assigned to one department, so there's a DepartmentID FK and a Department navigation property.

A course can have any number of students enrolled in it, so the Enrollments navigation property is a collection:
A course may be taught by multiple instructors, so the CourseAssignments navigation property is a collection:
CourseAssignment is explained later.
Create the Department entity
Create Models/Department.cs with the following code:

using System;
{
public class Department
{

[Column(TypeName = "money")]
public decimal Budget { get; set; }
[Display(Name = "Start Date")]
public DateTime StartDate { get; set; }
public int? InstructorID { get; set; }
public Instructor Administrator { get; set; }

public ICollection<Course> Courses { get; set; }
}
}

Previously the Column attribute was used to change column name mapping. In the code for the Department entity,
the Column attribute is used to change SQL data type mapping. The Budget column is defined using the SQL
Server money type in the DB:
[Column(TypeName="money")]
Column mapping is generally not required. EF Core generally chooses the appropriate SQL Server data type
based on the CLR type for the property. The CLR decimal type maps to a SQL Server decimal type. Budget is
for currency, and the money data type is more appropriate for currency.
The FK and navigation properties reflect the following relationships:
A department may or may not have an administrator.
An administrator is always an instructor. Therefore the InstructorID property is included as the FK to the
Instructor entity.
The navigation property is named Administrator but holds an Instructor entity:

The question mark (?) in the preceding code specifies the property is nullable.
A department may have many courses, so there's a Courses navigation property:
Note: By convention, EF Core enables cascade delete for non-nullable FKs and for many-to-many relationships.
Cascading delete can result in circular cascade delete rules. Circular cascade delete rules causes an exception when
a migration is added.
For example, if the Department.InstructorID property wasn't defined as nullable:
EF Core configures a cascade delete rule to delete the instructor when the department is deleted.
Deleting the instructor when the department is deleted isn't the intended behavior.
If business rules required the InstructorID property be non-nullable, use the following fluent API statement:
modelBuilder.Entity<Department>()
.HasOne(d => d.Administrator)
.WithMany()
.OnDelete(DeleteBehavior.Restrict)
The preceding code disables cascade delete on the department-instructor relationship.
Update the Enrollment entity

An enrollment record is for one course taken by one student.
Update Models/Enrollment.cs with the following code:
{
public enum Grade
{
A, B, C, D, F
}

{
[DisplayFormat(NullDisplayText = "No grade")]

}
}
The FK properties and navigation properties reflect the following relationships:
An enrollment record is for one course, so there's a CourseID FK property and a Course navigation property:

An enrollment record is for one student, so there's a StudentID FK property and a Student navigation property:

Many-to-Many Relationships
There's a many-to-many relationship between the Student and Course entities. The Enrollment entity functions
as a many-to-many join table with payload in the database. "With payload" means that the Enrollment table
contains additional data besides FKs for the joined tables (in this case, the PK and Grade ).
The following illustration shows what these relationships look like in an entity diagram. (This diagram was
generated using EF Power Tools for EF 6.x. Creating the diagram isn't part of the tutorial.)
Each relationship line has a 1 at one end and an asterisk (*) at the other, indicating a one-to-many relationship.
If the table didn't include grade information, it would only need to contain the two FKs ( CourseID and
Enrollment
StudentID ). A many-to-many join table without payload is sometimes called a pure join table ( PJT ).
The Instructor and Course entities have a many-to-many relationship using a pure join table.
Note: EF 6.x supports implicit join tables for many-to-many relationships, but EF Core doesn't. For more
information, see Many-to-many relationships in EF Core 2.0.
The CourseAssignment entity
Create Models/CourseAssignment.cs with the following code:
using System;
{
public class CourseAssignment
{
}
}
Instructor-to -Courses
The Instructor-to-Courses many-to-many relationship:

Requires a join table that must be represented by an entity set.
Is a pure join table (table without payload).
It's common to name a join entity EntityName1EntityName2 . For example, the Instructor-to-Courses join table using
this pattern is CourseInstructor . However, we recommend using a name that describes the relationship.
Data models start out simple and grow. No-payload joins (PJTs) frequently evolve to include payload. By starting
with a descriptive entity name, the name doesn't need to change when the join table changes. Ideally, the join
entity would have its own natural (possibly single word) name in the business domain. For example, Books and
Customers could be linked with a join entity called Ratings. For the Instructor-to-Courses many-to-many
relationship, CourseAssignment is preferred over CourseInstructor .
Composite key
FKs are not nullable. The two FKs in CourseAssignment ( InstructorID and CourseID ) together uniquely identify
each row of the CourseAssignment table. CourseAssignment doesn't require a dedicated PK. The InstructorID and
CourseID properties function as a composite PK. The only way to specify composite PKs to EF Core is with the
fluent API. The next section shows how to configure the composite PK.
The composite key ensures:
Multiple rows are allowed for one course.
Multiple rows are allowed for one instructor.
Multiple rows for the same instructor and course isn't allowed.
The Enrollment join entity defines its own PK, so duplicates of this sort are possible. To prevent such duplicates:
Add a unique index on the FK fields, or
Configure Enrollment with a primary composite key similar to CourseAssignment . For more information, see
Indexes.
Update the DB context

Add the following highlighted code to Data/SchoolContext.cs:
{
{
public SchoolContext(DbContextOptions<SchoolContext> options) : base(options)
{
}
public DbSet<Course> Courses { get; set; }

public DbSet<Department> Departments { get; set; }
public DbSet<Instructor> Instructors { get; set; }
public DbSet<OfficeAssignment> OfficeAssignments { get; set; }
public DbSet<CourseAssignment> CourseAssignments { get; set; }
protected override void OnModelCreating(ModelBuilder modelBuilder)

{
modelBuilder.Entity<Course>().ToTable("Course");
modelBuilder.Entity<Enrollment>().ToTable("Enrollment");
modelBuilder.Entity<Student>().ToTable("Student");
modelBuilder.Entity<Department>().ToTable("Department");
modelBuilder.Entity<Instructor>().ToTable("Instructor");
modelBuilder.Entity<OfficeAssignment>().ToTable("OfficeAssignment");
modelBuilder.Entity<CourseAssignment>().ToTable("CourseAssignment");
modelBuilder.Entity<CourseAssignment>()
.HasKey(c => new { c.CourseID, c.InstructorID });
}
}
}
The preceding code adds the new entities and configures the CourseAssignment entity's composite PK.
Fluent API alternative to attributes

The OnModelCreating method in the preceding code uses the fluent API to configure EF Core behavior. The API is
called "fluent" because it's often used by stringing a series of method calls together into a single statement. The
following code is an example of the fluent API:

{
modelBuilder.Entity<Blog>()
.Property(b => b.Url)
.IsRequired();
}
In this tutorial, the fluent API is used only for DB mapping that can't be done with attributes. However, the fluent
API can specify most of the formatting, validation, and mapping rules that can be done with attributes.
Some attributes such as MinimumLength can't be applied with the fluent API. MinimumLength doesn't change the
schema, it only applies a minimum length validation rule.
Some developers prefer to use the fluent API exclusively so that they can keep their entity classes "clean."
Attributes and the fluent API can be mixed. There are some configurations that can only be done with the fluent
API (specifying a composite PK). There are some configurations that can only be done with attributes (
MinimumLength ). The recommended practice for using fluent API or attributes:
Choose one of these two approaches.
Use the chosen approach consistently as much as possible.
Some of the attributes used in the this tutorial are used for:
Validation only (for example, MinimumLength ).
EF Core configuration only (for example, HasKey ).
Validation and EF Core configuration (for example, [StringLength(50)] ).
For more information about attributes vs. fluent API, see Methods of configuration.
Entity Diagram Showing Relationships

The following illustration shows the diagram that EF Power Tools create for the completed School model.
The preceding diagram shows:

Several one-to-many relationship lines (1 to *).
The one-to-zero-or-one relationship line (1 to 0..1) between the Instructor and OfficeAssignment entities.
The zero-or-one-to-many relationship line (0..1 to *) between the Instructor and Department entities.
Seed the DB with Test Data
Update the code in Data/DbInitializer.cs:
using System;
using System.Linq;
{
{
{
//context.Database.EnsureCreated();

{
}

{
new Student { FirstMidName = "Carson", LastName = "Alexander",
EnrollmentDate = DateTime.Parse("2010-09-01") },
new Student { FirstMidName = "Meredith", LastName = "Alonso",
new Student { FirstMidName = "Arturo", LastName = "Anand",
new Student { FirstMidName = "Gytis", LastName = "Barzdukas",
new Student { FirstMidName = "Yan", LastName = "Li",
new Student { FirstMidName = "Peggy", LastName = "Justice",
new Student { FirstMidName = "Laura", LastName = "Norman",
new Student { FirstMidName = "Nino", LastName = "Olivetto",
EnrollmentDate = DateTime.Parse("2005-09-01") }
};

{
}
var instructors = new Instructor[]

{
new Instructor { FirstMidName = "Kim", LastName = "Abercrombie",
HireDate = DateTime.Parse("1995-03-11") },
new Instructor { FirstMidName = "Fadi", LastName = "Fakhouri",
new Instructor { FirstMidName = "Roger", LastName = "Harui",
new Instructor { FirstMidName = "Candace", LastName = "Kapoor",
new Instructor { FirstMidName = "Roger", LastName = "Zheng",
HireDate = DateTime.Parse("2004-02-12") }
};
foreach (Instructor i in instructors)

{
context.Instructors.Add(i);
}
}
var departments = new Department[]

{
new Department { Name = "English", Budget = 350000,
StartDate = DateTime.Parse("2007-09-01"),
InstructorID = instructors.Single( i => i.LastName == "Abercrombie").ID },
new Department { Name = "Mathematics", Budget = 100000,
InstructorID = instructors.Single( i => i.LastName == "Fakhouri").ID },
new Department { Name = "Engineering", Budget = 350000,
InstructorID = instructors.Single( i => i.LastName == "Harui").ID },
new Department { Name = "Economics", Budget = 100000,
InstructorID = instructors.Single( i => i.LastName == "Kapoor").ID }
};
foreach (Department d in departments)

{
context.Departments.Add(d);
}

{
new Course {CourseID = 1050, Title = "Chemistry", Credits = 3,
DepartmentID = departments.Single( s => s.Name == "Engineering").DepartmentID
},
new Course {CourseID = 4022, Title = "Microeconomics", Credits = 3,
DepartmentID = departments.Single( s => s.Name == "Economics").DepartmentID
},
new Course {CourseID = 4041, Title = "Macroeconomics", Credits = 3,
},
new Course {CourseID = 1045, Title = "Calculus", Credits = 4,
DepartmentID = departments.Single( s => s.Name == "Mathematics").DepartmentID
},
new Course {CourseID = 3141, Title = "Trigonometry", Credits = 4,
},
new Course {CourseID = 2021, Title = "Composition", Credits = 3,
DepartmentID = departments.Single( s => s.Name == "English").DepartmentID
},
new Course {CourseID = 2042, Title = "Literature", Credits = 4,
},
};

{
context.Courses.Add(c);
}
var officeAssignments = new OfficeAssignment[]

{
new OfficeAssignment {
InstructorID = instructors.Single( i => i.LastName == "Fakhouri").ID,
Location = "Smith 17" },
InstructorID = instructors.Single( i => i.LastName == "Harui").ID,
Location = "Gowan 27" },
InstructorID = instructors.Single( i => i.LastName == "Kapoor").ID,
Location = "Thompson 304" },
};
foreach (OfficeAssignment o in officeAssignments)

{
context.OfficeAssignments.Add(o);
}
var courseInstructors = new CourseAssignment[]

{
new CourseAssignment {
CourseID = courses.Single(c => c.Title == "Chemistry" ).CourseID,
InstructorID = instructors.Single(i => i.LastName == "Kapoor").ID
},
InstructorID = instructors.Single(i => i.LastName == "Harui").ID
},
CourseID = courses.Single(c => c.Title == "Microeconomics" ).CourseID,
InstructorID = instructors.Single(i => i.LastName == "Zheng").ID
},
CourseID = courses.Single(c => c.Title == "Macroeconomics" ).CourseID,
},
CourseID = courses.Single(c => c.Title == "Calculus" ).CourseID,
InstructorID = instructors.Single(i => i.LastName == "Fakhouri").ID
},
CourseID = courses.Single(c => c.Title == "Trigonometry" ).CourseID,
},
CourseID = courses.Single(c => c.Title == "Composition" ).CourseID,
InstructorID = instructors.Single(i => i.LastName == "Abercrombie").ID
},
CourseID = courses.Single(c => c.Title == "Literature" ).CourseID,
},
};
foreach (CourseAssignment ci in courseInstructors)

{
context.CourseAssignments.Add(ci);
}

{
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alexander").ID,
Grade = Grade.A
},
new Enrollment {
Grade = Grade.C
},
new Enrollment {
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alonso").ID,
Grade = Grade.B
},
new Enrollment {
Grade = Grade.B
},
new Enrollment {
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Anand").ID,
CourseID = courses.Single(c => c.Title == "Chemistry" ).CourseID
},
new Enrollment {
CourseID = courses.Single(c => c.Title == "Microeconomics").CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Barzdukas").ID,
CourseID = courses.Single(c => c.Title == "Chemistry").CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Li").ID,
CourseID = courses.Single(c => c.Title == "Composition").CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Justice").ID,
CourseID = courses.Single(c => c.Title == "Literature").CourseID,
Grade = Grade.B
}
};

{
var enrollmentInDataBase = context.Enrollment.Where(
s =>
s.Student.ID == e.StudentID &&
s.Course.CourseID == e.CourseID).SingleOrDefault();
if (enrollmentInDataBase == null)
{
}
}
}
}
}
The preceding code provides seed data for the new entities. Most of this code creates new entity objects and loads
sample data. The sample data is used for testing. The preceding code creates the following many-to-many
relationships:
Enrollments
CourseAssignment
Add a migration
Build the project.
Visual Studio
.NET Core CLI
Add-Migration ComplexDataModel
The preceding command displays a warning about possible data loss.
An operation was scaffolded that may result in the loss of data.

Please review the migration for accuracy.
Done. To undo this action, use 'ef migrations remove'
If the database update command is run, the following error is produced:
The ALTER TABLE statement conflicted with the FOREIGN KEY constraint
"FK_dbo.Course_dbo.Department_DepartmentID". The conflict occurred in
database "ContosoUniversity", table "dbo.Department", column 'DepartmentID'.
When migrations are run with existing data, there may be FK constraints that are not satisfied with the exiting
data. For this tutorial, a new DB is created, so there are no FK constraint violations. See Fixing foreign key
constraints with legacy data for instructions on how to fix the FK violations on the current DB.
Drop and update the database
The code in the updated DbInitializer adds seed data for the new entities. To force EF Core to create a new DB,
drop and update the DB:
Visual Studio
.NET Core CLI
In the Package Manager Console (PMC ), run the following command:
Drop-Database
Update-Database
Run Get-Help about_EntityFrameworkCore from the PMC to get help information.

Run the app. Running the app runs the DbInitializer.Initialize method. The DbInitializer.Initialize
populates the new DB.
Open the DB in SSOX:
If SSOX was opened previously, click the Refresh button.
Expand the Tables node. The created tables are displayed.
Examine the CourseAssignment table:
Right-click the CourseAssignment table and select View Data.
Verify the CourseAssignment table contains data.
Fixing foreign key constraints with legacy data

This section is optional.
When migrations are run with existing data, there may be FK constraints that are not satisfied with the exiting
data. With production data, steps must be taken to migrate the existing data. This section provides an example of
fixing FK constraint violations. Don't make these code changes without a backup. Don't make these code changes
if you completed the previous section and updated the database.
The {timestamp }_ComplexDataModel.cs file contains the following code:
migrationBuilder.AddColumn<int>(
name: "DepartmentID",
table: "Course",
type: "int",
nullable: false,
defaultValue: 0);
The preceding code adds a non-nullable DepartmentID FK to the Course table. The DB from the previous tutorial
contains rows in Course , so that table cannot be updated by migrations.
To make the ComplexDataModel migration work with existing data:
Change the code to give the new column ( DepartmentID ) a default value.
Create a fake department named "Temp" to act as the default department.
Fix the foreign key constraints
Update the ComplexDataModel classes Up method:
Open the {timestamp }_ComplexDataModel.cs file.
Comment out the line of code that adds the DepartmentID column to the Course table.
migrationBuilder.AlterColumn<string>(
name: "Title",
table: "Course",
maxLength: 50,
nullable: true,
oldClrType: typeof(string),
oldNullable: true);
//migrationBuilder.AddColumn<int>(
// name: "DepartmentID",
// table: "Course",
// nullable: false,
// defaultValue: 0);
Add the following highlighted code. The new code goes after the .CreateTable( name: "Department" block:
name: "Department",
{
DepartmentID = table.Column<int>(type: "int", nullable: false)
.Annotation("SqlServer:ValueGenerationStrategy", SqlServerValueGenerationStrategy.IdentityColumn),
Budget = table.Column<decimal>(type: "money", nullable: false),
InstructorID = table.Column<int>(type: "int", nullable: true),
Name = table.Column<string>(type: "nvarchar(50)", maxLength: 50, nullable: true),
StartDate = table.Column<DateTime>(type: "datetime2", nullable: false)
},
{
table.PrimaryKey("PK_Department", x => x.DepartmentID);
table.ForeignKey(
name: "FK_Department_Instructor_InstructorID",
column: x => x.InstructorID,
principalTable: "Instructor",
principalColumn: "ID",
onDelete: ReferentialAction.Restrict);
});
migrationBuilder.Sql("INSERT INTO dbo.Department (Name, Budget, StartDate) VALUES ('Temp', 0.00,

GETDATE())");
// Default value for FK points to department created above, with
// defaultValue changed to 1 in following AddColumn statement.
table: "Course",
nullable: false,
defaultValue: 1);
With the preceding changes, existing Course rows will be related to the "Temp" department after the
ComplexDataModel Up method runs.
A production app would:
Include code or scripts to add Department rows and related Course rows to the new Department rows.
Not use the "Temp" department or the default value for Course.DepartmentID .
The next tutorial covers related data.
P R E V IO U S NEXT
Razor Pages with EF Core in ASP.NET Core - Read
Related Data - 6 of 8

In this tutorial, related data is read and displayed. Related data is data that EF Core loads into navigation
properties.
If you run into problems you can't solve, download or view the completed app. Download instructions.
The following illustrations show the completed pages for this tutorial:
Eager, explicit, and lazy Loading of related data
There are several ways that EF Core can load related data into the navigation properties of an entity:
Eager loading. Eager loading is when a query for one type of entity also loads related entities. When the
entity is read, its related data is retrieved. This typically results in a single join query that retrieves all of the
data that's needed. EF Core will issue multiple queries for some types of eager loading. Issuing multiple
queries can be more efficient than was the case for some queries in EF6 where there was a single query.
Eager loading is specified with the Include and ThenInclude methods.
Eager loading sends multiple queries when a collection navigation is included:

One query for the main query
One query for each collection "edge" in the load tree.
Separate queries with Load : The data can be retrieved in separate queries, and EF Core "fixes up" the
navigation properties. "fixes up" means that EF Core automatically populates the navigation properties.
Separate queries with Load is more like explict loading than eager loading.
Note: EF Core automatically fixes up navigation properties to any other entities that were previously loaded
into the context instance. Even if the data for a navigation property is not explicitly included, the property
may still be populated if some or all of the related entities were previously loaded.
Explicit loading. When the entity is first read, related data isn't retrieved. Code must be written to retrieve
the related data when it's needed. Explicit loading with separate queries results in multiple queries sent to
the DB. With explicit loading, the code specifies the navigation properties to be loaded. Use the Load
method to do explicit loading. For example:
Lazy loading. EF Core doesn't currently support lazy loading. When the entity is first read, related data isn't
retrieved. The first time a navigation property is accessed, the data required for that navigation property is
automatically retrieved. A query is sent to the DB each time a navigation property is accessed for the first
time.
The Select operator loads only the related data needed.
Create a Courses page that displays department name

The Course entity includes a navigation property that contains the Department entity. The Department entity
contains the department that the course is assigned to.
To display the name of the assigned department in a list of courses:
Get the Name property from the Department entity.
The Department entity comes from the Course.Department navigation property.
Scaffold the Course model
Visual Studio
.NET Core CLI
Follow the instructions in Scaffold the student model and use Course for the model class.
The preceding command scaffolds the Course model. Open the project in Visual Studio.
Open Pages/Courses/Index.cshtml.cs and examine the OnGetAsync method. The scaffolding engine specified eager
loading for the Department navigation property. The Include method specifies eager loading.
Run the app and select the Courses link. The department column displays the DepartmentID , which isn't useful.

{
Course = await _context.Courses
.Include(c => c.Department)
.AsNoTracking()
.ToListAsync();
}
The preceding code adds AsNoTracking . AsNoTracking improves performance because the entities returned are
not tracked. The entities are not tracked because they're not updated in the current context.
Update Pages/Courses/Index.cshtml with the following highlighted markup:
@page
@model ContosoUniversity.Pages.Courses.IndexModel
@{
ViewData["Title"] = "Courses";
}
<h2>Courses</h2>
<p>
<a asp-page="TestCreate">Create New</a>
</p>
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.Course[0].CourseID)
</th>
<th>
@Html.DisplayNameFor(model => model.Course[0].Title)
</th>
<th>
@Html.DisplayNameFor(model => model.Course[0].Credits)
</th>
<th>
@Html.DisplayNameFor(model => model.Course[0].Department)
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Course)
{
<tr>
<td>
@Html.DisplayFor(modelItem => item.CourseID)
</td>
<td>
</td>
<td>
@Html.DisplayFor(modelItem => item.Credits)
</td>
<td>
@Html.DisplayFor(modelItem => item.Department.Name)
</td>
<td>
<a asp-page="./Edit" asp-route-id="@item.CourseID">Edit</a> |
<a asp-page="./Details" asp-route-id="@item.CourseID">Details</a> |
<a asp-page="./Delete" asp-route-id="@item.CourseID">Delete</a>
</td>
</tr>
}
</tbody>
</table>
The following changes have been made to the scaffolded code:

Changed the heading from Index to Courses.
Added a Number column that shows the CourseID property value. By default, primary keys aren't
scaffolded because normally they're meaningless to end users. However, in this case the primary key is
meaningful.
Changed the Department column to display the department name. The code displays the Name property
of the Department entity that's loaded into the Department navigation property:
Run the app and select the Courses tab to see the list with department names.
Loading related data with Select

The OnGetAsync method loads related data with the Include method:

{
.AsNoTracking()
.ToListAsync();
}
The Select operator loads only the related data needed. For single items, like the Department.Name it uses a SQL
INNER JOIN. For collections, it uses another database access, but so does the Include operator on collections.
The following code loads related data with the Select method:
public IList<CourseViewModel> CourseVM { get; set; }

{
CourseVM = await _context.Courses
.Select(p => new CourseViewModel
{
CourseID = p.CourseID,
Title = p.Title,
Credits = p.Credits,
DepartmentName = p.Department.Name
}).ToListAsync();
}
The CourseViewModel :
public class CourseViewModel
{
public string DepartmentName { get; set; }
}
See IndexSelect.cshtml and IndexSelect.cshtml.cs for a complete example.
Create an Instructors page that shows Courses and Enrollments

In this section, the Instructors page is created.
This page reads and displays related data in the following ways:
The list of instructors displays related data from the OfficeAssignment entity (Office in the preceding image).
The Instructor and OfficeAssignment entities are in a one-to-zero-or-one relationship. Eager loading is used
for the OfficeAssignment entities. Eager loading is typically more efficient when the related data needs to be
displayed. In this case, office assignments for the instructors are displayed.
When the user selects an instructor (Harui in the preceding image), related Course entities are displayed. The
Instructor and Course entities are in a many-to-many relationship. Eager loading is used for the Course
entities and their related Department entities. In this case, separate queries might be more efficient because
only courses for the selected instructor are needed. This example shows how to use eager loading for
navigation properties in entities that are in navigation properties.
When the user selects a course (Chemistry in the preceding image), related data from the Enrollments entity is
displayed. In the preceding image, student name and grade are displayed. The Course and Enrollment entities
are in a one-to-many relationship.
Create a view model for the Instructor Index view
The instructors page shows data from three different tables. A view model is created that includes the three
entities representing the three tables.
In the SchoolViewModels folder, create InstructorIndexData.cs with the following code:
using System;
using System.Linq;
{
public class InstructorIndexData
{
public IEnumerable<Instructor> Instructors { get; set; }
public IEnumerable<Course> Courses { get; set; }
public IEnumerable<Enrollment> Enrollments { get; set; }
}
}
Scaffold the Instructor model

Visual Studio
.NET Core CLI
Follow the instructions in Scaffold the student model and use Instructor for the model class.
The preceding command scaffolds the Instructor model. Run the app and navigate to the instructors page.
Replace Pages/Instructors/Index.cshtml.cs with the following code:
using ContosoUniversity.Models.SchoolViewModels; // Add VM
using System.Linq;
namespace ContosoUniversity.Pages.Instructors
{
{
private readonly ContosoUniversity.Data.SchoolContext _context;
public IndexModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}
public InstructorIndexData Instructor { get; set; }

public async Task OnGetAsync(int? id)

{
Instructor = new InstructorIndexData();
Instructor.Instructors = await _context.Instructors
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.AsNoTracking()
.OrderBy(i => i.LastName)
.ToListAsync();
if (id != null)
{
InstructorID = id.Value;
}
}
}
}
The OnGetAsync method accepts optional route data for the ID of the selected instructor.
Examine the query in the Pages/Instructors/Index.cshtml.cs file:

.AsNoTracking()
.ToListAsync();
The query has two includes:

OfficeAssignment : Displayed in the instructors view.
CourseAssignments : Which brings in the courses taught.
Update the instructors Index page

Update Pages/Instructors/Index.cshtml with the following markup:
@page "{id:int?}"
@model ContosoUniversity.Pages.Instructors.IndexModel
@{
ViewData["Title"] = "Instructors";
}
<h2>Instructors</h2>
<p>
</p>
<thead>
<tr>
<th>Last Name</th>
<th>First Name</th>
<th>Hire Date</th>
<th>Office</th>
<th>Courses</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Instructor.Instructors)
{
string selectedRow = "";
if (item.ID == Model.InstructorID)
{
selectedRow = "success";
}
<tr class="@selectedRow">
<td>
</td>
<td>
</td>
<td>
@Html.DisplayFor(modelItem => item.HireDate)
</td>
<td>
@if (item.OfficeAssignment != null)
{
@item.OfficeAssignment.Location
}
</td>
<td>
@{
foreach (var course in item.CourseAssignments)
{
@course.Course.CourseID @: @course.Course.Title <br />
}
}
</td>
<td>
<a asp-page="./Index" asp-route-id="@item.ID">Select</a> |
</td>
</tr>
}
</tbody>
</table>
The preceding markup makes the following changes:
Updates the page directive from @page to @page "{id:int?}" . "{id:int?}" is a route template. The route
template changes integer query strings in the URL to route data. For example, clicking on the Select link
for an instructor with only the @page directive produces a URL like the following:
http://localhost:1234/Instructors?id=2
When the page directive is @page "{id:int?}" , the previous URL is:
http://localhost:1234/Instructors/2
Page title is Instructors.

Added an Office column that displays item.OfficeAssignment.Location only if item.OfficeAssignment isn't
null. Because this is a one-to-zero-or-one relationship, there might not be a related OfficeAssignment
entity.

{
}
Added a Courses column that displays courses taught by each instructor. See Explicit Line Transition with
@: for more about this razor syntax.
Added code that dynamically adds class="success" to the tr element of the selected instructor. This sets
a background color for the selected row using a Bootstrap class.

if (item.CourseID == Model.CourseID)
{
}
Added a new hyperlink labeled Select. This link sends the selected instructor's ID to the Index method
and sets a background color.
<a asp-action="Index" asp-route-id="@item.ID">Select</a> |
Run the app and select the Instructors tab. The page displays the Location (office) from the related
OfficeAssignment entity. If OfficeAssignment` is null, an empty table cell is displayed.
Click on the Select link. The row style changes.
Add courses taught by selected instructor
Update the OnGetAsync method in Pages/Instructors/Index.cshtml.cs with the following code:
public async Task OnGetAsync(int? id, int? courseID)

{
.ThenInclude(i => i.Department)
.AsNoTracking()
.ToListAsync();
if (id != null)
{
Instructor instructor = Instructor.Instructors.Where(
i => i.ID == id.Value).Single();
Instructor.Courses = instructor.CourseAssignments.Select(s => s.Course);
}
if (courseID != null)
{
CourseID = courseID.Value;
Instructor.Enrollments = Instructor.Courses.Where(
x => x.CourseID == courseID).Single().Enrollments;
}
}
Add public int CourseID { get; set; }

{
public IndexModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}
public InstructorIndexData Instructor { get; set; }


{
.AsNoTracking()
.ToListAsync();
if (id != null)
{
}
{
}
}
Examine the updated query:

.AsNoTracking()
.ToListAsync();
The preceding query adds the Department entities.

The following code executes when an instructor is selected ( id != null ). The selected instructor is retrieved from
the list of instructors in the view model. The view model's Courses property is loaded with the Course entities
from that instructor's CourseAssignments navigation property.
if (id != null)
{
}
The Where method returns a collection. In the preceding Where method, only a single Instructor entity is
returned. The Single method converts the collection into a single Instructor entity. The Instructor entity
provides access to the CourseAssignments property. CourseAssignments provides access to the related Course
entities.
The Single method is used on a collection when the collection has only one item. The Single method throws an
exception if the collection is empty or if there's more than one item. An alternative is SingleOrDefault , which
returns a default value (null in this case) if the collection is empty. Using SingleOrDefault on an empty collection:
Results in an exception (from trying to find a Courses property on a null reference).
The exception message would less clearly indicate the cause of the problem.
The following code populates the view model's Enrollments property when a course is selected:
{
}
Add the following markup to the end of the Pages/Instructors/Index.cshtml Razor Page:
</td>
</tr>
}
</tbody>
</table>
@if (Model.Instructor.Courses != null)

{
<h3>Courses Taught by Selected Instructor</h3>
<tr>
<th></th>
<th>Number</th>
<th>Title</th>
<th>Department</th>
</tr>
@foreach (var item in Model.Instructor.Courses)

{
if (item.CourseID == Model.CourseID)
{
}
<td>
<a asp-page="./Index" asp-route-courseID="@item.CourseID">Select</a>
</td>
<td>
@item.CourseID
</td>
<td>
@item.Title
</td>
<td>
@item.Department.Name
</td>
</tr>
}
</table>
}
The preceding markup displays a list of courses related to an instructor when an instructor is selected.
Test the app. Click on a Select link on the instructors page.
Show student data
In this section, the app is updated to show the student data for a selected course.
Update the query in the OnGetAsync method in Pages/Instructors/Index.cshtml.cs with the following code:

.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.AsNoTracking()
.ToListAsync();
Update Pages/Instructors/Index.cshtml. Add the following markup to the end of the file:
@if (Model.Instructor.Enrollments != null)
{
<h3>
Students Enrolled in Selected Course
</h3>
<tr>
<th>Name</th>
<th>Grade</th>
</tr>
@foreach (var item in Model.Instructor.Enrollments)
{
<tr>
<td>
@item.Student.FullName
</td>
<td>
</td>
</tr>
}
</table>
}
The preceding markup displays a list of the students who are enrolled in the selected course.
Refresh the page and select an instructor. Select a course to see the list of enrolled students and their grades.
Using Single
The Single method can pass in the Where condition instead of calling the Where method separately:
{

.AsNoTracking()
.ToListAsync();
if (id != null)
{
Instructor instructor = Instructor.Instructors.Single(
i => i.ID == id.Value);
Instructor.Courses = instructor.CourseAssignments.Select(
s => s.Course);
}
{
Instructor.Enrollments = Instructor.Courses.Single(
x => x.CourseID == courseID).Enrollments;
}
}
The preceding Single approach provides no benefits over using Where . Some developers prefer the Single
approach style.
Explicit loading
The current code specifies eager loading for Enrollments and Students :

.AsNoTracking()
.ToListAsync();
Suppose users rarely want to see enrollments in a course. In that case, an optimization would be to only load the
enrollment data if it's requested. In this section, the OnGetAsync is updated to use explicit loading of Enrollments
and Students .
Update the OnGetAsync with the following code:
{
//.Include(i => i.CourseAssignments)
// .ThenInclude(i => i.Course)
// .ThenInclude(i => i.Enrollments)
// .ThenInclude(i => i.Student)
// .AsNoTracking()
.ToListAsync();
if (id != null)
{
}
{
var selectedCourse = Instructor.Courses.Where(x => x.CourseID == courseID).Single();
await _context.Entry(selectedCourse).Collection(x => x.Enrollments).LoadAsync();
foreach (Enrollment enrollment in selectedCourse.Enrollments)
{
await _context.Entry(enrollment).Reference(x => x.Student).LoadAsync();
}
Instructor.Enrollments = selectedCourse.Enrollments;
}
}
The preceding code drops the ThenInclude method calls for enrollment and student data. If a course is selected,
the highlighted code retrieves:
The Enrollment entities for the selected course.
The Student entities for each Enrollment .
Notice the preceding code comments out .AsNoTracking() . Navigation properties can only be explicitly loaded for
tracked entities.
Test the app. From a users perspective, the app behaves identically to the previous version.
The next tutorial shows how to update related data.
P R E V IO U S NEXT
Razor Pages with EF Core in ASP.NET Core - Update
Related Data - 7 of 8
By Tom Dykstra, and Rick Anderson

This tutorial demonstrates updating related data. If you run into problems you can't solve, download or view the
completed app. Download instructions.
The following illustrations shows some of the completed pages.
Examine and test the Create and Edit course pages. Create a new course. The department is selected by its
primary key (an integer), not its name. Edit the new course. When you have finished testing, delete the new
course.
Create a base class to share common code

The Courses/Create and Courses/Edit pages each need a list of department names. Create the
Pages/Courses/DepartmentNamePageModel.cshtml.cs base class for the Create and Edit pages:
using System.Linq;
namespace ContosoUniversity.Pages.Courses
{
public class DepartmentNamePageModel : PageModel
{
public SelectList DepartmentNameSL { get; set; }
public void PopulateDepartmentsDropDownList(SchoolContext _context,

object selectedDepartment = null)
{
var departmentsQuery = from d in _context.Departments
orderby d.Name // Sort by name.
select d;
DepartmentNameSL = new SelectList(departmentsQuery.AsNoTracking(),

"DepartmentID", "Name", selectedDepartment);
}
}
}
The preceding code creates a SelectList to contain the list of department names. If selectedDepartment is
specified, that department is selected in the SelectList .
The Create and Edit page model classes will derive from DepartmentNamePageModel .
Customize the Courses Pages

When a new course entity is created, it must have a relationship to an existing department. To add a department
while creating a course, the base class for Create and Edit contains a drop-down list for selecting the department.
The drop-down list sets the Course.DepartmentID foreign key (FK) property. EF Core uses the Course.DepartmentID
FK to load the Department navigation property.
Update the Create page model with the following code:
{
public class CreateModel : DepartmentNamePageModel
{
public CreateModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

{
PopulateDepartmentsDropDownList(_context);
return Page();
}
[BindProperty]

{
{
return Page();
}
var emptyCourse = new Course();
if (await TryUpdateModelAsync<Course>(
emptyCourse,
"course", // Prefix for form value.
s => s.CourseID, s => s.DepartmentID, s => s.Title, s => s.Credits))
{
_context.Courses.Add(emptyCourse);
}
// Select DepartmentID if TryUpdateModelAsync fails.

PopulateDepartmentsDropDownList(_context, emptyCourse.DepartmentID);
return Page();
}
}
}
The preceding code:

Derives from DepartmentNamePageModel .
Uses TryUpdateModelAsync to prevent overposting.
Replaces ViewData["DepartmentID"] with DepartmentNameSL (from the base class).
ViewData["DepartmentID"] is replaced with the strongly typed DepartmentNameSL . Strongly typed models are
preferred over weakly typed. For more information, see Weakly typed data (ViewData and ViewBag).
Update the Courses Create page
Update Pages/Courses/Create.cshtml with the following markup:
@page
@model ContosoUniversity.Pages.Courses.CreateModel
@{
ViewData["Title"] = "Create Course";
}
<h2>Create</h2>
<h4>Course</h4>
<hr />
<div class="row">
<label asp-for="Course.CourseID" class="control-label"></label>
<input asp-for="Course.CourseID" class="form-control" />
<span asp-validation-for="Course.CourseID" class="text-danger"></span>
</div>
<label asp-for="Course.Title" class="control-label"></label>
<input asp-for="Course.Title" class="form-control" />
<span asp-validation-for="Course.Title" class="text-danger"></span>
</div>
<label asp-for="Course.Credits" class="control-label"></label>
<input asp-for="Course.Credits" class="form-control" />
<span asp-validation-for="Course.Credits" class="text-danger"></span>
</div>
<label asp-for="Course.Department" class="control-label"></label>
<select asp-for="Course.DepartmentID" class="form-control"
asp-items="@Model.DepartmentNameSL">
<option value="">-- Select Department --</option>
</select>
<span asp-validation-for="Course.DepartmentID" class="text-danger" />
</div>
</div>
</form>
</div>
</div>
<div>
</div>
@section Scripts {
}

Changes the caption from DepartmentID to Department.
Replaces "ViewBag.DepartmentID" with DepartmentNameSL (from the base class).
Adds the "Select Department" option. This change renders "Select Department" rather than the first
department.
Adds a validation message when the department isn't selected.
The Razor Page uses the Select Tag Helper:
asp-items="@Model.DepartmentNameSL">
</select>
<span asp-validation-for="Course.DepartmentID" class="text-danger" />
</div>
Test the Create page. The Create page displays the department name rather than the department ID.
Update the Courses Edit page.
Update the edit page model with the following code:
{
public class EditModel : DepartmentNamePageModel
{
public EditModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}

.Include(c => c.Department).FirstOrDefaultAsync(m => m.CourseID == id);
if (Course == null)
{
return NotFound();
}
// Select current DepartmentID.

PopulateDepartmentsDropDownList(_context,Course.DepartmentID);
return Page();
}

{
{
return Page();
}
var courseToUpdate = await _context.Courses.FindAsync(id);
if (await TryUpdateModelAsync<Course>(
courseToUpdate,
"course", // Prefix for form value.
c => c.Credits, c => c.DepartmentID, c => c.Title))
{
}
// Select DepartmentID if TryUpdateModelAsync fails.

PopulateDepartmentsDropDownList(_context, courseToUpdate.DepartmentID);
return Page();
}
}
}
The changes are similar to those made in the Create page model. In the preceding code,
PopulateDepartmentsDropDownList passes in the department ID, which select the department specified in the drop-
down list.
Update Pages/Courses/Edit.cshtml with the following markup:
@page
@model ContosoUniversity.Pages.Courses.EditModel
@{
}
<h2>Edit</h2>
<h4>Course</h4>
<hr />
<div class="row">
<input type="hidden" asp-for="Course.CourseID" />
<label asp-for="Course.CourseID" class="control-label"></label>
<div>@Html.DisplayFor(model => model.Course.CourseID)</div>
</div>
<label asp-for="Course.Title" class="control-label"></label>
<input asp-for="Course.Title" class="form-control" />
<span asp-validation-for="Course.Title" class="text-danger"></span>
</div>
<label asp-for="Course.Credits" class="control-label"></label>
<input asp-for="Course.Credits" class="form-control" />
<span asp-validation-for="Course.Credits" class="text-danger"></span>
</div>
asp-items="@Model.DepartmentNameSL"></select>
<span asp-validation-for="Course.DepartmentID" class="text-danger"></span>
</div>
</div>
</form>
</div>
</div>
<div>
</div>
@section Scripts {
}

Displays the course ID. Generally the Primary Key (PK) of an entity isn't displayed. PKs are usually meaningless
to users. In this case, the PK is the course number.
Changes the caption from DepartmentID to Department.
Replaces "ViewBag.DepartmentID" with DepartmentNameSL (from the base class).
The page contains a hidden field ( <input type="hidden"> ) for the course number. Adding a <label> tag helper
with asp-for="Course.CourseID" doesn't eliminate the need for the hidden field. <input type="hidden"> is required
for the course number to be included in the posted data when the user clicks Save.
Test the updated code. Create, edit, and delete a course.
Add AsNoTracking to the Details and Delete page models

AsNoTracking can improve performance when tracking isn't required. Add AsNoTracking to the Delete and Details
page model. The following code shows the updated Delete page model:

{
public DeleteModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}

.AsNoTracking()
.FirstOrDefaultAsync(m => m.CourseID == id);
if (Course == null)
{
return NotFound();
}
return Page();
}

{
if (id == null)
{
return NotFound();
}

.AsNoTracking()
if (Course != null)
{
_context.Courses.Remove(Course);
}
}
}
Update the OnGetAsync method in the Pages/Courses/Details.cshtml.cs file:

{
if (id == null)
{
return NotFound();
}

.AsNoTracking()
if (Course == null)
{
return NotFound();
}
return Page();
}
Modify the Delete and Details pages

Update the Delete Razor page with the following markup:
@page
@model ContosoUniversity.Pages.Courses.DeleteModel
@{
}
<h2>Delete</h2>

<div>
<h4>Course</h4>
<hr />
<dt>
@Html.DisplayNameFor(model => model.Course.CourseID)
</dt>
<dd>
@Html.DisplayFor(model => model.Course.CourseID)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Course.Title)
</dt>
<dd>
@Html.DisplayFor(model => model.Course.Title)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Course.Credits)
</dt>
<dd>
@Html.DisplayFor(model => model.Course.Credits)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Course.Department)
</dt>
<dd>
@Html.DisplayFor(model => model.Course.Department.DepartmentID)
</dd>
</dl>
<input type="hidden" asp-for="Course.CourseID" />
<input type="submit" value="Delete" class="btn btn-default" /> |
</form>
</div>
Make the same changes to the Details page.

Test the Course pages
Test create, edit, details, and delete.
Update the instructor pages

The following sections update the instructor pages.
Add office location
When editing an instructor record, you may want to update the instructor's office assignment. The Instructor
entity has a one-to-zero-or-one relationship with the OfficeAssignment entity. The instructor code must handle:
If the user clears the office assignment, delete the OfficeAssignment entity.
If the user enters an office assignment and it was empty, create a new OfficeAssignment entity.
If the user changes the office assignment, update the OfficeAssignment entity.
Update the instructors Edit page model with the following code:

{

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}
Instructor = await _context.Instructors

.AsNoTracking()
if (Instructor == null)
{
return NotFound();
}
return Page();
}

{
{
return Page();
}
var instructorToUpdate = await _context.Instructors

.FirstOrDefaultAsync(s => s.ID == id);
if (await TryUpdateModelAsync<Instructor>(
instructorToUpdate,
"Instructor",
i => i.FirstMidName, i => i.LastName,
i => i.HireDate, i => i.OfficeAssignment))
{
if (String.IsNullOrWhiteSpace(
instructorToUpdate.OfficeAssignment?.Location))
{
instructorToUpdate.OfficeAssignment = null;
}
}
}
}
The preceding code:

Gets the current Instructor entity from the database using eager loading for the OfficeAssignment navigation
property.
Updates the retrieved Instructor entity with values from the model binder. TryUpdateModel prevents
overposting.
If the office location is blank, sets Instructor.OfficeAssignment to null. When Instructor.OfficeAssignment is
null, the related row in the OfficeAssignment table is deleted.
Update the instructor Edit page
Update Pages/Instructors/Edit.cshtml with the office location:
@page
@model ContosoUniversity.Pages.Instructors.EditModel
@{
}
<h2>Edit</h2>
<h4>Instructor</h4>
<hr />
<div class="row">
<input type="hidden" asp-for="Instructor.ID" />
<label asp-for="Instructor.LastName" class="control-label"></label>
<input asp-for="Instructor.LastName" class="form-control" />
<span asp-validation-for="Instructor.LastName" class="text-danger"></span>
</div>
<label asp-for="Instructor.FirstMidName" class="control-label"></label>
<input asp-for="Instructor.FirstMidName" class="form-control" />
<span asp-validation-for="Instructor.FirstMidName" class="text-danger"></span>
</div>
<label asp-for="Instructor.HireDate" class="control-label"></label>
<input asp-for="Instructor.HireDate" class="form-control" />
<span asp-validation-for="Instructor.HireDate" class="text-danger"></span>
</div>
<label asp-for="Instructor.OfficeAssignment.Location" class="control-label"></label>
<input asp-for="Instructor.OfficeAssignment.Location" class="form-control" />
<span asp-validation-for="Instructor.OfficeAssignment.Location" class="text-danger" />
</div>
</div>
</form>
</div>
</div>
<div>
</div>
@section Scripts {
}
Verify you can change an instructors office location.
Add Course assignments to the instructor Edit page

Instructors may teach any number of courses. In this section, you add the ability to change course assignments.
The following image shows the updated instructor Edit page:
Course and Instructor has a many-to-many relationship. To add and remove relationships, you add and remove
entities from the CourseAssignments join entity set.
Check boxes enable changes to courses an instructor is assigned to. A check box is displayed for every course in
the database. Courses that the instructor is assigned to are checked. The user can select or clear check boxes to
change course assignments. If the number of courses were much greater:
You'd probably use a different user interface to display the courses.
The method of manipulating a join entity to create or delete relationships wouldn't change.
Add classes to support Create and Edit instructor pages
Create SchoolViewModels/AssignedCourseData.cs with the following code:
{
public class AssignedCourseData
{
public bool Assigned { get; set; }
}
}
The AssignedCourseData class contains data to create the check boxes for assigned courses by an instructor.
Create the Pages/Instructors/InstructorCoursesPageModel.cshtml.cs base class:
using System.Linq;
{
public class InstructorCoursesPageModel : PageModel
{
public List<AssignedCourseData> AssignedCourseDataList;
public void PopulateAssignedCourseData(SchoolContext context,

Instructor instructor)
{
var allCourses = context.Courses;
var instructorCourses = new HashSet<int>(
instructor.CourseAssignments.Select(c => c.CourseID));
AssignedCourseDataList = new List<AssignedCourseData>();
foreach (var course in allCourses)
{
AssignedCourseDataList.Add(new AssignedCourseData
{
CourseID = course.CourseID,
Title = course.Title,
Assigned = instructorCourses.Contains(course.CourseID)
});
}
}
public void UpdateInstructorCourses(SchoolContext context,

string[] selectedCourses, Instructor instructorToUpdate)
{
if (selectedCourses == null)
{
instructorToUpdate.CourseAssignments = new List<CourseAssignment>();
return;
}
var selectedCoursesHS = new HashSet<string>(selectedCourses);

var instructorCourses = new HashSet<int>
(instructorToUpdate.CourseAssignments.Select(c => c.Course.CourseID));
foreach (var course in context.Courses)
{
if (selectedCoursesHS.Contains(course.CourseID.ToString()))
{
if (!instructorCourses.Contains(course.CourseID))
{
instructorToUpdate.CourseAssignments.Add(
new CourseAssignment
{
InstructorID = instructorToUpdate.ID,
CourseID = course.CourseID
});
}
}
else
{
if (instructorCourses.Contains(course.CourseID))
{
CourseAssignment courseToRemove
= instructorToUpdate
.CourseAssignments
.SingleOrDefault(i => i.CourseID == course.CourseID);
.SingleOrDefault(i => i.CourseID == course.CourseID);
context.Remove(courseToRemove);
}
}
}
}
}
}
The InstructorCoursesPageModel is the base class you will use for the Edit and Create page models.
PopulateAssignedCourseData reads all Course entities to populate AssignedCourseDataList . For each course, the
code sets the CourseID , title, and whether or not the instructor is assigned to the course. A HashSet is used to
create efficient lookups.
Instructors Edit page model
Update the instructor Edit page model with the following code:
public class EditModel : InstructorCoursesPageModel
{

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}
Instructor = await _context.Instructors

.Include(i => i.CourseAssignments).ThenInclude(i => i.Course)
.AsNoTracking()
{
return NotFound();
}
PopulateAssignedCourseData(_context, Instructor);
return Page();
}
public async Task<IActionResult> OnPostAsync(int? id, string[] selectedCourses)

{
{
return Page();
}

.FirstOrDefaultAsync(s => s.ID == id);
instructorToUpdate,
"Instructor",
{
if (String.IsNullOrWhiteSpace(
instructorToUpdate.OfficeAssignment?.Location))
{
}
UpdateInstructorCourses(_context, selectedCourses, instructorToUpdate);
}
UpdateInstructorCourses(_context, selectedCourses, instructorToUpdate);
PopulateAssignedCourseData(_context, instructorToUpdate);
return Page();
}
}
The preceding code handles office assignment changes.
Update the instructor Razor View:
@page
@model ContosoUniversity.Pages.Instructors.EditModel
@{
}
<h2>Edit</h2>
<h4>Instructor</h4>
<hr />
<div class="row">
<input type="hidden" asp-for="Instructor.ID" />
</div>
</div>
</div>
</div>
<table>
<tr>
@{
int cnt = 0;
foreach (var course in Model.AssignedCourseDataList)

{
if (cnt++ % 3 == 0)
{
@:</tr><tr>
}
@:<td>
<input type="checkbox"
name="selectedCourses"
value="@course.CourseID"
@(Html.Raw(course.Assigned ? "checked=\"checked\"" : "")) />
@course.CourseID @: @course.Title
@:</td>
}
@:</tr>
}
</table>
</div>
</div>
</div>
</form>
</div>
</div>
</div>
<div>
</div>
@section Scripts {
}
NOTE
When you paste the code in Visual Studio, line breaks are changed in a way that breaks the code. Press Ctrl+Z one time to
undo the automatic formatting. Ctrl+Z fixes the line breaks so that they look like what you see here. The indentation doesn't
have to be perfect, but the @</tr><tr> , @:<td> , @:</td> , and @:</tr> lines must each be on a single line as shown.
With the block of new code selected, press Tab three times to line up the new code with the existing code. Vote on or review
the status of this bug with this link.
The preceding code creates an HTML table that has three columns. Each column has a check box and a caption
containing the course number and title. The check boxes all have the same name ("selectedCourses"). Using the
same name informs the model binder to treat them as a group. The value attribute of each check box is set to
CourseID . When the page is posted, the model binder passes an array that consists of the CourseID values for
only the check boxes that are selected.
When the check boxes are initially rendered, courses assigned to the instructor have checked attributes.
Run the app and test the updated instructors Edit page. Change some course assignments. The changes are
reflected on the Index page.
Note: The approach taken here to edit instructor course data works well when there's a limited number of courses.
For collections that are much larger, a different UI and a different updating method would be more useable and
efficient.
Update the instructors Create page
Update the instructor Create page model with the following code:
{
public class CreateModel : InstructorCoursesPageModel
{
public CreateModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

{
var instructor = new Instructor();
instructor.CourseAssignments = new List<CourseAssignment>();
// Provides an empty collection for the foreach loop

// foreach (var course in Model.AssignedCourseDataList)
// in the Create Razor page.
PopulateAssignedCourseData(_context, instructor);
PopulateAssignedCourseData(_context, instructor);
return Page();
}
[BindProperty]
public async Task<IActionResult> OnPostAsync(string[] selectedCourses)

{
{
return Page();
}
var newInstructor = new Instructor();

if (selectedCourses != null)
{
newInstructor.CourseAssignments = new List<CourseAssignment>();
foreach (var course in selectedCourses)
{
var courseToAdd = new CourseAssignment
{
CourseID = int.Parse(course)
};
newInstructor.CourseAssignments.Add(courseToAdd);
}
}
newInstructor,
"Instructor",
{
_context.Instructors.Add(newInstructor);
}
PopulateAssignedCourseData(_context, newInstructor);
return Page();
}
}
}
The preceding code is similar to the Pages/Instructors/Edit.cshtml.cs code.

Update the instructor Create Razor page with the following markup:
@page
@model ContosoUniversity.Pages.Instructors.CreateModel
@{
}
<h2>Create</h2>
<h4>Instructor</h4>
<hr />
<div class="row">
</div>
</div>
</div>
</div>
</div>
<table>
<tr>
@{
int cnt = 0;
foreach (var course in Model.AssignedCourseDataList)

{
if (cnt++ % 3 == 0)
{
@:</tr><tr>
}
@:<td>
@:</td>
}
@:</tr>
}
</table>
</div>
</div>
</div>
</form>
</div>
</div>
<div>
</div>
@section Scripts {
}
Test the instructor Create page.

Update the Delete page model with the following code:
using System.Linq;
{
{

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}
Instructor = await _context.Instructors.SingleAsync(m => m.ID == id);
{
return NotFound();
}
return Page();
}
public async Task<IActionResult> OnPostAsync(int id)

{
Instructor instructor = await _context.Instructors
.SingleAsync(i => i.ID == id);
var departments = await _context.Departments

.Where(d => d.InstructorID == id)
.ToListAsync();
departments.ForEach(d => d.InstructorID = null);
_context.Instructors.Remove(instructor);
}
}
}
The preceding code makes the following changes:

Uses eager loading for the CourseAssignments navigation property. CourseAssignments must be included or
they aren't deleted when the instructor is deleted. To avoid needing to read them, configure cascade delete
in the database.
If the instructor to be deleted is assigned as administrator of any departments, removes the instructor
assignment from those departments.
P R E V IO U S NEXT
Razor Pages with EF Core in ASP.NET Core -
Concurrency - 8 of 8
By Rick Anderson, Tom Dykstra, and Jon P Smith

This tutorial shows how to handle conflicts when multiple users update an entity concurrently (at the same time).
If you run into problems you can't solve, download or view the completed app. Download instructions.
Concurrency conflicts
A concurrency conflict occurs when:
A user navigates to the edit page for an entity.
Another user updates the same entity before the first user's change is written to the DB.
If concurrency detection isn't enabled, when concurrent updates occur:
The last update wins. That is, the last update values are saved to the DB.
The first of the current updates are lost.
Optimistic concurrency
Optimistic concurrency allows concurrency conflicts to happen, and then reacts appropriately when they do. For
example, Jane visits the Department edit page and changes the budget for the English department from
$350,000.00 to $0.00.
Before Jane clicks Save, John visits the same page and changes the Start Date field from 9/1/2007 to 9/1/2013.
Jane clicks Save first and sees her change when the browser displays the Index page.
John clicks Save on an Edit page that still shows a budget of $350,000.00. What happens next is determined by
how you handle concurrency conflicts.
Optimistic concurrency includes the following options:
You can keep track of which property a user has modified and update only the corresponding columns in
the DB.
In the scenario, no data would be lost. Different properties were updated by the two users. The next time
someone browses the English department, they will see both Jane's and John's changes. This method of
updating can reduce the number of conflicts that could result in data loss. This approach:
Can't avoid data loss if competing changes are made to the same property.
Is generally not practical in a web app. It requires maintaining significant state in order to keep track of
all fetched values and new values. Maintaining large amounts of state can affect app performance.
Can increase app complexity compared to concurrency detection on an entity.
You can let John's change overwrite Jane's change.
The next time someone browses the English department, they will see 9/1/2013 and the fetched
$350,000.00 value. This approach is called a Client Wins or Last in Wins scenario. (All values from the
client take precedence over what's in the data store.) If you don't do any coding for concurrency handling,
Client Wins happens automatically.
You can prevent John's change from being updated in the DB. Typically, the app would:
Display an error message.
Show the current state of the data.
Allow the user to reapply the changes.
This is called a Store Wins scenario. (The data-store values take precedence over the values submitted by
the client.) You implement the Store Wins scenario in this tutorial. This method ensures that no changes
are overwritten without a user being alerted.
Handling concurrency
When a property is configured as a concurrency token:
EF Core verifies that property has not been modified after it was fetched. The check occurs when
SaveChanges or SaveChangesAsync is called.
If the property has been changed after it was fetched, a DbUpdateConcurrencyException is thrown.
The DB and data model must be configured to support throwing DbUpdateConcurrencyException .
Detecting concurrency conflicts on a property
Concurrency conflicts can be detected at the property level with the ConcurrencyCheck attribute. The attribute
can be applied to multiple properties on the model. For more information, see Data Annotations-
ConcurrencyCheck.
The [ConcurrencyCheck] attribute isn't used in this tutorial.
Detecting concurrency conflicts on a row
To detect concurrency conflicts, a rowversion tracking column is added to the model. rowversion :
Is SQL Server specific. Other databases may not provide a similar feature.
Is used to determine that an entity has not been changed since it was fetched from the DB.
The DB generates a sequential rowversion number that's incremented each time the row is updated. In an
Update or Delete command, the Where clause includes the fetched value of rowversion . If the row being
updated has changed:
rowversion doesn't match the fetched value.
The Update or Delete commands don't find a row because the Where clause includes the fetched
rowversion .
A DbUpdateConcurrencyException is thrown.
In EF Core, when no rows have been updated by an Update or Delete command, a concurrency exception is
thrown.
Add a tracking property to the Department entity
In Models/Department.cs, add a tracking property named RowVersion:
using System;
{
{

[Timestamp]
public byte[] RowVersion { get; set; }

}
}
The Timestamp attribute specifies that this column is included in the Where clause of Update and Delete
commands. The attribute is called Timestamp because previous versions of SQL Server used a SQL timestamp
data type before the SQL rowversion type replaced it.
The fluent API can also specify the tracking property:
.Property<byte[]>("RowVersion")
.IsRowVersion();
The following code shows a portion of the T-SQL generated by EF Core when the Department name is updated:
SET NOCOUNT ON;

UPDATE [Department] SET [Name] = @p0
WHERE [DepartmentID] = @p1 AND [RowVersion] = @p2;
SELECT [RowVersion]
FROM [Department]
WHERE @@ROWCOUNT = 1 AND [DepartmentID] = @p1;
The preceding highlighted code shows the WHERE clause containing RowVersion . If the DB RowVersion doesn't
equal the RowVersion parameter ( @p2 ), no rows are updated.
The following highlighted code shows the T-SQL that verifies exactly one row was updated:
SET NOCOUNT ON;
UPDATE [Department] SET [Name] = @p0
WHERE [DepartmentID] = @p1 AND [RowVersion] = @p2;
SELECT [RowVersion]
FROM [Department]
WHERE @@ROWCOUNT = 1 AND [DepartmentID] = @p1;
@@ROWCOUNT returns the number of rows affected by the last statement. In no rows are updated, EF Core
throws a DbUpdateConcurrencyException .
You can see the T-SQL EF Core generates in the output window of Visual Studio.
Update the DB
Adding the RowVersion property changes the DB model, which requires a migration.
Build the project. Enter the following in a command window:
dotnet ef migrations add RowVersion

The preceding commands:

Adds the Migrations/{time stamp }_RowVersion.cs migration file.
Updates the Migrations/SchoolContextModelSnapshot.cs file. The update adds the following highlighted
code to the BuildModel method:
modelBuilder.Entity("ContosoUniversity.Models.Department", b =>
{
b.Property<int>("DepartmentID")
.ValueGeneratedOnAdd();
b.Property<decimal>("Budget")
.HasColumnType("money");
b.Property<int?>("InstructorID");
b.Property<string>("Name")
.HasMaxLength(50);
b.Property<byte[]>("RowVersion")
.IsConcurrencyToken()
.ValueGeneratedOnAddOrUpdate();
b.Property<DateTime>("StartDate");
b.HasKey("DepartmentID");
b.HasIndex("InstructorID");
b.ToTable("Department");
});
Runs migrations to update the DB.
Scaffold the Departments model

Visual Studio
.NET Core CLI
Follow the instructions in Scaffold the student model and use Department for the model class.
The preceding command scaffolds the Department model. Open the project in Visual Studio.
Build the project.
Update the Departments Index page
The scaffolding engine created a RowVersion column for the Index page, but that field shouldn't be displayed. In
this tutorial, the last byte of the RowVersion is displayed to help understand concurrency. The last byte isn't
guaranteed to be unique. A real app wouldn't display RowVersion or the last byte of RowVersion .
Update the Index page:
Replace Index with Departments.
Replace the markup containing RowVersion with the last byte of RowVersion .
Replace FirstMidName with FullName.
The following markup shows the updated page:
@page
@model ContosoUniversity.Pages.Departments.IndexModel
@{
ViewData["Title"] = "Departments";
}
<h2>Departments</h2>
<p>
</p>
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.Department[0].Name)
</th>
<th>
@Html.DisplayNameFor(model => model.Department[0].Budget)
</th>
<th>
@Html.DisplayNameFor(model => model.Department[0].StartDate)
</th>
<th>
@Html.DisplayNameFor(model => model.Department[0].Administrator)
</th>
<th>
RowVersion
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Department) {
<tr>
<td>
@Html.DisplayFor(modelItem => item.Name)
</td>
<td>
@Html.DisplayFor(modelItem => item.Budget)
</td>
<td>
@Html.DisplayFor(modelItem => item.StartDate)
</td>
<td>
@Html.DisplayFor(modelItem => item.Administrator.FullName)
</td>
<td>
@item.RowVersion[7]
</td>
<td>
<a asp-page="./Edit" asp-route-id="@item.DepartmentID">Edit</a> |
<a asp-page="./Details" asp-route-id="@item.DepartmentID">Details</a> |
<a asp-page="./Delete" asp-route-id="@item.DepartmentID">Delete</a>
</td>
</tr>
}
</tbody>
</table>
Update the Edit page model

Update pages\departments\edit.cshtml.cs with the following code:
using System.Linq;
namespace ContosoUniversity.Pages.Departments
{
{

{
_context = context;
}
[BindProperty]
// Replace ViewData["InstructorID"]
public SelectList InstructorNameSL { get; set; }

{
Department = await _context.Departments
.Include(d => d.Administrator) // eager loading
.AsNoTracking() // tracking not required
.FirstOrDefaultAsync(m => m.DepartmentID == id);
if (Department == null)
{
return NotFound();
}
// Use strongly typed data rather than ViewData.

InstructorNameSL = new SelectList(_context.Instructors,
"ID", "FirstMidName");
return Page();
}

{
{
return Page();
}
var departmentToUpdate = await _context.Departments

.Include(i => i.Administrator)
// null means Department was deleted by another user.

if (departmentToUpdate == null)
{
return await HandleDeletedDepartment();
}
// Update the RowVersion to the value when this entity was

// fetched. If the entity has been updated after it was
// fetched, RowVersion won't match the DB RowVersion and
// a DbUpdateConcurrencyException is thrown.
// A second postback will make them match, unless a new
// concurrency issue happens.
_context.Entry(departmentToUpdate)
.Property("RowVersion").OriginalValue = Department.RowVersion;
if (await TryUpdateModelAsync<Department>(
departmentToUpdate,
"Department",
s => s.Name, s => s.StartDate, s => s.Budget, s => s.InstructorID))
{
try
{
}
catch (DbUpdateConcurrencyException ex)
{
var exceptionEntry = ex.Entries.Single();
var clientValues = (Department)exceptionEntry.Entity;
var databaseEntry = exceptionEntry.GetDatabaseValues();
if (databaseEntry == null)
{
ModelState.AddModelError(string.Empty, "Unable to save. " +
"The department was deleted by another user.");
return Page();
}
var dbValues = (Department)databaseEntry.ToObject();

await setDbErrorMessage(dbValues, clientValues, _context);
// Save the current RowVersion so next postback

// matches unless an new concurrency issue happens.
Department.RowVersion = (byte[])dbValues.RowVersion;
// Must clear the model error for the next postback.
ModelState.Remove("Department.RowVersion");
}
}
InstructorNameSL = new SelectList(_context.Instructors,

"ID", "FullName", departmentToUpdate.InstructorID);
return Page();
}
private async Task<IActionResult> HandleDeletedDepartment()

{
Department deletedDepartment = new Department();
// ModelState contains the posted data because of the deletion error and will overide the
Department instance values when displaying Page().
ModelState.AddModelError(string.Empty,
"Unable to save. The department was deleted by another user.");
InstructorNameSL = new SelectList(_context.Instructors, "ID", "FullName",
Department.InstructorID);
return Page();
}
private async Task setDbErrorMessage(Department dbValues,

Department clientValues, SchoolContext context)
{
if (dbValues.Name != clientValues.Name)
{
ModelState.AddModelError("Department.Name",
$"Current value: {dbValues.Name}");
}
if (dbValues.Budget != clientValues.Budget)
{
ModelState.AddModelError("Department.Budget",
$"Current value: {dbValues.Budget:c}");
}
if (dbValues.StartDate != clientValues.StartDate)
{
ModelState.AddModelError("Department.StartDate",
$"Current value: {dbValues.StartDate:d}");
}
if (dbValues.InstructorID != clientValues.InstructorID)
{
Instructor dbInstructor = await _context.Instructors
.FindAsync(dbValues.InstructorID);
ModelState.AddModelError("Department.InstructorID",
$"Current value: {dbInstructor?.FullName}");
}
"The record you attempted to edit "
+ "was modified by another user after you. The "
+ "edit operation was canceled and the current values in the database "
+ "have been displayed. If you still want to edit this record, click "
+ "the Save button again.");
}
}
}
To detect a concurrency issue, the OriginalValue is updated with the rowVersion value from the entity it was
fetched. EF Core generates a SQL UPDATE command with a WHERE clause containing the original RowVersion
value. If no rows are affected by the UPDATE command (no rows have the original RowVersion value), a
DbUpdateConcurrencyException exception is thrown.

{
{
return Page();
}
var departmentToUpdate = await _context.Departments

// null means Department was deleted by another user.

{
return await HandleDeletedDepartment();
}
// Update the RowVersion to the value when this entity was

// fetched. If the entity has been updated after it was
// fetched, RowVersion won't match the DB RowVersion and
// a DbUpdateConcurrencyException is thrown.
// A second postback will make them match, unless a new
// concurrency issue happens.
_context.Entry(departmentToUpdate)
.Property("RowVersion").OriginalValue = Department.RowVersion;
In the preceding code, Department.RowVersion is the value when the entity was fetched. OriginalValue is the value
in the DB when FirstOrDefaultAsync was called in this method.
The following code gets the client values (the values posted to this method) and the DB values:
try
{
}
{
{
return Page();
}


}
The follwing code adds a custom error message for each column that has DB values different from what was
posted to OnPostAsync :
private async Task setDbErrorMessage(Department dbValues,

Department clientValues, SchoolContext context)
{
if (dbValues.Name != clientValues.Name)
{
ModelState.AddModelError("Department.Name",
$"Current value: {dbValues.Name}");
}
if (dbValues.Budget != clientValues.Budget)
{
ModelState.AddModelError("Department.Budget",
$"Current value: {dbValues.Budget:c}");
}
if (dbValues.StartDate != clientValues.StartDate)
{
ModelState.AddModelError("Department.StartDate",
$"Current value: {dbValues.StartDate:d}");
}
if (dbValues.InstructorID != clientValues.InstructorID)
{
Instructor dbInstructor = await _context.Instructors
.FindAsync(dbValues.InstructorID);
ModelState.AddModelError("Department.InstructorID",
$"Current value: {dbInstructor?.FullName}");
}
"The record you attempted to edit "
+ "was modified by another user after you. The "
+ "the Save button again.");
}
The following highlighted code sets the RowVersion value to the new value retrieved from the DB. The next time
the user clicks Save, only concurrency errors that happen since the last display of the Edit page will be caught.
try
{
}
{
{
return Page();
}


}
The ModelState.Remove statement is required because ModelState has the old RowVersion value. In the Razor
Page, the ModelState value for a field takes precedence over the model property values when both are present.

Update Pages/Departments/Edit.cshtml with the following markup:
@page "{id:int}"
@model ContosoUniversity.Pages.Departments.EditModel
@{
}
<h2>Edit</h2>
<h4>Department</h4>
<hr />
<div class="row">
<input type="hidden" asp-for="Department.DepartmentID" />
<input type="hidden" asp-for="Department.RowVersion" />
<label>RowVersion</label>
@Model.Department.RowVersion[7]
</div>
<label asp-for="Department.Name" class="control-label"></label>
<input asp-for="Department.Name" class="form-control" />
<span asp-validation-for="Department.Name" class="text-danger"></span>
</div>
<label asp-for="Department.Budget" class="control-label"></label>
<input asp-for="Department.Budget" class="form-control" />
<span asp-validation-for="Department.Budget" class="text-danger"></span>
</div>
<label asp-for="Department.StartDate" class="control-label"></label>
<input asp-for="Department.StartDate" class="form-control" />
<span asp-validation-for="Department.StartDate" class="text-danger">
</span>
</div>
<label class="control-label">Instructor</label>
<select asp-for="Department.InstructorID" class="form-control"
asp-items="@Model.InstructorNameSL"></select>
<span asp-validation-for="Department.InstructorID" class="text-danger">
</span>
</div>
</div>
</form>
</div>
</div>
<div>
</div>
@section Scripts {
}
The preceding markup:

Updates the page directive from @page to @page "{id:int}" .
Adds a hidden row version. RowVersion must be added so post back binds the value.
Displays the last byte of RowVersion for debugging purposes.
Replaces ViewData with the strongly-typed InstructorNameSL .
Test concurrency conflicts with the Edit page

Open two browsers instances of Edit on the English department:
Run the app and select Departments.
Right-click the Edit hyperlink for the English department and select Open in new tab.
In the first tab, click the Edit hyperlink for the English department.
The two browser tabs display the same information.
Change the name in the first browser tab and click Save.
The browser shows the Index page with the changed value and updated rowVersion indicator. Note the updated
rowVersion indicator, it's displayed on the second postback in the other tab.
Change a different field in the second browser tab.
Click Save. You see error messages for all fields that don't match the DB values:
This browser window didn't intend to change the Name field. Copy and paste the current value (Languages) into
the Name field. Tab out. Client-side validation removes the error message.
Click Save again. The value you entered in the second browser tab is saved. You see the saved values in the Index
page.

Update the Delete page model with the following code:
namespace ContosoUniversity.Pages.Departments
{
{
{
_context = context;
}
[BindProperty]
public string ConcurrencyErrorMessage { get; set; }
public async Task<IActionResult> OnGetAsync(int id, bool? concurrencyError)

{
Department = await _context.Departments
.Include(d => d.Administrator)
.AsNoTracking()
if (Department == null)
{
return NotFound();
}
if (concurrencyError.GetValueOrDefault())
{
ConcurrencyErrorMessage = "The record you attempted to delete "
+ "was modified by another user after you selected delete. "
+ "The delete operation was canceled and the current values in the "
+ "database have been displayed. If you still want to delete this "
+ "record, click the Delete button again.";
}
return Page();
}

{
try
{
if (await _context.Departments.AnyAsync(
m => m.DepartmentID == id))
{
// Department.rowVersion value is from when the entity
// was fetched. If it doesn't match the DB, a
// DbUpdateConcurrencyException exception is thrown.
_context.Departments.Remove(Department);
}
}
{
return RedirectToPage("./Delete",
new { concurrencyError = true, id = id });
}
}
}
}
The Delete page detects concurrency conflicts when the entity has changed after it was fetched.
Department.RowVersion is the row version when the entity was fetched. When EF Core creates the SQL DELETE
command, it includes a WHERE clause with RowVersion . If the SQL DELETE command results in zero rows
affected:
The RowVersion in the SQL DELETE command doesn't match RowVersion in the DB.
A DbUpdateConcurrencyException exception is thrown.
OnGetAsync is called with the concurrencyError .
Update Pages/Departments/Delete.cshtml with the following code:
@page "{id:int}"
@model ContosoUniversity.Pages.Departments.DeleteModel
@{
}
<h2>Delete</h2>
<p class="text-danger">@Model.ConcurrencyErrorMessage</p>

<div>
<h4>Department</h4>
<hr />
<dt>
@Html.DisplayNameFor(model => model.Department.Name)
</dt>
<dd>
@Html.DisplayFor(model => model.Department.Name)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Department.Budget)
</dt>
<dd>
@Html.DisplayFor(model => model.Department.Budget)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Department.StartDate)
</dt>
<dd>
@Html.DisplayFor(model => model.Department.StartDate)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Department.RowVersion)
</dt>
<dd>
@Html.DisplayFor(model => model.Department.RowVersion[7])
</dd>
<dt>
@Html.DisplayNameFor(model => model.Department.Administrator)
</dt>
<dd>
@Html.DisplayFor(model => model.Department.Administrator.FullName)
</dd>
</dl>
<input type="hidden" asp-for="Department.DepartmentID" />
<input type="hidden" asp-for="Department.RowVersion" />
</div>
</form>
</div>

Updates the page directive from @page to @page "{id:int}" .
Adds an error message.
Replaces FirstMidName with FullName in the Administrator field.
Changes RowVersion to display the last byte.
Adds a hidden row version. RowVersion must be added so post back binds the value.
Test concurrency conflicts with the Delete page
Create a test department.
Open two browsers instances of Delete on the test department:
Run the app and select Departments.
Right-click the Delete hyperlink for the test department and select Open in new tab.
Click the Edit hyperlink for the test department.
The two browser tabs display the same information.
Change the budget in the first browser tab and click Save.
The browser shows the Index page with the changed value and updated rowVersion indicator. Note the updated
rowVersion indicator, it's displayed on the second postback in the other tab.
Delete the test department from the second tab. A concurrency error is display with the current values from the
DB. Clicking Delete deletes the entity, unless RowVersion has been updated.department has been deleted.
See Inheritance on how to inherit a data model.
Concurrency Tokens in EF Core
Handle concurrency in EF Core
P R E V IO U S
ASP.NET Core MVC with EF Core - tutorial series
This tutorial teaches ASP.NET Core MVC and Entity Framework Core with controllers and views. Razor Pages is a
new alternative in ASP.NET Core 2.0, a page-based programming model that makes building web UI easier and
more productive. We recommend the Razor Pages tutorial over the MVC version. The Razor Pages tutorial:
Provides more EF Core best practices.
Uses more efficient queries.
Is more current with the latest API.
1. Get started
4. Migrations
9. Inheritance
10. Advanced topics
ASP.NET Core MVC with Entity Framework Core -
Tutorial 1 of 10
This tutorial has not been upgraded to ASP.NET Core 2.1. The ASP.NET Core 2.0 version of this tutorial is
available by selecting ASP.NET Core 2.0 above the table of contents or at the top of the page:
The ASP.NET Core 2.1 Razor Pages version of this tutorial has many improvements over the 2.0 version.
The 2.0 tutorial teaches ASP.NET Core MVC and Entity Framework Core with controllers and views. Razor
Pages is a page-based programming model that makes building web UI easier and more productive. We
recommend the Razor Pages tutorial over the MVC version. The Razor Pages tutorial:
Is easier to follow. For example, the scaffolding code has been significantly simplified.
If you choose this tutorial over the Razor Pages version, let us know why in this GitHub discussion.
This tutorial teaches ASP.NET Core MVC and Entity Framework Core with controllers and views. Razor Pages is
a new alternative in ASP.NET Core 2.0, a page-based programming model that makes building web UI easier
and more productive. We recommend the Razor Pages tutorial over the MVC version. The Razor Pages tutorial:
The Contoso University sample web application demonstrates how to create ASP.NET Core 2.0 MVC web
applications using Entity Framework (EF ) Core 2.0 and Visual Studio 2017.
The sample application is a web site for a fictional Contoso University. It includes functionality such as student
admission, course creation, and instructor assignments. This is the first in a series of tutorials that explain how to
build the Contoso University sample application from scratch.
Download or view the completed application.
EF Core 2.0 is the latest version of EF but doesn't yet have all the features of EF 6.x. For information about how
to choose between EF 6.x and EF Core, see EF Core vs. EF6.x. If you choose EF 6.x, see the previous version of
this tutorial series.
NOTE
For the ASP.NET Core 1.1 version of this tutorial, see the VS 2017 Update 2 version of this tutorial in PDF format.
Prerequisites
IDE/editor tooling
Troubleshooting
If you run into a problem you can't resolve, you can generally find the solution by comparing your code to the
completed project. For a list of common errors and how to solve them, see the Troubleshooting section of the
last tutorial in the series. If you don't find what you need there, you can post a question to StackOverflow.com for
ASP.NET Core or EF Core.
TIP
This is a series of 10 tutorials, each of which builds on what is done in earlier tutorials. Consider saving a copy of the
project after each successful tutorial completion. Then if you run into problems, you can start over from the previous
tutorial instead of going back to the beginning of the whole series.
The Contoso University web application

The application you'll be building in these tutorials is a simple university web site.
Users can view and update student, course, and instructor information. Here are a few of the screens you'll
create.
The UI style of this site has been kept close to what's generated by the built-in templates, so that the tutorial can
focus mainly on how to use the Entity Framework.
Create an ASP.NET Core MVC web application

Open Visual Studio and create a new ASP.NET Core C# web project named "ContosoUniversity".
From the left pane, select Installed > Visual C# > Web.
Select the ASP.NET Core Web Application project template.
Enter ContosoUniversity as the name and click OK.
Wait for the New ASP.NET Core Web Application (.NET Core) dialog to appear
Select ASP.NET Core 2.0 and the Web Application (Model-View-Controller) template.
Note: This tutorial requires ASP.NET Core 2.0 and EF Core 2.0 or later -- make sure that ASP.NET Core
1.1 isn't selected.
Make sure Authentication is set to No Authentication.
Click OK

A few simple changes will set up the site menu, layout, and home page.
Open Views/Shared/_Layout.cshtml and make the following changes:
Change each occurrence of "ContosoUniversity" to "Contoso University". There are three occurrences.
Add menu entries for Students, Courses, Instructors, and Departments, and delete the Contact menu
entry.
The changes are highlighted.
<!DOCTYPE html>
<html>
<head>
<title>@ViewData["Title"] - Contoso University</title>
</environment>
value="absolute" />
</environment>
</head>
<body>
collapse">
</button>
<a asp-area="" asp-controller="Home" asp-action="Index" class="navbar-brand">Contoso
University</a>
</div>
<li><a asp-area="" asp-controller="Students" asp-action="Index">Students</a></li>
<li><a asp-area="" asp-controller="Courses" asp-action="Index">Courses</a></li>
<li><a asp-area="" asp-controller="Instructors" asp-action="Index">Instructors</a></li>
<li><a asp-area="" asp-controller="Departments" asp-action="Index">Departments</a></li>
</ul>
</div>
</div>
</nav>
@RenderBody()
<hr />
<footer>
<p>© 2017 - Contoso University</p>
</footer>
</div>
</environment>
</script>
</script>
</environment>

</body>
</html>
In Views/Home/Index.cshtml, replace the contents of the file with the following code to replace the text about
ASP.NET and MVC with text about this application:
@{
ViewData["Title"] = "Home Page";
}
</div>
<div class="row">
<p>
ASP.NET Core MVC web application.
</p>
</div>
<p><a class="btn btn-default" href="https://docs.asp.net/en/latest/data/ef-mvc/intro.html">See the
tutorial »</a></p>
</div>
<p><a class="btn btn-default" href="https://github.com/aspnet/Docs/tree/master/aspnetcore/data/ef-
mvc/intro/samples/cu-final">See project source code »</a></p>
</div>
</div>
Press CTRL+F5 to run the project or choose Debug > Start Without Debugging from the menu. You see the
home page with tabs for the pages you'll create in these tutorials.
Entity Framework Core NuGet packages
To add EF Core support to a project, install the database provider that you want to target. This tutorial uses SQL
Server, and the provider package is Microsoft.EntityFrameworkCore.SqlServer. This package is included in the
Microsoft.AspNetCore.All metapackage, so you don't have to install it.
This package and its dependencies ( Microsoft.EntityFrameworkCore and
Microsoft.EntityFrameworkCore.Relational ) provide runtime support for EF. You'll add a tooling package later, in
the Migrations tutorial.
For information about other database providers that are available for Entity Framework Core, see Database
providers.

Next you'll create entity classes for the Contoso University application. You'll start with the following three
entities.
There's a one-to-many relationship between Student and Enrollment entities, and there's a one-to-many
relationship between Course and Enrollment entities. In other words, a student can be enrolled in any number
of courses, and a course can have any number of students enrolled in it.
In the following sections you'll create a class for each one of these entities.
The Student entity
In the Models folder, create a class file named Student.cs and replace the template code with the following code.
using System;
{
{

}
}
The ID property will become the primary key column of the database table that corresponds to this class. By
default, the Entity Framework interprets a property that's named ID or classnameID as the primary key.
The Enrollments property is a navigation property. Navigation properties hold other entities that are related to
this entity. In this case, the Enrollments property of a Student entity will hold all of the Enrollment entities that
are related to that Student entity. In other words, if a given Student row in the database has two related
Enrollment rows (rows that contain that student's primary key value in their StudentID foreign key column), that
Student entity's Enrollments navigation property will contain those two Enrollment entities.
If a navigation property can hold multiple entities (as in many-to-many or one-to-many relationships), its type
must be a list in which entries can be added, deleted, and updated, such as ICollection<T> . You can specify
ICollection<T> or a type such as List<T> or HashSet<T> . If you specify ICollection<T> , EF creates a
HashSet<T> collection by default.
In the Models folder, create Enrollment.cs and replace the existing code with the following code:
{
public enum Grade
{
A, B, C, D, F
}

{

}
}
The EnrollmentID property will be the primary key; this entity uses the classnameID pattern instead of ID by
itself as you saw in the Student entity. Ordinarily you would choose one pattern and use it throughout your data
model. Here, the variation illustrates that you can use either pattern. In a later tutorial, you'll see how using ID
without classname makes it easier to implement inheritance in the data model.
The Grade property is an enum . The question mark after the Grade type declaration indicates that the Grade
property is nullable. A grade that's null is different from a zero grade -- null means a grade isn't known or hasn't
been assigned yet.
The StudentID property is a foreign key, and the corresponding navigation property is Student . An Enrollment
entity is associated with one Student entity, so the property can only hold a single Student entity (unlike the
Student.Enrollments navigation property you saw earlier, which can hold multiple Enrollment entities).
The CourseID property is a foreign key, and the corresponding navigation property is Course . An Enrollment
entity is associated with one Course entity.
Entity Framework interprets a property as a foreign key property if it's named
<navigation property name><primary key property name> (for example, StudentID for the Student navigation
property since the Student entity's primary key is ID ). Foreign key properties can also be named simply
<primary key property name> (for example, CourseID since the Course entity's primary key is CourseID ).
The Course entity

In the Models folder, create Course.cs and replace the existing code with the following code:
{
public class Course
{

}
}
The Enrollments property is a navigation property. A Course entity can be related to any number of
Enrollment entities.
We'll say more about the DatabaseGenerated attribute in a later tutorial in this series. Basically, this attribute lets
you enter the primary key for the course rather than having the database generate it.
Create the Database Context

The main class that coordinates Entity Framework functionality for a given data model is the database context
class. You create this class by deriving from the Microsoft.EntityFrameworkCore.DbContext class. In your code you
specify which entities are included in the data model. You can also customize certain Entity Framework behavior.
In this project, the class is named SchoolContext .
In the project folder, create a folder named Data.
In the Data folder create a new class file named SchoolContext.cs, and replace the template code with the
following code:
{
{
{
}

public DbSet<Enrollment> Enrollments { get; set; }
public DbSet<Student> Students { get; set; }
}
}
This code creates a DbSet property for each entity set. In Entity Framework terminology, an entity set typically
corresponds to a database table, and an entity corresponds to a row in the table.
You could've omitted the DbSet<Enrollment> and DbSet<Course> statements and it would work the same. The
Entity Framework would include them implicitly because the Student entity references the Enrollment entity
and the Enrollment entity references the Course entity.
When the database is created, EF creates tables that have names the same as the DbSet property names.
Property names for collections are typically plural (Students rather than Student), but developers disagree about
whether table names should be pluralized or not. For these tutorials you'll override the default behavior by
specifying singular table names in the DbContext. To do that, add the following highlighted code after the last
DbSet property.
{
{
{
}


{
}
}
}
Register the context with dependency injection

ASP.NET Core implements dependency injection by default. Services (such as the EF database context) are
registered with dependency injection during application startup. Components that require these services (such
as MVC controllers) are provided these services via constructor parameters. You'll see the controller constructor
code that gets a context instance later in this tutorial.
To register SchoolContext as a service, open Startup.cs, and add the highlighted lines to the ConfigureServices
method.

{
options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")));
services.AddMvc();
}
The name of the connection string is passed in to the context by calling a method on a DbContextOptionsBuilder
object. For local development, the ASP.NET Core configuration system reads the connection string from the
Add using statements for ContosoUniversity.Data and Microsoft.EntityFrameworkCore namespaces, and then
build the project.
Open the appsettings.json file and add a connection string as shown in the following example.
{
"DefaultConnection": "Server=
(localdb)\\mssqllocaldb;Database=ContosoUniversity1;Trusted_Connection=True;MultipleActiveResultSets=true"
},
"Logging": {
"LogLevel": {
}
}
}

The connection string specifies a SQL Server LocalDB database. LocalDB is a lightweight version of the SQL
Server Express Database Engine and is intended for application development, not production use. LocalDB starts
on demand and runs in user mode, so there's no complex configuration. By default, LocalDB creates .mdf
database files in the C:/Users/<user> directory.
Add code to initialize the database with test data

The Entity Framework will create an empty database for you. In this section, you write a method that's called
after the database is created in order to populate it with test data.
Here you'll use the EnsureCreated method to automatically create the database. In a later tutorial you'll see how
to handle model changes by using Code First Migrations to change the database schema instead of dropping
and re-creating the database.
In the Data folder, create a new class file named DbInitializer.cs and replace the template code with the following
code, which causes a database to be created when needed and loads test data into the new database.
using System;
using System.Linq;
using System.Linq;
{
{
{

if (context.Students.Any())
{
}

{
new Student{FirstMidName="Carson",LastName="Alexander",EnrollmentDate=DateTime.Parse("2005-09-
01")},
new Student{FirstMidName="Meredith",LastName="Alonso",EnrollmentDate=DateTime.Parse("2002-09-
01")},
new Student{FirstMidName="Arturo",LastName="Anand",EnrollmentDate=DateTime.Parse("2003-09-01")},
new Student{FirstMidName="Gytis",LastName="Barzdukas",EnrollmentDate=DateTime.Parse("2002-09-
01")},
new Student{FirstMidName="Yan",LastName="Li",EnrollmentDate=DateTime.Parse("2002-09-01")},
new Student{FirstMidName="Peggy",LastName="Justice",EnrollmentDate=DateTime.Parse("2001-09-
01")},
new Student{FirstMidName="Laura",LastName="Norman",EnrollmentDate=DateTime.Parse("2003-09-01")},
new Student{FirstMidName="Nino",LastName="Olivetto",EnrollmentDate=DateTime.Parse("2005-09-01")}
};
{
context.Students.Add(s);
}

{
};
{
}

{
};
{
{
context.Enrollments.Add(e);
}
}
}
}
The code checks if there are any students in the database, and if not, it assumes the database is new and needs to
be seeded with test data. It loads test data into arrays rather than List<T> collections to optimize performance.
In Program.cs, modify the Main method to do the following on application startup:
Get a database context instance from the dependency injection container.
Call the seed method, passing to it the context.
Dispose the context when the seed method is done.

{

{
try
{
}
{
logger.LogError(ex, "An error occurred while seeding the database.");
}
}
host.Run();
}
Add using statements:
In older tutorials, you may see similar code in the Configure method in Startup.cs. We recommend that you use
the Configure method only to set up the request pipeline. Application startup code belongs in the Main
method.
Now the first time you run the application, the database will be created and seeded with test data. Whenever you
change your data model, you can delete the database, update your seed method, and start afresh with a new
database the same way. In later tutorials, you'll see how to modify the database when the data model changes,
without deleting and re-creating it.
Create a controller and views

Next, you'll use the scaffolding engine in Visual Studio to add an MVC controller and views that will use EF to
query and save data.
The automatic creation of CRUD action methods and views is known as scaffolding. Scaffolding differs from
code generation in that the scaffolded code is a starting point that you can modify to suit your own
requirements, whereas you typically don't modify generated code. When you need to customize generated code,
you use partial classes or you regenerate the code when things change.
Right-click the Controllers folder in Solution Explorer and select Add > New Scaffolded Item.
If the Add MVC Dependencies dialog appears:
Update Visual Studio to the latest version. Visual Studio versions prior to 15.5 show this dialog.
If you can't update, select ADD, and then follow the add controller steps again.
In the Add Scaffold dialog box:
Select MVC controller with views, using Entity Framework.
Click Add.
In the Add Controller dialog box:
In Model class select Student.
In Data context class select SchoolContext.
Accept the default StudentsController as the name.
Click Add.
When you click Add, the Visual Studio scaffolding engine creates a StudentsController.cs file and a set of
views (.cshtml files) that work with the controller.
(The scaffolding engine can also create the database context for you if you don't create it manually first as you
did earlier for this tutorial. You can specify a new context class in the Add Controller box by clicking the plus
sign to the right of Data context class. Visual Studio will then create your DbContext class as well as the
controller and views.)
You'll notice that the controller takes a SchoolContext as a constructor parameter.
namespace ContosoUniversity.Controllers
{
public class StudentsController : Controller
{
public StudentsController(SchoolContext context)

{
_context = context;
}
ASP.NET Core dependency injection takes care of passing an instance of SchoolContext into the controller. You
configured that in the Startup.cs file earlier.
The controller contains an Index action method, which displays all students in the database. The method gets a
list of students from the Students entity set by reading the Students property of the database context instance:

{
return View(await _context.Students.ToListAsync());
}
You'll learn about the asynchronous programming elements in this code later in the tutorial.
The Views/Students/Index.cshtml view displays this list in a table:
@model IEnumerable<ContosoUniversity.Models.Student>
@{
}
<h2>Index</h2>
<p>
</p>
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.LastName)
</th>
<th>
@Html.DisplayNameFor(model => model.FirstMidName)
</th>
<th>
@Html.DisplayNameFor(model => model.EnrollmentDate)
</th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
Press CTRL+F5 to run the project or choose Debug > Start Without Debugging from the menu.
Click the Students tab to see the test data that the DbInitializer.Initialize method inserted. Depending on
how narrow your browser window is, you'll see the Student tab link at the top of the page or you'll have to click
the navigation icon in the upper right corner to see the link.
View the Database
When you started the application, the DbInitializer.Initialize method calls EnsureCreated . EF saw that there
was no database and so it created one, then the remainder of the Initialize method code populated the
database with data. You can use SQL Server Object Explorer (SSOX) to view the database in Visual Studio.
Close the browser.
If the SSOX window isn't already open, select it from the View menu in Visual Studio.
In SSOX, click (localdb)\MSSQLLocalDB > Databases, and then click the entry for the database name that's
in the connection string in your appsettings.json file.
Expand the Tables node to see the tables in your database.
Right-click the Student table and click View Data to see the columns that were created and the rows that were
inserted into the table.
The .mdf and .ldf database files are in the C:\Users\ folder.
Because you're calling EnsureCreated in the initializer method that runs on app start, you could now make a
change to the Student class, delete the database, run the application again, and the database would
automatically be re-created to match your change. For example, if you add an EmailAddress property to the
Student class, you'll see a new EmailAddress column in the re-created table.
Conventions
The amount of code you had to write in order for the Entity Framework to be able to create a complete database
for you is minimal because of the use of conventions, or assumptions that the Entity Framework makes.
The names of DbSet properties are used as table names. For entities not referenced by a DbSet property,
entity class names are used as table names.
Entity property names are used for column names.
Entity properties that are named ID or classnameID are recognized as primary key properties.
A property is interpreted as a foreign key property if it's named (for example, StudentID for the Student
navigation property since the Student entity's primary key is ID ). Foreign key properties can also be
named simply (for example, EnrollmentID since the Enrollment entity's primary key is EnrollmentID ).
Conventional behavior can be overridden. For example, you can explicitly specify table names, as you saw earlier
in this tutorial. And you can set column names and set any property as primary key or foreign key, as you'll see
in a later tutorial in this series.
Asynchronous code
A web server has a limited number of threads available, and in high load situations all of the available threads
might be in use. When that happens, the server can't process new requests until the threads are freed up. With
synchronous code, many threads may be tied up while they aren't actually doing any work because they're
waiting for I/O to complete. With asynchronous code, when a process is waiting for I/O to complete, its thread is
freed up for the server to use for processing other requests. As a result, asynchronous code enables server
resources to be used more efficiently, and the server is enabled to handle more traffic without delays.
Asynchronous code does introduce a small amount of overhead at run time, but for low traffic situations the
performance hit is negligible, while for high traffic situations, the potential performance improvement is
substantial.
In the following code, the async keyword, Task<T> return value, await keyword, and ToListAsync method
make the code execute asynchronously.

{
return View(await _context.Students.ToListAsync());
}
The async keyword tells the compiler to generate callbacks for parts of the method body and to
automatically create the Task<IActionResult> object that's returned.
The return type Task<IActionResult> represents ongoing work with a result of type IActionResult .
The await keyword causes the compiler to split the method into two parts. The first part ends with the
operation that's started asynchronously. The second part is put into a callback method that's called when
the operation completes.
Some things to be aware of when you are writing asynchronous code that uses the Entity Framework:
Only statements that cause queries or commands to be sent to the database are executed asynchronously.
That includes, for example, ToListAsync , SingleOrDefaultAsync , and SaveChangesAsync . It doesn't include,
for example, statements that just change an IQueryable , such as
An EF context isn't thread safe: don't try to do multiple operations in parallel. When you call any async EF
method, always use the await keyword.
If you want to take advantage of the performance benefits of async code, make sure that any library
packages that you're using (such as for paging), also use async if they call any Entity Framework methods
that cause queries to be sent to the database.
For more information about asynchronous programming in .NET, see Async Overview.
Summary
You've now created a simple application that uses the Entity Framework Core and SQL Server Express LocalDB
to store and display data. In the following tutorial, you'll learn how to perform basic CRUD (create, read, update,
delete) operations.
NEXT
ASP.NET Core MVC with EF Core - CRUD - 2 of 10
The 2.0 tutorial teaches ASP.NET Core MVC and Entity Framework Core with controllers and views. Razor Pages
is a page-based programming model that makes building web UI easier and more productive. We recommend
the Razor Pages tutorial over the MVC version. The Razor Pages tutorial:
The Contoso University sample web application demonstrates how to create ASP.NET Core MVC web
applications using Entity Framework Core and Visual Studio. For information about the tutorial series, see the
first tutorial in the series.
In the previous tutorial, you created an MVC application that stores and displays data using the Entity Framework
and SQL Server LocalDB. In this tutorial, you'll review and customize the CRUD (create, read, update, delete)
code that the MVC scaffolding automatically creates for you in controllers and views.
NOTE
It's a common practice to implement the repository pattern in order to create an abstraction layer between your controller
and the data access layer. To keep these tutorials simple and focused on teaching how to use the Entity Framework itself,
they don't use repositories. For information about repositories with EF, see the last tutorial in this series.
In this tutorial, you'll work with the following web pages:

Customize the Details page
The scaffolded code for the Students Index page left out the Enrollments property, because that property holds a
collection. In the Details page, you'll display the contents of the collection in an HTML table.
In Controllers/StudentsController.cs, the action method for the Details view uses the SingleOrDefaultAsync
method to retrieve a single Student entity. Add code that calls Include . ThenInclude , and AsNoTracking
methods, as shown in the following highlighted code.

{
if (id == null)
{
return NotFound();
}
var student = await _context.Students

.Include(s => s.Enrollments)
.ThenInclude(e => e.Course)
.AsNoTracking()
{
return NotFound();
}
return View(student);
}
The Include and ThenInclude methods cause the context to load the Student.Enrollments navigation property,
and within each enrollment the Enrollment.Course navigation property. You'll learn more about these methods in
the read related data tutorial.
The AsNoTracking method improves performance in scenarios where the entities returned won't be updated in
the current context's lifetime. You'll learn more about AsNoTracking at the end of this tutorial.
Route data
The key value that's passed to the Details method comes from route data. Route data is data that the model
binder found in a segment of the URL. For example, the default route specifies controller, action, and id segments:
{
routes.MapRoute(
name: "default",
});
In the following URL, the default route maps Instructor as the controller, Index as the action, and 1 as the id; these
are route data values.
http://localhost:1230/Instructor/Index/1?courseID=2021
The last part of the URL ("?courseID=2021") is a query string value. The model binder will also pass the ID value
to the Details method id parameter if you pass it as a query string value:
http://localhost:1230/Instructor/Index?id=1&CourseID=2021
In the Index page, hyperlink URLs are created by tag helper statements in the Razor view. In the following Razor
code, the id parameter matches the default route, so id is added to the route data.
<a asp-action="Edit" asp-route-id="@item.ID">Edit</a>

This generates the following HTML when item.ID is 6:
<a href="/Students/Edit/6">Edit</a>
In the following Razor code, studentID doesn't match a parameter in the default route, so it's added as a query
string.
<a asp-action="Edit" asp-route-studentID="@item.ID">Edit</a>
This generates the following HTML when item.ID is 6:
<a href="/Students/Edit?studentID=6">Edit</a>
For more information about tag helpers, see Tag helpers in ASP.NET Core.
Add enrollments to the Details view
Open Views/Students/Details.cshtml. Each field is displayed using DisplayNameFor and DisplayFor helpers, as
shown in the following example:
<dt>
@Html.DisplayNameFor(model => model.LastName)
</dt>
<dd>
@Html.DisplayFor(model => model.LastName)
</dd>
After the last field and immediately before the closing </dl> tag, add the following code to display a list of
enrollments:
<dt>
@Html.DisplayNameFor(model => model.Enrollments)
</dt>
<dd>
<tr>
<th>Course Title</th>
<th>Grade</th>
</tr>
@foreach (var item in Model.Enrollments)
{
<tr>
<td>
@Html.DisplayFor(modelItem => item.Course.Title)
</td>
<td>
</td>
</tr>
}
</table>
</dd>
If code indentation is wrong after you paste the code, press CTRL -K-D to correct it.
This code loops through the entities in the Enrollments navigation property. For each enrollment, it displays the
course title and the grade. The course title is retrieved from the Course entity that's stored in the Course
navigation property of the Enrollments entity.
Run the app, select the Students tab, and click the Details link for a student. You see the list of courses and
grades for the selected student:
Update the Create page

In StudentsController.cs, modify the HttpPost Create method by adding a try-catch block and removing ID from
the Bind attribute.
[HttpPost]
[Bind("EnrollmentDate,FirstMidName,LastName")] Student student)
{
try
{
{
_context.Add(student);
}
}
{
//Log the error (uncomment ex variable name and write a log.
ModelState.AddModelError("", "Unable to save changes. " +
"Try again, and if the problem persists " +
"see your system administrator.");
}
}
This code adds the Student entity created by the ASP.NET Core MVC model binder to the Students entity set and
then saves the changes to the database. (Model binder refers to the ASP.NET Core MVC functionality that makes
it easier for you to work with data submitted by a form; a model binder converts posted form values to CLR types
and passes them to the action method in parameters. In this case, the model binder instantiates a Student entity
for you using property values from the Form collection.)
You removed ID from the Bind attribute because ID is the primary key value which SQL Server will set
automatically when the row is inserted. Input from the user doesn't set the ID value.
Other than the Bind attribute, the try-catch block is the only change you've made to the scaffolded code. If an
exception that derives from DbUpdateException is caught while the changes are being saved, a generic error
message is displayed. DbUpdateException exceptions are sometimes caused by something external to the
application rather than a programming error, so the user is advised to try again. Although not implemented in this
sample, a production quality application would log the exception. For more information, see the Log for insight
section in Monitoring and Telemetry (Building Real-World Cloud Apps with Azure).
The ValidateAntiForgeryToken attribute helps prevent cross-site request forgery (CSRF ) attacks. The token is
automatically injected into the view by the FormTagHelper and is included when the form is submitted by the
user. The token is validated by the ValidateAntiForgeryToken attribute. For more information about CSRF, see
Anti-Request Forgery.
Security note about overposting
The Bind attribute that the scaffolded code includes on the Create method is one way to protect against
overposting in create scenarios. For example, suppose the Student entity includes a Secret property that you
don't want this web page to set.

{
public string Secret { get; set; }
}
Even if you don't have a Secret field on the web page, a hacker could use a tool such as Fiddler, or write some
JavaScript, to post a Secret form value. Without the Bind attribute limiting the fields that the model binder uses
when it creates a Student instance, the model binder would pick up that Secret form value and use it to create
the Student entity instance. Then whatever value the hacker specified for the Secret form field would be updated
in your database. The following image shows the Fiddler tool adding the Secret field (with the value "OverPost")
to the posted form values.
The value "OverPost" would then be successfully added to the Secret property of the inserted row, although you
never intended that the web page be able to set that property.
You can prevent overposting in edit scenarios by reading the entity from the database first and then calling
TryUpdateModel , passing in an explicit allowed properties list. That's the method used in these tutorials.
An alternative way to prevent overposting that's preferred by many developers is to use view models rather than
entity classes with model binding. Include only the properties you want to update in the view model. Once the
MVC model binder has finished, copy the view model properties to the entity instance, optionally using a tool
such as AutoMapper. Use _context.Entry on the entity instance to set its state to Unchanged , and then set
Property("PropertyName").IsModified to true on each entity property that's included in the view model. This
method works in both edit and create scenarios.
Test the Create page
The code in Views/Students/Create.cshtml uses label , input , and span (for validation messages) tag helpers
for each field.
Run the app, select the Students tab, and click Create New.
Enter names and a date. Try entering an invalid date if your browser lets you do that. (Some browsers force you to
use a date picker.) Then click Create to see the error message.
This is server-side validation that you get by default; in a later tutorial you'll see how to add attributes that will
generate code for client-side validation also. The following highlighted code shows the model validation check in
the Create method.
[HttpPost]
[Bind("EnrollmentDate,FirstMidName,LastName")] Student student)
{
try
{
{
_context.Add(student);
}
}
{
//Log the error (uncomment ex variable name and write a log.
"Try again, and if the problem persists " +
}
}
Change the date to a valid value and click Create to see the new student appear in the Index page.

In StudentController.cs, the HttpGet Edit method (the one without the HttpPost attribute) uses the
SingleOrDefaultAsync method to retrieve the selected Student entity, as you saw in the Details method. You
don't need to change this method.
Recommended HttpPost Edit code: Read and update
Replace the HttpPost Edit action method with the following code.
[HttpPost, ActionName("Edit")]
public async Task<IActionResult> EditPost(int? id)
{
if (id == null)
{
return NotFound();
}
var studentToUpdate = await _context.Students.SingleOrDefaultAsync(s => s.ID == id);
studentToUpdate,
"",
{
try
{
}
{
"Try again, and if the problem persists, " +
}
}
return View(studentToUpdate);
}
These changes implement a security best practice to prevent overposting. The scaffolder generated a Bind
attribute and added the entity created by the model binder to the entity set with a Modified flag. That code isn't
recommended for many scenarios because the Bind attribute clears out any pre-existing data in fields not listed
in the Include parameter.
The new code reads the existing entity and calls TryUpdateModel to update fields in the retrieved entity based on
user input in the posted form data. The Entity Framework's automatic change tracking sets the Modified flag on
the fields that are changed by form input. When the SaveChanges method is called, the Entity Framework creates
SQL statements to update the database row. Concurrency conflicts are ignored, and only the table columns that
were updated by the user are updated in the database. (A later tutorial shows how to handle concurrency
conflicts.)
As a best practice to prevent overposting, the fields that you want to be updateable by the Edit page are
whitelisted in the TryUpdateModel parameters. (The empty string preceding the list of fields in the parameter list is
for a prefix to use with the form fields names.) Currently there are no extra fields that you're protecting, but listing
the fields that you want the model binder to bind ensures that if you add fields to the data model in the future,
they're automatically protected until you explicitly add them here.
As a result of these changes, the method signature of the HttpPost Edit method is the same as the HttpGet
Edit method; therefore you've renamed the method EditPost .
Alternative HttpPost Edit code: Create and attach

The recommended HttpPost edit code ensures that only changed columns get updated and preserves data in
properties that you don't want included for model binding. However, the read-first approach requires an extra
database read, and can result in more complex code for handling concurrency conflicts. An alternative is to attach
an entity created by the model binder to the EF context and mark it as modified. (Don't update your project with
this code, it's only shown to illustrate an optional approach.)
public async Task<IActionResult> Edit(int id, [Bind("ID,EnrollmentDate,FirstMidName,LastName")] Student

student)
{
if (id != student.ID)
{
return NotFound();
}
{
try
{
_context.Update(student);
}
{
}
}
}
You can use this approach when the web page UI includes all of the fields in the entity and can update any of
them.
The scaffolded code uses the create-and-attach approach but only catches DbUpdateConcurrencyException
exceptions and returns 404 error codes. The example shown catches any database update exception and displays
an error message.
Entity States
The database context keeps track of whether entities in memory are in sync with their corresponding rows in the
database, and this information determines what happens when you call the SaveChanges method. For example,
when you pass a new entity to the Add method, that entity's state is set to Added . Then when you call the
SaveChanges method, the database context issues a SQL INSERT command.
An entity may be in one of the following states:

Added . The entity doesn't yet exist in the database. The SaveChanges method issues an INSERT statement.
Unchanged . Nothing needs to be done with this entity by the SaveChanges method. When you read an
entity from the database, the entity starts out with this status.
. Some or all of the entity's property values have been modified. The
Modified SaveChanges method issues
an UPDATE statement.
Deleted . The entity has been marked for deletion. The SaveChanges method issues a DELETE statement.
Detached . The entity isn't being tracked by the database context.
In a desktop application, state changes are typically set automatically. You read an entity and make changes to
some of its property values. This causes its entity state to automatically be changed to Modified . Then when you
call SaveChanges , the Entity Framework generates a SQL UPDATE statement that updates only the actual
properties that you changed.
In a web app, the DbContext that initially reads an entity and displays its data to be edited is disposed after a page
is rendered. When the HttpPost Edit action method is called, a new web request is made and you have a new
instance of the DbContext . If you re-read the entity in that new context, you simulate desktop processing.
But if you don't want to do the extra read operation, you have to use the entity object created by the model binder.
The simplest way to do this is to set the entity state to Modified as is done in the alternative HttpPost Edit code
shown earlier. Then when you call SaveChanges , the Entity Framework updates all columns of the database row,
because the context has no way to know which properties you changed.
If you want to avoid the read-first approach, but you also want the SQL UPDATE statement to update only the
fields that the user actually changed, the code is more complex. You have to save the original values in some way
(such as by using hidden fields) so that they're available when the HttpPost Edit method is called. Then you can
create a Student entity using the original values, call the Attach method with that original version of the entity,
update the entity's values to the new values, and then call SaveChanges .
Test the Edit page
Run the app, select the Students tab, then click an Edit hyperlink.
Change some of the data and click Save. The Index page opens and you see the changed data.

In StudentController.cs, the template code for the HttpGet Delete method uses the SingleOrDefaultAsync
method to retrieve the selected Student entity, as you saw in the Details and Edit methods. However, to
implement a custom error message when the call to SaveChanges fails, you'll add some functionality to this
method and its corresponding view.
As you saw for update and create operations, delete operations require two action methods. The method that's
called in response to a GET request displays a view that gives the user a chance to approve or cancel the delete
operation. If the user approves it, a POST request is created. When that happens, the HttpPost Delete method is
called and then that method actually performs the delete operation.
You'll add a try-catch block to the HttpPost Delete method to handle any errors that might occur when the
database is updated. If an error occurs, the HttpPost Delete method calls the HttpGet Delete method, passing it a
parameter that indicates that an error has occurred. The HttpGet Delete method then redisplays the confirmation
page along with the error message, giving the user an opportunity to cancel or try again.
Replace the HttpGet Delete action method with the following code, which manages error reporting.
public async Task<IActionResult> Delete(int? id, bool? saveChangesError = false)

{
if (id == null)
{
return NotFound();
}

.AsNoTracking()
{
return NotFound();
}
if (saveChangesError.GetValueOrDefault())
{
ViewData["ErrorMessage"] =
"Delete failed. Try again, and if the problem persists " +
"see your system administrator.";
}
}
This code accepts an optional parameter that indicates whether the method was called after a failure to save
changes. This parameter is false when the HttpGet Delete method is called without a previous failure. When it's
called by the HttpPost Delete method in response to a database update error, the parameter is true and an error
message is passed to the view.
The read-first approach to HttpPost Delete
Replace the HttpPost Delete action method (named DeleteConfirmed ) with the following code, which performs
the actual delete operation and catches any database update errors.
{
.AsNoTracking()
{
}
try
{
_context.Students.Remove(student);
}
{
return RedirectToAction(nameof(Delete), new { id = id, saveChangesError = true });
}
}
This code retrieves the selected entity, then calls the Remove method to set the entity's status to Deleted . When
SaveChanges is called, a SQL DELETE command is generated.
The create -and-attach approach to HttpPost Delete

If improving performance in a high-volume application is a priority, you could avoid an unnecessary SQL query
by instantiating a Student entity using only the primary key value and then setting the entity state to Deleted .
That's all that the Entity Framework needs in order to delete the entity. (Don't put this code in your project; it's
here just to illustrate an alternative.)
[HttpPost]
{
try
{
Student studentToDelete = new Student() { ID = id };
_context.Entry(studentToDelete).State = EntityState.Deleted;
}
{
return RedirectToAction(nameof(Delete), new { id = id, saveChangesError = true });
}
}
If the entity has related data that should also be deleted, make sure that cascade delete is configured in the
database. With this approach to entity deletion, EF might not realize there are related entities to be deleted.
Update the Delete view
In Views/Student/Delete.cshtml, add an error message between the h2 heading and the h3 heading, as shown in
the following example:
<h2>Delete</h2>
<p class="text-danger">@ViewData["ErrorMessage"]</p>
Run the app, select the Students tab, and click a Delete hyperlink:
Click Delete. The Index page is displayed without the deleted student. (You'll see an example of the error
handling code in action in the concurrency tutorial.)
Closing database connections

To free up the resources that a database connection holds, the context instance must be disposed as soon as
possible when you are done with it. The ASP.NET Core built-in dependency injection takes care of that task for
you.
In Startup.cs, you call the AddDbContext extension method to provision the DbContext class in the ASP.NET Core
DI container. That method sets the service lifetime to Scoped by default. Scoped means the context object
lifetime coincides with the web request life time, and the Dispose method will be called automatically at the end
of the web request.
Handling Transactions
By default the Entity Framework implicitly implements transactions. In scenarios where you make changes to
multiple rows or tables and then call SaveChanges , the Entity Framework automatically makes sure that either all
of your changes succeed or they all fail. If some changes are done first and then an error happens, those changes
are automatically rolled back. For scenarios where you need more control -- for example, if you want to include
operations done outside of Entity Framework in a transaction -- see Transactions.
No-tracking queries
When a database context retrieves table rows and creates entity objects that represent them, by default it keeps
track of whether the entities in memory are in sync with what's in the database. The data in memory acts as a
cache and is used when you update an entity. This caching is often unnecessary in a web application because
context instances are typically short-lived (a new one is created and disposed for each request) and the context
that reads an entity is typically disposed before that entity is used again.
You can disable tracking of entity objects in memory by calling the AsNoTracking method. Typical scenarios in
which you might want to do that include the following:
During the context lifetime you don't need to update any entities, and you don't need EF to automatically
load navigation properties with entities retrieved by separate queries. Frequently these conditions are met
in a controller's HttpGet action methods.
You are running a query that retrieves a large volume of data, and only a small portion of the returned data
will be updated. It may be more efficient to turn off tracking for the large query, and run a query later for
the few entities that need to be updated.
You want to attach an entity in order to update it, but earlier you retrieved the same entity for a different
purpose. Because the entity is already being tracked by the database context, you can't attach the entity that
you want to change. One way to handle this situation is to call AsNoTracking on the earlier query.
For more information, see Tracking vs. No-Tracking.
Summary
You now have a complete set of pages that perform simple CRUD operations for Student entities. In the next
tutorial you'll expand the functionality of the Index page by adding sorting, filtering, and paging.
P R E V IO U S NEXT
ASP.NET Core MVC with EF Core - Sort, Filter,
Paging - 3 of 10
In the previous tutorial, you implemented a set of web pages for basic CRUD operations for Student entities. In
this tutorial you'll add sorting, filtering, and paging functionality to the Students Index page. You'll also create a
page that does simple grouping.
The following illustration shows what the page will look like when you're done. The column headings are links
that the user can click to sort by that column. Clicking a column heading repeatedly toggles between ascending
and descending sort order.
Add Column Sort Links to the Students Index Page
To add sorting to the Student Index page, you'll change the Index method of the Students controller and add
code to the Student Index view.
Add sorting Functionality to the Index method
In StudentsController.cs, replace the Index method with the following code:
public async Task<IActionResult> Index(string sortOrder)

{
ViewData["NameSortParm"] = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";
ViewData["DateSortParm"] = sortOrder == "Date" ? "date_desc" : "Date";
var students = from s in _context.Students
select s;
switch (sortOrder)
{
case "name_desc":
students = students.OrderByDescending(s => s.LastName);
break;
case "Date":
students = students.OrderBy(s => s.EnrollmentDate);
break;
case "date_desc":
students = students.OrderByDescending(s => s.EnrollmentDate);
break;
default:
students = students.OrderBy(s => s.LastName);
break;
}
return View(await students.AsNoTracking().ToListAsync());
}
This code receives a sortOrder parameter from the query string in the URL. The query string value is provided
by ASP.NET Core MVC as a parameter to the action method. The parameter will be a string that's either "Name"
or "Date", optionally followed by an underscore and the string "desc" to specify descending order. The default sort
order is ascending.
The first time the Index page is requested, there's no query string. The students are displayed in ascending order
by last name, which is the default as established by the fall-through case in the switch statement. When the user
clicks a column heading hyperlink, the appropriate sortOrder value is provided in the query string.
The two ViewData elements (NameSortParm and DateSortParm) are used by the view to configure the column
heading hyperlinks with the appropriate query string values.
public async Task<IActionResult> Index(string sortOrder)

{
select s;
switch (sortOrder)
{
case "name_desc":
break;
case "Date":
break;
case "date_desc":
break;
default:
break;
}
}
These are ternary statements. The first one specifies that if the sortOrder parameter is null or empty,
NameSortParm should be set to "name_desc"; otherwise, it should be set to an empty string. These two
statements enable the view to set the column heading hyperlinks as follows:
CURRENT SORT ORDER LAST NAME HYPERLINK DATE HYPERLINK
Last Name ascending descending ascending
Last Name descending ascending ascending
Date ascending ascending descending
Date descending ascending ascending
The method uses LINQ to Entities to specify the column to sort by. The code creates an IQueryable variable
before the switch statement, modifies it in the switch statement, and calls the ToListAsync method after the
switch statement. When you create and modify IQueryable variables, no query is sent to the database. The
query isn't executed until you convert the IQueryable object into a collection by calling a method such as
ToListAsync . Therefore, this code results in a single query that's not executed until the return View statement.
This code could get verbose with a large number of columns. The last tutorial in this series shows how to write
code that lets you pass the name of the OrderBy column in a string variable.
Add column heading hyperlinks to the Student Index view
Replace the code in Views/Students/Index.cshtml, with the following code to add column heading hyperlinks. The
changed lines are highlighted.
@model IEnumerable<ContosoUniversity.Models.Student>
@{
}
<h2>Index</h2>
<p>
</p>
<thead>
<tr>
<th>
<a asp-action="Index" asp-route-
sortOrder="@ViewData["NameSortParm"]">@Html.DisplayNameFor(model => model.LastName)</a>
</th>
<th>
@Html.DisplayNameFor(model => model.FirstMidName)
</th>
<th>
<a asp-action="Index" asp-route-
sortOrder="@ViewData["DateSortParm"]">@Html.DisplayNameFor(model => model.EnrollmentDate)</a>
</th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
This code uses the information in ViewData properties to set up hyperlinks with the appropriate query string
values.
Run the app, select the Students tab, and click the Last Name and Enrollment Date column headings to verify
that sorting works.
Add a Search Box to the Students Index page
To add filtering to the Students Index page, you'll add a text box and a submit button to the view and make
corresponding changes in the Index method. The text box will let you enter a string to search for in the first name
and last name fields.
Add filtering functionality to the Index method
In StudentsController.cs, replace the Index method with the following code (the changes are highlighted).
public async Task<IActionResult> Index(string sortOrder, string searchString)

{
ViewData["CurrentFilter"] = searchString;

select s;
{
students = students.Where(s => s.LastName.Contains(searchString)
}
switch (sortOrder)
{
case "name_desc":
break;
case "Date":
break;
case "date_desc":
break;
default:
break;
}
}
You've added a searchString parameter to the Index method. The search string value is received from a text box
that you'll add to the Index view. You've also added to the LINQ statement a where clause that selects only
students whose first name or last name contains the search string. The statement that adds the where clause is
executed only if there's a value to search for.
NOTE
Here you are calling the Where method on an IQueryable object, and the filter will be processed on the server. In some
scenarios you might be calling the Where method as an extension method on an in-memory collection. (For example,
suppose you change the reference to _context.Students so that instead of an EF DbSet it references a repository
method that returns an IEnumerable collection.) The result would normally be the same but in some cases may be
different.
For example, the .NET Framework implementation of the Contains method performs a case-sensitive comparison by
default, but in SQL Server this is determined by the collation setting of the SQL Server instance. That setting defaults to
case-insensitive. You could call the ToUpper method to make the test explicitly case-insensitive: Where(s =>
s.LastName.ToUpper().Contains (searchString.ToUpper()). That would ensure that results stay the same if you change the
code later to use a repository which returns an IEnumerable collection instead of an IQueryable object. (When you call
the Contains method on an IEnumerable collection, you get the .NET Framework implementation; when you call it on
an IQueryable object, you get the database provider implementation.) However, there's a performance penalty for this
solution. The ToUpper code would put a function in the WHERE clause of the TSQL SELECT statement. That would prevent
the optimizer from using an index. Given that SQL is mostly installed as case-insensitive, it's best to avoid the ToUpper
code until you migrate to a case-sensitive data store.
Add a Search Box to the Student Index View

In Views/Student/Index.cshtml, add the highlighted code immediately before the opening table tag in order to
create a caption, a text box, and a Search button.
<p>
</p>
<form asp-action="Index" method="get">

<p>
Find by name: <input type="text" name="SearchString" value="@ViewData["currentFilter"]" />
<a asp-action="Index">Back to Full List</a>
</p>
</div>
</form>
This code uses the <form> tag helper to add the search text box and button. By default, the <form> tag helper
submits form data with a POST, which means that parameters are passed in the HTTP message body and not in
the URL as query strings. When you specify HTTP GET, the form data is passed in the URL as query strings,
which enables users to bookmark the URL. The W3C guidelines recommend that you should use GET when the
action doesn't result in an update.
Run the app, select the Students tab, enter a search string, and click Search to verify that filtering is working.
Notice that the URL contains the search string.
http://localhost:5813/Students?SearchString=an
If you bookmark this page, you'll get the filtered list when you use the bookmark. Adding method="get" to the
form tag is what caused the query string to be generated.
At this stage, if you click a column heading sort link you'll lose the filter value that you entered in the Search box.
You'll fix that in the next section.
Add paging functionality to the Students Index page

To add paging to the Students Index page, you'll create a PaginatedList class that uses Skip and Take
statements to filter data on the server instead of always retrieving all rows of the table. Then you'll make
additional changes in the Index method and add paging buttons to the Index view. The following illustration
shows the paging buttons.
In the project folder, create PaginatedList.cs , and then replace the template code with the following code.
using System;
using System.Linq;
{
public class PaginatedList<T> : List<T>
{
public int PageIndex { get; private set; }
public int TotalPages { get; private set; }
public PaginatedList(List<T> items, int count, int pageIndex, int pageSize)

{
PageIndex = pageIndex;
TotalPages = (int)Math.Ceiling(count / (double)pageSize);
this.AddRange(items);
}
public bool HasPreviousPage

{
get
{
return (PageIndex > 1);
}
}
public bool HasNextPage

{
get
{
return (PageIndex < TotalPages);
}
}
public static async Task<PaginatedList<T>> CreateAsync(IQueryable<T> source, int pageIndex, int

pageSize)
{
var count = await source.CountAsync();
var items = await source.Skip((pageIndex - 1) * pageSize).Take(pageSize).ToListAsync();
return new PaginatedList<T>(items, count, pageIndex, pageSize);
}
}
}
The CreateAsync method in this code takes page size and page number and applies the appropriate Skip and
Take statements to the IQueryable . When ToListAsync is called on the IQueryable , it will return a List
containing only the requested page. The properties HasPreviousPage and HasNextPage can be used to enable or
disable Previous and Next paging buttons.
A CreateAsync method is used instead of a constructor to create the PaginatedList<T> object because
constructors can't run asynchronous code.
Add paging functionality to the Index method

In StudentsController.cs, replace the Index method with the following code.
public async Task<IActionResult> Index(
string sortOrder,
string currentFilter,
string searchString,
int? page)
{
ViewData["CurrentSort"] = sortOrder;
{
page = 1;
}
else
{
}

select s;
{
}
switch (sortOrder)
{
case "name_desc":
break;
case "Date":
break;
case "date_desc":
break;
default:
break;
}
int pageSize = 3;
return View(await PaginatedList<Student>.CreateAsync(students.AsNoTracking(), page ?? 1, pageSize));
}
This code adds a page number parameter, a current sort order parameter, and a current filter parameter to the
method signature.

string sortOrder,
int? page)
The first time the page is displayed, or if the user hasn't clicked a paging or sorting link, all the parameters will be
null. If a paging link is clicked, the page variable will contain the page number to display.
The ViewData element named CurrentSort provides the view with the current sort order, because this must be
included in the paging links in order to keep the sort order the same while paging.
The ViewData element named CurrentFilter provides the view with the current filter string. This value must be
included in the paging links in order to maintain the filter settings during paging, and it must be restored to the
text box when the page is redisplayed.
If the search string is changed during paging, the page has to be reset to 1, because the new filter can result in
different data to display. The search string is changed when a value is entered in the text box and the Submit
button is pressed. In that case, the searchString parameter isn't null.
{
page = 1;
}
else
{
}
At the end of the Index method, the PaginatedList.CreateAsync method converts the student query to a single
page of students in a collection type that supports paging. That single page of students is then passed to the view.
return View(await PaginatedList<Student>.CreateAsync(students.AsNoTracking(), page ?? 1, pageSize));
The PaginatedList.CreateAsync method takes a page number. The two question marks represent the null-
coalescing operator. The null-coalescing operator defines a default value for a nullable type; the expression
(page ?? 1) means return the value of page if it has a value, or return 1 if page is null.
Add paging links to the Student Index view

In Views/Students/Index.cshtml, replace the existing code with the following code. The changes are highlighted.
@model PaginatedList<ContosoUniversity.Models.Student>
@{
}
<h2>Index</h2>
<p>
</p>
<form asp-action="Index" method="get">

<p>
Find by name: <input type="text" name="SearchString" value="@ViewData["currentFilter"]" />
<a asp-action="Index">Back to Full List</a>
</p>
</div>
</form>
<thead>
<tr>
<th>
<a asp-action="Index" asp-route-sortOrder="@ViewData["NameSortParm"]" asp-route-
currentFilter="@ViewData["CurrentFilter"]">Last Name</a>
</th>
<th>
First Name
First Name
</th>
<th>
<a asp-action="Index" asp-route-sortOrder="@ViewData["DateSortParm"]" asp-route-
currentFilter="@ViewData["CurrentFilter"]">Enrollment Date</a>
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model)
{
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
@{
var prevDisabled = !Model.HasPreviousPage ? "disabled" : "";
var nextDisabled = !Model.HasNextPage ? "disabled" : "";
}
<a asp-action="Index"
asp-route-sortOrder="@ViewData["CurrentSort"]"
asp-route-page="@(Model.PageIndex - 1)"
asp-route-currentFilter="@ViewData["CurrentFilter"]"
Previous
</a>
asp-route-page="@(Model.PageIndex + 1)"
Next
</a>
The @model statement at the top of the page specifies that the view now gets a PaginatedList<T> object instead
of a List<T> object.
The column header links use the query string to pass the current search string to the controller so that the user
can sort within filter results:
<a asp-action="Index" asp-route-sortOrder="@ViewData["DateSortParm"]" asp-route-currentFilter

="@ViewData["CurrentFilter"]">Enrollment Date</a>
The paging buttons are displayed by tag helpers:

asp-route-page="@(Model.PageIndex - 1)"
Previous
</a>
Run the app and go to the Students page.
Click the paging links in different sort orders to make sure paging works. Then enter a search string and try
paging again to verify that paging also works correctly with sorting and filtering.
Create an About page that shows Student statistics

For the Contoso University website's About page, you'll display how many students have enrolled for each
enrollment date. This requires grouping and simple calculations on the groups. To accomplish this, you'll do the
following:
Create a view model class for the data that you need to pass to the view.
Modify the About method in the Home controller.
Modify the About view.
Create the view model
Create a SchoolViewModels folder in the Models folder.
In the new folder, add a class file EnrollmentDateGroup.cs and replace the template code with the following code:
using System;
{
public class EnrollmentDateGroup
{
public DateTime? EnrollmentDate { get; set; }
public int StudentCount { get; set; }

}
}
Modify the Home Controller

In HomeController.cs, add the following using statements at the top of the file:
Add a class variable for the database context immediately after the opening curly brace for the class, and get an
instance of the context from ASP.NET Core DI:
public class HomeController : Controller

{
public HomeController(SchoolContext context)

{
_context = context;
}
Replace the About method with the following code:
public async Task<ActionResult> About()

{
IQueryable<EnrollmentDateGroup> data =
from student in _context.Students
group student by student.EnrollmentDate into dateGroup
select new EnrollmentDateGroup()
{
EnrollmentDate = dateGroup.Key,
StudentCount = dateGroup.Count()
};
return View(await data.AsNoTracking().ToListAsync());
}
The LINQ statement groups the student entities by enrollment date, calculates the number of entities in each
group, and stores the results in a collection of EnrollmentDateGroup view model objects.
NOTE
In the 1.0 version of Entity Framework Core, the entire result set is returned to the client, and grouping is done on the
client. In some scenarios this could create performance problems. Be sure to test performance with production volumes of
data, and if necessary use raw SQL to do the grouping on the server. For information about how to use raw SQL, see the
last tutorial in this series.
Modify the About View
Replace the code in the Views/Home/About.cshtml file with the following code:
@model IEnumerable<ContosoUniversity.Models.SchoolViewModels.EnrollmentDateGroup>
@{
ViewData["Title"] = "Student Body Statistics";
}
<h2>Student Body Statistics</h2>
<table>
<tr>
<th>
Enrollment Date
</th>
<th>
Students
</th>
</tr>

{
<tr>
<td>
</td>
<td>
@item.StudentCount
</td>
</tr>
}
</table>
Run the app and go to the About page. The count of students for each enrollment date is displayed in a table.
Summary
In this tutorial, you've seen how to perform sorting, filtering, paging, and grouping. In the next tutorial, you'll learn
how to handle data model changes by using migrations.
P R E V IO U S NEXT
ASP.NET Core MVC with EF Core - Migrations - 4 of
10
In this tutorial, you start using the EF Core migrations feature for managing data model changes. In later
tutorials, you'll add more migrations as you change the data model.
Introduction to migrations
When you develop a new application, your data model changes frequently, and each time the model changes, it
gets out of sync with the database. You started these tutorials by configuring the Entity Framework to create the
database if it doesn't exist. Then each time you change the data model -- add, remove, or change entity classes or
change your DbContext class -- you can delete the database and EF creates a new one that matches the model,
and seeds it with test data.
This method of keeping the database in sync with the data model works well until you deploy the application to
production. When the application is running in production it's usually storing data that you want to keep, and you
don't want to lose everything each time you make a change such as adding a new column. The EF Core
Migrations feature solves this problem by enabling EF to update the database schema instead of creating a new
database.
Entity Framework Core NuGet packages for migrations

To work with migrations, you can use the Package Manager Console (PMC ) or the command-line interface
(CLI). These tutorials show how to use CLI commands. Information about the PMC is at the end of this tutorial.
The EF tools for the command-line interface (CLI) are provided in Microsoft.EntityFrameworkCore.Tools.DotNet.
To install this package, add it to the DotNetCliToolReference collection in the .csproj file, as shown. Note: You
have to install this package by editing the .csproj file; you can't use the install-package command or the package
manager GUI. You can edit the .csproj file by right-clicking the project name in Solution Explorer and selecting
Edit ContosoUniversity.csproj.
<ItemGroup>
<DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet" Version="2.0.0" />
<DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.0" />
</ItemGroup>
(The version numbers in this example were current when the tutorial was written.)
Change the connection string

In the appsettings.json file, change the name of the database in the connection string to ContosoUniversity2 or
some other name that you haven't used on the computer you're using.
{
},
This change sets up the project so that the first migration will create a new database. This isn't required to get
started with migrations, but you'll see later why it's a good idea.
NOTE
As an alternative to changing the database name, you can delete the database. Use SQL Server Object Explorer (SSOX)
or the database drop CLI command:
dotnet ef database drop
The following section explains how to run CLI commands.
Create an initial migration

Save your changes and build the project. Then open a command window and navigate to the project folder.
Here's a quick way to do that:
In Solution Explorer, right-click the project and choose Open in File Explorer from the context menu.
Enter "cmd" in the address bar and press Enter.
Enter the following command in the command window:
dotnet ef migrations add InitialCreate
You see output like the following in the command window:
info: Microsoft.AspNetCore.DataProtection.KeyManagement.XmlKeyManager[0]
User profile is available. Using 'C:\Users\username\AppData\Local\ASP.NET\DataProtection-Keys' as key
repository and Windows DPAPI to encrypt keys at rest.
info: Microsoft.EntityFrameworkCore.Infrastructure[100403]
Entity Framework Core 2.0.0-rtm-26452 initialized 'SchoolContext' using provider
'Microsoft.EntityFrameworkCore.SqlServer' with options: None
NOTE
If you see an error message No executable found matching command "dotnet-ef", see this blog post for help
troubleshooting.
If you see an error message "cannot access the file ... ContosoUniversity.dll because it is being used by another
process.", find the IIS Express icon in the Windows System Tray, and right-click it, then click ContosoUniversity
> Stop Site.
Examine the Up and Down methods
When you executed the migrations add command, EF generated the code that will create the database from
scratch. This code is in the Migrations folder, in the file named <timestamp>_InitialCreate.cs. The Up method of
the InitialCreate class creates the database tables that correspond to the data model entity sets, and the Down
method deletes them, as shown in the following example.
public partial class InitialCreate : Migration

{
{
name: "Course",
{
CourseID = table.Column<int>(nullable: false),
Credits = table.Column<int>(nullable: false),
Title = table.Column<string>(nullable: true)
},
{
table.PrimaryKey("PK_Course", x => x.CourseID);
});
// Additional code not shown

}
protected override void Down(MigrationBuilder migrationBuilder)

{
name: "Enrollment");
// Additional code not shown
}
}
Migrations calls the Up method to implement the data model changes for a migration. When you enter a
command to roll back the update, Migrations calls the Down method.
This code is for the initial migration that was created when you entered the migrations add InitialCreate
command. The migration name parameter ("InitialCreate" in the example) is used for the file name and can be
whatever you want. It's best to choose a word or phrase that summarizes what is being done in the migration.
For example, you might name a later migration "AddDepartmentTable".
If you created the initial migration when the database already exists, the database creation code is generated but
it doesn't have to run because the database already matches the data model. When you deploy the app to
another environment where the database doesn't exist yet, this code will run to create your database, so it's a
good idea to test it first. That's why you changed the name of the database in the connection string earlier -- so
that migrations can create a new one from scratch.
The data model snapshot

Migrations creates a snapshot of the current database schema in Migrations/SchoolContextModelSnapshot.cs.
When you add a migration, EF determines what changed by comparing the data model to the snapshot file.
When deleting a migration, use the dotnet ef migrations remove command. dotnet ef migrations remove deletes
the migration and ensures the snapshot is correctly reset.
See EF Core Migrations in Team Environments for more information about how the snapshot file is used.
Apply the migration to the database
In the command window, enter the following command to create the database and tables in it.
The output from the command is similar to the migrations add command, except that you see logs for the SQL
commands that set up the database. Most of the logs are omitted in the following sample output. If you prefer
not to see this level of detail in log messages, you can change the log level in the appsettings.Development.json
file. For more information, see Introduction to logging.
info: Microsoft.AspNetCore.DataProtection.KeyManagement.XmlKeyManager[0]
User profile is available. Using 'C:\Users\username\AppData\Local\ASP.NET\DataProtection-Keys' as key
repository and Windows DPAPI to encrypt keys at rest.
info: Microsoft.EntityFrameworkCore.Infrastructure[100403]
Entity Framework Core 2.0.0-rtm-26452 initialized 'SchoolContext' using provider
'Microsoft.EntityFrameworkCore.SqlServer' with options: None
info: Microsoft.EntityFrameworkCore.Database.Command[200101]
Executed DbCommand (467ms) [Parameters=[], CommandType='Text', CommandTimeout='60']
CREATE DATABASE [ContosoUniversity2];
CREATE TABLE [__EFMigrationsHistory] (
[MigrationId] nvarchar(150) NOT NULL,
[ProductVersion] nvarchar(32) NOT NULL,
CONSTRAINT [PK___EFMigrationsHistory] PRIMARY KEY ([MigrationId])
);
<logs omitted for brevity>
INSERT INTO [__EFMigrationsHistory] ([MigrationId], [ProductVersion])
VALUES (N'20170816151242_InitialCreate', N'2.0.0-rtm-26452');
Done.
Use SQL Server Object Explorer to inspect the database as you did in the first tutorial. You'll notice the
addition of an __EFMigrationsHistory table that keeps track of which migrations have been applied to the
database. View the data in that table and you'll see one row for the first migration. (The last log in the preceding
CLI output example shows the INSERT statement that creates this row.)
Run the application to verify that everything still works the same as before.
Command-line interface (CLI) vs. Package Manager Console (PMC)
The EF tooling for managing migrations is available from .NET Core CLI commands or from PowerShell cmdlets
in the Visual Studio Package Manager Console (PMC ) window. This tutorial shows how to use the CLI, but
you can use the PMC if you prefer.
The EF commands for the PMC commands are in the Microsoft.EntityFrameworkCore.Tools package. This
package is already included in the Microsoft.AspNetCore.All metapackage, so you don't have to install it.
Important: This isn't the same package as the one you install for the CLI by editing the .csproj file. The name of
this one ends in Tools , unlike the CLI package name which ends in Tools.DotNet .
For more information about the CLI commands, see .NET Core CLI.
For more information about the PMC commands, see Package Manager Console (Visual Studio).
Summary
In this tutorial, you've seen how to create and apply your first migration. In the next tutorial, you'll begin looking
at more advanced topics by expanding the data model. Along the way you'll create and apply additional
migrations.
P R E V IO U S NEXT
ASP.NET Core MVC with EF Core - Data Model - 5
of 10
In the previous tutorials, you worked with a simple data model that was composed of three entities. In this
tutorial, you'll add more entities and relationships and you'll customize the data model by specifying formatting,
validation, and database mapping rules.
When you're finished, the entity classes will make up the completed data model that's shown in the following
illustration:
Customize the Data Model by Using Attributes
In this section you'll see how to customize the data model by using attributes that specify formatting, validation,
and database mapping rules. Then in several of the following sections you'll create the complete School data
model by adding attributes to the classes you already created and creating new classes for the remaining entity
types in the model.
The DataType attribute
For student enrollment dates, all of the web pages currently display the time along with the date, although all you
care about for this field is the date. By using data annotation attributes, you can make one code change that will
fix the display format in every view that shows the data. To see an example of how to do that, you'll add an
attribute to the EnrollmentDate property in the Student class.
In Models/Student.cs, add a using statement for the System.ComponentModel.DataAnnotations namespace and add
DataType and DisplayFormat attributes to the EnrollmentDate property, as shown in the following example:
using System;
{
{

}
}
The DataType attribute is used to specify a data type that's more specific than the database intrinsic type. In this
case we only want to keep track of the date, not the date and time. The DataType Enumeration provides for many
data types, such as Date, Time, PhoneNumber, Currency, EmailAddress, and more. The DataType attribute can
also enable the application to automatically provide type-specific features. For example, a mailto: link can be
created for DataType.EmailAddress , and a date selector can be provided for DataType.Date in browsers that
support HTML5. The DataType attribute emits HTML 5 data- (pronounced data dash) attributes that HTML 5
browsers can understand. The DataType attributes don't provide any validation.
according to the default formats based on the server's CultureInfo.
The ApplyFormatInEditMode setting specifies that the formatting should also be applied when the value is
displayed in a text box for editing. (You might not want that for some fields -- for example, for currency values,
you might not want the currency symbol in the text box for editing.)
You can use the DisplayFormat attribute by itself, but it's generally a good idea to use the DataType attribute also.
The DataType attribute conveys the semantics of the data as opposed to how to render it on a screen, and
provides the following benefits that you don't get with DisplayFormat :
currency symbol, email links, some client-side input validation, etc.).
For more information, see the <input> tag helper documentation.
Run the app, go to the Students Index page and notice that times are no longer displayed for the enrollment
dates. The same will be true for any view that uses the Student model.
The StringLength attribute
You can also specify data validation rules and validation error messages using attributes. The StringLength
attribute sets the maximum length in the database and provides client side and server side validation for
ASP.NET Core MVC. You can also specify the minimum string length in this attribute, but the minimum value has
no impact on the database schema.
Suppose you want to ensure that users don't enter more than 50 characters for a name. To add this limitation,
add StringLength attributes to the LastName and FirstMidName properties, as shown in the following example:
using System;
{
{
[StringLength(50)]

}
}
The StringLengthattribute won't prevent a user from entering white space for a name. You can use the
RegularExpression attribute to apply restrictions to the input. For example, the following code requires the first
character to be upper case and the remaining characters to be alphabetical:
The MaxLength attribute provides functionality similar to the StringLength attribute but doesn't provide client
side validation.
The database model has now changed in a way that requires a change in the database schema. You'll use
migrations to update the schema without losing any data that you may have added to the database by using the
application UI.
Save your changes and build the project. Then open the command window in the project folder and enter the
following commands:
dotnet ef migrations add MaxLengthOnNames
The migrations add command warns that data loss may occur, because the change makes the maximum length
shorter for two columns. Migrations creates a file named <timeStamp>_MaxLengthOnNames.cs. This file
contains code in the Up method that will update the database to match the current data model. The
database update command ran that code.
The timestamp prefixed to the migrations file name is used by Entity Framework to order the migrations. You can
create multiple migrations before running the update-database command, and then all of the migrations are
applied in the order in which they were created.
Run the app, select the Students tab, click Create New, and enter either name longer than 50 characters. When
you click Create, client side validation shows an error message.
You can also use attributes to control how your classes and properties are mapped to the database. Suppose you
had used the name FirstMidName for the first-name field because the field might also contain a middle name. But
you want the database column to be named FirstName , because users who will be writing ad-hoc queries against
the database are accustomed to that name. To make this mapping, you can use the Column attribute.
The Column attribute specifies that when the database is created, the column of the Student table that maps to
the FirstMidName property will be named FirstName . In other words, when your code refers to
Student.FirstMidName , the data will come from or be updated in the FirstName column of the Student table. If
you don't specify column names, they're given the same name as the property name.
In the Student.cs file, add a using statement for System.ComponentModel.DataAnnotations.Schema and add the
column name attribute to the FirstMidName property, as shown in the following highlighted code:
using System;
{
{
[StringLength(50)]

}
}
The addition of the Column attribute changes the model backing the SchoolContext , so it won't match the
database.
following commands to create another migration:
dotnet ef migrations add ColumnFirstName
In SQL Server Object Explorer, open the Student table designer by double-clicking the Student table.
Before you applied the first two migrations, the name columns were of type nvarchar(MAX). They're now
nvarchar(50) and the column name has changed from FirstMidName to FirstName.
NOTE
If you try to compile before you finish creating all of the entity classes in the following sections, you might get compiler
errors.
Final changes to the Student entity
In Models/Student.cs, replace the code you added earlier with the following code. The changes are highlighted.
using System;
{
{
[Required]
[StringLength(50)]
[Required]
{
get
{
}
}

}
}
The Required attribute

The Required attribute makes the name properties required fields. The Required attribute isn't needed for non-
nullable types such as value types (DateTime, int, double, float, etc.). Types that can't be null are automatically
treated as required fields.
You could remove the Required attribute and replace it with a minimum length parameter for the StringLength
attribute:

[StringLength(50, MinimumLength=1)]
The Display attribute

The Display attribute specifies that the caption for the text boxes should be "First Name", "Last Name", "Full
Name", and "Enrollment Date" instead of the property name in each instance (which has no space dividing the
words).
The FullName calculated property
FullName is a calculated property that returns a value that's created by concatenating two other properties.
Therefore it has only a get accessor, and no FullName column will be generated in the database.
Create the Instructor Entity

Create Models/Instructor.cs, replacing the template code with the following code:
using System;
{
public class Instructor
{
[Required]
[StringLength(50)]
[Required]
[StringLength(50)]

{
get { return LastName + ", " + FirstMidName; }
}

}
}
Notice that several properties are the same in the Student and Instructor entities. In the Implementing
Inheritance tutorial later in this series, you'll refactor this code to eliminate the redundancy.
You can put multiple attributes on one line, so you could also write the HireDate attributes as follows:
[DataType(DataType.Date),Display(Name = "Hire Date"),DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}",

ApplyFormatInEditMode = true)]
The CourseAssignments and OfficeAssignment navigation properties

The CourseAssignments and OfficeAssignment properties are navigation properties.
An instructor can teach any number of courses, so CourseAssignments is defined as a collection.
If a navigation property can hold multiple entities, its type must be a list in which entries can be added, deleted,
and updated. You can specify ICollection<T> or a type such as List<T> or HashSet<T> . If you specify
ICollection<T> , EF creates a HashSet<T> collection by default.
The reason why these are CourseAssignment entities is explained below in the section about many-to-many
relationships.
Contoso University business rules state that an instructor can only have at most one office, so the
OfficeAssignment property holds a single OfficeAssignment entity (which may be null if no office is assigned).
Create the OfficeAssignment entity
Create Models/OfficeAssignment.cs with the following code:
{
public class OfficeAssignment
{
[Key]
[StringLength(50)]
[Display(Name = "Office Location")]
public string Location { get; set; }

}
}
The Key attribute

There's a one-to-zero-or-one relationship between the Instructor and the OfficeAssignment entities. An office
assignment only exists in relation to the instructor it's assigned to, and therefore its primary key is also its foreign
key to the Instructor entity. But the Entity Framework can't automatically recognize InstructorID as the primary
key of this entity because its name doesn't follow the ID or classnameID naming convention. Therefore, the Key
attribute is used to identify it as the key:
[Key]
You can also use the Key attribute if the entity does have its own primary key but you want to name the property
something other than classnameID or ID.
By default, EF treats the key as non-database-generated because the column is for an identifying relationship.
The Instructor navigation property
The Instructor entity has a nullable OfficeAssignment navigation property (because an instructor might not have
an office assignment), and the OfficeAssignment entity has a non-nullable Instructor navigation property
(because an office assignment can't exist without an instructor -- InstructorID is non-nullable). When an
Instructor entity has a related OfficeAssignment entity, each entity will have a reference to the other one in its
navigation property.
You could put a [Required] attribute on the Instructor navigation property to specify that there must be a related
instructor, but you don't have to do that because the InstructorID foreign key (which is also the key to this table)
is non-nullable.
Modify the Course Entity
In Models/Course.cs, replace the code you added earlier with the following code. The changes are highlighted.
{
public class Course
{

[Range(0, 5)]

}
}
The course entity has a foreign key property DepartmentID which points to the related Department entity and it
has a Department navigation property.
The Entity Framework doesn't require you to add a foreign key property to your data model when you have a
navigation property for a related entity. EF automatically creates foreign keys in the database wherever they're
needed and creates shadow properties for them. But having the foreign key in the data model can make updates
simpler and more efficient. For example, when you fetch a course entity to edit, the Department entity is null if
you don't load it, so when you update the course entity, you would have to first fetch the Department entity.
When the foreign key property DepartmentID is included in the data model, you don't need to fetch the
Department entity before you update.
The DatabaseGenerated attribute
The DatabaseGenerated attribute with the None parameter on the CourseID property specifies that primary key
values are provided by the user rather than generated by the database.
By default, Entity Framework assumes that primary key values are generated by the database. That's what you
want in most scenarios. However, for Course entities, you'll use a user-specified course number such as a 1000
series for one department, a 2000 series for another department, and so on.
The DatabaseGenerated attribute can also be used to generate default values, as in the case of database columns
used to record the date a row was created or updated. For more information, see Generated Properties.
The foreign key properties and navigation properties in the Course entity reflect the following relationships:
A course is assigned to one department, so there's a DepartmentID foreign key and a Department navigation
property for the reasons mentioned above.

A course can have any number of students enrolled in it, so the Enrollments navigation property is a collection:
A course may be taught by multiple instructors, so the CourseAssignments navigation property is a collection (the
type CourseAssignment is explained later):
Create the Department entity

Create Models/Department.cs with the following code:
using System;
{
{


}
}

Earlier you used the Column attribute to change column name mapping. In the code for the Department entity,
the Column attribute is being used to change SQL data type mapping so that the column will be defined using
the SQL Server money type in the database:
[Column(TypeName="money")]
Column mapping is generally not required, because the Entity Framework chooses the appropriate SQL Server
data type based on the CLR type that you define for the property. The CLR decimal type maps to a SQL Server
decimal type. But in this case you know that the column will be holding currency amounts, and the money data
type is more appropriate for that.
The foreign key and navigation properties reflect the following relationships:
A department may or may not have an administrator, and an administrator is always an instructor. Therefore the
InstructorID property is included as the foreign key to the Instructor entity, and a question mark is added after
the int type designation to mark the property as nullable. The navigation property is named Administrator but
holds an Instructor entity:

A department may have many courses, so there's a Courses navigation property:
NOTE
By convention, the Entity Framework enables cascade delete for non-nullable foreign keys and for many-to-many
relationships. This can result in circular cascade delete rules, which will cause an exception when you try to add a migration.
For example, if you didn't define the Department.InstructorID property as nullable, EF would configure a cascade delete rule
to delete the instructor when you delete the department, which isn't what you want to have happen. If your business rules
required the InstructorID property to be non-nullable, you would have to use the following fluent API statement to
disable cascade delete on the relationship:
.HasOne(d => d.Administrator)
.WithMany()
.OnDelete(DeleteBehavior.Restrict)
Modify the Enrollment entity
In Models/Enrollment.cs, replace the code you added earlier with the following code:
{
public enum Grade
{
A, B, C, D, F
}

{
[DisplayFormat(NullDisplayText = "No grade")]

}
}

The foreign key properties and navigation properties reflect the following relationships:
An enrollment record is for a single course, so there's a CourseID foreign key property and a Course navigation
property:

An enrollment record is for a single student, so there's a StudentID foreign key property and a Student
navigation property:

Many-to-Many Relationships
There's a many-to-many relationship between the Student and Course entities, and the Enrollment entity
functions as a many-to-many join table with payload in the database. "With payload" means that the Enrollment
table contains additional data besides foreign keys for the joined tables (in this case, a primary key and a Grade
property).
The following illustration shows what these relationships look like in an entity diagram. (This diagram was
generated using the Entity Framework Power Tools for EF 6.x; creating the diagram isn't part of the tutorial, it's
just being used here as an illustration.)
Each relationship line has a 1 at one end and an asterisk (*) at the other, indicating a one-to-many relationship.
If the Enrollment table didn't include grade information, it would only need to contain the two foreign keys
CourseID and StudentID. In that case, it would be a many-to-many join table without payload (or a pure join
table) in the database. The Instructor and Course entities have that kind of many-to-many relationship, and your
next step is to create an entity class to function as a join table without payload.
(EF 6.x supports implicit join tables for many-to-many relationships, but EF Core doesn't. For more information,
see the discussion in the EF Core GitHub repository.)
The CourseAssignment entity
Create Models/CourseAssignment.cs with the following code:

using System;
{
public class CourseAssignment
{
}
}
Join entity names

A join table is required in the database for the Instructor-to-Courses many-to-many relationship, and it has to be
represented by an entity set. It's common to name a join entity EntityName1EntityName2 , which in this case would
be CourseInstructor . However, we recommend that you choose a name that describes the relationship. Data
models start out simple and grow, with no-payload joins frequently getting payloads later. If you start with a
descriptive entity name, you won't have to change the name later. Ideally, the join entity would have its own
natural (possibly single word) name in the business domain. For example, Books and Customers could be linked
through Ratings. For this relationship, CourseAssignment is a better choice than CourseInstructor .
Composite key
Since the foreign keys are not nullable and together uniquely identify each row of the table, there's no need for a
separate primary key. The InstructorID and CourseID properties should function as a composite primary key. The
only way to identify composite primary keys to EF is by using the fluent API (it can't be done by using attributes).
You'll see how to configure the composite primary key in the next section.
The composite key ensures that while you can have multiple rows for one course, and multiple rows for one
instructor, you can't have multiple rows for the same instructor and course. The Enrollment join entity defines its
own primary key, so duplicates of this sort are possible. To prevent such duplicates, you could add a unique index
on the foreign key fields, or configure Enrollment with a primary composite key similar to CourseAssignment . For
more information, see Indexes.
Update the database context

Add the following highlighted code to the Data/SchoolContext.cs file:
{
{
{
}


{
}
}
}
This code adds the new entities and configures the CourseAssignment entity's composite primary key.
Fluent API alternative to attributes

The code in the OnModelCreating method of the DbContext class uses the fluent API to configure EF behavior.
The API is called "fluent" because it's often used by stringing a series of method calls together into a single
statement, as in this example from the EF Core documentation:

{
modelBuilder.Entity<Blog>()
.Property(b => b.Url)
.IsRequired();
}
In this tutorial, you're using the fluent API only for database mapping that you can't do with attributes. However,
you can also use the fluent API to specify most of the formatting, validation, and mapping rules that you can do
by using attributes. Some attributes such as MinimumLength can't be applied with the fluent API. As mentioned
previously, MinimumLength doesn't change the schema, it only applies a client and server side validation rule.
Some developers prefer to use the fluent API exclusively so that they can keep their entity classes "clean." You can
mix attributes and fluent API if you want, and there are a few customizations that can only be done by using
fluent API, but in general the recommended practice is to choose one of these two approaches and use that
consistently as much as possible. If you do use both, note that wherever there's a conflict, Fluent API overrides
attributes.
For more information about attributes vs. fluent API, see Methods of configuration.
Entity Diagram Showing Relationships

The following illustration shows the diagram that the Entity Framework Power Tools create for the completed
School model.
Besides the one-to-many relationship lines (1 to *), you can see here the one-to-zero-or-one relationship line (1
to 0..1) between the Instructor and OfficeAssignment entities and the zero-or-one-to-many relationship line (0..1
to *) between the Instructor and Department entities.
Seed the Database with Test Data

Replace the code in the Data/DbInitializer.cs file with the following code in order to provide seed data for the new
entities you've created.
using System;
using System.Linq;
{
{
{
//context.Database.EnsureCreated();

if (context.Students.Any())
{
}

{
new Student { FirstMidName = "Carson", LastName = "Alexander",
new Student { FirstMidName = "Meredith", LastName = "Alonso",
new Student { FirstMidName = "Arturo", LastName = "Anand",
new Student { FirstMidName = "Gytis", LastName = "Barzdukas",
new Student { FirstMidName = "Yan", LastName = "Li",
new Student { FirstMidName = "Peggy", LastName = "Justice",
new Student { FirstMidName = "Laura", LastName = "Norman",
new Student { FirstMidName = "Nino", LastName = "Olivetto",
EnrollmentDate = DateTime.Parse("2005-09-01") }
};

{
context.Students.Add(s);
}
var instructors = new Instructor[]

{
new Instructor { FirstMidName = "Kim", LastName = "Abercrombie",
new Instructor { FirstMidName = "Fadi", LastName = "Fakhouri",
new Instructor { FirstMidName = "Roger", LastName = "Harui",
new Instructor { FirstMidName = "Candace", LastName = "Kapoor",
new Instructor { FirstMidName = "Roger", LastName = "Zheng",
HireDate = DateTime.Parse("2004-02-12") }
};
foreach (Instructor i in instructors)

{
context.Instructors.Add(i);
}
var departments = new Department[]

{
new Department { Name = "English", Budget = 350000,
InstructorID = instructors.Single( i => i.LastName == "Abercrombie").ID },
new Department { Name = "Mathematics", Budget = 100000,
InstructorID = instructors.Single( i => i.LastName == "Fakhouri").ID },
new Department { Name = "Engineering", Budget = 350000,
InstructorID = instructors.Single( i => i.LastName == "Harui").ID },
new Department { Name = "Economics", Budget = 100000,
InstructorID = instructors.Single( i => i.LastName == "Kapoor").ID }
};
foreach (Department d in departments)

{
context.Departments.Add(d);
}

{
new Course {CourseID = 1050, Title = "Chemistry", Credits = 3,
DepartmentID = departments.Single( s => s.Name == "Engineering").DepartmentID
},
new Course {CourseID = 4022, Title = "Microeconomics", Credits = 3,
},
new Course {CourseID = 4041, Title = "Macroeconomics", Credits = 3,
},
new Course {CourseID = 1045, Title = "Calculus", Credits = 4,
},
new Course {CourseID = 3141, Title = "Trigonometry", Credits = 4,
},
new Course {CourseID = 2021, Title = "Composition", Credits = 3,
},
new Course {CourseID = 2042, Title = "Literature", Credits = 4,
},
};

{
}
var officeAssignments = new OfficeAssignment[]

{
InstructorID = instructors.Single( i => i.LastName == "Fakhouri").ID,
Location = "Smith 17" },
InstructorID = instructors.Single( i => i.LastName == "Harui").ID,
Location = "Gowan 27" },
InstructorID = instructors.Single( i => i.LastName == "Kapoor").ID,
Location = "Thompson 304" },
};

{
context.OfficeAssignments.Add(o);
}
var courseInstructors = new CourseAssignment[]

{
InstructorID = instructors.Single(i => i.LastName == "Kapoor").ID
},
},
},
},
InstructorID = instructors.Single(i => i.LastName == "Fakhouri").ID
},
},
},
CourseID = courses.Single(c => c.Title == "Literature" ).CourseID,
},
};
foreach (CourseAssignment ci in courseInstructors)

{
context.CourseAssignments.Add(ci);
}

{
new Enrollment {
Grade = Grade.A
},
new Enrollment {
Grade = Grade.C
},
new Enrollment {
Grade = Grade.B
},
new Enrollment {
Grade = Grade.B
},
new Enrollment {
Grade = Grade.B
},
new Enrollment {
Grade = Grade.B
},
new Enrollment {
CourseID = courses.Single(c => c.Title == "Chemistry" ).CourseID
},
new Enrollment {
CourseID = courses.Single(c => c.Title == "Microeconomics").CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Barzdukas").ID,
CourseID = courses.Single(c => c.Title == "Chemistry").CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Li").ID,
CourseID = courses.Single(c => c.Title == "Composition").CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Justice").ID,
CourseID = courses.Single(c => c.Title == "Literature").CourseID,
Grade = Grade.B
}
};

{
var enrollmentInDataBase = context.Enrollments.Where(
s =>
s.Student.ID == e.StudentID &&
s.Course.CourseID == e.CourseID).SingleOrDefault();
if (enrollmentInDataBase == null)
{
context.Enrollments.Add(e);
}
}
}
}
}
As you saw in the first tutorial, most of this code simply creates new entity objects and loads sample data into
properties as required for testing. Notice how the many-to-many relationships are handled: the code creates
relationships by creating entities in the Enrollments and CourseAssignment join entity sets.
Add a migration
migrations add command (don't do the update-database command yet):
dotnet ef migrations add ComplexDataModel
You get a warning about possible data loss.
An operation was scaffolded that may result in the loss of data. Please review the migration for accuracy.
If you tried to run the database update command at this point (don't do it yet), you would get the following error:
The ALTER TABLE statement conflicted with the FOREIGN KEY constraint
"FK_dbo.Course_dbo.Department_DepartmentID". The conflict occurred in database "ContosoUniversity",
table "dbo.Department", column 'DepartmentID'.
Sometimes when you execute migrations with existing data, you need to insert stub data into the database to
satisfy foreign key constraints. The generated code in the Up method adds a non-nullable DepartmentID foreign
key to the Course table. If there are already rows in the Course table when the code runs, the AddColumn
operation fails because SQL Server doesn't know what value to put in the column that can't be null. For this
tutorial you'll run the migration on a new database, but in a production application you'd have to make the
migration handle existing data, so the following directions show an example of how to do that.
To make this migration work with existing data you have to change the code to give the new column a default
value, and create a stub department named "Temp" to act as the default department. As a result, existing Course
rows will all be related to the "Temp" department after the Up method runs.
Open the {timestamp }_ComplexDataModel.cs file.
Comment out the line of code that adds the DepartmentID column to the Course table.
migrationBuilder.AlterColumn<string>(
name: "Title",
table: "Course",
maxLength: 50,
nullable: true,
oldClrType: typeof(string),
oldNullable: true);
//migrationBuilder.AddColumn<int>(
// name: "DepartmentID",
// table: "Course",
// nullable: false,
// defaultValue: 0);
Add the following highlighted code after the code that creates the Department table:
name: "Department",
{
DepartmentID = table.Column<int>(nullable: false)
.Annotation("SqlServer:ValueGenerationStrategy",
SqlServerValueGenerationStrategy.IdentityColumn),
Budget = table.Column<decimal>(type: "money", nullable: false),
InstructorID = table.Column<int>(nullable: true),
Name = table.Column<string>(maxLength: 50, nullable: true),
StartDate = table.Column<DateTime>(nullable: false)
},
{
table.PrimaryKey("PK_Department", x => x.DepartmentID);
table.ForeignKey(
name: "FK_Department_Instructor_InstructorID",
column: x => x.InstructorID,
principalTable: "Instructor",
onDelete: ReferentialAction.Restrict);
});
migrationBuilder.Sql("INSERT INTO dbo.Department (Name, Budget, StartDate) VALUES ('Temp', 0.00,

GETDATE())");
// Default value for FK points to department created above, with
// defaultValue changed to 1 in following AddColumn statement.
table: "Course",
nullable: false,
defaultValue: 1);
In a production application, you would write code or scripts to add Department rows and relate Course rows to
the new Department rows. You would then no longer need the "Temp" department or the default value on the
Course.DepartmentID column.
Save your changes and build the project.
Change the connection string and update the database

You now have new code in the DbInitializer class that adds seed data for the new entities to an empty database.
To make EF create a new empty database, change the name of the database in the connection string in
appsettings.json to ContosoUniversity3 or some other name that you haven't used on the computer you're using.
{
},
Save your change to appsettings.json.

NOTE
As an alternative to changing the database name, you can delete the database. Use SQL Server Object Explorer (SSOX)
or the database drop CLI command:
After you have changed the database name or deleted the database, run the database update command in the
command window to execute the migrations.
Run the app to cause the DbInitializer.Initialize method to run and populate the new database.
Open the database in SSOX as you did earlier, and expand the Tables node to see that all of the tables have been
created. (If you still have SSOX open from the earlier time, click the Refresh button.)
Run the app to trigger the initializer code that seeds the database.
Right-click the CourseAssignment table and select View Data to verify that it has data in it.
Summary
You now have a more complex data model and corresponding database. In the following tutorial, you'll learn
more about how to access related data.
P R E V IO U S NEXT
ASP.NET Core MVC with EF Core - Read Related
Data - 6 of 10
In the previous tutorial, you completed the School data model. In this tutorial, you'll read and display related data
-- that is, data that the Entity Framework loads into navigation properties.
The following illustrations show the pages that you'll work with.
Eager, explicit, and lazy Loading of related data
There are several ways that Object-Relational Mapping (ORM ) software such as Entity Framework can load
related data into the navigation properties of an entity:
Eager loading. When the entity is read, related data is retrieved along with it. This typically results in a
single join query that retrieves all of the data that's needed. You specify eager loading in Entity Framework
Core by using the Include and ThenInclude methods.
You can retrieve some of the data in separate queries, and EF "fixes up" the navigation properties. That is,
EF automatically adds the separately retrieved entities where they belong in navigation properties of
previously retrieved entities. For the query that retrieves related data, you can use the Load method
instead of a method that returns a list or object, such as ToList or Single .
Explicit loading. When the entity is first read, related data isn't retrieved. You write code that retrieves the
related data if it's needed. As in the case of eager loading with separate queries, explicit loading results in
multiple queries sent to the database. The difference is that with explicit loading, the code specifies the
navigation properties to be loaded. In Entity Framework Core 1.1 you can use the Load method to do
explicit loading. For example:
Lazy loading. When the entity is first read, related data isn't retrieved. However, the first time you attempt
to access a navigation property, the data required for that navigation property is automatically retrieved. A
query is sent to the database each time you try to get data from a navigation property for the first time.
Entity Framework Core 1.0 doesn't support lazy loading.
Performance considerations
If you know you need related data for every entity retrieved, eager loading often offers the best performance,
because a single query sent to the database is typically more efficient than separate queries for each entity
retrieved. For example, suppose that each department has ten related courses. Eager loading of all related data
would result in just a single (join) query and a single round trip to the database. A separate query for courses for
each department would result in eleven round trips to the database. The extra round trips to the database are
especially detrimental to performance when latency is high.
On the other hand, in some scenarios separate queries is more efficient. Eager loading of all related data in one
query might cause a very complex join to be generated, which SQL Server can't process efficiently. Or if you need
to access an entity's navigation properties only for a subset of a set of the entities you're processing, separate
queries might perform better because eager loading of everything up front would retrieve more data than you
need. If performance is critical, it's best to test performance both ways in order to make the best choice.
Create a Courses page that displays Department name

The Course entity includes a navigation property that contains the Department entity of the department that the
course is assigned to. To display the name of the assigned department in a list of courses, you need to get the
Name property from the Department entity that's in the Course.Department navigation property.
Create a controller named CoursesController for the Course entity type, using the same options for the MVC
Controller with views, using Entity Framework scaffolder that you did earlier for the Students controller, as
shown in the following illustration:
Open CoursesController.cs and examine the Index method. The automatic scaffolding has specified eager
loading for the Department navigation property by using the Include method.
Replace the Index method with the following code that uses a more appropriate name for the IQueryable that
returns Course entities ( courses instead of schoolContext ):

{
var courses = _context.Courses
.AsNoTracking();
return View(await courses.ToListAsync());
}
Open Views/Courses/Index.cshtml and replace the template code with the following code. The changes are
highlighted:
@model IEnumerable<ContosoUniversity.Models.Course>
@{
ViewData["Title"] = "Courses";
}
<h2>Courses</h2>
<p>
</p>
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.CourseID)
</th>
<th>
</th>
<th>
@Html.DisplayNameFor(model => model.Credits)
</th>
<th>
@Html.DisplayNameFor(model => model.Department)
</th>
<th></th>
</tr>
</thead>
<tbody>
{
<tr>
<td>
@Html.DisplayFor(modelItem => item.CourseID)
</td>
<td>
</td>
<td>
@Html.DisplayFor(modelItem => item.Credits)
</td>
<td>
</td>
<td>
<a asp-action="Edit" asp-route-id="@item.CourseID">Edit</a> |
<a asp-action="Details" asp-route-id="@item.CourseID">Details</a> |
<a asp-action="Delete" asp-route-id="@item.CourseID">Delete</a>
</td>
</tr>
}
</tbody>
</table>
You've made the following changes to the scaffolded code:

Changed the heading from Index to Courses.
Added a Number column that shows the CourseID property value. By default, primary keys aren't
scaffolded because normally they're meaningless to end users. However, in this case the primary key is
meaningful and you want to show it.
Changed the Department column to display the department name. The code displays the Name property
of the Department entity that's loaded into the Department navigation property:
Run the app and select the Courses tab to see the list with department names.
Create an Instructors page that shows Courses and Enrollments

In this section, you'll create a controller and view for the Instructor entity in order to display the Instructors page:
This page reads and displays related data in the following ways:
The list of instructors displays related data from the OfficeAssignment entity. The Instructor and
OfficeAssignment entities are in a one-to-zero-or-one relationship. You'll use eager loading for the
OfficeAssignment entities. As explained earlier, eager loading is typically more efficient when you need the
related data for all retrieved rows of the primary table. In this case, you want to display office assignments
for all displayed instructors.
When the user selects an instructor, related Course entities are displayed. The Instructor and Course
entities are in a many-to-many relationship. You'll use eager loading for the Course entities and their
related Department entities. In this case, separate queries might be more efficient because you need
courses only for the selected instructor. However, this example shows how to use eager loading for
navigation properties within entities that are themselves in navigation properties.
When the user selects a course, related data from the Enrollments entity set is displayed. The Course and
Enrollment entities are in a one-to-many relationship. You'll use separate queries for Enrollment entities
and their related Student entities.
Create a view model for the Instructor Index view
The Instructors page shows data from three different tables. Therefore, you'll create a view model that includes
three properties, each holding the data for one of the tables.
In the SchoolViewModels folder, create InstructorIndexData.cs and replace the existing code with the following
code:
using System;
using System.Linq;
{
public class InstructorIndexData
{
public IEnumerable<Instructor> Instructors { get; set; }
public IEnumerable<Course> Courses { get; set; }
public IEnumerable<Enrollment> Enrollments { get; set; }
}
}
Create the Instructor controller and views

Create an Instructors controller with EF read/write actions as shown in the following illustration:
Open InstructorsController.cs and add a using statement for the ViewModels namespace:
Replace the Index method with the following code to do eager loading of related data and put it in the view
model.
public async Task<IActionResult> Index(int? id, int? courseID)
{
var viewModel = new InstructorIndexData();
viewModel.Instructors = await _context.Instructors
.AsNoTracking()
.ToListAsync();
if (id != null)
{
ViewData["InstructorID"] = id.Value;
Instructor instructor = viewModel.Instructors.Where(
viewModel.Courses = instructor.CourseAssignments.Select(s => s.Course);
}
{
ViewData["CourseID"] = courseID.Value;
viewModel.Enrollments = viewModel.Courses.Where(
}
return View(viewModel);
}
The method accepts optional route data ( id ) and a query string parameter ( courseID ) that provide the ID
values of the selected instructor and selected course. The parameters are provided by the Select hyperlinks on
the page.
The code begins by creating an instance of the view model and putting in it the list of instructors. The code
specifies eager loading for the Instructor.OfficeAssignment and the Instructor.CourseAssignments navigation
properties. Within the CourseAssignments property, the Course property is loaded, and within that, the
Enrollments and Department properties are loaded, and within each Enrollment entity the Student property is
loaded.

.AsNoTracking()
.ToListAsync();
Since the view always requires the OfficeAssignment entity, it's more efficient to fetch that in the same query.
Course entities are required when an instructor is selected in the web page, so a single query is better than
multiple queries only if the page is displayed more often with a course selected than without.
The code repeats CourseAssignments and Course because you need two properties from Course . The first string
of ThenInclude calls gets CourseAssignment.Course , Course.Enrollments , and Enrollment.Student .

.AsNoTracking()
.ToListAsync();
At that point in the code, another ThenInclude would be for navigation properties of Student , which you don't
need. But calling Include starts over with Instructor properties, so you have to go through the chain again, this
time specifying Course.Department instead of Course.Enrollments .

.AsNoTracking()
.ToListAsync();
The following code executes when an instructor was selected. The selected instructor is retrieved from the list of
instructors in the view model. The view model's Courses property is then loaded with the Course entities from
that instructor's CourseAssignments navigation property.
if (id != null)
{
}
The Where method returns a collection, but in this case the criteria passed to that method result in only a single
Instructor entity being returned. The Single method converts the collection into a single Instructor entity, which
gives you access to that entity's CourseAssignments property. The CourseAssignments property contains
CourseAssignment entities, from which you want only the related Course entities.
You use the Single method on a collection when you know the collection will have only one item. The Single
method throws an exception if the collection passed to it's empty or if there's more than one item. An alternative
is SingleOrDefault , which returns a default value (null in this case) if the collection is empty. However, in this case
that would still result in an exception (from trying to find a Courses property on a null reference), and the
exception message would less clearly indicate the cause of the problem. When you call the Single method, you
can also pass in the Where condition instead of calling the Where method separately:
.Single(i => i.ID == id.Value)
Instead of:
.Where(i => i.ID == id.Value).Single()
Next, if a course was selected, the selected course is retrieved from the list of courses in the view model. Then the
view model's Enrollments property is loaded with the Enrollment entities from that course's Enrollments
navigation property.
{
viewModel.Enrollments = viewModel.Courses.Where(
}
Modify the Instructor Index view

In Views/Instructors/Index.cshtml, replace the template code with the following code. The changes are
highlighted.
@model ContosoUniversity.Models.SchoolViewModels.InstructorIndexData
@{
ViewData["Title"] = "Instructors";
}
<h2>Instructors</h2>
<p>
</p>
<thead>
<tr>
<th>Last Name</th>
<th>First Name</th>
<th>Hire Date</th>
<th>Office</th>
<th>Courses</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Instructors)
{
if (item.ID == (int?)ViewData["InstructorID"])
{
}
<td>
</td>
<td>
</td>
<td>
@Html.DisplayFor(modelItem => item.HireDate)
</td>
<td>
{
}
</td>
<td>
@{
foreach (var course in item.CourseAssignments)
{
@course.Course.CourseID @: @course.Course.Title <br />
}
}
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
You've made the following changes to the existing code:

Changed the model class to InstructorIndexData .
Changed the page title from Index to Instructors.
Added an Office column that displays item.OfficeAssignment.Location only if item.OfficeAssignment isn't
null. (Because this is a one-to-zero-or-one relationship, there might not be a related OfficeAssignment
entity.)

{
}
Added a Courses column that displays courses taught by each instructor. See Explicit Line Transition with
@: for more about this razor syntax.
Added code that dynamically adds class="success" to the tr element of the selected instructor. This sets
a background color for the selected row using a Bootstrap class.

if (item.ID == (int?)ViewData["InstructorID"])
{
}
Added a new hyperlink labeled Select immediately before the other links in each row, which causes the
selected instructor's ID to be sent to the Index method.
Run the app and select the Instructors tab. The page displays the Location property of related OfficeAssignment
entities and an empty table cell when there's no related OfficeAssignment entity.
In the Views/Instructors/Index.cshtml file, after the closing table element (at the end of the file), add the following
code. This code displays a list of courses related to an instructor when an instructor is selected.
@if (Model.Courses != null)
{
<h3>Courses Taught by Selected Instructor</h3>
<tr>
<th></th>
<th>Number</th>
<th>Title</th>
<th>Department</th>
</tr>
@foreach (var item in Model.Courses)

{
if (item.CourseID == (int?)ViewData["CourseID"])
{
}
<td>
@Html.ActionLink("Select", "Index", new { courseID = item.CourseID })
</td>
<td>
@item.CourseID
</td>
<td>
@item.Title
</td>
<td>
@item.Department.Name
</td>
</tr>
}
</table>
}
This code reads the Courses property of the view model to display a list of courses. It also provides a Select
hyperlink that sends the ID of the selected course to the Index action method.
Refresh the page and select an instructor. Now you see a grid that displays courses assigned to the selected
instructor, and for each course you see the name of the assigned department.
After the code block you just added, add the following code. This displays a list of the students who are enrolled
in a course when that course is selected.
@if (Model.Enrollments != null)

{
<h3>
Students Enrolled in Selected Course
</h3>
<tr>
<th>Name</th>
<th>Grade</th>
</tr>
@foreach (var item in Model.Enrollments)
{
<tr>
<td>
@item.Student.FullName
</td>
<td>
</td>
</tr>
}
</table>
}
This code reads the Enrollments property of the view model in order to display a list of students enrolled in the
course.
Refresh the page again and select an instructor. Then select a course to see the list of enrolled students and their
grades.
Explicit loading
When you retrieved the list of instructors in InstructorsController.cs, you specified eager loading for the
CourseAssignments navigation property.
Suppose you expected users to only rarely want to see enrollments in a selected instructor and course. In that
case, you might want to load the enrollment data only if it's requested. To see an example of how to do explicit
loading, replace the Index method with the following code, which removes eager loading for Enrollments and
loads that property explicitly. The code changes are highlighted.
public async Task<IActionResult> Index(int? id, int? courseID)
{
var viewModel = new InstructorIndexData();
.ToListAsync();
if (id != null)
{
}
{
var selectedCourse = viewModel.Courses.Where(x => x.CourseID == courseID).Single();
await _context.Entry(selectedCourse).Collection(x => x.Enrollments).LoadAsync();
foreach (Enrollment enrollment in selectedCourse.Enrollments)
{
await _context.Entry(enrollment).Reference(x => x.Student).LoadAsync();
}
viewModel.Enrollments = selectedCourse.Enrollments;
}
}
The new code drops the ThenInclude method calls for enrollment data from the code that retrieves instructor
entities. If an instructor and course are selected, the highlighted code retrieves Enrollment entities for the selected
course, and Student entities for each Enrollment.
Run the app, go to the Instructors Index page now and you'll see no difference in what's displayed on the page,
although you've changed how the data is retrieved.
Summary
You've now used eager loading with one query and with multiple queries to read related data into navigation
properties. In the next tutorial you'll learn how to update related data.
P R E V IO U S NEXT
ASP.NET Core MVC with EF Core - Update Related
Data - 7 of 10
applications using Entity Framework Core and Visual Studio. For information about the tutorial series, see the first
tutorial in the series.
In the previous tutorial you displayed related data; in this tutorial you'll update related data by updating foreign
key fields and navigation properties.
The following illustrations show some of the pages that you'll work with.
Customize the Create and Edit Pages for Courses
When a new course entity is created, it must have a relationship to an existing department. To facilitate this, the
scaffolded code includes controller methods and Create and Edit views that include a drop-down list for selecting
the department. The drop-down list sets the Course.DepartmentID foreign key property, and that's all the Entity
Framework needs in order to load the Department navigation property with the appropriate Department entity.
You'll use the scaffolded code, but change it slightly to add error handling and sort the drop-down list.
In CoursesController.cs, delete the four Create and Edit methods and replace them with the following code:

{
PopulateDepartmentsDropDownList();
return View();
}
[HttpPost]
public async Task<IActionResult> Create([Bind("CourseID,Credits,DepartmentID,Title")] Course course)
{
{
_context.Add(course);
}
PopulateDepartmentsDropDownList(course.DepartmentID);
return View(course);
}

{
if (id == null)
{
return NotFound();
}
var course = await _context.Courses

.AsNoTracking()
.SingleOrDefaultAsync(m => m.CourseID == id);
if (course == null)
{
return NotFound();
}
}
{
if (id == null)
{
return NotFound();
}
var courseToUpdate = await _context.Courses

.SingleOrDefaultAsync(c => c.CourseID == id);
if (await TryUpdateModelAsync<Course>(courseToUpdate,
"",
c => c.Credits, c => c.DepartmentID, c => c.Title))
{
try
{
}
{
}
}
PopulateDepartmentsDropDownList(courseToUpdate.DepartmentID);
return View(courseToUpdate);
}
After the Edit HttpPost method, create a new method that loads department info for the drop-down list.
private void PopulateDepartmentsDropDownList(object selectedDepartment = null)

{
var departmentsQuery = from d in _context.Departments
orderby d.Name
select d;
ViewBag.DepartmentID = new SelectList(departmentsQuery.AsNoTracking(), "DepartmentID", "Name",
selectedDepartment);
}
The PopulateDepartmentsDropDownList method gets a list of all departments sorted by name, creates a SelectList
collection for a drop-down list, and passes the collection to the view in ViewBag . The method accepts the optional
selectedDepartment parameter that allows the calling code to specify the item that will be selected when the drop-
down list is rendered. The view will pass the name "DepartmentID" to the <select> tag helper, and the helper
then knows to look in the ViewBag object for a SelectList named "DepartmentID".
The HttpGet Create method calls the PopulateDepartmentsDropDownList method without setting the selected item,
because for a new course the department isn't established yet:

{
PopulateDepartmentsDropDownList();
return View();
}
The HttpGet Edit method sets the selected item, based on the ID of the department that's already assigned to
the course being edited:

{
if (id == null)
{
return NotFound();
}

.AsNoTracking()
if (course == null)
{
return NotFound();
}
}
The HttpPost methods for both Create and Edit also include code that sets the selected item when they
redisplay the page after an error. This ensures that when the page is redisplayed to show the error message,
whatever department was selected stays selected.
Add .AsNoTracking to Details and Delete methods
To optimize performance of the Course Details and Delete pages, add AsNoTracking calls in the Details and
HttpGet Delete methods.

{
if (id == null)
{
return NotFound();
}

.AsNoTracking()
if (course == null)
{
return NotFound();
}
}
{
if (id == null)
{
return NotFound();
}

.AsNoTracking()
if (course == null)
{
return NotFound();
}
}
Modify the Course views

In Views/Courses/Create.cshtml, add a "Select Department" option to the Department drop-down list, change
the caption from DepartmentID to Department, and add a validation message.
<label asp-for="Department" class="control-label"></label>
<select asp-for="DepartmentID" class="form-control" asp-items="ViewBag.DepartmentID">
</select>
<span asp-validation-for="DepartmentID" class="text-danger" />
In Views/Courses/Edit.cshtml, make the same change for the Department field that you just did in Create.cshtml.
Also in Views/Courses/Edit.cshtml, add a course number field before the Title field. Because the course number is
the primary key, it's displayed, but it can't be changed.
<label asp-for="CourseID" class="control-label"></label>
<div>@Html.DisplayFor(model => model.CourseID)</div>
</div>
There's already a hidden field ( <input type="hidden"> ) for the course number in the Edit view. Adding a <label>
tag helper doesn't eliminate the need for the hidden field because it doesn't cause the course number to be
included in the posted data when the user clicks Save on the Edit page.
In Views/Courses/Delete.cshtml, add a course number field at the top and change department ID to department
name.
@model ContosoUniversity.Models.Course
@{
}
<h2>Delete</h2>

<div>
<h4>Course</h4>
<hr />
<dt>
@Html.DisplayNameFor(model => model.CourseID)
</dt>
<dd>
@Html.DisplayFor(model => model.CourseID)
</dd>
<dt>
</dt>
<dd>
@Html.DisplayFor(model => model.Title)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Credits)
</dt>
<dd>
@Html.DisplayFor(model => model.Credits)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Department)
</dt>
<dd>
@Html.DisplayFor(model => model.Department.Name)
</dd>
</dl>
<form asp-action="Delete">
</div>
</form>
</div>
In Views/Courses/Details.cshtml, make the same change that you just did for Delete.cshtml.
Test the Course pages
Run the app, select the Courses tab, click Create New, and enter data for a new course:
Click Create. The Courses Index page is displayed with the new course added to the list. The department name in
the Index page list comes from the navigation property, showing that the relationship was established correctly.
Click Edit on a course in the Courses Index page.
Change data on the page and click Save. The Courses Index page is displayed with the updated course data.
Add an Edit Page for Instructors

When you edit an instructor record, you want to be able to update the instructor's office assignment. The
Instructor entity has a one-to-zero-or-one relationship with the OfficeAssignment entity, which means your code
has to handle the following situations:
If the user clears the office assignment and it originally had a value, delete the OfficeAssignment entity.
If the user enters an office assignment value and it originally was empty, create a new OfficeAssignment
entity.
If the user changes the value of an office assignment, change the value in an existing OfficeAssignment
entity.
Update the Instructors controller
In InstructorsController.cs, change the code in the HttpGet Edit method so that it loads the Instructor entity's
OfficeAssignment navigation property and calls AsNoTracking :
{
if (id == null)
{
return NotFound();
}
var instructor = await _context.Instructors

.AsNoTracking()
if (instructor == null)
{
return NotFound();
}
return View(instructor);
}
Replace the HttpPost Edit method with the following code to handle office assignment updates:
{
if (id == null)
{
return NotFound();
}

.SingleOrDefaultAsync(s => s.ID == id);
instructorToUpdate,
"",
i => i.FirstMidName, i => i.LastName, i => i.HireDate, i => i.OfficeAssignment))
{
if (String.IsNullOrWhiteSpace(instructorToUpdate.OfficeAssignment?.Location))
{
}
try
{
}
{
}
}
return View(instructorToUpdate);
}
The code does the following:

Changes the method name to EditPost because the signature is now the same as the HttpGet Edit
method (the ActionName attribute specifies that the /Edit/ URL is still used).
Gets the current Instructor entity from the database using eager loading for the OfficeAssignment
navigation property. This is the same as what you did in the HttpGet Edit method.
Updates the retrieved Instructor entity with values from the model binder. The TryUpdateModel overload
enables you to whitelist the properties you want to include. This prevents over-posting, as explained in the
second tutorial.
instructorToUpdate,
"",
If the office location is blank, sets the Instructor.OfficeAssignment property to null so that the related row
in the OfficeAssignment table will be deleted.
{
}
Saves the changes to the database.

Update the Instructor Edit view
In Views/Instructors/Edit.cshtml, add a new field for editing the office location, at the end before the Save button:
<label asp-for="OfficeAssignment.Location" class="control-label"></label>
<input asp-for="OfficeAssignment.Location" class="form-control" />
<span asp-validation-for="OfficeAssignment.Location" class="text-danger" />
</div>
Run the app, select the Instructors tab, and then click Edit on an instructor. Change the Office Location and
click Save.
Add Course assignments to the Instructor Edit page
Instructors may teach any number of courses. Now you'll enhance the Instructor Edit page by adding the ability to
change course assignments using a group of check boxes, as shown in the following screen shot:
The relationship between the Course and Instructor entities is many-to-many. To add and remove relationships,
you add and remove entities to and from the CourseAssignments join entity set.
The UI that enables you to change which courses an instructor is assigned to is a group of check boxes. A check
box for every course in the database is displayed, and the ones that the instructor is currently assigned to are
selected. The user can select or clear check boxes to change course assignments. If the number of courses were
much greater, you would probably want to use a different method of presenting the data in the view, but you'd use
the same method of manipulating a join entity to create or delete relationships.
Update the Instructors controller
To provide data to the view for the list of check boxes, you'll use a view model class.
Create AssignedCourseData.cs in the SchoolViewModels folder and replace the existing code with the following
code:
using System;
using System.Linq;
{
public class AssignedCourseData
{
public bool Assigned { get; set; }
}
}
In InstructorsController.cs, replace the HttpGet Edit method with the following code. The changes are
highlighted.

{
if (id == null)
{
return NotFound();
}
var instructor = await _context.Instructors

.Include(i => i.CourseAssignments).ThenInclude(i => i.Course)
.AsNoTracking()
if (instructor == null)
{
return NotFound();
}
PopulateAssignedCourseData(instructor);
}
private void PopulateAssignedCourseData(Instructor instructor)

{
var allCourses = _context.Courses;
var instructorCourses = new HashSet<int>(instructor.CourseAssignments.Select(c => c.CourseID));
var viewModel = new List<AssignedCourseData>();
foreach (var course in allCourses)
{
viewModel.Add(new AssignedCourseData
{
CourseID = course.CourseID,
Title = course.Title,
Assigned = instructorCourses.Contains(course.CourseID)
});
}
ViewData["Courses"] = viewModel;
}
The code adds eager loading for the Courses navigation property and calls the new PopulateAssignedCourseData
method to provide information for the check box array using the AssignedCourseData view model class.
The code in the PopulateAssignedCourseData method reads through all Course entities in order to load a list of
courses using the view model class. For each course, the code checks whether the course exists in the instructor's
Courses navigation property. To create efficient lookup when checking whether a course is assigned to the
instructor, the courses assigned to the instructor are put into a HashSet collection. The Assigned property is set to
true for courses the instructor is assigned to. The view will use this property to determine which check boxes must
be displayed as selected. Finally, the list is passed to the view in ViewData .
Next, add the code that's executed when the user clicks Save. Replace the EditPost method with the following
code, and add a new method that updates the Courses navigation property of the Instructor entity.
[HttpPost]
public async Task<IActionResult> Edit(int? id, string[] selectedCourses)
{
if (id == null)
{
return NotFound();
}

instructorToUpdate,
"",
{
{
}
UpdateInstructorCourses(selectedCourses, instructorToUpdate);
try
{
}
{
}
}
UpdateInstructorCourses(selectedCourses, instructorToUpdate);
PopulateAssignedCourseData(instructorToUpdate);
return View(instructorToUpdate);
}
private void UpdateInstructorCourses(string[] selectedCourses, Instructor instructorToUpdate)
{
{
return;
}

foreach (var course in _context.Courses)
{
{
{
instructorToUpdate.CourseAssignments.Add(new CourseAssignment { InstructorID =
instructorToUpdate.ID, CourseID = course.CourseID });
}
}
else
{
{
CourseAssignment courseToRemove = instructorToUpdate.CourseAssignments.SingleOrDefault(i =>
i.CourseID == course.CourseID);
_context.Remove(courseToRemove);
}
}
}
}
The method signature is now different from the HttpGet Edit method, so the method name changes from
EditPost back to Edit .
Since the view doesn't have a collection of Course entities, the model binder can't automatically update the
CourseAssignments navigation property. Instead of using the model binder to update the CourseAssignments
navigation property, you do that in the new UpdateInstructorCourses method. Therefore you need to exclude the
CourseAssignments property from model binding. This doesn't require any change to the code that calls
TryUpdateModel because you're using the whitelisting overload and CourseAssignments isn't in the include list.
If no check boxes were selected, the code in UpdateInstructorCourses initializes the CourseAssignments navigation
property with an empty collection and returns:
{
{
return;
}

{
{
{
}
}
else
{
{
}
}
}
}
The code then loops through all courses in the database and checks each course against the ones currently
assigned to the instructor versus the ones that were selected in the view. To facilitate efficient lookups, the latter
two collections are stored in HashSet objects.
If the check box for a course was selected but the course isn't in the Instructor.CourseAssignments navigation
property, the course is added to the collection in the navigation property.
{
{
return;
}

{
{
{
}
}
else
{
{
}
}
}
}
If the check box for a course wasn't selected, but the course is in the Instructor.CourseAssignments navigation
property, the course is removed from the navigation property.
{
{
return;
}

{
{
{
}
}
else
{
{
}
}
}
}
Update the Instructor views

In Views/Instructors/Edit.cshtml, add a Courses field with an array of check boxes by adding the following code
immediately after the div elements for the Office field and before the div element for the Save button.
NOTE
When you paste the code in Visual Studio, line breaks will be changed in a way that breaks the code. Press Ctrl+Z one time
to undo the automatic formatting. This will fix the line breaks so that they look like what you see here. The indentation
doesn't have to be perfect, but the @</tr><tr> , @:<td> , @:</td> , and @:</tr> lines must each be on a single line as
shown or you'll get a runtime error. With the block of new code selected, press Tab three times to line up the new code with
the existing code. You can check the status of this problem here.
<table>
<tr>
@{
int cnt = 0;
List<ContosoUniversity.Models.SchoolViewModels.AssignedCourseData> courses =
ViewBag.Courses;
foreach (var course in courses)

{
if (cnt++ % 3 == 0)
{
@:</tr><tr>
}
@:<td>
@:</td>
}
@:</tr>
}
</table>
</div>
</div>
This code creates an HTML table that has three columns. In each column is a check box followed by a caption that
consists of the course number and title. The check boxes all have the same name ("selectedCourses"), which
informs the model binder that they're to be treated as a group. The value attribute of each check box is set to the
value of CourseID . When the page is posted, the model binder passes an array to the controller that consists of
the CourseID values for only the check boxes which are selected.
When the check boxes are initially rendered, those that are for courses assigned to the instructor have checked
attributes, which selects them (displays them checked).
Run the app, select the Instructors tab, and click Edit on an instructor to see the Edit page.
Change some course assignments and click Save. The changes you make are reflected on the Index page.
NOTE
The approach taken here to edit instructor course data works well when there's a limited number of courses. For collections
that are much larger, a different UI and a different updating method would be required.

In InstructorsController.cs, delete the DeleteConfirmed method and insert the following code in its place.
{
Instructor instructor = await _context.Instructors
.SingleAsync(i => i.ID == id);
var departments = await _context.Departments

.Where(d => d.InstructorID == id)
.ToListAsync();
departments.ForEach(d => d.InstructorID = null);
_context.Instructors.Remove(instructor);
}
This code makes the following changes:

Does eager loading for the CourseAssignments navigation property. You have to include this or EF won't
know about related CourseAssignment entities and won't delete them. To avoid needing to read them here
you could configure cascade delete in the database.
If the instructor to be deleted is assigned as administrator of any departments, removes the instructor
assignment from those departments.
Add office location and courses to the Create page

In InstructorsController.cs, delete the HttpGet and HttpPost Create methods, and then add the following code in
their place:
{
var instructor = new Instructor();
return View();
}
// POST: Instructors/Create
[HttpPost]
public async Task<IActionResult> Create([Bind("FirstMidName,HireDate,LastName,OfficeAssignment")] Instructor
instructor, string[] selectedCourses)
{
if (selectedCourses != null)
{
foreach (var course in selectedCourses)
{
var courseToAdd = new CourseAssignment { InstructorID = instructor.ID, CourseID =
int.Parse(course) };
instructor.CourseAssignments.Add(courseToAdd);
}
}
{
_context.Add(instructor);
}
}
This code is similar to what you saw for the Edit methods except that initially no courses are selected. The
HttpGet Create method calls the PopulateAssignedCourseData method not because there might be courses
selected but in order to provide an empty collection for the foreach loop in the view (otherwise the view code
would throw a null reference exception).
The HttpPost Create method adds each selected course to the CourseAssignments navigation property before it
checks for validation errors and adds the new instructor to the database. Courses are added even if there are
model errors so that when there are model errors (for an example, the user keyed an invalid date), and the page is
redisplayed with an error message, any course selections that were made are automatically restored.
Notice that in order to be able to add courses to the CourseAssignments navigation property you have to initialize
the property as an empty collection:
As an alternative to doing this in controller code, you could do it in the Instructor model by changing the property
getter to automatically create the collection if it doesn't exist, as shown in the following example:
private ICollection<CourseAssignment> _courseAssignments;
public ICollection<CourseAssignment> CourseAssignments
{
get
{
return _courseAssignments ?? (_courseAssignments = new List<CourseAssignment>());
}
set
{
_courseAssignments = value;
}
}
If you modify the CourseAssignments property in this way, you can remove the explicit property initialization code
in the controller.
In Views/Instructor/Create.cshtml, add an office location text box and check boxes for courses before the Submit
button. As in the case of the Edit page, fix the formatting if Visual Studio reformats the code when you paste it.
<label asp-for="OfficeAssignment.Location" class="control-label"></label>
<input asp-for="OfficeAssignment.Location" class="form-control" />
<span asp-validation-for="OfficeAssignment.Location" class="text-danger" />
</div>
<table>
<tr>
@{
int cnt = 0;
List<ContosoUniversity.Models.SchoolViewModels.AssignedCourseData> courses =
ViewBag.Courses;
foreach (var course in courses)

{
if (cnt++ % 3 == 0)
{
@:</tr><tr>
}
@:<td>
@:</td>
}
@:</tr>
}
</table>
</div>
</div>
Test by running the app and creating an instructor.
Handling Transactions
As explained in the CRUD tutorial, the Entity Framework implicitly implements transactions. For scenarios where
you need more control -- for example, if you want to include operations done outside of Entity Framework in a
transaction -- see Transactions.
Summary
You have now completed the introduction to working with related data. In the next tutorial you'll see how to
handle concurrency conflicts.
P R E V IO U S NEXT
ASP.NET Core MVC with EF Core - Concurrency - 8
of 10
applications using Entity Framework Core and Visual Studio. For information about the tutorial series, see the first
tutorial in the series.
In earlier tutorials, you learned how to update data. This tutorial shows how to handle conflicts when multiple
users update the same entity at the same time.
You'll create web pages that work with the Department entity and handle concurrency errors. The following
illustrations show the Edit and Delete pages, including some messages that are displayed if a concurrency conflict
occurs.
Concurrency conflicts
A concurrency conflict occurs when one user displays an entity's data in order to edit it, and then another user
updates the same entity's data before the first user's change is written to the database. If you don't enable the
detection of such conflicts, whoever updates the database last overwrites the other user's changes. In many
applications, this risk is acceptable: if there are few users, or few updates, or if isn't really critical if some changes
are overwritten, the cost of programming for concurrency might outweigh the benefit. In that case, you don't have
to configure the application to handle concurrency conflicts.
Pessimistic concurrency (locking)
If your application does need to prevent accidental data loss in concurrency scenarios, one way to do that is to use
database locks. This is called pessimistic concurrency. For example, before you read a row from a database, you
request a lock for read-only or for update access. If you lock a row for update access, no other users are allowed to
lock the row either for read-only or update access, because they would get a copy of data that's in the process of
being changed. If you lock a row for read-only access, others can also lock it for read-only access but not for
update.
Managing locks has disadvantages. It can be complex to program. It requires significant database management
resources, and it can cause performance problems as the number of users of an application increases. For these
reasons, not all database management systems support pessimistic concurrency. Entity Framework Core provides
no built-in support for it, and this tutorial doesn't show you how to implement it.
Optimistic Concurrency
The alternative to pessimistic concurrency is optimistic concurrency. Optimistic concurrency means allowing
concurrency conflicts to happen, and then reacting appropriately if they do. For example, Jane visits the
Department Edit page and changes the Budget amount for the English department from $350,000.00 to $0.00.
Before Jane clicks Save, John visits the same page and changes the Start Date field from 9/1/2007 to 9/1/2013.
Jane clicks Save first and sees her change when the browser returns to the Index page.
Then John clicks Save on an Edit page that still shows a budget of $350,000.00. What happens next is determined
by how you handle concurrency conflicts.
Some of the options include the following:
You can keep track of which property a user has modified and update only the corresponding columns in
the database.
In the example scenario, no data would be lost, because different properties were updated by the two users.
The next time someone browses the English department, they will see both Jane's and John's changes -- a
start date of 9/1/2013 and a budget of zero dollars. This method of updating can reduce the number of
conflicts that could result in data loss, but it can't avoid data loss if competing changes are made to the
same property of an entity. Whether the Entity Framework works this way depends on how you implement
your update code. It's often not practical in a web application, because it can require that you maintain
large amounts of state in order to keep track of all original property values for an entity as well as new
values. Maintaining large amounts of state can affect application performance because it either requires
server resources or must be included in the web page itself (for example, in hidden fields) or in a cookie.
You can let John's change overwrite Jane's change.
The next time someone browses the English department, they will see 9/1/2013 and the restored
$350,000.00 value. This is called a Client Wins or Last in Wins scenario. (All values from the client take
precedence over what's in the data store.) As noted in the introduction to this section, if you don't do any
coding for concurrency handling, this will happen automatically.
You can prevent John's change from being updated in the database.
Typically, you would display an error message, show him the current state of the data, and allow him to
reapply his changes if he still wants to make them. This is called a Store Wins scenario. (The data-store
values take precedence over the values submitted by the client.) You'll implement the Store Wins scenario
in this tutorial. This method ensures that no changes are overwritten without a user being alerted to what's
happening.
Detecting concurrency conflicts
You can resolve conflicts by handling DbConcurrencyException exceptions that the Entity Framework throws. In
order to know when to throw these exceptions, the Entity Framework must be able to detect conflicts. Therefore,
you must configure the database and the data model appropriately. Some options for enabling conflict detection
include the following:
In the database table, include a tracking column that can be used to determine when a row has been
changed. You can then configure the Entity Framework to include that column in the Where clause of SQL
Update or Delete commands.
The data type of the tracking column is typically rowversion . The rowversion value is a sequential number
that's incremented each time the row is updated. In an Update or Delete command, the Where clause
includes the original value of the tracking column (the original row version) . If the row being updated has
been changed by another user, the value in the rowversion column is different than the original value, so
the Update or Delete statement can't find the row to update because of the Where clause. When the Entity
Framework finds that no rows have been updated by the Update or Delete command (that is, when the
number of affected rows is zero), it interprets that as a concurrency conflict.
Configure the Entity Framework to include the original values of every column in the table in the Where
clause of Update and Delete commands.
As in the first option, if anything in the row has changed since the row was first read, the Where clause
won't return a row to update, which the Entity Framework interprets as a concurrency conflict. For database
tables that have many columns, this approach can result in very large Where clauses, and can require that
you maintain large amounts of state. As noted earlier, maintaining large amounts of state can affect
application performance. Therefore this approach is generally not recommended, and it isn't the method
used in this tutorial.
If you do want to implement this approach to concurrency, you have to mark all non-primary-key
properties in the entity you want to track concurrency for by adding the ConcurrencyCheck attribute to
them. That change enables the Entity Framework to include all columns in the SQL Where clause of
Update and Delete statements.
In the remainder of this tutorial you'll add a rowversion tracking property to the Department entity, create a
controller and views, and test to verify that everything works correctly.
Add a tracking property to the Department entity

In Models/Department.cs, add a tracking property named RowVersion:
using System;
{
{

[Timestamp]
public byte[] RowVersion { get; set; }

}
}
The Timestamp attribute specifies that this column will be included in the Where clause of Update and Delete
commands sent to the database. The attribute is called Timestamp because previous versions of SQL Server used
a SQL timestamp data type before the SQL rowversion replaced it. The .NET type for rowversion is a byte array.
If you prefer to use the fluent API, you can use the IsConcurrencyToken method (in Data/SchoolContext.cs) to
specify the tracking property, as shown in the following example:
.Property(p => p.RowVersion).IsConcurrencyToken();
By adding a property you changed the database model, so you need to do another migration.
Save your changes and build the project, and then enter the following commands in the command window:
dotnet ef migrations add RowVersion
Create a Departments controller and views

Scaffold a Departments controller and views as you did earlier for Students, Courses, and Instructors.
In the DepartmentsController.cs file, change all four occurrences of "FirstMidName" to "FullName" so that the
department administrator drop-down lists will contain the full name of the instructor rather than just the last
name.
ViewData["InstructorID"] = new SelectList(_context.Instructors, "ID", "FullName", department.InstructorID);
Update the Departments Index view

The scaffolding engine created a RowVersion column in the Index view, but that field shouldn't be displayed.
Replace the code in Views/Departments/Index.cshtml with the following code.
@model IEnumerable<ContosoUniversity.Models.Department>
@{
ViewData["Title"] = "Departments";
}
<h2>Departments</h2>
<p>
</p>
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.Name)
</th>
<th>
@Html.DisplayNameFor(model => model.Budget)
</th>
<th>
@Html.DisplayNameFor(model => model.StartDate)
</th>
<th>
@Html.DisplayNameFor(model => model.Administrator)
</th>
<th></th>
</tr>
</thead>
<tbody>
{
<tr>
<td>
</td>
<td>
@Html.DisplayFor(modelItem => item.Budget)
</td>
<td>
@Html.DisplayFor(modelItem => item.StartDate)
</td>
<td>
@Html.DisplayFor(modelItem => item.Administrator.FullName)
</td>
<td>
<a asp-action="Edit" asp-route-id="@item.DepartmentID">Edit</a> |
<a asp-action="Details" asp-route-id="@item.DepartmentID">Details</a> |
<a asp-action="Delete" asp-route-id="@item.DepartmentID">Delete</a>
</td>
</tr>
}
</tbody>
</table>
This changes the heading to "Departments", deletes the RowVersion column, and shows full name instead of first
name for the administrator.
Update the Edit methods in the Departments controller

In both the HttpGet Edit method and the Details method, add AsNoTracking . In the HttpGet Edit method,
add eager loading for the Administrator.
var department = await _context.Departments
.AsNoTracking()
.SingleOrDefaultAsync(m => m.DepartmentID == id);
Replace the existing code for the HttpPost Edit method with the following code:
[HttpPost]
public async Task<IActionResult> Edit(int? id, byte[] rowVersion)
{
if (id == null)
{
return NotFound();
}
var departmentToUpdate = await _context.Departments.Include(i => i.Administrator).SingleOrDefaultAsync(m

=> m.DepartmentID == id);
{
Department deletedDepartment = new Department();
await TryUpdateModelAsync(deletedDepartment);
"Unable to save changes. The department was deleted by another user.");
ViewData["InstructorID"] = new SelectList(_context.Instructors, "ID", "FullName",
deletedDepartment.InstructorID);
return View(deletedDepartment);
}
_context.Entry(departmentToUpdate).Property("RowVersion").OriginalValue = rowVersion;
departmentToUpdate,
"",
s => s.Name, s => s.StartDate, s => s.Budget, s => s.InstructorID))
{
try
{
}
{
{
"Unable to save changes. The department was deleted by another user.");
}
else
{
var databaseValues = (Department)databaseEntry.ToObject();
if (databaseValues.Name != clientValues.Name)
{
ModelState.AddModelError("Name", $"Current value: {databaseValues.Name}");
}
if (databaseValues.Budget != clientValues.Budget)
{
ModelState.AddModelError("Budget", $"Current value: {databaseValues.Budget:c}");
}
if (databaseValues.StartDate != clientValues.StartDate)
{
ModelState.AddModelError("StartDate", $"Current value: {databaseValues.StartDate:d}");
}
if (databaseValues.InstructorID != clientValues.InstructorID)
{
Instructor databaseInstructor = await _context.Instructors.SingleOrDefaultAsync(i => i.ID
== databaseValues.InstructorID);
ModelState.AddModelError("InstructorID", $"Current value:
{databaseInstructor?.FullName}");
}
ModelState.AddModelError(string.Empty, "The record you attempted to edit "

+ "was modified by another user after you got the original value. The "
+ "the Save button again. Otherwise click the Back to List hyperlink.");
departmentToUpdate.RowVersion = (byte[])databaseValues.RowVersion;
ModelState.Remove("RowVersion");
}
}
}
ViewData["InstructorID"] = new SelectList(_context.Instructors, "ID", "FullName",
departmentToUpdate.InstructorID);
return View(departmentToUpdate);
}
The code begins by trying to read the department to be updated. If the SingleOrDefaultAsync method returns null,
the department was deleted by another user. In that case the code uses the posted form values to create a
department entity so that the Edit page can be redisplayed with an error message. As an alternative, you wouldn't
have to re-create the department entity if you display only an error message without redisplaying the department
fields.
The view stores the original RowVersion value in a hidden field, and this method receives that value in the
rowVersion parameter. Before you call SaveChanges , you have to put that original RowVersion property value in
the OriginalValues collection for the entity.
_context.Entry(departmentToUpdate).Property("RowVersion").OriginalValue = rowVersion;
Then when the Entity Framework creates a SQL UPDATE command, that command will include a WHERE clause
that looks for a row that has the original RowVersion value. If no rows are affected by the UPDATE command (no
rows have the original RowVersion value), the Entity Framework throws a DbUpdateConcurrencyException
exception.
The code in the catch block for that exception gets the affected Department entity that has the updated values
from the Entries property on the exception object.
The Entries collection will have just one EntityEntry object. You can use that object to get the new values
entered by the user and the current database values.

The code adds a custom error message for each column that has database values different from what the user
entered on the Edit page (only one field is shown here for brevity).
var databaseValues = (Department)databaseEntry.ToObject();
if (databaseValues.Name != clientValues.Name)
{
ModelState.AddModelError("Name", $"Current value: {databaseValues.Name}");
Finally, the code sets the RowVersion value of the departmentToUpdate to the new value retrieved from the
database. This new RowVersion value will be stored in the hidden field when the Edit page is redisplayed, and the
next time the user clicks Save, only concurrency errors that happen since the redisplay of the Edit page will be
caught.
departmentToUpdate.RowVersion = (byte[])databaseValues.RowVersion;
ModelState.Remove("RowVersion");
The ModelState.Remove statement is required because ModelState has the old RowVersion value. In the view, the
ModelState value for a field takes precedence over the model property values when both are present.
Update the Department Edit view

In Views/Departments/Edit.cshtml, make the following changes:
Add a hidden field to save the RowVersion property value, immediately following the hidden field for the
DepartmentID property.
Add a "Select Administrator" option to the drop-down list.

@model ContosoUniversity.Models.Department
@{
}
<h2>Edit</h2>
<h4>Department</h4>
<hr />
<div class="row">
<input type="hidden" asp-for="DepartmentID" />
<input type="hidden" asp-for="RowVersion" />
<label asp-for="Name" class="control-label"></label>
<input asp-for="Name" class="form-control" />
<span asp-validation-for="Name" class="text-danger"></span>
</div>
<label asp-for="Budget" class="control-label"></label>
<input asp-for="Budget" class="form-control" />
<span asp-validation-for="Budget" class="text-danger"></span>
</div>
<label asp-for="StartDate" class="control-label"></label>
<input asp-for="StartDate" class="form-control" />
<span asp-validation-for="StartDate" class="text-danger"></span>
</div>
<label asp-for="InstructorID" class="control-label"></label>
<select asp-for="InstructorID" class="form-control" asp-items="ViewBag.InstructorID">
<option value="">-- Select Administrator --</option>
</select>
<span asp-validation-for="InstructorID" class="text-danger"></span>
</div>
</div>
</form>
</div>
</div>
<div>
</div>
@section Scripts {
}
Test concurrency conflicts in the Edit page

Run the app and go to the Departments Index page. Right-click the Edit hyperlink for the English department and
select Open in new tab, then click the Edit hyperlink for the English department. The two browser tabs now
display the same information.
Change a field in the first browser tab and click Save.
The browser shows the Index page with the changed value.
Change a field in the second browser tab.
Click Save. You see an error message:
Click Save again. The value you entered in the second browser tab is saved. You see the saved values when the
Index page appears.

For the Delete page, the Entity Framework detects concurrency conflicts caused by someone else editing the
department in a similar manner. When the HttpGet Delete method displays the confirmation view, the view
includes the original RowVersion value in a hidden field. That value is then available to the HttpPost Delete
method that's called when the user confirms the deletion. When the Entity Framework creates the SQL DELETE
command, it includes a WHERE clause with the original RowVersion value. If the command results in zero rows
affected (meaning the row was changed after the Delete confirmation page was displayed), a concurrency
exception is thrown, and the HttpGet Delete method is called with an error flag set to true in order to redisplay
the confirmation page with an error message. It's also possible that zero rows were affected because the row was
deleted by another user, so in that case no error message is displayed.
Update the Delete methods in the Departments controller
In DepartmentsController.cs, replace the HttpGet Delete method with the following code:
public async Task<IActionResult> Delete(int? id, bool? concurrencyError)
{
if (id == null)
{
return NotFound();
}

.AsNoTracking()
.SingleOrDefaultAsync(m => m.DepartmentID == id);
if (department == null)
{
{
}
return NotFound();
}
{
ViewData["ConcurrencyErrorMessage"] = "The record you attempted to delete "
+ "was modified by another user after you got the original values. "
+ "The delete operation was canceled and the current values in the "
+ "database have been displayed. If you still want to delete this "
+ "record, click the Delete button again. Otherwise "
+ "click the Back to List hyperlink.";
}
return View(department);
}
The method accepts an optional parameter that indicates whether the page is being redisplayed after a
concurrency error. If this flag is true and the department specified no longer exists, it was deleted by another user.
In that case, the code redirects to the Index page. If this flag is true and the Department does exist, it was changed
by another user. In that case, the code sends an error message to the view using ViewData .
Replace the code in the HttpPost Delete method (named DeleteConfirmed ) with the following code:
[HttpPost]
public async Task<IActionResult> Delete(Department department)
{
try
{
if (await _context.Departments.AnyAsync(m => m.DepartmentID == department.DepartmentID))
{
_context.Departments.Remove(department);
}
}
catch (DbUpdateConcurrencyException /* ex */)
{
return RedirectToAction(nameof(Delete), new { concurrencyError = true, id = department.DepartmentID
});
}
}
In the scaffolded code that you just replaced, this method accepted only a record ID:
You've changed this parameter to a Department entity instance created by the model binder. This gives EF access
to the RowVersion property value in addition to the record key.
public async Task<IActionResult> Delete(Department department)
You have also changed the action method name from DeleteConfirmed to Delete . The scaffolded code used the
name DeleteConfirmed to give the HttpPost method a unique signature. (The CLR requires overloaded methods
to have different method parameters.) Now that the signatures are unique, you can stick with the MVC convention
and use the same name for the HttpPost and HttpGet delete methods.
If the department is already deleted, the AnyAsync method returns false and the application just goes back to the
Index method.
If a concurrency error is caught, the code redisplays the Delete confirmation page and provides a flag that
indicates it should display a concurrency error message.
Update the Delete view
In Views/Departments/Delete.cshtml, replace the scaffolded code with the following code that adds an error
message field and hidden fields for the DepartmentID and RowVersion properties. The changes are highlighted.
@{
}
<h2>Delete</h2>
<p class="text-danger">@ViewData["ConcurrencyErrorMessage"]</p>

<div>
<h4>Department</h4>
<hr />
<dt>
</dt>
<dd>
@Html.DisplayFor(model => model.Name)
</dd>
<dt>
</dt>
<dd>
@Html.DisplayFor(model => model.Budget)
</dd>
<dt>
</dt>
<dd>
@Html.DisplayFor(model => model.StartDate)
</dd>
<dt>
</dt>
<dd>
@Html.DisplayFor(model => model.Administrator.FullName)
</dd>
</dl>
<form asp-action="Delete">
<input type="hidden" asp-for="DepartmentID" />
<input type="hidden" asp-for="RowVersion" />
</div>
</form>
</div>
This makes the following changes:

Adds an error message between the h2 and h3 headings.
Replaces FirstMidName with FullName in the Administrator field.
Removes the RowVersion field.
Adds a hidden field for the RowVersion property.
Run the app and go to the Departments Index page. Right-click the Delete hyperlink for the English department
and select Open in new tab, then in the first tab click the Edit hyperlink for the English department.
In the first window, change one of the values, and click Save:
In the second tab, click Delete. You see the concurrency error message, and the Department values are refreshed
with what's currently in the database.
If you click Delete again, you're redirected to the Index page, which shows that the department has been deleted.
Update Details and Create views

You can optionally clean up scaffolded code in the Details and Create views.
Replace the code in Views/Departments/Details.cshtml to delete the RowVersion column and show the full name
of the Administrator.
@{
}
<h2>Details</h2>
<div>
<h4>Department</h4>
<hr />
<dt>
</dt>
<dd>
</dd>
<dt>
</dt>
<dd>
@Html.DisplayFor(model => model.Budget)
</dd>
<dt>
</dt>
<dd>
@Html.DisplayFor(model => model.StartDate)
</dd>
<dt>
</dt>
<dd>
@Html.DisplayFor(model => model.Administrator.FullName)
</dd>
</dl>
</div>
<div>
<a asp-action="Edit" asp-route-id="@Model.DepartmentID">Edit</a> |
</div>
Replace the code in Views/Departments/Create.cshtml to add a Select option to the drop-down list.
@{
}
<h2>Create</h2>
<h4>Department</h4>
<hr />
<div class="row">
<label asp-for="Name" class="control-label"></label>
<input asp-for="Name" class="form-control" />
<span asp-validation-for="Name" class="text-danger"></span>
</div>
<label asp-for="Budget" class="control-label"></label>
<input asp-for="Budget" class="form-control" />
<span asp-validation-for="Budget" class="text-danger"></span>
</div>
<label asp-for="StartDate" class="control-label"></label>
<input asp-for="StartDate" class="form-control" />
<span asp-validation-for="StartDate" class="text-danger"></span>
</div>
<label asp-for="InstructorID" class="control-label"></label>
<select asp-for="InstructorID" class="form-control" asp-items="ViewBag.InstructorID">
<option value="">-- Select Administrator --</option>
</select>
</div>
</div>
</form>
</div>
</div>
<div>
</div>
@section Scripts {
}
Summary
This completes the introduction to handling concurrency conflicts. For more information about how to handle
concurrency in EF Core, see Concurrency conflicts. The next tutorial shows how to implement table-per-hierarchy
inheritance for the Instructor and Student entities.
P R E V IO U S NEXT
ASP.NET Core MVC with EF Core - Inheritance - 9 of
10
In the previous tutorial, you handled concurrency exceptions. This tutorial will show you how to implement
inheritance in the data model.
In object-oriented programming, you can use inheritance to facilitate code reuse. In this tutorial, you'll change the
Instructor and Student classes so that they derive from a Person base class which contains properties such as
LastName that are common to both instructors and students. You won't add or change any web pages, but you'll
change some of the code and those changes will be automatically reflected in the database.
Options for mapping inheritance to database tables

The Instructor and Student classes in the School data model have several properties that are identical:
Suppose you want to eliminate the redundant code for the properties that are shared by the Instructor and
Student entities. Or you want to write a service that can format names without caring whether the name came
from an instructor or a student. You could create a Person base class that contains only those shared properties,
then make the Instructor and Student classes inherit from that base class, as shown in the following
illustration:
There are several ways this inheritance structure could be represented in the database. You could have a Person
table that includes information about both students and instructors in a single table. Some of the columns could
apply only to instructors (HireDate), some only to students (EnrollmentDate), some to both (LastName,
FirstName). Typically, you'd have a discriminator column to indicate which type each row represents. For
example, the discriminator column might have "Instructor" for instructors and "Student" for students.
This pattern of generating an entity inheritance structure from a single database table is called table-per-
hierarchy (TPH) inheritance.
An alternative is to make the database look more like the inheritance structure. For example, you could have only
the name fields in the Person table and have separate Instructor and Student tables with the date fields.
This pattern of making a database table for each entity class is called table per type (TPT) inheritance.
Yet another option is to map all non-abstract types to individual tables. All properties of a class, including
inherited properties, map to columns of the corresponding table. This pattern is called Table-per-Concrete Class
(TPC ) inheritance. If you implemented TPC inheritance for the Person, Student, and Instructor classes as shown
earlier, the Student and Instructor tables would look no different after implementing inheritance than they did
before.
TPC and TPH inheritance patterns generally deliver better performance than TPT inheritance patterns, because
TPT patterns can result in complex join queries.
This tutorial demonstrates how to implement TPH inheritance. TPH is the only inheritance pattern that the Entity
Framework Core supports. What you'll do is create a Person class, change the Instructor and Student classes
to derive from Person , add the new class to the DbContext , and create a migration.
TIP
Consider saving a copy of the project before making the following changes. Then if you run into problems and need to
start over, it will be easier to start from the saved project instead of reversing steps done for this tutorial or going back to
the beginning of the whole series.
Create the Person class

In the Models folder, create Person.cs and replace the template code with the following code:
{
public abstract class Person
{
[Required]
[StringLength(50)]
[Required]

{
get
{
}
}
}
}
Make Student and Instructor classes inherit from Person

In Instructor.cs, derive the Instructor class from the Person class and remove the key and name fields. The code
will look like the following example:
using System;
{
public class Instructor : Person
{

}
}
Make the same changes in Student.cs.

using System;
{
public class Student : Person
{

}
}
Add the Person entity type to the data model

Add the Person entity type to SchoolContext.cs. The new lines are highlighted.
{
{
{
}

public DbSet<Person> People { get; set; }

{
modelBuilder.Entity<Person>().ToTable("Person");
}
}
}
This is all that the Entity Framework needs in order to configure table-per-hierarchy inheritance. As you'll see,
when the database is updated, it will have a Person table in place of the Student and Instructor tables.
Create and customize migration code
following command:
dotnet ef migrations add Inheritance
Don't run the database update command yet. That command will result in lost data because it will drop the
Instructor table and rename the Student table to Person. You need to provide custom code to preserve existing
data.
Open Migrations/<timestamp>_Inheritance.cs and replace the Up method with the following code:

{
migrationBuilder.DropForeignKey(
name: "FK_Enrollment_Student_StudentID",
table: "Enrollment");
migrationBuilder.DropIndex(name: "IX_Enrollment_StudentID", table: "Enrollment");
migrationBuilder.RenameTable(name: "Instructor", newName: "Person");

migrationBuilder.AddColumn<DateTime>(name: "EnrollmentDate", table: "Person", nullable: true);
migrationBuilder.AddColumn<string>(name: "Discriminator", table: "Person", nullable: false, maxLength:
128, defaultValue: "Instructor");
migrationBuilder.AlterColumn<DateTime>(name: "HireDate", table: "Person", nullable: true);
migrationBuilder.AddColumn<int>(name: "OldId", table: "Person", nullable: true);
// Copy existing Student data into new Person table.

migrationBuilder.Sql("INSERT INTO dbo.Person (LastName, FirstName, HireDate, EnrollmentDate,
Discriminator, OldId) SELECT LastName, FirstName, null AS HireDate, EnrollmentDate, 'Student' AS
Discriminator, ID AS OldId FROM dbo.Student");
// Fix up existing relationships to match new PK's.
migrationBuilder.Sql("UPDATE dbo.Enrollment SET StudentId = (SELECT ID FROM dbo.Person WHERE OldId =
Enrollment.StudentId AND Discriminator = 'Student')");
// Remove temporary key

migrationBuilder.DropColumn(name: "OldID", table: "Person");
name: "Student");
migrationBuilder.CreateIndex(
name: "IX_Enrollment_StudentID",
table: "Enrollment",
column: "StudentID");
migrationBuilder.AddForeignKey(
name: "FK_Enrollment_Person_StudentID",
table: "Enrollment",
column: "StudentID",
principalTable: "Person",
onDelete: ReferentialAction.Cascade);
}
This code takes care of the following database update tasks:

Removes foreign key constraints and indexes that point to the Student table.
Renames the Instructor table as Person and makes changes needed for it to store Student data:
Adds nullable EnrollmentDate for students.
Adds Discriminator column to indicate whether a row is for a student or an instructor.
Makes HireDate nullable since student rows won't have hire dates.
Adds a temporary field that will be used to update foreign keys that point to students. When you copy
students into the Person table they will get new primary key values.
Copies data from the Student table into the Person table. This causes students to get assigned new
primary key values.
Fixes foreign key values that point to students.
Re-creates foreign key constraints and indexes, now pointing them to the Person table.
(If you had used GUID instead of integer as the primary key type, the student primary key values wouldn't have
to change, and several of these steps could have been omitted.)
Run the database update command:
(In a production system you would make corresponding changes to the Down method in case you ever had to
use that to go back to the previous database version. For this tutorial you won't be using the Down method.)
NOTE
It's possible to get other errors when making schema changes in a database that has existing data. If you get migration
errors that you can't resolve, you can either change the database name in the connection string or delete the database.
With a new database, there's no data to migrate, and the update-database command is more likely to complete without
errors. To delete the database, use SSOX or run the database drop CLI command.
Test with inheritance implemented

Run the app and try various pages. Everything works the same as it did before.
In SQL Server Object Explorer, expand Data Connections/SchoolContext and then Tables, and you see
that the Student and Instructor tables have been replaced by a Person table. Open the Person table designer and
you see that it has all of the columns that used to be in the Student and Instructor tables.
Right-click the Person table, and then click Show Table Data to see the discriminator column.
Summary
You've implemented table-per-hierarchy inheritance for the Person , Student , and Instructor classes. For more
information about inheritance in Entity Framework Core, see Inheritance. In the next tutorial you'll see how to
handle a variety of relatively advanced Entity Framework scenarios.
P R E V IO U S NEXT
ASP.NET Core MVC with EF Core - Advanced - 10 of
10
In the previous tutorial, you implemented table-per-hierarchy inheritance. This tutorial introduces several topics
that are useful to be aware of when you go beyond the basics of developing ASP.NET Core web applications that
use Entity Framework Core.
Raw SQL Queries

One of the advantages of using the Entity Framework is that it avoids tying your code too closely to a particular
method of storing data. It does this by generating SQL queries and commands for you, which also frees you from
having to write them yourself. But there are exceptional scenarios when you need to run specific SQL queries that
you have manually created. For these scenarios, the Entity Framework Code First API includes methods that
enable you to pass SQL commands directly to the database. You have the following options in EF Core 1.0:
Use the DbSet.FromSql method for queries that return entity types. The returned objects must be of the
type expected by the DbSet object, and they're automatically tracked by the database context unless you
turn tracking off.
Use the Database.ExecuteSqlCommand for non-query commands.
If you need to run a query that returns types that aren't entities, you can use ADO.NET with the database
connection provided by EF. The returned data isn't tracked by the database context, even if you use this method to
retrieve entity types.
As is always true when you execute SQL commands in a web application, you must take precautions to protect
your site against SQL injection attacks. One way to do that is to use parameterized queries to make sure that
strings submitted by a web page can't be interpreted as SQL commands. In this tutorial you'll use parameterized
queries when integrating user input into a query.
Call a query that returns entities

The class provides a method that you can use to execute a query that returns an entity of type
DbSet<TEntity>
TEntity . To see how this works you'll change the code in the Details method of the Department controller.
In DepartmentsController.cs, in the Details method, replace the code that retrieves a department with a
FromSql method call, as shown in the following highlighted code:

{
if (id == null)
{
return NotFound();
}
string query = "SELECT * FROM Department WHERE DepartmentID = {0}";

.FromSql(query, id)
.AsNoTracking()
.SingleOrDefaultAsync();
if (department == null)
{
return NotFound();
}
return View(department);
}
To verify that the new code works correctly, select the Departments tab and then Details for one of the
departments.
Call a query that returns other types

Earlier you created a student statistics grid for the About page that showed the number of students for each
enrollment date. You got the data from the Students entity set ( _context.Students ) and used LINQ to project the
results into a list of EnrollmentDateGroup view model objects. Suppose you want to write the SQL itself rather
than using LINQ. To do that you need to run a SQL query that returns something other than entity objects. In EF
Core 1.0, one way to do that is write ADO.NET code and get the database connection from EF.
In HomeController.cs, replace the About method with the following code:
public async Task<ActionResult> About()

{
List<EnrollmentDateGroup> groups = new List<EnrollmentDateGroup>();
var conn = _context.Database.GetDbConnection();
try
{
await conn.OpenAsync();
using (var command = conn.CreateCommand())
{
string query = "SELECT EnrollmentDate, COUNT(*) AS StudentCount "
+ "FROM Person "
+ "WHERE Discriminator = 'Student' "
+ "GROUP BY EnrollmentDate";
command.CommandText = query;
DbDataReader reader = await command.ExecuteReaderAsync();
if (reader.HasRows)
{
while (await reader.ReadAsync())
{
var row = new EnrollmentDateGroup { EnrollmentDate = reader.GetDateTime(0), StudentCount
= reader.GetInt32(1) };
groups.Add(row);
}
}
reader.Dispose();
}
}
finally
{
conn.Close();
}
return View(groups);
}
Add a using statement:
using System.Data.Common;
Run the app and go to the About page. It displays the same data it did before.
Call an update query
Suppose Contoso University administrators want to perform global changes in the database, such as changing
the number of credits for every course. If the university has a large number of courses, it would be inefficient to
retrieve them all as entities and change them individually. In this section you'll implement a web page that
enables the user to specify a factor by which to change the number of credits for all courses, and you'll make the
change by executing a SQL UPDATE statement. The web page will look like the following illustration:
In CoursesContoller.cs, add UpdateCourseCredits methods for HttpGet and HttpPost:
public IActionResult UpdateCourseCredits()

{
return View();
}
[HttpPost]
public async Task<IActionResult> UpdateCourseCredits(int? multiplier)
{
if (multiplier != null)
{
ViewData["RowsAffected"] =
await _context.Database.ExecuteSqlCommandAsync(
"UPDATE Course SET Credits = Credits * {0}",
parameters: multiplier);
}
return View();
}
When the controller processes an HttpGet request, nothing is returned in ViewData["RowsAffected"] , and the view
displays an empty text box and a submit button, as shown in the preceding illustration.
When the Update button is clicked, the HttpPost method is called, and multiplier has the value entered in the text
box. The code then executes the SQL that updates courses and returns the number of affected rows to the view in
ViewData . When the view gets a RowsAffected value, it displays the number of rows updated.
In Solution Explorer, right-click the Views/Courses folder, and then click Add > New Item.
In the Add New Item dialog, click ASP.NET under Installed in the left pane, click MVC View Page, and name
the new view UpdateCourseCredits.cshtml.
In Views/Courses/UpdateCourseCredits.cshtml, replace the template code with the following code:
@{
ViewBag.Title = "UpdateCourseCredits";
}
<h2>Update Course Credits</h2>
@if (ViewData["RowsAffected"] == null)

{
<form asp-action="UpdateCourseCredits">
<p>
Enter a number to multiply every course's credits by: @Html.TextBox("multiplier")
</p>
<p>
<input type="submit" value="Update" class="btn btn-default" />
</p>
</div>
</form>
}
@if (ViewData["RowsAffected"] != null)
{
<p>
Number of rows updated: @ViewData["RowsAffected"]
</p>
}
<div>
@Html.ActionLink("Back to List", "Index")
</div>
Run the UpdateCourseCredits method by selecting the Courses tab, then adding "/UpdateCourseCredits" to the
end of the URL in the browser's address bar (for example: http://localhost:5813/Courses/UpdateCourseCredits ).
Enter a number in the text box:
Click Update. You see the number of rows affected:

Click Back to List to see the list of courses with the revised number of credits.
Note that production code would ensure that updates always result in valid data. The simplified code shown here
could multiply the number of credits enough to result in numbers greater than 5. (The Credits property has a
[Range(0, 5)] attribute.) The update query would work but the invalid data could cause unexpected results in
other parts of the system that assume the number of credits is 5 or less.
For more information about raw SQL queries, see Raw SQL Queries.
Examine SQL sent to the database

Sometimes it's helpful to be able to see the actual SQL queries that are sent to the database. Built-in logging
functionality for ASP.NET Core is automatically used by EF Core to write logs that contain the SQL for queries
and updates. In this section you'll see some examples of SQL logging.
Open StudentsController.cs and in the Details method set a breakpoint on the if (student == null) statement.
Run the app in debug mode, and go to the Details page for a student.
Go to the Output window showing debug output, and you see the query:
Microsoft.EntityFrameworkCore.Database.Command:Information: Executed DbCommand (56ms) [Parameters=

[@__id_0='?'], CommandType='Text', CommandTimeout='30']
SELECT TOP(2) [s].[ID], [s].[Discriminator], [s].[FirstName], [s].[LastName], [s].[EnrollmentDate]
FROM [Person] AS [s]
WHERE ([s].[Discriminator] = N'Student') AND ([s].[ID] = @__id_0)
ORDER BY [s].[ID]
Microsoft.EntityFrameworkCore.Database.Command:Information: Executed DbCommand (122ms) [Parameters=
[@__id_0='?'], CommandType='Text', CommandTimeout='30']
SELECT [s.Enrollments].[EnrollmentID], [s.Enrollments].[CourseID], [s.Enrollments].[Grade], [s.Enrollments].
[StudentID], [e.Course].[CourseID], [e.Course].[Credits], [e.Course].[DepartmentID], [e.Course].[Title]
FROM [Enrollment] AS [s.Enrollments]
INNER JOIN [Course] AS [e.Course] ON [s.Enrollments].[CourseID] = [e.Course].[CourseID]
INNER JOIN (
SELECT TOP(1) [s0].[ID]
FROM [Person] AS [s0]
WHERE ([s0].[Discriminator] = N'Student') AND ([s0].[ID] = @__id_0)
ORDER BY [s0].[ID]
) AS [t] ON [s.Enrollments].[StudentID] = [t].[ID]
ORDER BY [t].[ID]
You'll notice something here that might surprise you: the SQL selects up to 2 rows ( TOP(2) ) from the Person
table. The SingleOrDefaultAsync method doesn't resolve to 1 row on the server. Here's why:
If the query would return multiple rows, the method returns null.
To determine whether the query would return multiple rows, EF has to check if it returns at least 2.
Note that you don't have to use debug mode and stop at a breakpoint to get logging output in the Output
window. It's just a convenient way to stop the logging at the point you want to look at the output. If you don't do
that, logging continues and you have to scroll back to find the parts you're interested in.
Repository and unit of work patterns

Many developers write code to implement the repository and unit of work patterns as a wrapper around code
that works with the Entity Framework. These patterns are intended to create an abstraction layer between the
data access layer and the business logic layer of an application. Implementing these patterns can help insulate
your application from changes in the data store and can facilitate automated unit testing or test-driven
development (TDD ). However, writing additional code to implement these patterns isn't always the best choice
for applications that use EF, for several reasons:
The EF context class itself insulates your code from data-store-specific code.
The EF context class can act as a unit-of-work class for database updates that you do using EF.
EF includes features for implementing TDD without writing repository code.
For information about how to implement the repository and unit of work patterns, see the Entity Framework 5
version of this tutorial series.
Entity Framework Core implements an in-memory database provider that can be used for testing. For more
information, see Test with InMemory.
Automatic change detection

The Entity Framework determines how an entity has changed (and therefore which updates need to be sent to the
database) by comparing the current values of an entity with the original values. The original values are stored
when the entity is queried or attached. Some of the methods that cause automatic change detection are the
following:
DbContext.SaveChanges
DbContext.Entry
ChangeTracker.Entries
If you're tracking a large number of entities and you call one of these methods many times in a loop, you might
get significant performance improvements by temporarily turning off automatic change detection using the
ChangeTracker.AutoDetectChangesEnabled property. For example:
_context.ChangeTracker.AutoDetectChangesEnabled = false;
Entity Framework Core source code and development plans

The Entity Framework Core source is at https://github.com/aspnet/EntityFrameworkCore. The EF Core
repository contains nightly builds, issue tracking, feature specs, design meeting notes, and the roadmap for future
development. You can file or find bugs, and contribute.
Although the source code is open, Entity Framework Core is fully supported as a Microsoft product. The
Microsoft Entity Framework team keeps control over which contributions are accepted and tests all code changes
to ensure the quality of each release.
Reverse engineer from existing database

To reverse engineer a data model including entity classes from an existing database, use the scaffold-dbcontext
command. See the getting-started tutorial.
Use dynamic LINQ to simplify sort selection code

The third tutorial in this series shows how to write LINQ code by hard-coding column names in a switch
statement. With two columns to choose from, this works fine, but if you have many columns the code could get
verbose. To solve that problem, you can use the EF.Property method to specify the name of the property as a
string. To try out this approach, replace the Index method in the StudentsController with the following code.
string sortOrder,
int? page)
{
ViewData["CurrentSort"] = sortOrder;
ViewData["NameSortParm"] =
String.IsNullOrEmpty(sortOrder) ? "LastName_desc" : "";
ViewData["DateSortParm"] =
sortOrder == "EnrollmentDate" ? "EnrollmentDate_desc" : "EnrollmentDate";
{
page = 1;
}
else
{
}

select s;
{
}
if (string.IsNullOrEmpty(sortOrder))
{
sortOrder = "LastName";
}
bool descending = false;

if (sortOrder.EndsWith("_desc"))
{
sortOrder = sortOrder.Substring(0, sortOrder.Length - 5);
descending = true;
}
if (descending)
{
students = students.OrderByDescending(e => EF.Property<object>(e, sortOrder));
}
else
{
students = students.OrderBy(e => EF.Property<object>(e, sortOrder));
}
int pageSize = 3;
return View(await PaginatedList<Student>.CreateAsync(students.AsNoTracking(),
page ?? 1, pageSize));
}
Next steps
This completes this series of tutorials on using the Entity Framework Core in an ASP.NET Core MVC application.
For more information about EF Core, see the Entity Framework Core documentation. A book is also available:
Entity Framework Core in Action.
For information on how to deploy a web app, see Host and deploy.
For information about other topics related to ASP.NET Core MVC, such as authentication and authorization, see
the ASP.NET Core documentation.
Acknowledgments
Tom Dykstra and Rick Anderson (twitter @RickAndMSFT) wrote this tutorial. Rowan Miller, Diego Vega, and
other members of the Entity Framework team assisted with code reviews and helped debug issues that arose
while we were writing code for the tutorials.
Common errors
ContosoUniversity.dll used by another process
Error message:
Cannot open '...bin\Debug\netcoreapp1.0\ContosoUniversity.dll' for writing -- 'The process cannot access the
file '...\bin\Debug\netcoreapp1.0\ContosoUniversity.dll' because it is being used by another process.
Solution:
Stop the site in IIS Express. Go to the Windows System Tray, find IIS Express and right-click its icon, select the
Contoso University site, and then click Stop Site.
Migration scaffolded with no code in Up and Down methods
Possible cause:
The EF CLI commands don't automatically close and save code files. If you have unsaved changes when you run
the migrations add command, EF won't find your changes.
Solution:
Run the migrations remove command, save your code changes and rerun the migrations add command.
Errors while running database update
It's possible to get other errors when making schema changes in a database that has existing data. If you get
migration errors you can't resolve, you can either change the database name in the connection string or delete the
database. With a new database, there's no data to migrate, and the update-database command is much more
likely to complete without errors.
The simplest approach is to rename the database in appsettings.json. The next time you run database update ,a
new database will be created.
To delete a database in SSOX, right-click the database, click Delete, and then in the Delete Database dialog box
select Close existing connections and click OK.
To delete a database by using the CLI, run the database drop CLI command:
Error locating SQL Server instance

Error Message:
A network-related or instance-specific error occurred while establishing a connection to SQL Server. The
server was not found or was not accessible. Verify that the instance name is correct and that SQL Server is
configured to allow remote connections. (provider: SQL Network Interfaces, error: 26 - Error Locating
Server/Instance Specified)
Solution:
Check the connection string. If you have manually deleted the database file, change the name of the database in
the construction string to start over with a new database.
P R E V IO U S
The following step-by-step guides for developing ASP.NET Core applications are available:
Build web apps

Razor Pages is the recommended approach to create a new Web UI app with ASP.NET Core 2.0 and later.
Razor Pages on macOS
Razor Pages with VS Code
Create an ASP.NET Core MVC web app
Web app with Visual Studio for Mac
Web app with Visual Studio Code on macOS or Linux
Build Web APIs

Create a Web API with ASP.NET Core
on macOS with Visual Studio for Mac
This is a work in progress.

This series explains the basics of building a Razor Pages web app with ASP.NET Core on macOS.
1. Get started with Razor Pages on macOS
4. Work with SQLite
5. Update the pages
6. Add search
Until the next section is complete, follow the Visual Studio for Windows version.
1. Add a new field
2. Add validation
Get started with Razor Pages in ASP.NET Core on
macOS with Visual Studio for Mac
By Rick Anderson
This tutorial teaches the basics of building an ASP.NET Core Razor Pages web app. We recommend you review
Introduction to Razor Pages before starting this tutorial. Razor Pages is the recommended way to build UI for web
applications in ASP.NET Core.
Prerequisites

From a terminal, run the following commands:
dotnet new webapp -o RazorPagesMovie

cd RazorPagesMovie
dotnet run
dotnet new razor -o RazorPagesMovie

cd RazorPagesMovie
dotnet run
The preceding commands use the .NET Core CLI to create and run a Razor Pages project. Open a browser to
http://localhost:5000 to view the application.
The default template creates RazorPagesMovie, Home, About and Contact links and pages. Depending on the
size of your browser window, you might need to click the navigation icon to show the links.
Test the links. The RazorPagesMovie and Home links go to the Index page. The About and Contact links go to
the About and Contact pages, respectively.

important to understand. You don't need to review each link provided below. The links are provided as a reference
when you need more information on a file or folder in the project.
The Pages folder

The _ViewStart.cshtml sets the Razor Pages Layout property to use the _Layout.cshtml file. See Layout for more
information.
The _ValidationScriptsPartial.cshtml file provides a reference to jQuery validation scripts. When we add Create
and Edit pages later in the tutorial, the _ValidationScriptsPartial.cshtml file will be used.
The About , Contact and Index pages are basic pages you can use to start an app. The Error page is used to
display error information.
Open the project

Press Ctrl+C to shut down the application.
From Visual Studio, select File > Open, and then select the RazorPagesMovie.csproj file.
Launch the app
In Visual Studio, select Run > Start Without Debugging to launch the app. Visual Studio starts Kestrel, launches
a browser, and navigates to http://localhost:5000 .
In the next tutorial, we add a model to the project.
M ODEL
Add a model to an ASP.NET Core Razor Pages app
with Visual Studio for Mac
By Rick Anderson
Add a data model

In Solution Explorer, right-click the RazorPagesMovie project, and then select Add > New Folder. Name
the folder Models.
Right-click the Models folder, and then select Add > New File.
In the New File dialog:
Select General in the left pane.
Select Empty Class in the center pain.
Name the class Movie and select New.
using System;
{
public class Movie
{
}
}

{
{
: base(options)
{
}

}
}
{
"Logging": {
"LogLevel": {
}
},
"MovieContext": "Data Source=MvcMovie.db"
}
}

Register the database context with the dependency injection container in the Startup.cs file.

{
options.UseSqlite(Configuration.GetConnectionString("MovieContext")));
services.AddMvc();
}
Right click on a red squiggly line, for example MovieContextin the line
services.AddDbContext<MovieContext>(options => . Select Quick Fix > using RazorPagesMovie.Models;. Visual
studio adds the using statement.
Click on the Microsoft.EntityFrameworkCore.Tools.DotNet link to get the version number to use. To install this
package, add it to the DotNetCliToolReference collection in the .csproj file. Note: You have to install this package
by editing the .csproj file; you can't use the install-package command or the package manager GUI.
To edit a .csproj file:
Select File > Open, and then select the .csproj file.
Select Options.
Change Open with to Source Code Editor.
Add the Microsoft.EntityFrameworkCore.Tools.DotNet tool reference to the second <ItemGroup>.:

<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>netcoreapp2.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
</ItemGroup>
<ItemGroup>
</ItemGroup>
</Project>
The version numbers shown in the following code were correct at the time of writing.

Add the following lines to the RazorPagesMovie.csproj file, just before the closing </Project> tag:
<ItemGroup>
<DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.1.0-preview1-
final"/>
</ItemGroup>
From the command line, run the following .NET Core CLI commands:

dotnet restore
The DotNetCliToolReference element and the add package command install the tooling required to run the
scaffolding engine.
The ef migrations add InitialCreate command generates code to create the initial database schema. The schema
is based on the model specified in the DbContext (In the Models/MovieContext.cs file). The InitialCreate
The ef database update command runs the Up method in the Migrations/<time-stamp>_InitialCreate.cs file,
which creates the database.
Run the following from the command line (in the project directory that contains the Program.cs, Startup.cs,
and .csproj files):
dotnet aspnet-codegenerator razorpage -m Movie -dc MovieContext -udl -outDir Pages/Movies --

No executable found matching command "dotnet-aspnet-codegenerator"
Open a command shell to the project directory (The directory that contains the Program.cs, Startup.cs, and .csproj
files).


Test the app

If you get the error similar to the following, verify you have run migrations and updated the database:

'no such table: Movie'.
Add the Pages/Movies files to the project

In Visual Studio, Right-click the Pages folder and select Add > Add existing Folder.
Select the Movies folder.
In the Choose files to include in the project dialog, select Include All.
STA RTE D PAGES
By Rick Anderson

{
{

{
_context = context;
}

{
}
}
}
{
{

{
_context = context;
}

{
}
}
}

{
{
return Page();
}
}

@page
@{
}
<h2>Index</h2>
<p>
</p>
<thead>
<tr>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
</th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
evaluated.
@page
@model
ViewData and layout

@page
@{
}
block of C# code.
<!DOCTYPE html>
<html>
<head>
Pages/Index.cshtml and Pages/Movies/Index.cshtml currently have the same title, but you can modify them to have
different values.
NOTE
@{
Layout = "_Layout";
}
Update the layout
<!DOCTYPE html>
<html>
<head>
{
{

{
_context = context;
}

{
return Page();
}
[BindProperty]

{
{
return Page();
}
}
}
}
{
{

{
_context = context;
}

{
return Page();
}
[BindProperty]

{
{
return Page();
}
}
}
}
OnGet

{
{
return Page();
}
}
the tutorial.
@page
@{
}
<h2>Create</h2>
<h4>Movie</h4>
<hr />
<div class="row">
</div>
</div>
</div>
</div>
</div>
</form>
</div>
</div>
<div>
</div>
@section Scripts {
}
antiforgery token.
</div>
The next tutorial explains SQLite and seeding the database.
P R E V IO U S : A D D IN G A N E X T:
M ODEL S Q L IT E
Work with SQLite in an ASP.NET Core Razor Pages
app
By Rick Anderson

{
// requires
services.AddMvc();
}
SQLite
The SQLite website states:
SQLite is a self-contained, high-reliability, embedded, full-featured, public-domain, SQL database engine.

SQLite is the most used database engine in the world.
There are many third party tools you can download to manage and view a SQLite database. The image below is
from DB Browser for SQLite. If you have a favorite SQLite tool, leave a comment on what you like about it.
Seed the database
using System;
using System.Linq;
{
{
{
{
{
}
new Movie
{
Price = 7.99M
},
new Movie
{
Genre = "Comedy",
Price = 8.99M
},
new Movie
{
Genre = "Comedy",
Price = 9.99M
},
new Movie
{
Genre = "Western",
Price = 3.99M
}
);
}
}
}
}
If there are any movies in the DB, the seed initializer returns.
{
}


using System;
{
{
{

{
try
{
}
{
}
}
host.Run();
}

.Build();
}
}
Test the app

Delete all the records in the DB (So the seed method will run). Stop and start the app to seed the database.
P R E V IO U S : A D D IN G A N E X T: U P D A T E T H E
M ODEL PAGES
Update the generated pages
By Rick Anderson

using System;
{
public class Movie
{

}
}
using System;
{
public class Movie
{


}
}
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
information.
<td>
</td>
<td>
</td>
@page "{id:int?}"

changes:

{
{
return Page();
}
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
Edit a movie.
{

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}
if (Movie == null)
{
return NotFound();
}
return Page();
}

{
{
return Page();
}
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
}
{

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}
if (Movie == null)
{
return NotFound();
}
return Page();
}

{
{
return Page();
}
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
}
Model binding.
[BindProperty]
Razor Page.
P R E V IO U S : W O R K W IT H ADD
S Q L L IT E SE A RCH
Add search to an ASP.NET Core Razor Pages app
By Rick Anderson
@{
Layout = "_Layout";
}

{
select m;
{
}

}

select m;
{
}
information.
example, http://localhost:5000/Movies/ghost ).
@page
@{
}
<h2>Index</h2>
<p>
</p>
<form>
<p>
</p>
</form>
Search by genre
{

{
_context = context;
}


{
orderby m.Genre
select m.Genre;

select m;
{
}
{
}
}

orderby m.Genre
select m.Genre;

@page
@{
}
<h2>Index</h2>
<p>
</p>
<form>
<p>
</select>

</p>
</form>
<thead>
PAGES F IE L D
and Visual Studio Code
This is a work in progress.

This series explains the basics of building a Razor Pages web app with ASP.NET Core using Visual Studio Code.
1. Get started with Razor Pages with VS Code
4. Work with SQLite
5. Update the pages
6. Add search
Until the next section is complete, follow the Visual Studio for Windows version.
1. Add a new field
2. Add validation
Get started with ASP.NET Core Razor Pages in Visual
Studio Code
By Rick Anderson
This tutorial teaches the basics of building an ASP.NET Core Razor Pages web app. We recommend you complete
Introduction to Razor Pages before starting this tutorial. Razor Pages is the recommended way to build UI for web
applications in ASP.NET Core.
Prerequisites
Visual Studio Code
Visual Studio Code

dotnet new webapp -o RazorPagesMovie

cd RazorPagesMovie
dotnet run
dotnet new razor -o RazorPagesMovie

cd RazorPagesMovie
dotnet run
The preceding commands use the .NET Core CLI to create and run a Razor Pages project. Open a browser to
http://localhost:5000 to view the application.
The default template creates RazorPagesMovie, Home, About and Contact links and pages. Depending on the
size of your browser window, you might need to click the navigation icon to show the links.
Test the links. The RazorPagesMovie and Home links go to the Index page. The About and Contact links go to
the About and Contact pages, respectively.

important to understand. You don't need to review each link provided below. The links are provided as a reference
when you need more information on a file or folder in the project.
The Pages folder

The _ViewStart.cshtml sets the Razor Pages Layout property to use the _Layout.cshtml file. See Layout for more
information.
The _ValidationScriptsPartial.cshtml file provides a reference to jQuery validation scripts. When we add Create
and Edit pages later in the tutorial, the _ValidationScriptsPartial.cshtml file will be used.
The About , Contact and Index pages are basic pages you can use to start an app. The Error page is used to
display error information.
Open the project

Press Ctrl+C to shut down the application.
From Visual Studio Code (VS Code), select File > Open Folder, and then select the RazorPagesMovie folder.
Select Yes to the Warn message "Required assets to build and debug are missing from 'RazorPagesMovie'.
Add them?"
Launch the app
Press Ctrl+F5 to start the app without debugging. Alternatively, from the Debug menu, select Start Without
Debugging.
In the next tutorial, we add a model to the project.
M ODEL
Add a model to an ASP.NET Core Razor Pages app
with Visual Studio Code
By Rick Anderson
Add a data model

Add a folder named Models.
Add a class to the Models folder named Movie.cs.
Add the following code to the Models/Movie.cs file:
using System;
{
public class Movie
{
}
}

{
{
: base(options)
{
}

}
}
{
"Logging": {
"LogLevel": {
}
},
"MovieContext": "Data Source=MvcMovie.db"
}
}

Register the database context with the dependency injection container in the Startup.cs file.
Entity Framework Core NuGet package for SQLite
From the command line, run the following .NET Core CLI command:
dotnet add package Microsoft.EntityFrameworkCore.SQLite

{
services.AddMvc();
}
Add the following using statements at the top of Startup.cs:

To install this package, add it to the DotNetCliToolReference collection in the .csproj file. Note: You have to install
this package by editing the .csproj file; you can't use the install-package command or the package manager GUI.
Edit the RazorPagesMovie.csproj file:
Select File > Open File, and then select the RazorPagesMovie.csproj file.
Add tool reference for Microsoft.EntityFrameworkCore.Tools.DotNet to the second <ItemGroup>:
<PropertyGroup>
</PropertyGroup>
<ItemGroup>
</ItemGroup>
<ItemGroup>
</ItemGroup>
</Project>

Add the following lines to the RazorPagesMovie.csproj file, just before the closing </Project> tag:
<ItemGroup>
<DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.1.0-preview1-
final"/>
</ItemGroup>

dotnet restore
The DotNetCliToolReference element and the add package command install the tooling required to run the
scaffolding engine.
The ef migrations add InitialCreate command generates code to create the initial database schema. The schema
is based on the model specified in the DbContext (In the Models/MovieContext.cs file). The InitialCreate
The ef database update command runs the Up method in the Migrations/<time-stamp>_InitialCreate.cs file,
which creates the database.
Open a command window in the project directory (The directory that contains the Program.cs, Startup.cs, and
.csproj files).
Run the following command:
Note: Run the following command on Windows. For MacOS and Linux, see the next command
dotnet aspnet-codegenerator razorpage -m Movie -dc MovieContext -udl -outDir Pages\Movies --
On MacOS and Linux, run the following command:
dotnet aspnet-codegenerator razorpage -m Movie -dc MovieContext -udl -outDir Pages/Movies --



Test the app

If you get the error similar to the following, verify you have run migrations and updated the database:

'no such table: Movie'.
STA RTE D PAGES
By Rick Anderson

{
{

{
_context = context;
}

{
}
}
}
{
{

{
_context = context;
}

{
}
}
}

{
{
return Page();
}
}

@page
@{
}
<h2>Index</h2>
<p>
</p>
<thead>
<tr>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
</th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
evaluated.
@page
@model
ViewData and layout

@page
@{
}
block of C# code.
<!DOCTYPE html>
<html>
<head>
Pages/Index.cshtml and Pages/Movies/Index.cshtml currently have the same title, but you can modify them to have
different values.
NOTE
@{
Layout = "_Layout";
}
Update the layout
<!DOCTYPE html>
<html>
<head>
{
{

{
_context = context;
}

{
return Page();
}
[BindProperty]

{
{
return Page();
}
}
}
}
{
{

{
_context = context;
}

{
return Page();
}
[BindProperty]

{
{
return Page();
}
}
}
}
OnGet

{
{
return Page();
}
}
the tutorial.
@page
@{
}
<h2>Create</h2>
<h4>Movie</h4>
<hr />
<div class="row">
</div>
</div>
</div>
</div>
</div>
</form>
</div>
</div>
<div>
</div>
@section Scripts {
}
antiforgery token.
</div>
The next tutorial explains SQLite and seeding the database.
P R E V IO U S : A D D IN G A N E X T:
M ODEL S Q L IT E
Work with SQLite in an ASP.NET Core Razor Pages
app
By Rick Anderson

{
// requires
services.AddMvc();
}
SQLite

Seed the database
using System;
using System.Linq;
{
{
{
{
{
}
new Movie
{
Price = 7.99M
},
new Movie
{
Genre = "Comedy",
Price = 8.99M
},
new Movie
{
Genre = "Comedy",
Price = 9.99M
},
new Movie
{
Genre = "Western",
Price = 3.99M
}
);
}
}
}
}
{
}


using System;
{
{
{

{
try
{
}
{
}
}
host.Run();
}

.Build();
}
}
Test the app

P R E V IO U S : A D D IN G A N E X T: U P D A T E T H E
M ODEL PAGES
Update the generated pages
By Rick Anderson

using System;
{
public class Movie
{

}
}
using System;
{
public class Movie
{


}
}
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
information.
<td>
</td>
<td>
</td>
@page "{id:int?}"

changes:

{
{
return Page();
}
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
Edit a movie.
{

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}
if (Movie == null)
{
return NotFound();
}
return Page();
}

{
{
return Page();
}
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
}
{

{
_context = context;
}
[BindProperty]

{
if (id == null)
{
return NotFound();
}
if (Movie == null)
{
return NotFound();
}
return Page();
}

{
{
return Page();
}
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
}
Model binding.
[BindProperty]
Razor Page.
P R E V IO U S : W O R K IN G W IT H ADD
S Q L L IT E SE A RCH
Add search to an ASP.NET Core Razor Pages app
By Rick Anderson
@{
Layout = "_Layout";
}

{
select m;
{
}

}

select m;
{
}
information.
example, http://localhost:5000/Movies/ghost ).
@page
@{
}
<h2>Index</h2>
<p>
</p>
<form>
<p>
</p>
</form>
Search by genre
{

{
_context = context;
}


{
orderby m.Genre
select m.Genre;

select m;
{
}
{
}
}

orderby m.Genre
select m.Genre;

@page
@{
}
<h2>Index</h2>
<p>
</p>
<form>
<p>
</select>

</p>
</form>
<thead>
PAGES F IE L D
Create a web app with ASP.NET Core MVC on
macOS with Visual Studio for Mac
This series of tutorials teaches you the basics of building an ASP.NET Core MVC web app using Visual Studio for
Mac.
tutorial:
1. Get started
2. Add a controller
3. Add a view
4. Add a model
5. SQLite
7. Add search
8. Add a new field
9. Add validation
Get started with ASP.NET Core MVC and Visual
Studio for Mac
By Rick Anderson
This tutorial teaches you the basics of building an ASP.NET Core MVC web app using Visual Studio for Mac.
tutorial:
macOS: Build an ASP.NET Core MVC app with Visual Studio for Mac
Windows: Build an ASP.NET Core MVC app with Visual Studio
Linux, macOS, and Windows: Build an ASP.NET Core MVC app with Visual Studio Code
Prerequisites
Create a web app

Select .NET Core App > ASP.NET Core > Web App > Next.
Name the project MvcMovie, and then select Create.

Launch the app
In Visual Studio, select Run > Start Without Debugging to launch the app. Visual Studio starts Kestrel, launches
a browser, and navigates to http://localhost:port , where port is a randomly chosen port number.
The address bar shows localhost:port# and not something like example.com . That's because localhost is the
standard hostname for your local computer. When Visual Studio creates a web project, a random port is used
for the web server. When you run the app, you'll see a different port number.
You can launch the app in debug or non-debug mode from the Run menu.
The default template gives you Home, About and Contact links. The browser image above doesn't show these
links. Depending on the size of your browser, you might need to click the navigation icon to show them.
In the next part of this tutorial, you learn about MVC and start writing some code.
NEXT
Add a controller to an ASP.NET Core MVC app with
By Rick Anderson
model data.
Add a controller
In Solution Explorer, right-click Controllers > Add > New File.
Select ASP.NET Core and MVC Controller Class.
Name the controller HelloWorldController.

{
{
//

{
}
//

{
}
}
}
returns a string.
{
routes.MapRoute(
name: "default",
});
the following code.
{
}
The preceding code:


{
}
is optional.
{
routes.MapRoute(
name: "default",
});
P R E V IO U S NEXT
By Rick Anderson
Index

{
return View();
}
Add a view
Right click on the Views folder, and then Add > New Folder and name the folder HelloWorld.
Right click on the Views/HelloWorld folder, and then Add > New File.
Select Web in the left pane.
Select Empty HTML file in the center pane.
Type Index.cshtml in the Name box.
Select New.
@{
}
<h2>Index</h2>




<!DOCTYPE html>
<html>
<head>
</environment>
value="absolute" />
</environment>
</head>
<body>
collapse">
</button>
</div>
</ul>
</div>
</div>
</nav>
@RenderBody()
<hr />
<footer>
</footer>
</div>
</environment>
</environment>
</script>
</script>
</environment>

</body>
</html>

<!DOCTYPE html>
<html>
<head>
</environment>
value="absolute" />
</environment>
</head>
<body>
collapse">
</button>
</div>
</ul>
</div>
</div>
</nav>
@RenderBody()
<hr />
<footer>
<footer>
</footer>
</div>
</environment>
</script>
</script>
</environment>

</body>
</html>
WARNING
@{
Layout = "_Layout";
}

@{
}

{
{
{
return View();
}

{
return View();
}
}
}
@{
}
<h2>Welcome</h2>
<ul>
{
}
</ul>

the browser.
database of movies.
P R E V IO U S NEXT

of the MVC app.

Right-click the Models folder, and then select Add > New File.
Select General in the left pane.
Select Empty Class in the center pain.
Name the class Movie and select New.
using System;
{
public class Movie
{
}
}

Build the project to verify you don't have any errors. You now have a Model in your MVC app.
Prepare the project for scaffolding

Right click on the project file, and then select Tools > Edit File.
Add the following highlighted NuGet packages to the MvcMovie.csproj file:
<PropertyGroup>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.0.0" />
</ItemGroup>
<ItemGroup>
<DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.0"
/>
</ItemGroup>
</Project>
Save the file.

Create a Models/MvcMovieContext.cs file and add the following MvcMovieContext class:
{
public class MvcMovieContext : DbContext
{
public MvcMovieContext (DbContextOptions<MvcMovieContext> options)
: base(options)
{
}
public DbSet<MvcMovie.Models.Movie> Movie { get; set; }

}
}
Open the Startup.cs file and add two usings:
namespace MvcMovie
{
{
Add the database context to the Startup.cs file:

{
services.AddMvc();
options.UseSqlite("Data Source=MvcMovie.db"));
This tells Entity Framework which model classes are included in the data model. You're defining one entity
set of Movie objects, which will be represented in the database as a Movie table.
Build the project to verify there are no errors.
Scaffold the MovieController

Open a terminal window in the project folder and run the following commands:
dotnet restore
dotnet aspnet-codegenerator controller -name MoviesController -m Movie -dc MvcMovieContext --
relativeFolderPath Controllers --useDefaultLayout --referenceScriptLibraries
If you get the error No executable found matching command "dotnet-aspnet-codegenerator", verify :
You are in the project directory. The project directory has the Program.cs, Startup.cs and .csproj files.
Your dotnet version is 1.1 or higher. Run dotnet to get the version.
You have added the <DotNetCliToolReference> element to the MvcMovie.csproj file.
The scaffolding engine creates the following:

Razor view files for Create, Delete, Details, Edit and Index pages (Views/Movies/*.cshtml)
The automatic creation of CRUD (create, read, update, and delete) action methods and views is known as
scaffolding. You'll soon have a fully functional web application that lets you manage a movie database.
Add the files to Visual Studio
Add the MovieController.cs file to the Visual Studio project:
Right-click on the Controllers folder and select Add > Add Files.
Select the MovieController.cs file.
Add the Movies folder and views:
Right-click on the Views folder and select Add > Add Existing Folder.
Navigate to the Views folder, select Views\Movies, and then select Open.
In the Select files to add from Movies dialog, select Include All, and then OK.


The dotnet ef migrations add InitialCreate command generates code to create the initial database schema. The
schema is based on the model specified in the DbContext (In the Models/MvcMovieContext.cs file). The Initial
The dotnet ef database update command runs the Up method in the Migrations/<time-stamp>_InitialCreate.cs
file, which creates the database.
Test the app

using System;
{
public class Movie
{
}
}

You now have a database and pages to display, edit, update and delete data. In the next tutorial, we'll work with the
database.
Tag Helpers
P R E V IO U S A D D IN G A N E X T W O R K IN G W IT H
V IE W SQL
Work with SQLite in an ASP.NET Core MVC app
By Rick Anderson

{
services.AddMvc();
SQLite

Seed the database
using System;
using System.Linq;
{
{
{
{
{
}
new Movie
{
Price = 7.99M
},
new Movie
{
Genre = "Comedy",
Price = 8.99M
},
new Movie
{
Genre = "Comedy",
Price = 9.99M
},
new Movie
{
Genre = "Western",
Price = 3.99M
}
);
}
}
}
}
{
}

using System;
using MvcMovie;
namespace MvcMovie
{
{
{

{
try
{
}
{
}
}
host.Run();
}

}
}
using System;
namespace MvcMovie
{
{
{

{
try
{
}
{
}
}
host.Run();
}

.Build();
}
}
Test the app

P R E V IO U S - A D D A N E X T - C ON TROL L E R M E THOD S A N D
M ODEL V IE W S
Controller methods and views in an ASP.NET Core
MVC app
By Rick Anderson
AM in the following image) and ReleaseDate should be two words.
using System;
{
public class Movie
{

}
}
Build and run the app.


</td>
</tr>
<td>
</td>

{
routes.MapRoute(
name: "default",
});
information.
file.
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
Request Forgery.
HttpGet Edit
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
@{
}
<h2>Edit</h2>
<h4>Movie</h4>
<hr />
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</form>
<div>
</div>
@section Scripts {
}

<h4>Movie</h4>
<hr />
value="7" />
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</form>

[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
changes just made.
messages.
Author Tag Helpers
ViewModels
Form Tag Helper
Input Tag Helper
Label Tag Helper
Select Tag Helper
P R E V IO U S - W O R K IN G W IT H NE X T - ADD
S Q L IT E SE A RCH
By Rick Anderson
name.

{
select m;
{
}

}

select m;
string:
{
}
are displayed.
{
routes.MapRoute(
name: "default",
});
Note: SQLlite is case sensitive, so you'll need to search for "Ghost" and not "ghost".

{
select m;
{
}

}

{
select m;
{
}

}

{
select m;
{
}

}
}
<h2>Index</h2>
<p>
</p>

<p>
</p>
</form>
<thead>
[HttpPost]
{
}
tutorial.
Change the <form> tag in the Views\movie\Index.cshtml Razor view to specify method="get" :

{
{
}
}

A list of movies.

{
orderby m.Genre
select m.Genre;

select m;
{
}
{
}

}

orderby m.Genre
select m.Genre;
duplicate genres).

@{
}
<h2>Index</h2>
<p>
</p>

<p>
</select>

</p>
</form>
<thead>
<tr>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
</th>
<th></th>
</tr>
</thead>
<tbody>
{
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
P R E V IO U S - C O N T R O L L E R M E T H O D S A N D NE X T - ADD A
V IE W S F IE L D
By Rick Anderson
This tutorial will add a new field to the Movies table. We'll drop the database and create a new one when we
change the schema (add a new field). This workflow works well early in development when we don't have any
production data to perserve.
Once your app is deployed and you have data that you need to perserve, you can't drop your DB when you need
to change the schema. Entity Framework Code First Migrations allows you to update your schema and migrate
the database without losing data. Migrations is a popular feature when using SQL Server, but SQLlite doesn't
support many migration schema operations, so only very simply migrations are possible. See SQLite Limitations
for more information.

public class Movie

{


}
public class Movie

{

}
Because you've added a new field to the Movie class, you also need to update the binding whitelist so this new
You also need to update the view templates in order to display, create, and edit the new Rating property in the
browser view.
<thead>
<tr>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
</th>
<th></th>
</tr>
</thead>
<tbody>
{
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
Update the /Views/Movies/Create.cshtml with a Rating field.

SqliteException :
SqliteException: SQLite Error 1: 'no such column: m.Rating'.
1. Drop the database and have the Entity Framework automatically re-create the database based on the new
model class schema. With this approach, you lose existing data in the database — so you can't do this with a
production database! Using an initializer to automatically seed a database with test data is often a
productive way to develop an app.
2. Manually modify the schema of the existing database so that it matches the model classes. The advantage
For this tutorial, we'll drop and re-create the database when the schema changes. Run the following command
from a terminal to drop the db:
new Movie
{
Rating = "R",
Price = 7.99M
},
Add the Rating field to the Edit , Details , and Delete view.
Run the app and verify you can create/edit/display movies with a Rating field. templates.
P R E V IO U S - A D D NE X T - ADD
By Rick Anderson
Keeping things DRY


public class Movie

{

[Required]

[Range(1, 100)]
[Required]
[StringLength(30)]
[StringLength(5)]
[Required]
}
public class Movie
{

[Required]

[Range(1, 100)]
[Required]
[StringLength(30)]
[StringLength(5)]
[Required]
}

NOTE

{
return View();
}
[HttpPost]
{
{
}
return View(movie);
}
browser, then submit the form with errors, the break point will be hit. You still get full validation without JavaScript.
<h4>Movie</h4>
<hr />

</div>
</div>

</div>
</form>
information.

DataType enumeration value to the release date and to the price fields. The following code shows the ReleaseDate
and Price properties with the appropriate DataType attribute.
[Range(1, 100)]
Time, PhoneNumber, Currency, EmailAddress and more. The DataType attribute can also enable the application to
automatically provide type-specific features. For example, a mailto: link can be created for

NOTE
public class Movie
{




}
public class Movie

{





}
Working with Forms
Author Tag Helpers
P R E V IO U S - A D D A N E X T - E X A M IN E T H E D E T A IL S A N D D E L E T E
F IE L D M E THOD S
ASP.NET Core app
By Rick Anderson
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
routes.MapRoute(
name: "default",
});
exception.
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
}
Note that the HTTP GET Delete method doesn't delete the specified movie, it returns a view of the movie where you
can submit (HttpPost) the deletion. Performing a delete operation in response to a GET request (or for that matter,
performing an edit operation, create operation, or any other operation that changes data) opens up a security hole.
The [HttpPost] method that deletes the data is named DeleteConfirmed to give the HTTP POST method a unique
signature or name. The two method signatures are shown below:
{
{
parameter.)
There are two approaches to this problem, one is to give the methods different names. That's what the scaffolding
mechanism did in the preceding example. However, this introduces a small problem: ASP.NET maps segments of a
URL to action methods by name, and if you rename a method, routing normally wouldn't be able to find that
method. The solution is what you see in the example, which is to add the ActionName("Delete") attribute to the
DeleteConfirmed method. That attribute performs mapping for the routing system so that a URL that includes
/Delete/ for a POST request will find the DeleteConfirmed method.
signature of the POST method to include an extra (unused) parameter. That's what we did in a previous post when
we added the notUsed parameter. You could do the same thing here for the [HttpPost] Delete method:
Publish to Azure
P R E V IO U S
Create an ASP.NET Core MVC app with Visual Studio
Code
This series of tutorials teaches you the basics of building an ASP.NET Core MVC web app using Visual Studio
Code.
tutorial:
1. Get started
2. Add a controller
3. Add a view
4. Add a model
5. Work with SQLite
7. Add search
8. Add a new field
9. Add validation
Introduction to ASP.NET Core MVC on macOS,
Linux, or Windows
By Rick Anderson
This tutorial will teach you the basics of building an ASP.NET Core MVC web app using Visual Studio Code (VS
Code). The tutorial assumes familarity with VS Code. See Getting started with VS Code and Visual Studio Code
help for more information.
This tutorial teaches ASP.NET Core MVC web development with controllers and views. Razor Pages is a feature
of the ASP.NET Core MVC framework that makes building and testing web UI easier and more productive. You
can use Razor pages alongside controllers and views in the same project.
tutorial:
Windows: Create an ASP.NET Core MVC app with Visual Studio
Prerequisites
Visual Studio Code
Visual Studio Code
Create a web app with dotnet

mkdir MvcMovie
cd MvcMovie
dotnet new mvc
Open the MvcMovie folder in Visual Studio Code (VS Code) and select the Startup.cs file.
Select Yes to the Warn message "Required assets to build and debug are missing from 'MvcMovie'. Add
them?"
Press Debug (F5) to build and run the program.
VS Code starts the Kestrel web server and runs your app. Notice that the address bar shows localhost:5000 and
them.

Getting started
Debugging
Integrated terminal
Keyboard shortcuts
NE X T - ADD A
C ON TROL L E R
Add a controller to an ASP.NET Core app
By Rick Anderson
model data.
In VS Code, select the EXPLORER icon and then control-click (right-click) Controllers > New File and
name the new file HelloWorldController.cs.
{
{
//

{
}
//

{
}
}
}
returns a string.
{
routes.MapRoute(
name: "default",
});
the following code.
{
}
The preceding code:


{
}
is optional.
{
routes.MapRoute(
name: "default",
});
P R E V IO U S - A D D A NE X T - ADD A
C ON TROL L E R V IE W
By Rick Anderson
Index

{
return View();
}
Add an Index view for the HelloWorldController .
Add a new folder named Views/HelloWorld.
Add a new file to the Views/HelloWorld folder name Index.cshtml.
@{
}
<h2>Index</h2>




<!DOCTYPE html>
<html>
<head>
</environment>
value="absolute" />
</environment>
</head>
<body>
collapse">
</button>
</div>
</ul>
</div>
</div>
</nav>
@RenderBody()
<hr />
<footer>
</footer>
</div>
</environment>
</script>
</script>
</environment>

</body>
</html>
</html>

<!DOCTYPE html>
<html>
<head>
</environment>
value="absolute" />
</environment>
</head>
<body>
collapse">
</button>
</div>
</ul>
</div>
</div>
</nav>
@RenderBody()
<hr />
<footer>
</footer>
</div>
</environment>
</script>
</script>
</environment>

</body>
</html>
WARNING
@{
Layout = "_Layout";
}

@{
}

{
{
{
return View();
}

{
return View();
}
}
}
@{
}
<h2>Welcome</h2>
<ul>
{
}
</ul>

the browser.
database of movies.
P R E V IO U S - A D D A NE X T - ADD A
C ON TROL L E R M ODEL

of the MVC app.

Add a class to the Models folder named Movie.cs.
Add the following code to the Models/Movie.cs file:
using System;
{
public class Movie
{
}
}

Build the app to verify you don't have any errors, and you've finally added a Model to your MVC app.
Prepare the project for scaffolding

Add the following highlighted NuGet packages to the MvcMovie.csproj file:
<PropertyGroup>
</PropertyGroup>
<ItemGroup>
</ItemGroup>
<ItemGroup>
<DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.0"
/>
</ItemGroup>
</Project>
Save the file and select Restore to the Info message "There are unresolved dependencies".
Create a Models/MvcMovieContext.cs file and add the following MvcMovieContext class:
{
public class MvcMovieContext : DbContext
{
public MvcMovieContext (DbContextOptions<MvcMovieContext> options)
: base(options)
{
}
public DbSet<MvcMovie.Models.Movie> Movie { get; set; }

}
}
Open the Startup.cs file and add two usings:
namespace MvcMovie
{
{
Add the database context to the Startup.cs file:

{
services.AddMvc();
This tells Entity Framework which model classes are included in the data model. You're defining one entity
set of Movie objects, which will be represented in the database as a Movie table.
Build the project to verify there are no errors.
Scaffold the MovieController
Open a terminal window in the project folder and run the following commands:
dotnet restore
dotnet aspnet-codegenerator controller -name MoviesController -m Movie -dc MvcMovieContext --
relativeFolderPath Controllers --useDefaultLayout --referenceScriptLibraries
The scaffolding engine creates the following:

Razor view files for Create, Delete, Details, Edit and Index pages (Views/Movies/*.cshtml)
The automatic creation of CRUD (create, read, update, and delete) action methods and views is known as
scaffolding. You'll soon have a fully functional web application that lets you manage a movie database.


The dotnet ef migrations add InitialCreate command generates code to create the initial database schema. The
schema is based on the model specified in the DbContext (In the Models/MvcMovieContext.cs file). The Initial
The dotnet ef database update command runs the Up method in the Migrations/<time-stamp>_InitialCreate.cs
file, which creates the database.
Test the app

using System;
{
public class Movie
{
}
}

You now have a database and pages to display, edit, update and delete data. In the next tutorial, we'll work with the
database.
Tag Helpers
P R E V IO U S - A D D A N E X T - W O R K IN G W IT H
V IE W S Q L IT E
Work with SQLite in an ASP.NET Core MVC app
By Rick Anderson

{
services.AddMvc();
SQLite

Seed the database
using System;
using System.Linq;
{
{
{
{
{
}
new Movie
{
Price = 7.99M
},
new Movie
{
Genre = "Comedy",
Price = 8.99M
},
new Movie
{
Genre = "Comedy",
Price = 9.99M
},
new Movie
{
Genre = "Western",
Price = 3.99M
}
);
}
}
}
}
{
}

using System;
using MvcMovie;
namespace MvcMovie
{
{
{

{
try
{
}
{
}
}
host.Run();
}

}
}
using System;
namespace MvcMovie
{
{
{

{
try
{
}
{
}
}
host.Run();
}

.Build();
}
}
Test the app

P R E V IO U S - A D D A N E X T - C ON TROL L E R M E THOD S A N D
M ODEL V IE W S
Controller methods and views in ASP.NET Core
By Rick Anderson
AM in the image below ) and ReleaseDate should be two words.
using System;
{
public class Movie
{

}
}
Build and run the app.


</td>
</tr>
<td>
</td>

{
routes.MapRoute(
name: "default",
});
information.
file.
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
Request Forgery.
HttpGet Edit
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
@{
}
<h2>Edit</h2>
<h4>Movie</h4>
<hr />
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</form>
<div>
</div>
@section Scripts {
}

<h4>Movie</h4>
<hr />
value="7" />
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</form>

[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
[HttpPost]
{
if (id != movie.ID)
{
return NotFound();
}
{
try
{
}
{
{
return NotFound();
}
else
{
throw;
}
}
}
return View(movie);
}
changes just made.
messages.
Author Tag Helpers
ViewModels
Form Tag Helper
Input Tag Helper
Label Tag Helper
Select Tag Helper
P R E V IO U S - W O R K IN G W IT H NE X T - ADD
S Q L IT E SE A RCH
By Rick Anderson
name.

{
select m;
{
}

}

select m;
string:
{
}
are displayed.
{
routes.MapRoute(
name: "default",
});
Note: SQLlite is case sensitive, so you'll need to search for "Ghost" and not "ghost".

{
select m;
{
}

}

{
select m;
{
}

}

{
select m;
{
}

}
}
<h2>Index</h2>
<p>
</p>

<p>
</p>
</form>
<thead>
[HttpPost]
{
}
tutorial.
Change the <form> tag in the Views\movie\Index.cshtml Razor view to specify method="get" :

{
{
}
}

A list of movies.

{
orderby m.Genre
select m.Genre;

select m;
{
}
{
}

}

orderby m.Genre
select m.Genre;
duplicate genres).

@{
}
<h2>Index</h2>
<p>
</p>

<p>
</select>

</p>
</form>
<thead>
<tr>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
</th>
<th></th>
</tr>
</thead>
<tbody>
{
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
</tr>
}
</tbody>
</table>
P R E V IO U S - C O N T R O L L E R M E T H O D S A N D NE X T - ADD A
V IE W S F IE L D
By Rick Anderson
This tutorial will add a new field to the Movies table. We'll drop the database and create a new one when we
change the schema (add a new field). This workflow works well early in development when we don't have any
production data to perserve.
Once your app is deployed and you have data that you need to perserve, you can't drop your DB when you need
to change the schema. Entity Framework Code First Migrations allows you to update your schema and migrate
the database without losing data. Migrations is a popular feature when using SQL Server, but SQLlite doesn't
support many migration schema operations, so only very simply migrations are possible. See SQLite Limitations

public class Movie

{


}
public class Movie

{

}
Because you've added a new field to the Movie class, you also need to update the binding whitelist so this new
You also need to update the view templates in order to display, create, and edit the new Rating property in the
browser view.
<thead>
<tr>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
</th>
<th>
</th>
<th></th>
</tr>
</thead>
<tbody>
{
<tr>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
</td>
<td>
Update the /Views/Movies/Create.cshtml with a Rating field.

SqliteException :
SqliteException: SQLite Error 1: 'no such column: m.Rating'.
1. Drop the database and have the Entity Framework automatically re-create the database based on the new
model class schema. With this approach, you lose existing data in the database — so you can't do this with a
production database! Using an initializer to automatically seed a database with test data is often a
productive way to develop an app.
2. Manually modify the schema of the existing database so that it matches the model classes. The advantage
For this tutorial, we'll drop and re-create the database when the schema changes. Run the following command
from a terminal to drop the db:
new Movie
{
Rating = "R",
Price = 7.99M
},
Add the Rating field to the Edit , Details , and Delete view.
Run the app and verify you can create/edit/display movies with a Rating field. templates.
P R E V IO U S - A D D NE X T - ADD
By Rick Anderson
Keeping things DRY


public class Movie

{

[Required]

[Range(1, 100)]
[Required]
[StringLength(30)]
[StringLength(5)]
[Required]
}
public class Movie
{

[Required]

[Range(1, 100)]
[Required]
[StringLength(30)]
[StringLength(5)]
[Required]
}

NOTE

{
return View();
}
[HttpPost]
{
{
}
return View(movie);
}
browser, then submit the form with errors, the break point will be hit. You still get full validation without JavaScript.
<h4>Movie</h4>
<hr />

</div>
</div>

</div>
</form>
information.

DataType enumeration value to the release date and to the price fields. The following code shows the ReleaseDate
and Price properties with the appropriate DataType attribute.
[Range(1, 100)]
Time, PhoneNumber, Currency, EmailAddress and more. The DataType attribute can also enable the application to
automatically provide type-specific features. For example, a mailto: link can be created for

NOTE
public class Movie
{




}
public class Movie

{





}
Working with Forms
Author Tag Helpers
P R E V IO U S - A D D A N E X T - E X A M IN E T H E D E T A IL S A N D D E L E T E
F IE L D M E THOD S
ASP.NET Core app
By Rick Anderson
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
routes.MapRoute(
name: "default",
});
exception.
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
}
{
if (id == null)
{
return NotFound();
}

if (movie == null)
{
return NotFound();
}
return View(movie);
}
{
}
Note that the HTTP GET Delete method doesn't delete the specified movie, it returns a view of the movie where
you can submit (HttpPost) the deletion. Performing a delete operation in response to a GET request (or for that
matter, performing an edit operation, create operation, or any other operation that changes data) opens up a
security hole.
The [HttpPost] method that deletes the data is named DeleteConfirmed to give the HTTP POST method a
unique signature or name. The two method signatures are shown below:
{
{
parameter.)
There are two approaches to this problem, one is to give the methods different names. That's what the
scaffolding mechanism did in the preceding example. However, this introduces a small problem: ASP.NET maps
segments of a URL to action methods by name, and if you rename a method, routing normally wouldn't be able
to find that method. The solution is what you see in the example, which is to add the ActionName("Delete")
attribute to the DeleteConfirmed method. That attribute performs mapping for the routing system so that a URL
that includes /Delete/ for a POST request will find the DeleteConfirmed method.
signature of the POST method to include an extra (unused) parameter. That's what we did in a previous post
when we added the notUsed parameter. You could do the same thing here for the [HttpPost] Delete method:
Publish to Azure
P R E V IO U S
Studio for Mac

In this tutorial, build a web API for managing a list of "to-do" items. The UI isn't constructed.
macOS: Web API with Visual Studio for Mac (This tutorial)
Overview
controller.
See Introduction to ASP.NET Core MVC on macOS or Linux for an example that uses a persistent database.
Prerequisites
Create the project

Select .NET Core App > ASP.NET Core Web API > Next.
Enter TodoApi for the Project Name, and then click Create.
Launch the app

navigates to http://localhost:5000 . You get an HTTP 404 (Not Found) error. Change the URL to
http://localhost:<port>/api/values . The ValuesController data is displayed:
["value1","value2"]

Install the Entity Framework Core InMemory database provider. This database provider allows Entity Framework
Core to be used with an in-memory database.
From the Project menu, select Add NuGet Packages.
Alternatively, you can right-click Dependencies, and then select Add Packages.
Enter EntityFrameworkCore.InMemory in the search box.
Select Microsoft.EntityFrameworkCore.InMemory , and then select Add Package.
Add a model class
NOTE
You can put model classes anywhere in your project, but the Models folder is used by convention.
Right-click the Models folder, and select Add > New File > General > Empty Class. Name the class TodoItem,
and then click New.
Replace the generated code with:
{
{
}
}

You create this class by deriving from the Microsoft.EntityFrameworkCore.DbContext class.
Add a TodoContext class to the Models folder.
{
{
: base(options)
{
}

}
}

namespace TodoApi
{
{
{
services.AddMvc()
}

{
app.UseMvc();
}
}
}
namespace TodoApi
{
{
{
services.AddMvc();
}

{
app.UseMvc();
}
}
}
The preceding code:

Add a controller
In Solution Explorer, in the Controllers folder, add the class TodoController .
Replace the generated code with the following:
using System.Linq;
{
{

{
_context = context;
{
}
}
}
}
implement the API.
using System.Linq;
{
[ApiController]
{

{
_context = context;
{
}
}
}
}
The preceding code:

Get to-do items

[HttpGet]
{
}

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}
[HttpGet]
{
}

{
if (item == null)
{
return NotFound();
}
return item;
}

GET /api/todo
GET /api/todo/{id}
[
{
"id": 1,
"name": "Item1",
"isComplete": false
}
]
{
{
{
[ApiController]
{

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}

{
if (item == null)
{
return NotFound();
}
return item;
}

Return values
and writes the JSON into the body of the response message. The response code for this method is 200, assuming
there are no unhandled exceptions. Unhandled exceptions are translated into 5xx errors.
404 response.
response.
404 response.
response.
Launch the app
navigates to http://localhost:<port> , where <port> is a randomly chosen port number. You get an HTTP 404
(Not Found) error. Change the URL to http://localhost:<port>/api/values . The ValuesController data is
displayed:
["value1","value2"]
Navigate to the Todo controller at http://localhost:<port>/api/todo . The following JSON is returned:
[{"key":1,"name":"Item1","isComplete":false}]

We'll add Create , Update , and Delete methods to the controller. These methods are variations on a theme, so
I'll just show the code and highlight the main differences. Build the project after adding or changing code.
Create
[HttpPost]
{
if (item == null)
{
}

}
The preceding method responds to an HTTP POST, as indicated by the [HttpPost] attribute. The [FromBody]
attribute tells MVC to get the value of the to-do item from the body of the HTTP request.
[HttpPost]
{

}
The preceding method responds to an HTTP POST, as indicated by the [HttpPost] attribute. MVC gets the value
of the to-do item from the body of the HTTP request.
The CreatedAtRoute method returns a 201 response. It's the standard response for an HTTP POST method that
creates a new resource on the server. CreatedAtRoute also adds a Location header to the response. The Location
header specifies the URI of the newly created to-do item. See 10.2.2 201 Created.
Start the app (Run > Start With Debugging).
Open Postman.

Click the Body tab.
{
"name":"walk dog",
"isComplete":true
}
TIP
You can use the Location header URI to access the resource you created. The Create method returns
CreatedAtRoute. The first parameter passed to CreatedAtRoute represents the named route to use for generating
the URL. Recall that the GetById method created the "GetTodo" named route:
Update
[HttpPut("{id}")]
{
{
}

if (todo == null)
{
return NotFound();
}
return NoContent();
}
[HttpPut("{id}")]
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}
Update is similar to Create , but uses HTTP PUT. The response is 204 (No Content). According to the HTTP
spec, a PUT request requires the client to send the entire updated entity, not just the deltas. To support partial
updates, use HTTP PATCH.
{
"key": 1,
"name": "walk dog",
"isComplete": true
}
Delete
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}
The response is 204 (No Content).

files.

{
app.UseMvc();
}
markup:
<!DOCTYPE html>
<html>
<head>
<style>
cursor: pointer;
}
#spoiler {
display: none;
}
table {
border: 1px solid;
}
th {
color: white;
}
td {
border: 1px solid;
padding: 5px;
}
</style>
</head>
<body>
<h1>To-do CRUD</h1>
<h3>Add</h3>
</form>
<div id="spoiler">
<h3>Edit</h3>
</form>
</div>
<table>
<tr>
<th>Name</th>
<th></th>
<th></th>
</tr>
</table>
</body>
</html>
code:

let todos = null;
let name = 'to-do';
if (data) {
if (data > 1) {
name = 'to-dos';
}
} else {
}
}
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}
const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
alert('here');
},
getData();
}
});
}
$.ajax({
type: 'DELETE',
getData();
}
});
}
}
});
}
const item = {
};
$.ajax({
type: 'PUT',
getData();
}
});
closeInput();
return false;
});
}
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}
Add a to -do item

const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
alert('here');
},
getData();
}
});
}

PUT .
$.ajax({
type: 'PUT',
getData();
}
});

$.ajax({
type: 'DELETE',
getData();
}
});
Next steps
Studio Code

In this tutorial, build a web API for managing a list of "to-do" items. A UI isn't constructed.
macOS, Linux, Windows: Web API with Visual Studio Code (This tutorial)
Overview
controller.
To keep the tutorial simple, the app doesn't use a persistent database. The sample app stores to-do items
in an in-memory database.
Prerequisites
Visual Studio Code
Visual Studio Code
Create the project

From a console, run the following commands:
dotnet new webapi -o TodoApi

code TodoApi
The TodoApi folder opens in Visual Studio Code (VS Code). Select the Startup.cs file.
Select Yes to the Warn message "Required assets to build and debug are missing from 'TodoApi'. Add them?"
Press Debug (F5) to build and run the program. In a browser, navigate to http://localhost:5000/api/values. The
following output is displayed:
["value1","value2"]
See Visual Studio Code help for tips on using VS Code.

Creating a new project in ASP.NET Core 2.1 or later adds the Microsoft.AspNetCore.App package reference to
the TodoApi.csproj file. Add the Version attribute, if not already specified.
<ItemGroup>
</ItemGroup>
Creating a new project in ASP.NET Core 2.0 adds the Microsoft.AspNetCore.All package reference to the
TodoApi.csproj file:
<ItemGroup>
</ItemGroup>
There's no need to install the Entity Framework Core InMemory database provider separately. This database
provider allows Entity Framework Core to be used with an in-memory database.
Add a model class

Add a folder named Models. You can put model classes anywhere in your project, but the Models folder is used
by convention.
Add a TodoItem class with the following code:
{
{
}
}

You create this class by deriving from the Microsoft.EntityFrameworkCore.DbContext class.
Add a TodoContext class in the Models folder:
{
{
: base(options)
{
}

}
}

namespace TodoApi
{
{
{
services.AddMvc()
}

{
app.UseMvc();
}
}
}
namespace TodoApi
{
{
{
services.AddMvc();
}

{
app.UseMvc();
}
}
}
The preceding code:

Add a controller
In the Controllers folder, create a class named TodoController . Replace its contents with the following code:
using System.Linq;
{
{

{
_context = context;
{
}
}
}
}
implement the API.
using System.Linq;
{
[ApiController]
{

{
_context = context;
{
}
}
}
}
The preceding code:

Get to-do items

[HttpGet]
{
}

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}
[HttpGet]
{
}

{
if (item == null)
{
return NotFound();
}
return item;
}

GET /api/todo
GET /api/todo/{id}
[
{
"id": 1,
"name": "Item1",
"isComplete": false
}
]
{
{
{
[ApiController]
{

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}

{
if (item == null)
{
return NotFound();
}
return item;
}

Return values
and writes the JSON into the body of the response message. The response code for this method is 200,
assuming there are no unhandled exceptions. Unhandled exceptions are translated into 5xx errors.
404 response.
response.
404 response.
response.
Launch the app
In VS Code, press F5 to launch the app. Navigate to http://localhost:5000/api/todo (the Todo controller we
created).

files.

{
app.UseMvc();
}
markup:
<!DOCTYPE html>
<html>
<head>
<style>
cursor: pointer;
}
#spoiler {
display: none;
}
table {
border: 1px solid;
}
th {
color: white;
}
td {
border: 1px solid;
padding: 5px;
}
</style>
</head>
<body>
<h1>To-do CRUD</h1>
<h3>Add</h3>
</form>
<div id="spoiler">
<h3>Edit</h3>
</form>
</div>
<table>
<tr>
<th>Name</th>
<th></th>
<th></th>
</tr>
</table>
</body>
</html>
code:

let todos = null;
let name = 'to-do';
if (data) {
if (data > 1) {
name = 'to-dos';
}
} else {
}
}
getData();
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}
const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
alert('here');
},
getData();
}
});
}
$.ajax({
type: 'DELETE',
getData();
}
});
}
}
});
}
const item = {
const item = {
};
$.ajax({
type: 'PUT',
getData();
}
});
closeInput();
return false;
});
}
getData();
});
$.ajax({
type: 'GET',
url: uri,

});
todos = data;
}
});
}
Add a to -do item

const item = {
'isComplete': false
};
$.ajax({
type: 'POST',
url: uri,
alert('here');
},
getData();
}
});
}

PUT .
$.ajax({
type: 'PUT',
getData();
}
});

$.ajax({
type: 'DELETE',
getData();
}
});

Create
[HttpPost]
{
if (item == null)
{
}

}
[HttpPost]
{

}
Adds a Location header to the response. The Location header specifies the URI of the newly created to-do
item. See 10.2.2 201 Created.

{
if (item == null)
{
return NotFound();
}
return Ok(item);
}

{
if (item == null)
{
return NotFound();
}
return item;
}

Start the app.
Open Postman.
Click the Body tab.
{
"name":"walk dog",
"isComplete":true
}
TIP
Update
[HttpPut("{id}")]
{
{
}

if (todo == null)
{
return NotFound();
}
return NoContent();
}
[HttpPut("{id}")]
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}
Delete
{
if (todo == null)
{
return NotFound();
}
return NoContent();
}


Getting started
Debugging
Integrated terminal
Keyboard shortcuts
Next steps
Develop ASP.NET Core apps using a file watcher
By Rick Anderson and Victor Hurdugaci

dotnet watch is a tool that runs a .NET Core CLI command when source files change. For example, a file change
can trigger compilation, test execution, or deployment.
This tutorial uses an existing web API with two endpoints: one that returns a sum and one that returns a product.
The product method has a bug, which is fixed in this tutorial.
Download the sample app. It consists of two projects: WebApp (an ASP.NET Core web API) and WebAppTests
(unit tests for the web API).
In a command shell, navigate to the WebApp folder. Run the following command:
dotnet run
The console output shows messages similar to the following (indicating that the app is running and awaiting
requests):
$ dotnet run
Hosting environment: Development
Content root path: C:/Docs/aspnetcore/tutorials/dotnet-watch/sample/WebApp
Now listening on: http://localhost:5000
Application started. Press Ctrl+C to shut down.
In a web browser, navigate to http://localhost:<port number>/api/math/sum?a=4&b=5 . You should see the result of
9 .
Navigate to the product API ( http://localhost:<port number>/api/math/product?a=4&b=5 ). It returns 9 , not 20 as

you'd expect. That problem is fixed later in the tutorial.
Add dotnet watch to a project

The dotnet watch file watcher tool is included with version 2.1.300 of the .NET Core SDK. The following steps are
required when using an earlier version of the .NET Core SDK.
1. Add a Microsoft.DotNet.Watcher.Tools package reference to the .csproj file:
<ItemGroup>
<DotNetCliToolReference Include="Microsoft.DotNet.Watcher.Tools" Version="2.0.0" />
</ItemGroup>
2. Install the Microsoft.DotNet.Watcher.Tools package by running the following command:
dotnet restore
Run .NET Core CLI commands using dotnet watch

Any .NET Core CLI command can be run with dotnet watch . For example:
COMMAND COMMAND WITH WATCH
dotnet run dotnet watch run
dotnet run -f netcoreapp2.0 dotnet watch run -f netcoreapp2.0
dotnet run -f netcoreapp2.0 -- --arg1 dotnet watch run -f netcoreapp2.0 -- --arg1
dotnet test dotnet watch test
Run dotnet watch run in the WebApp folder. The console output indicates watch has started.
Make changes with dotnet watch

Make sure dotnet watch is running.
Fix the bug in the Product method of MathController.cs so it returns the product and not the sum:
public static int Product(int a, int b)

{
return a * b;
}
Save the file. The console output indicates that dotnet watch detected a file change and restarted the app.
Verify http://localhost:<port number>/api/math/product?a=4&b=5 returns the correct result.
Run tests using dotnet watch

1. Change the Product method of MathController.cs back to returning the sum. Save the file.
2. In a command shell, navigate to the WebAppTests folder.
3. Run dotnet restore.
4. Run dotnet watch test . Its output indicates that a test failed and that the watcher is awaiting file changes:
Total tests: 2. Passed: 1. Failed: 1. Skipped: 0.

Test Run Failed.
5. Fix the Product method code so it returns the product. Save the file.
dotnet watch detects the file change and reruns the tests. The console output indicates the tests passed.
Customize files list to watch

By default, dotnet-watch tracks all files matching the following glob patterns:
**/*.cs
*.csproj
**/*.resx
More items can be added to the watch list by editing the .csproj file. Items can be specified individually or by using
glob patterns.
<ItemGroup>

<Watch Include="**\*.js" Exclude="node_modules\**\*;**\*.js.map;obj\**\*;bin\**\*" />
</ItemGroup>
Opt-out of files to be watched

dotnet-watch can be configured to ignore its default settings. To ignore specific files, add the Watch="false"
attribute to an item's definition in the .csproj file:
<ItemGroup>

<Compile Include="Generated.cs" Watch="false" />


<EmbeddedResource Include="Strings.resx" Watch="false" />


<ProjectReference Include="..\ClassLibrary1\ClassLibrary1.csproj" Watch="false" />
</ItemGroup>
Custom watch projects

dotnet-watch isn't restricted to C# projects. Custom watch projects can be created to handle different scenarios.
Consider the following project layout:
test/
UnitTests/UnitTests.csproj
IntegrationTests/IntegrationTests.csproj
If the goal is to watch both projects, create a custom project file configured to watch both projects:
<Project>
<ItemGroup>
<TestProjects Include="**\*.csproj" />
<Watch Include="**\*.cs" />
</ItemGroup>
<Target Name="Test">
<MSBuild Targets="VSTest" Projects="@(TestProjects)" />
</Target>
<Import Project="$(MSBuildExtensionsPath)\Microsoft.Common.targets" />

</Project>
To start file watching on both projects, change to the test folder. Execute the following command:
dotnet watch msbuild /t:Test
VSTest executes when any file changes in either test project.
dotnet-watch in GitHub
dotnet-watch is part of the GitHub DotNetTools repository.
ASP.NET Core
By Steve Smith

Features
well (5000). In order to test that your services work with a device, ensure you don't have an active firewall blocking
access to this port.




.UseKestrel()
.Build();
NOTE
Studio toolbar.
{
{
[Required]
[Required]
[Required]

}
}
{
{
}
}
using System.Linq;
{
{
{
InitializeData();
}

{
}

{
}

{
}

{
}

{
}

{
}

{

{
Done = true
};

{
ID = "b94afb54-a1cb-4313-8af3-b7511551b33b",
Done = false
};

{
Done = false,
};
}
}
}

{
services.AddMvc();
}
TIP

using System;
{
{

{
}
Reading Items
[HttpGet]
{
}
Creating Items
[HttpPost] attribute applied to it, and accepts a ToDoItem instance. Since the item argument will be passed in the
body of the POST, this parameter is decorated with the [FromBody] attribute.
added using the repository. Checking ModelState.IsValid performs model validation, and should be done in every
API method that accepts user input.
[HttpPost]
{
try
{
{
}
if (itemExists)
{
}
}
catch (Exception)
{
}
return Ok(item);
}

{
TodoItemIDInUse,
RecordNotFound,
CouldNotCreateItem,
CouldNotUpdateItem,
CouldNotDeleteItem
}
Updating Items
Modifying records is done using HTTP PUT requests. Other than this change, the Edit method is almost identical
to Create . Note that if the record isn't found, the Edit action will return a NotFound (404) response.
[HttpPut]
{
try
{
{
}
{
}
}
catch (Exception)
{
}
return NoContent();
}
Deleting Items
{
try
{
if (item == null)
{
}
}
catch (Exception)
{
}
return NoContent();
}

As you develop the backend services for your app, you will want to come up with a consistent set of conventions or
policies for handling cross-cutting concerns. For example, in the service shown above, requests for specific records
that weren't found received a NotFound response, rather than a BadRequest response. Similarly, commands made
to this service that passed in model bound types always checked ModelState.IsValid and returned a BadRequest
for invalid model types.
ASP.NET Core fundamentals
An ASP.NET Core app is a console app that creates a web server in its Main method:

{
{
CreateWebHostBuilder(args).Build().Run();
}

}
The Main method invokes WebHost.CreateDefaultBuilder, which follows the builder pattern to create a web host.
The builder has methods that define the web server (for example, UseKestrel) and the startup class ( UseStartup).
In the preceding example, the Kestrel web server is automatically allocated. ASP.NET Core's web host attempts to
run on IIS, if available. Other web servers, such as HTTP.sys, can be used by invoking the appropriate extension
method. UseStartup is explained further in the next section.
IWebHostBuilder, the return type of the WebHost.CreateDefaultBuilder invocation, provides many optional
methods. Some of these methods include UseHttpSys for hosting the app in HTTP.sys and UseContentRoot for
specifying the root content directory. The Build and Run methods build the IWebHost object that hosts the app
and begins listening for HTTP requests.

{
{
.UseKestrel()
.Build();
host.Run();
}
}
The Main method uses WebHostBuilder, which follows the builder pattern to create a web app host. The builder
has methods that define the web server (for example, UseKestrel) and the startup class ( UseStartup). In the
preceding example, the Kestrel web server is used. Other web servers, such as WebListener, can be used by
invoking the appropriate extension method. UseStartup is explained further in the next section.
WebHostBuilder provides many optional methods, including UseIISIntegration for hosting in IIS and IIS Express
and UseContentRoot for specifying the root content directory. The Build and Run methods build the IWebHost
object that hosts the app and begins listening for HTTP requests.
Startup
The UseStartup method on WebHostBuilder specifies the Startup class for your app:
{
{
}

}

{
{
.UseKestrel()
.Build();
host.Run();
}
}
The Startup class is where you define the request handling pipeline and where any services needed by the app
are configured. The Startup class must be public and contain the following methods:

{
// This method gets called by the runtime. Use this method
// to add services to the container.
{
}

// to configure the HTTP request pipeline.
{
}
}

{
// to add services to the container.
{
}

// to configure the HTTP request pipeline.
{
}
}
ConfigureServices defines the Services used by your app (for example, ASP.NET Core MVC, Entity Framework
Core, Identity). Configure defines the middleware called in the request pipeline.
For more information, see Application startup in ASP.NET Core.
Content root
The content root is the base path to any content used by the app, such as Razor Pages, MVC views, and static
assets. By default, the content root is the same location as the app base path for the executable hosting the app.
Web root
The web root of an app is the directory in the project containing public, static resources, such as CSS, JavaScript,
and image files.
Dependency injection (services)

A service is a component that's intended for common consumption in an app. Services are made available through
dependency injection (DI). ASP.NET Core includes a native Inversion of Control (IoC ) container that supports
constructor injection by default. You can replace the default container if you wish. In addition to its loose coupling
benefit, DI makes services, such as logging, available throughout your app.
For more information, see Dependency injection in ASP.NET Core.
Middleware
In ASP.NET Core, you compose your request pipeline using middleware. ASP.NET Core middleware performs
asynchronous operations on an HttpContext and then either invokes the next middleware in the pipeline or
terminates the request.
By convention, a middleware component called "XYZ" is added to the pipeline by invoking a UseXYZ extension
method in the Configure method.
ASP.NET Core includes a rich set of built-in middleware, and you can write your own custom middleware. Open
Web Interface for .NET (OWIN ), which allows web apps to be decoupled from web servers, is supported in
ASP.NET Core apps.
For more information, see ASP.NET Core Middleware and Open Web Interface for .NET (OWIN ) with ASP.NET
Core.

IHttpClientFactory is available to access HttpClient instances to make HTTP requests.
For more information, see Initiate HTTP requests.
Environments
Environments, such as Development and Production, are a first-class notion in ASP.NET Core and can be set
using an environment variable, settings file, and command-line argument.
For more information, see Use multiple environments in ASP.NET Core.
Hosting
ASP.NET Core apps configure and launch a host, which is responsible for app startup and lifetime management.
For more information, see Host in ASP.NET Core.
Servers
The ASP.NET Core hosting model doesn't directly listen for requests. The hosting model relies on an HTTP server
implementation to forward the request to the app. The forwarded request is wrapped as a set of feature objects
that can be accessed through interfaces. ASP.NET Core includes a managed, cross-platform web server, called
Kestrel. Kestrel is commonly run behind a production web server, such as IIS or Nginx in a reverse proxy
configuration. Kestrel can also be run as an edge server exposed directly to the Internet in ASP.NET Core 2.0 or
later.
For more information, see Web server implementations in ASP.NET Core.
Configuration
ASP.NET Core uses a configuration model based on name-value pairs. The configuration model isn't based on
System.Configuration or web.config. Configuration obtains settings from an ordered set of configuration
providers. The built-in configuration providers support a variety of file formats (XML, JSON, INI), environment
variables, and command-line arguments. You can also write your own custom configuration providers.
For more information, see Configuration in ASP.NET Core.
Logging
ASP.NET Core supports a Logging API that works with a variety of logging providers. Built-in providers support
sending logs to one or more destinations. Third-party logging frameworks can be used.
For more information, see Logging in ASP.NET Core.
Error handling
ASP.NET Core has built-in scenarios for handling errors in apps, including a developer exception page, custom
error pages, static status code pages, and startup exception handling.
For more information, see Handle errors in ASP.NET Core.
Routing
ASP.NET Core offers scenarios for routing of app requests to route handlers.
For more information, see Routing in ASP.NET Core.
File Providers
ASP.NET Core abstracts file system access through the use of File Providers, which offers a common interface for
working with files across platforms.
For more information, see File Providers in ASP.NET Core.
Static files
Static Files Middleware serves static files, such as HTML, CSS, image, and JavaScript files.
For more information, see Static files in ASP.NET Core.
Session and app state

ASP.NET Core offers several approaches to preserve session and app state while a user browses a web app.
For more information, see Session and app state in ASP.NET Core.

Creating a multilingual website with ASP.NET Core allows your site to reach a wider audience. ASP.NET Core
provides services and middleware for localizing content into different languages and cultures.
For more information, see Globalization and localization in ASP.NET Core.
Request features
Web server implementation details related to HTTP requests and responses are defined in interfaces. These
interfaces are used by server implementations and middleware to create and modify the app's hosting pipeline.
For more information, see Request Features in ASP.NET Core.
Background tasks
Background tasks are implemented as hosted services. A hosted service is a class with background task logic that
implements the IHostedService interface.
For more information, see Background tasks with hosted services in ASP.NET Core.
Access HttpContext
HttpContext is automatically available when processing requests with Razor Pages and MVC. In circumstances
where HttpContext isn't readily available, you can access the HttpContext through the IHttpContextAccessor
interface and its default implementation, HttpContextAccessor.
For more information, see Access HttpContext in ASP.NET Core.
WebSockets
WebSocket is a protocol that enables two-way persistent communication channels over TCP connections. It's used
for apps such as chat, stock tickers, games, and anywhere you desire real-time functionality in a web app.
ASP.NET Core supports web socket scenarios.
For more information, see WebSockets support in ASP.NET Core.
Microsoft.AspNetCore.App metapackage
The Microsoft.AspNetCore.App metapackage simplifies package management.
For more information, see Microsoft.AspNetCore.App metapackage for ASP.NET Core 2.1 and later.
Microsoft.AspNetCore.All metapackage
The Microsoft.AspNetCore.All metapackage for ASP.NET Core includes:
All supported packages by the ASP.NET Core team.
All supported packages by Entity Framework Core.
Internal and 3rd-party dependencies used by ASP.NET Core and Entity Framework Core.
For more information, see Microsoft.AspNetCore.All metapackage for ASP.NET Core 2.0.
.NET Core vs. .NET Framework runtime

An ASP.NET Core app can target the .NET Core or .NET Framework runtime.
For more information, see Choosing between .NET Core and .NET Framework.
Choose between ASP.NET Core and ASP.NET

For more information on choosing between ASP.NET Core and ASP.NET, see Choose between ASP.NET and
ASP.NET Core.
Application startup in ASP.NET Core
By Steve Smith, Tom Dykstra, and Luke Latham

The Startup class configures services and the app's request pipeline.
The Startup class

ASP.NET Core apps use a Startup class, which is named Startup by convention. The Startup class:
Can optionally include a ConfigureServices method to configure the app's services.
Must include a Configure method to create the app's request processing pipeline.
ConfigureServices and Configure are called by the runtime when the app starts:

{
// Use this method to add services to the container.
{
...
}
// Use this method to configure the HTTP request pipeline.

{
...
}
}
Specify the Startup class with the WebHostBuilderExtensions UseStartup<TStartup> method:

{
{
}

}
The web host provides some services that are available to the Startup class constructor. The app adds
additional services via ConfigureServices . Both the host and app services are then available in Configure and
throughout the app.
A common use of dependency injection into the Startup class is to inject:
IHostingEnvironment to configure services by environment.
IConfiguration to read configuration.
ILoggerFactory to create a logger in Startup.ConfigureServices .
{
private readonly IHostingEnvironment _env;
private readonly IConfiguration _config;
private readonly ILoggerFactory _loggerFactory;
public Startup(IHostingEnvironment env, IConfiguration config,

ILoggerFactory loggerFactory)
{
_env = env;
_config = config;
_loggerFactory = loggerFactory;
}

{
var logger = _loggerFactory.CreateLogger<Startup>();
if (_env.IsDevelopment())
{
// Development service configuration
logger.LogInformation("Development environment");
}
else
{
// Non-development service configuration
logger.LogInformation($"Environment: {_env.EnvironmentName}");
}
// Configuration is available during startup.

// Examples:
// _config["key"]
// _config["subsection:suboption1"]
}
}
An alternative to injecting IHostingEnvironment is to use a conventions-based approach. The app can define
separate Startup classes for different environments (for example, StartupDevelopment ), and the appropriate
Startup class is selected at runtime. The class whose name suffix matches the current environment is
prioritized. If the app is run in the Development environment and includes both a Startup class and a
StartupDevelopment class, the StartupDevelopment class is used. For more information, see Use multiple
environments.
To learn more about WebHostBuilder , see the Hosting topic. For information on handling errors during startup,
see Startup exception handling.
The ConfigureServices method

The ConfigureServices method is:
Optional
Called by the web host before the Configure method to configure the app's services.
Where configuration options are set by convention.
The typical pattern is to call all the Add{Service} methods, and then call all the services.Configure{Service}
methods. For example, see Configure Identity services.
Adding services to the service container makes them available within the app and in the Configure method.
The services are resolved via dependency injection or from IApplicationBuilder.ApplicationServices.
The web host may configure some services before Startup methods are called. Details are available in the Host
in ASP.NET Core topic.
For features that require substantial setup, there are Add[Service] extension methods on IServiceCollection. A
typical web app registers services for Entity Framework, Identity, and MVC:

{
services.AddDbContext<ApplicationDbContext>(options =>
services.AddIdentity<ApplicationUser, IdentityRole>()
.AddEntityFrameworkStores<ApplicationDbContext>()
.AddDefaultTokenProviders();
services.AddMvc();
// Add application services.

services.AddTransient<IEmailSender, AuthMessageSender>();
services.AddTransient<ISmsSender, AuthMessageSender>();
}
The Configure method

The Configure method is used to specify how the app responds to HTTP requests. The request pipeline is
configured by adding middleware components to an IApplicationBuilder instance. IApplicationBuilder is
available to the Configure method, but it isn't registered in the service container. Hosting creates an
IApplicationBuilder and passes it directly to Configure .
The ASP.NET Core templates configure the pipeline with support for a developer exception page, BrowserLink,
error pages, static files, and ASP.NET Core MVC:

{
{
app.UseBrowserLink();
}
else
{
}
{
routes.MapRoute(
name: "default",
template: "{controller}/{action=Index}/{id?}");
});
}
Each Use extension method adds a middleware component to the request pipeline. For instance, the UseMvc
extension method adds the Routing Middleware to the request pipeline and configures MVC as the default
handler.
Each middleware component in the request pipeline is responsible for invoking the next component in the
pipeline or short-circuiting the chain, if appropriate. If short-circuiting doesn't occur along the middleware chain,
each middleware has a second chance to process the request before it's sent to the client.
Additional services, such as IHostingEnvironment and ILoggerFactory , may also be specified in the method
signature. When specified, additional services are injected if they're available.
For more information on how to use IApplicationBuilder and the order of middleware processing, see
Middleware.
Convenience methods
ConfigureServices and Configure convenience methods can be used instead of specifying a Startup class.
Multiple calls to ConfigureServices append to one another. Multiple calls to Configure use the last method call.

{
public static IHostingEnvironment HostingEnvironment { get; set; }
public static IConfiguration Configuration { get; set; }

{
}

.ConfigureAppConfiguration((hostingContext, config) =>
{
HostingEnvironment = hostingContext.HostingEnvironment;
Configuration = config.Build();
})
.ConfigureServices(services =>
{
services.AddMvc();
})
.Configure(app =>
{
var loggerFactory = app.ApplicationServices
.GetRequiredService<ILoggerFactory>();
var logger = loggerFactory.CreateLogger<Program>();
logger.LogInformation("Logged in Configure");
if (HostingEnvironment.IsDevelopment())
{
}
else
{
}
// Configuration is available during startup. Examples:

// Configuration["key"]
// Configuration["subsection:suboption1"]
app.UseMvcWithDefaultRoute();
});
}
Extend Startup with startup filters

Use IStartupFilter to configure middleware at the beginning or end of an app's Configure middleware pipeline.
IStartupFilter is useful to ensure that a middleware runs before or after middleware added by libraries at the
start or end of the app's request processing pipeline.
IStartupFilter implements a single method, Configure, which receives and returns an
Action<IApplicationBuilder> . An IApplicationBuilder defines a class to configure an app's request pipeline. For
more information, see Create a middleware pipeline with IApplicationBuilder.
Each IStartupFilter implements one or more middlewares in the request pipeline. The filters are invoked in
the order they were added to the service container. Filters may add middleware before or after passing control
to the next filter, thus they append to the beginning or end of the app pipeline.
The sample app (how to download) demonstrates how to register a middleware with IStartupFilter . The
sample app includes a middleware that sets an options value from a query string parameter:
public class RequestSetOptionsMiddleware

{
private readonly RequestDelegate _next;
private IOptions<AppOptions> _injectedOptions;
public RequestSetOptionsMiddleware(
RequestDelegate next, IOptions<AppOptions> injectedOptions)
{
_next = next;
_injectedOptions = injectedOptions;
}
public async Task Invoke(HttpContext httpContext)

{
Console.WriteLine("RequestSetOptionsMiddleware.Invoke");
var option = httpContext.Request.Query["option"];
if (!string.IsNullOrWhiteSpace(option))
{
_injectedOptions.Value.Option = WebUtility.HtmlEncode(option);
}
await _next(httpContext);
}
}
The RequestSetOptionsMiddleware is configured in the RequestSetOptionsStartupFilter class:
public class RequestSetOptionsStartupFilter : IStartupFilter

{
public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
{
return builder =>
{
builder.UseMiddleware<RequestSetOptionsMiddleware>();
next(builder);
};
}
}
The IStartupFilter is registered in the service container in IWebHostBuilder.ConfigureServices to

demonstrate how the startup filter augments Startup from outside of the Startup class:
.ConfigureServices(services =>
{
services.AddTransient<IStartupFilter,
RequestSetOptionsStartupFilter>();
})
.Build();
When a query string parameter for option is provided, the middleware processes the value assignment before
the MVC middleware renders the response:
Middleware execution order is set by the order of IStartupFilter registrations:

Multiple IStartupFilter implementations may interact with the same objects. If ordering is important, order
their IStartupFilter service registrations to match the order that their middlewares should run.
Libraries may add middleware with one or more IStartupFilter implementations that run before or after
other app middleware registered with IStartupFilter . To invoke an IStartupFilter middleware before a
middleware added by a library's IStartupFilter , position the service registration before the library is added
to the service container. To invoke it afterward, position the service registration after the library is added.
Add configuration at startup from an external assembly

An IHostingStartup implementation allows adding enhancements to an app at startup from an external
assembly outside of the app's Startup class. For more information, see Enhance an app from an external
assembly.
Host in ASP.NET Core
Use multiple environments in ASP.NET Core
ASP.NET Core Middleware
Logging in ASP.NET Core
Configuration in ASP.NET Core
Dependency injection in ASP.NET Core
By Steve Smith, Scott Addie, and Luke Latham

ASP.NET Core supports the dependency injection (DI) software design pattern, which is a
technique for achieving Inversion of Control (IoC ) between classes and their dependencies.
For more information specific to dependency injection within MVC controllers, see
Dependency injection into controllers in ASP.NET Core.
Overview of dependency injection

A dependency is any object that another object requires. Examine the following MyDependency
class with a WriteMessage method that other classes in an app depend upon:
public class MyDependency

{
public MyDependency()
{
}
public Task WriteMessage(string message)

{
Console.WriteLine(
$"MyDependency.WriteMessage called. Message: {message}");
return Task.FromResult(0);
}
}
An instance of the MyDependency class can be created to make the WriteMessage method
available to a class. The MyDependency class is a dependency of the IndexModel class:

{
MyDependency _dependency = new MyDependency();

{
await _dependency.WriteMessage(
"IndexModel.OnGetAsync created this message.");
}
}
An instance of the MyDependency class can be created to make the WriteMessage method
available to a class. The MyDependency class is a dependency of the HomeController class:
{
MyDependency _dependency = new MyDependency();

{
await _dependency.WriteMessage(
"HomeController.Index created this message.");
return View();
}
}
The class creates and directly depends on the MyDependency instance. Code dependencies (such
as the previous example) are problematic and should be avoided for the following reasons:
To replace MyDependency with a different implementation, the class must be modified.
If MyDependency has dependencies, they must be configured by the class. In a large project
with multiple classes depending on MyDependency , the configuration code becomes
scattered across the app.
This implementation is difficult to unit test. The app should use a mock or stub
MyDependency class, which isn't possible with this approach.
Dependency injection addresses these problems through:

The use of an interface to abstract the dependency implementation.
Registration of the dependency in a service container. ASP.NET Core provides a built-in
service container, IServiceProvider. Services are registered in the app's
Startup.ConfigureServices method.
Injection of the service into the constructor of the class where it's used. The framework
takes on the responsibility of creating an instance of the dependency and disposing of it
when it's no longer needed.
In the sample app, the IMyDependency interface defines a method that the service provides to
the app:
public interface IMyDependency

{
Task WriteMessage(string message);
}
public interface IMyDependency

{
Task WriteMessage(string message);
}
This interface is implemented by a concrete type, MyDependency :

public class MyDependency : IMyDependency
{
private readonly ILogger<MyDependency> _logger;
public MyDependency(ILogger<MyDependency> logger)

{
_logger = logger;
}

{
_logger.LogInformation(
"MyDependency.WriteMessage called. Message: {MESSAGE}",
message);
}
}

{
private readonly ILogger<MyDependency> _logger;
public MyDependency(ILogger<MyDependency> logger)

{
_logger = logger;
}

{
"MyDependency.WriteMessage called. Message: {MESSAGE}",
message);
}
}
MyDependency requests an ILogger<TCategoryName> in its constructor. It's not unusual to use

dependency injection in a chained fashion. Each requested dependency in turn requests its own
dependencies. The container resolves the dependencies in the graph and returns the fully
resolved service. The collective set of dependencies that must be resolved is typically referred
to as a dependency tree, dependency graph, or object graph.
IMyDependency and ILogger<TCategoryName> must be registered in the service container.
IMyDependency is registered in Startup.ConfigureServices . ILogger<TCategoryName> is
registered by the logging abstractions infrastructure, so it's a framework-provided service
registered by default by the framework.
In the sample app, the IMyDependency service is registered with the concrete type
MyDependency . The registration scopes the service lifetime to the lifetime of a single request.
Service lifetimes are described later in this topic.
{
{
});
services.AddScoped<IMyDependency, MyDependency>();
services.AddTransient<IOperationTransient, Operation>();
services.AddScoped<IOperationScoped, Operation>();
services.AddSingleton<IOperationSingleton, Operation>();
services.AddSingleton<IOperationSingletonInstance>(new Operation(Guid.Empty));
// OperationService depends on each of the other Operation types.

services.AddTransient<OperationService, OperationService>();
}

{
services.AddMvc();

}
NOTE
Each services.Add{SERVICE_NAME} extension method adds (and potentially configures) services. For
example, services.AddMvc() adds the services Razor Pages and MVC require. We recommended
that apps follow this convention. Place extension methods in the
Microsoft.Extensions.DependencyInjection namespace to encapsulate groups of service registrations.
If the service's constructor requires a primitive, such as a string , the primitive can be injected
by using configuration or the options pattern:

{
public MyDependency(IConfiguration config)
{
var myStringValue = config["MyStringKey"];
// Use myStringValue
}
...
}
An instance of the service is requested via the constructor of a class where the service is used
and assigned to a private field. The field is used to access the service as necessary throughout
the class.
In the sample app, the IMyDependency instance is requested and used to call the service's
WriteMessage method:

{
private readonly IMyDependency _myDependency;
public IndexModel(
IMyDependency myDependency,
OperationService operationService,
IOperationTransient transientOperation,
IOperationScoped scopedOperation,
IOperationSingleton singletonOperation,
IOperationSingletonInstance singletonInstanceOperation)
{
_myDependency = myDependency;
OperationService = operationService;
TransientOperation = transientOperation;
ScopedOperation = scopedOperation;
SingletonOperation = singletonOperation;
SingletonInstanceOperation = singletonInstanceOperation;
}
public OperationService OperationService { get; }

public IOperationTransient TransientOperation { get; }
public IOperationScoped ScopedOperation { get; }
public IOperationSingleton SingletonOperation { get; }
public IOperationSingletonInstance SingletonInstanceOperation { get; }

{
await _myDependency.WriteMessage(
}
}
public class MyDependencyController : Controller

{
public MyDependencyController(IMyDependency myDependency)

{
}
// GET: /mydependency/
{
"MyDependencyController.Index created this message.");
return View();
}
}
Framework-provided services
The Startup.ConfigureServices method is responsible for defining the services the app uses,
including platform features, such as Entity Framework Core and ASP.NET Core MVC. Initially,
the IServiceCollection provided to ConfigureServices has the following services defined
(depending on how the host was configured):
SERVICE TYPE LIFETIME
Microsoft.AspNetCore.Hosting.Builder.IApplication Transient
BuilderFactory
Microsoft.AspNetCore.Hosting.IApplicationLifetime Singleton
Microsoft.AspNetCore.Hosting.IHostingEnvironme Singleton
nt
Microsoft.AspNetCore.Hosting.IStartup Singleton
Microsoft.AspNetCore.Hosting.IStartupFilter Transient
Microsoft.AspNetCore.Hosting.Server.IServer Singleton
Microsoft.AspNetCore.Http.IHttpContextFactory Transient
Microsoft.Extensions.Logging.ILogger<T> Singleton
Microsoft.Extensions.Logging.ILoggerFactory Singleton
Microsoft.Extensions.ObjectPool.ObjectPoolProvide Singleton
r
Microsoft.Extensions.Options.IConfigureOptions<T Transient
>
Microsoft.Extensions.Options.IOptions<T> Singleton
System.Diagnostics.DiagnosticSource Singleton
System.Diagnostics.DiagnosticListener Singleton
When a service collection extension method is available to register a service (and its dependent
services, if required), the convention is to use a single Add{SERVICE_NAME} extension method to
register all of the services required by that service. The following code is an example of how to
add additional services to the container using the extension methods AddDbContext,
AddIdentity, and AddMvc:

{
services.AddMvc();
}
For more information, see the ServiceCollection Class in the API documentation.
Service lifetimes
Choose an appropriate lifetime for each registered service. ASP.NET Core services can be
configured with the following lifetimes:
Transient
Transient lifetime services are created each time they're requested. This lifetime works best for
lightweight, stateless services.
Scoped
Scoped lifetime services are created once per request.
WARNING
When using a scoped service in a middleware, inject the service into the Invoke or InvokeAsync
method. Don't inject via constructor injection because it forces the service to behave like a singleton.
For more information, see ASP.NET Core Middleware.
Singleton
Singleton lifetime services are created the first time they're requested (or when
ConfigureServices is run and an instance is specified with the service registration). Every
subsequent request uses the same instance. If the app requires singleton behavior, allowing the
service container to manage the service's lifetime is recommended. Don't implement the
singleton design pattern and provide user code to manage the object's lifetime in the class.
WARNING
It's dangerous to resolve a scoped service from a singleton. It may cause the service to have incorrect
state when processing subsequent requests.
Constructor injection behavior

Services can be resolved by two mechanisms:
IServiceProvider
ActivatorUtilities – Permits object creation without service registration in the dependency
injection container. ActivatorUtilities is used with user-facing abstractions, such as Tag
Helpers, MVC controllers, and model binders.
Constructors can accept arguments that aren't provided by dependency injection, but the
arguments must assign default values.
When services are resolved by IServiceProvider or ActivatorUtilities , constructor injection
requires a public constructor.
When services are resolved by ActivatorUtilities , constructor injection requires that only
one applicable constructor exist. Constructor overloads are supported, but only one overload
can exist whose arguments can all be fulfilled by dependency injection.
Entity Framework contexts

Entity Framework contexts should be added to the service container using the scoped lifetime.
This is handled automatically with a call to the AddDbContext method when registering the
database context. Services that use the database context should also use the scoped lifetime.
Lifetime and registration options
To demonstrate the difference between the lifetime and registration options, consider the
following interfaces that represent tasks as an operation with a unique identifier, OperationId .
Depending on how the lifetime of an operations service is configured for the following
interfaces, the container provides either the same or a different instance of the service when
requested by a class:
public interface IOperation

{
Guid OperationId { get; }
}
public interface IOperationTransient : IOperation

{
}
public interface IOperationScoped : IOperation

{
}
public interface IOperationSingleton : IOperation

{
}
public interface IOperationSingletonInstance : IOperation

{
}
public interface IOperation

{
Guid OperationId { get; }
}
public interface IOperationTransient : IOperation

{
}
public interface IOperationScoped : IOperation

{
}
public interface IOperationSingleton : IOperation

{
}
public interface IOperationSingletonInstance : IOperation

{
}
The interfaces are implemented in the Operation class. The Operation constructor generates a
GUID if one isn't supplied:
public class Operation : IOperationTransient,
IOperationScoped,
IOperationSingleton,
IOperationSingletonInstance
{
public Operation() : this(Guid.NewGuid())
{
}
public Operation(Guid id)

{
OperationId = id;
}
public Guid OperationId { get; private set; }

}
public class Operation : IOperationTransient,

IOperationScoped,
IOperationSingleton,
IOperationSingletonInstance
{
public Operation() : this(Guid.NewGuid())
{
}
public Operation(Guid id)

{
OperationId = id;
}
public Guid OperationId { get; private set; }

}
An is registered that depends on each of the other Operation types. When

OperationService
OperationService is requested via dependency injection, it receives either a new instance of
each service or an existing instance based on the lifetime of the dependent service.
If transient services are created when requested, the OperationsId of the
IOperationTransient service is different than the OperationsId of the OperationService .
OperationService receives a new instance of the IOperationTransient class. The new
instance yields a different OperationsId .
If scoped services are created per request, the OperationsId of the IOperationScoped
service is the same as that of OperationService within a request. Across requests, both
services share a different OperationsId value.
If singleton and singleton-instance services are created once and used across all requests
and all services, the OperationsId is constant across all service requests.
public class OperationService
{
public OperationService(
IOperationSingletonInstance instanceOperation)
{
SingletonInstanceOperation = instanceOperation;
}

}
public class OperationService

{
public OperationService(IOperationTransient transientOperation,
IOperationSingletonInstance instanceOperation)
{
SingletonInstanceOperation = instanceOperation;
}

}
In Startup.ConfigureServices , each type is added to the container according to its named

lifetime:

{
{
});

}
{
services.AddMvc();

}
The IOperationSingletonInstance service is using a specific instance with a known ID of

Guid.Empty . It's clear when this type is in use (its GUID is all zeroes).
The sample app demonstrates object lifetimes within and between individual requests. The
sample app's IndexModel requests each kind of IOperation type and the OperationService .
The page then displays all of the page model class's and service's OperationId values through
property assignments:

{
public IndexModel(
IMyDependency myDependency,
{
OperationService = operationService;
SingletonInstanceOperation = singletonInstanceOperation;
}
public OperationService OperationService { get; }


{
}
}
The sample app demonstrates object lifetimes within and between individual requests. The
sample app includes an OperationsController that requests each kind of IOperation type and
the OperationService . The Index action sets the services into the ViewBag for display of the
service's OperationId values:
public class OperationsController : Controller
{
private readonly OperationService _operationService;
private readonly IOperationTransient _transientOperation;
private readonly IOperationScoped _scopedOperation;
private readonly IOperationSingleton _singletonOperation;
private readonly IOperationSingletonInstance _singletonInstanceOperation;
public OperationsController(
{
_operationService = operationService;
_transientOperation = transientOperation;
_scopedOperation = scopedOperation;
_singletonOperation = singletonOperation;
_singletonInstanceOperation = singletonInstanceOperation;
}

{
// Viewbag contains controller-requested services.
ViewBag.Transient = _transientOperation;
ViewBag.Scoped = _scopedOperation;
ViewBag.Singleton = _singletonOperation;
ViewBag.SingletonInstance = _singletonInstanceOperation;
// Operation service has its own requested services.

ViewBag.Service = _operationService;
return View();
}
}
Two following output shows the results of two requests:

First request:
Controller operations:
Transient: d233e165-f417-469b-a866-1cf1935d2518
Scoped: 5d997e2d-55f5-4a64-8388-51c4e3a1ad19
Singleton: 01271bc1-9e31-48e7-8f7c-7261b040ded9
Instance: 00000000-0000-0000-0000-000000000000
OperationService operations:
Transient: c6b049eb-1318-4e31-90f1-eb2dd849ff64
Scoped: 5d997e2d-55f5-4a64-8388-51c4e3a1ad19
Instance: 00000000-0000-0000-0000-000000000000
Second request:
Controller operations:
Transient: b63bd538-0a37-4ff1-90ba-081c5138dda0
Scoped: 31e820c5-4834-4d22-83fc-a60118acb9f4
Instance: 00000000-0000-0000-0000-000000000000
OperationService operations:
Transient: c4cbacb8-36a2-436d-81c8-8c1b78808aaf
Scoped: 31e820c5-4834-4d22-83fc-a60118acb9f4
Instance: 00000000-0000-0000-0000-000000000000
Observe which of the OperationId values vary within a request and between requests:
Transient objects are always different. Note that the transient OperationId value for both
the first and second requests are different for both OperationService operations and across
requests. A new instance is provided to each service and request.
Scoped objects are the same within a request but different across requests.
Singleton objects are the same for every object and every request regardless of whether an
Operation instance is provided in ConfigureServices .
Call services from main

Create an IServiceScope with IServiceScopeFactory.CreateScope to resolve a scoped service
within the app's scope. This approach is useful to access a scoped service at startup to run
initialization tasks. The following example shows how to obtain a context for the
MyScopedService in Program.Main :

{
using (var serviceScope = host.Services.CreateScope())

{
var services = serviceScope.ServiceProvider;
try
{
var serviceContext = services.GetRequiredService<MyScopedService>();
// Use the context here
}
{
logger.LogError(ex, "An error occurred.");
}
}
host.Run();
}
Scope validation
When the app is running in the Development environment, the default service provider
performs checks to verify that:
Scoped services aren't directly or indirectly resolved from the root service provider.
Scoped services aren't directly or indirectly injected into singletons.
The root service provider is created when BuildServiceProvider is called. The root service
provider's lifetime corresponds to the app/server's lifetime when the provider starts with the
app and is disposed when the app shuts down.
Scoped services are disposed by the container that created them. If a scoped service is created
in the root container, the service's lifetime is effectively promoted to singleton because it's only
disposed by the root container when app/server is shut down. Validating service scopes
catches these situations when BuildServiceProvider is called.
For more information, see ASP.NET Core Web Host.
Request Services
The services available within an ASP.NET Core request from HttpContext are exposed
through the HttpContext.RequestServices collection.
Request Services represent the services configured and requested as part of the app. When the
objects specify dependencies, these are satisfied by the types found in RequestServices , not
ApplicationServices .
Generally, the app shouldn't use these properties directly. Instead, request the types that
classes require via class constructors and allow the framework inject the dependencies. This
yields classes that are easier to test (see the Test and debug topics).
NOTE
Prefer requesting dependencies as constructor parameters to accessing the RequestServices
collection.
Design services for dependency injection

Best practices are to:
Design services to use dependency injection to obtain their dependencies.
Avoid stateful, static method calls (a practice known as static cling).
Avoid direct instantiation of dependent classes within services. Direct instantiation couples
the code to a particular implementation.
By following the SOLID Principles of Object Oriented Design, app classes naturally tend to be
small, well-factored, and easily tested.
If a class seems to have too many injected dependencies, this is generally a sign that the class
has too many responsibilities and is violating the Single Responsibility Principle (SRP ).
Attempt to refactor the class by moving some of its responsibilities into a new class. Keep in
mind that Razor Pages page model classes and MVC controller classes should focus on UI
concerns. Business rules and data access implementation details should be kept in classes
appropriate to these separate concerns.
Disposal of services
The container calls Dispose for the IDisposable types it creates. If an instance is added to the
container by user code, it isn't disposed automatically.
// Services that implement IDisposable:
public class Service1 : IDisposable {}
public interface ISomeService {}

public class SomeServiceImplementation : ISomeService, IDisposable {}

{
// The container creates the following instances and disposes them automatically:
services.AddScoped<Service1>();
services.AddSingleton<Service2>();
services.AddSingleton<ISomeService>(sp => new SomeServiceImplementation());
// The container doesn't create the following instances, so it doesn't dispose of

// the instances automatically:
services.AddSingleton<Service3>(new Service3());
services.AddSingleton(new Service3());
}
NOTE
In ASP.NET Core 1.0, the container calls dispose on all IDisposable objects, including those it didn't
create.
Default service container replacement

The built-in service container is meant to serve the needs of the framework and most
consumer apps. We recommend using the built-in container unless you need a specific feature
that it doesn't support. Some of the features supported in 3rd party containers not found in the
built-in container:
Property injection
Injection based on name
Child containers
Custom lifetime management
Func<T> support for lazy initialization
See the Dependency Injection readme.md file for a list of some of the containers that support
adapters.
The following sample replaces the built-in container with Autofac:
Install the appropriate container package(s):
Autofac
Autofac.Extensions.DependencyInjection
Configure the container in Startup.ConfigureServices and return an IServiceProvider :
public IServiceProvider ConfigureServices(IServiceCollection services)
{
services.AddMvc();
// Add other framework services
// Add Autofac
var containerBuilder = new ContainerBuilder();
containerBuilder.RegisterModule<DefaultModule>();
containerBuilder.Populate(services);
var container = containerBuilder.Build();
return new AutofacServiceProvider(container);
}
To use a 3rd party container, Startup.ConfigureServices must return IServiceProvider .

Configure Autofac in DefaultModule :
public class DefaultModule : Module

{
protected override void Load(ContainerBuilder builder)
{
builder.RegisterType<CharacterRepository>().As<ICharacterRepository>();
}
}
At runtime, Autofac is used to resolve types and inject dependencies. To learn more about
using Autofac with ASP.NET Core, see the Autofac documentation.
Thread safety
Singleton services need to be thread safe. If a singleton service has a dependency on a
transient service, the transient service may also need to be thread safe depending how it's used
by the singleton.
The factory method of single service, such as the second argument to
AddSingleton<TService>(IServiceCollection, Func<IServiceProvider,TService>), doesn't need
to be thread-safe. Like a type ( static ) constructor, it's guaranteed to be called once by a single
thread.
Recommendations
When working with dependency injection, keep the following recommendations in mind:
Avoid storing data and configuration directly in the service container. For example, a
user's shopping cart shouldn't typically be added to the service container. Configuration
should use the options pattern. Similarly, avoid "data holder" objects that only exist to
allow access to some other object. It's better to request the actual item via dependency
injection, if possible.
Avoid static access to services (for example, statically-typing
IApplicationBuilder.ApplicationServices for use elsewhere).
Avoid using the service locator pattern (for example, IServiceProvider.GetService).
Avoid static access to HttpContext (for example, IHttpContextAccessor.HttpContext).
Like all sets of recommendations, you may encounter situations where ignoring a
recommendation is required. Exceptions are rare—mostly special cases within the framework
itself.
Dependency injection is an alternative to static/global object access patterns. You may not be
able to realize the benefits of dependency injection if you mix it with static object access.
Dependency injection into views in ASP.NET Core
Dependency injection into controllers in ASP.NET Core
Dependency injection in requirement handlers in ASP.NET Core
Repository pattern with ASP.NET Core
Test, debug, and troubleshoot in ASP.NET Core
Factory-based middleware activation in ASP.NET Core
Writing Clean Code in ASP.NET Core with Dependency Injection (MSDN )
Container-Managed Application Design, Prelude: Where does the Container Belong?
Explicit Dependencies Principle
Inversion of Control Containers and the Dependency Injection Pattern (Martin Fowler)
New is Glue ("gluing" code to a particular implementation)
How to register a service with multiple interfaces in ASP.NET Core DI
By Rick Anderson and Steve Smith

Middleware is software that's assembled into an app pipeline to handle requests and responses. Each component:
Chooses whether to pass the request to the next component in the pipeline.
Can perform work before and after the next component in the pipeline is invoked.
Request delegates are used to build the request pipeline. The request delegates handle each HTTP request.
Request delegates are configured using Run, Map, and Use extension methods. An individual request delegate can
be specified in-line as an anonymous method (called in-line middleware), or it can be defined in a reusable class.
These reusable classes and in-line anonymous methods are middleware, also called middleware components. Each
middleware component in the request pipeline is responsible for invoking the next component in the pipeline or
short-circuiting the pipeline.
Migrate HTTP handlers and modules to ASP.NET Core middleware explains the difference between request
pipelines in ASP.NET Core and ASP.NET 4.x and provides more middleware samples.
Create a middleware pipeline with IApplicationBuilder

The ASP.NET Core request pipeline consists of a sequence of request delegates, called one after the other. The
following diagram demonstrates the concept. The thread of execution follows the black arrows.
Each delegate can perform operations before and after the next delegate. A delegate can also decide to not pass a
request to the next delegate, which is called short-circuiting the request pipeline. Short-circuiting is often desirable
because it avoids unnecessary work. For example, Static Files Middleware can return a request for a static file and
short-circuit the rest of the pipeline. Exception-handling delegates are called early in the pipeline, so they can catch
exceptions that occur in later stages of the pipeline.
The simplest possible ASP.NET Core app sets up a single request delegate that handles all requests. This case
doesn't include an actual request pipeline. Instead, a single anonymous function is called in response to every HTTP
request.
{
{
app.Run(async context =>
{
await context.Response.WriteAsync("Hello, World!");
});
}
}
The first Run delegate terminates the pipeline.

Chain multiple request delegates together with Use. The next parameter represents the next delegate in the
pipeline. You can short-circuit the pipeline by not calling the next parameter. You can typically perform actions both
before and after the next delegate, as the following example demonstrates:

{
{
app.Use(async (context, next) =>
{
// Do work that doesn't write to the Response.
await next.Invoke();
// Do logging or other work that doesn't write to the Response.
});

{
await context.Response.WriteAsync("Hello from 2nd delegate.");
});
}
}
WARNING
Don't call next.Invoke after the response has been sent to the client. Changes to HttpResponse after the response has
started throw an exception. For example, changes such as setting headers and a status code throw an exception. Writing to
the response body after calling next :
May cause a protocol violation. For example, writing more than the stated Content-Length .
May corrupt the body format. For example, writing an HTML footer to a CSS file.
HasStarted is a useful hint to indicate if headers have been sent or the body has been written to.
Order
The order that middleware components are added in the Startup.Configure method defines the order in which the
middleware components are invoked on requests and the reverse order for the response. The order is critical for
security, performance, and functionality.
The following Startup.Configure method adds middleware components for common app scenarios:
1. Exception/error handling
2. HTTP Strict Transport Security Protocol
3. HTTPS redirection
4. Static file server
5. Cookie policy enforcement
6. Authentication
7. Session
8. MVC

{
{
// When the app runs in the Development environment:
// Use the Developer Exception Page to report app runtime errors.
// Use the Database Error Page to report database runtime errors.
app.UseDatabaseErrorPage();
}
else
{
// When the app doesn't run in the Development environment:
// Enable the Exception Handler Middleware to catch exceptions
// thrown in the following middlewares.
// Use the HTTP Strict Transport Security Protocol (HSTS)
// Middleware.
app.UseHsts();
}
// Use HTTPS Redirection Middleware to redirect HTTP requests to HTTPS.

// Return static files and end the pipeline.

// Use Cookie Policy Middleware to conform to EU General Data

// Protection Regulation (GDPR) regulations.
// Authenticate before the user accesses secure resources.

app.UseAuthentication();
// If the app uses session state, call Session Middleware after Cookie
// Policy Middleware and before MVC Middleware.
app.UseSession();
// Add MVC to the request pipeline.

app.UseMvc();
}
2. Static files
3. Authentication
4. Session
5. MVC
{
app.UseExceptionHandler("/Home/Error");

// Authenticate before you access secure resources.

app.UseIdentity();
// If the app uses session state, call UseSession before

// MVC Middleware.
app.UseSession();

}
In the preceding example code, each middleware extension method is exposed on IApplicationBuilder through the
Microsoft.AspNetCore.Builder namespace.
UseExceptionHandler is the first middleware component added to the pipeline. Therefore, the Exception Handler
Middleware catches any exceptions that occur in later calls.
Static Files Middleware is called early in the pipeline so that it can handle requests and short-circuit without going
through the remaining components. The Static Files Middleware provides no authorization checks. Any files served
by it, including those under wwwroot, are publicly available. For an approach to secure static files, see Static files in
ASP.NET Core.
If the request isn't handled by the Static Files Middleware, it's passed on to the Authentication Middleware
(UseAuthentication), which performs authentication. Authentication doesn't short-circuit unauthenticated requests.
Although Authentication Middleware authenticates requests, authorization (and rejection) occurs only after MVC
selects a specific Razor Page or MVC controller and action.
If the request isn't handled by Static Files Middleware, it's passed on to the Identity Middleware (UseIdentity),
which performs authentication. Identity doesn't short-circuit unauthenticated requests. Although Identity
authenticates requests, authorization (and rejection) occurs only after MVC selects a specific controller and action.
The following example demonstrates a middleware order where requests for static files are handled by Static Files
Middleware before Response Compression Middleware. Static files aren't compressed with this middleware order.
The MVC responses from UseMvcWithDefaultRoute can be compressed.

{
// Static files not compressed by Static Files Middleware.
app.UseResponseCompression();
}
Use, Run, and Map

Configure the HTTP pipeline using Use , Run , and Map . The Use method can short-circuit the pipeline (that is, if it
doesn't call a next request delegate). Run is a convention, and some middleware components may expose
Run[Middleware] methods that run at the end of the pipeline.
Map extensions are used as a convention for branching the pipeline. Map* branches the request pipeline based on
matches of the given request path. If the request path starts with the given path, the branch is executed.
{
private static void HandleMapTest1(IApplicationBuilder app)
{
{
await context.Response.WriteAsync("Map Test 1");
});
}

{
{
});
}

{
app.Map("/map1", HandleMapTest1);

{
await context.Response.WriteAsync("Hello from non-Map delegate. <p>");
});
}
}
The following table shows the requests and responses from http://localhost:1234 using the previous code.
REQUEST RESPONSE
localhost:1234 Hello from non-Map delegate.
localhost:1234/map1 Map Test 1
localhost:1234/map3 Hello from non-Map delegate.
When Mapis used, the matched path segment(s) are removed from HttpRequest.Path and appended to
HttpRequest.PathBase for each request.
MapWhen branches the request pipeline based on the result of the given predicate. Any predicate of type
Func<HttpContext, bool> can be used to map requests to a new branch of the pipeline. In the following example, a
predicate is used to detect the presence of a query string variable branch :
{
private static void HandleBranch(IApplicationBuilder app)
{
{
var branchVer = context.Request.Query["branch"];
await context.Response.WriteAsync($"Branch used = {branchVer}");
});
}

{
app.MapWhen(context => context.Request.Query.ContainsKey("branch"),
HandleBranch);

{
});
}
}
The following table shows the requests and responses from http://localhost:1234 using the previous code.
REQUEST RESPONSE
localhost:1234/?branch=master Branch used = master
Map supports nesting, for example:
app.Map("/level1", level1App => {

level1App.Map("/level2a", level2AApp => {
// "/level1/level2a" processing
});
level1App.Map("/level2b", level2BApp => {
// "/level1/level2b" processing
});
});
Map can also match multiple segments at once:

{
private static void HandleMultiSeg(IApplicationBuilder app)
{
{
await context.Response.WriteAsync("Map multiple segments.");
});
}

{
app.Map("/map1/seg1", HandleMultiSeg);

{
await context.Response.WriteAsync("Hello from non-Map delegate.");
});
}
}
Built-in middleware
ASP.NET Core ships with the following middleware components. The Order column provides notes on the
middleware's placement in the request pipeline and under what conditions the middleware may terminate the
request and prevent other middleware from processing a request.
MIDDLEWARE DESCRIPTION ORDER
Authentication Provides authentication support. Before HttpContext.User is needed.

Terminal for OAuth callbacks.
Cookie Policy Tracks consent from users for storing Before middleware that issues cookies.
personal information and enforces Examples: Authentication, Session, MVC
minimum standards for cookie fields, (TempData).
such as secure and SameSite .
CORS Configures Cross-Origin Resource Before components that use CORS.

Sharing.
Diagnostics Configures diagnostics. Before components that generate

errors.
Forwarded Headers Forwards proxied headers onto the Before components that consume the
current request. updated fields. Examples: scheme, host,
client IP, method.
HTTP Method Override Allows an incoming POST request to Before components that consume the
override the method. updated method.
HTTPS Redirection Redirect all HTTP requests to HTTPS Before components that consume the
(ASP.NET Core 2.1 or later). URL.
HTTP Strict Transport Security (HSTS) Security enhancement middleware that Before responses are sent and after
adds a special response header components that modify requests.
(ASP.NET Core 2.1 or later). Examples: Forwarded Headers, URL
Rewriting.
MVC Processes requests with MVC/Razor Terminal if a request matches a route.

Pages (ASP.NET Core 2.0 or later).
OWIN Interop with OWIN-based apps, servers, Terminal if the OWIN Middleware fully
and middleware. processes the request.
Response Caching Provides support for caching responses. Before components that require
caching.
Response Compression Provides support for compressing Before components that require
responses. compression.
Request Localization Provides localization support. Before localization sensitive

components.
Routing Defines and constrains request routes. Terminal for matching routes.
Session Provides support for managing user Before components that require Session.
sessions.
Static Files Provides support for serving static files Terminal if a request matches a file.
and directory browsing.
URL Rewriting Provides support for rewriting URLs and Before components that consume the
redirecting requests. URL.
WebSockets Enables the WebSockets protocol. Before components that are required to
accept WebSocket requests.
Write middleware
Middleware is generally encapsulated in a class and exposed with an extension method. Consider the following
middleware, which sets the culture for the current request from a query string:
{
{
app.Use((context, next) =>
{
var cultureQuery = context.Request.Query["culture"];
if (!string.IsNullOrWhiteSpace(cultureQuery))
{
var culture = new CultureInfo(cultureQuery);
CultureInfo.CurrentCulture = culture;
CultureInfo.CurrentUICulture = culture;
}
// Call the next delegate/middleware in the pipeline

return next();
});
app.Run(async (context) =>

{
await context.Response.WriteAsync(
$"Hello {CultureInfo.CurrentCulture.DisplayName}");
});
}
}
The preceding sample code is used to demonstrate creating a middleware component. For ASP.NET Core's built-in
localization support, see Globalization and localization in ASP.NET Core.
You can test the middleware by passing in the culture, for example http://localhost:7997/?culture=no .
The following code moves the middleware delegate to a class:
using System.Globalization;
namespace Culture
{
public class RequestCultureMiddleware
{
public RequestCultureMiddleware(RequestDelegate next)

{
_next = next;
}
public async Task InvokeAsync(HttpContext context)

{
{

await _next(context);
}
}
}
The middleware Task method's name must be Invoke . In ASP.NET Core 2.0 or later, the name can be either
Invoke or InvokeAsync .
The following extension method exposes the middleware through IApplicationBuilder:
namespace Culture
{
public static class RequestCultureMiddlewareExtensions
{
public static IApplicationBuilder UseRequestCulture(
this IApplicationBuilder builder)
{
return builder.UseMiddleware<RequestCultureMiddleware>();
}
}
}
The following code calls the middleware from Startup.Configure :

{
{
app.UseRequestCulture();

{
});
}
}
Middleware should follow the Explicit Dependencies Principle by exposing its dependencies in its constructor.
Middleware is constructed once per application lifetime. See the Per-request dependencies section if you need to
share services with middleware within a request.
Middleware components can resolve their dependencies from dependency injection (DI) through constructor
parameters. UseMiddleware<T> can also accept additional parameters directly.
Per-request dependencies
Because middleware is constructed at app startup, not per-request, scoped lifetime services used by middleware
constructors aren't shared with other dependency-injected types during each request. If you must share a scoped
service between your middleware and other types, add these services to the Invoke method's signature. The
Invoke method can accept additional parameters that are populated by DI:
public class CustomMiddleware

{
public CustomMiddleware(RequestDelegate next)

{
_next = next;
}
// IMyScopedService is injected into Invoke

public async Task Invoke(HttpContext httpContext, IMyScopedService svc)
{
svc.MyProperty = 1000;
}
}
Migrate HTTP handlers and modules to ASP.NET Core middleware
Request Features in ASP.NET Core
Middleware activation with a third-party container in ASP.NET Core
By Rick Anderson and Steve Smith

Middleware is software that's assembled into an app pipeline to handle requests and responses. Each
component:
Chooses whether to pass the request to the next component in the pipeline.
Can perform work before and after the next component in the pipeline is invoked.
Request delegates are used to build the request pipeline. The request delegates handle each HTTP request.
Request delegates are configured using Run, Map, and Use extension methods. An individual request
delegate can be specified in-line as an anonymous method (called in-line middleware), or it can be defined
in a reusable class. These reusable classes and in-line anonymous methods are middleware, also called
middleware components. Each middleware component in the request pipeline is responsible for invoking
the next component in the pipeline or short-circuiting the pipeline.
Migrate HTTP handlers and modules to ASP.NET Core middleware explains the difference between request
pipelines in ASP.NET Core and ASP.NET 4.x and provides more middleware samples.
Create a middleware pipeline with IApplicationBuilder

The ASP.NET Core request pipeline consists of a sequence of request delegates, called one after the other.
The following diagram demonstrates the concept. The thread of execution follows the black arrows.
Each delegate can perform operations before and after the next delegate. A delegate can also decide to not
pass a request to the next delegate, which is called short-circuiting the request pipeline. Short-circuiting is
often desirable because it avoids unnecessary work. For example, Static Files Middleware can return a
request for a static file and short-circuit the rest of the pipeline. Exception-handling delegates are called
early in the pipeline, so they can catch exceptions that occur in later stages of the pipeline.
The simplest possible ASP.NET Core app sets up a single request delegate that handles all requests. This
case doesn't include an actual request pipeline. Instead, a single anonymous function is called in response to
every HTTP request.

{
{
{
await context.Response.WriteAsync("Hello, World!");
});
}
}
The first Run delegate terminates the pipeline.

Chain multiple request delegates together with Use. The next parameter represents the next delegate in
the pipeline. You can short-circuit the pipeline by not calling the next parameter. You can typically perform
actions both before and after the next delegate, as the following example demonstrates:

{
{
{
// Do work that doesn't write to the Response.
// Do logging or other work that doesn't write to the Response.
});

{
await context.Response.WriteAsync("Hello from 2nd delegate.");
});
}
}
WARNING
Don't call next.Invoke after the response has been sent to the client. Changes to HttpResponse after the response
has started throw an exception. For example, changes such as setting headers and a status code throw an exception.
Writing to the response body after calling next :
May cause a protocol violation. For example, writing more than the stated Content-Length .
May corrupt the body format. For example, writing an HTML footer to a CSS file.
HasStarted is a useful hint to indicate if headers have been sent or the body has been written to.
Order
The order that middleware components are added in the Startup.Configure method defines the order in
which the middleware components are invoked on requests and the reverse order for the response. The
order is critical for security, performance, and functionality.
The following Startup.Configure method adds middleware components for common app scenarios:
2. HTTP Strict Transport Security Protocol
3. HTTPS redirection
4. Static file server
5. Cookie policy enforcement
6. Authentication
7. Session
8. MVC

{
{
// When the app runs in the Development environment:
// Use the Developer Exception Page to report app runtime errors.
// Use the Database Error Page to report database runtime errors.
}
else
{
// When the app doesn't run in the Development environment:
// Use the HTTP Strict Transport Security Protocol (HSTS)
// Middleware.
app.UseHsts();
}
// Use HTTPS Redirection Middleware to redirect HTTP requests to HTTPS.


// Use Cookie Policy Middleware to conform to EU General Data

// Protection Regulation (GDPR) regulations.
// Authenticate before the user accesses secure resources.

app.UseSession();

app.UseMvc();
}
2. Static files
3. Authentication
4. Session
5. MVC
{

// Authenticate before you access secure resources.

app.UseIdentity();
// If the app uses session state, call UseSession before

// MVC Middleware.
app.UseSession();

}
In the preceding example code, each middleware extension method is exposed on IApplicationBuilder
through the Microsoft.AspNetCore.Builder namespace.
UseExceptionHandler is the first middleware component added to the pipeline. Therefore, the Exception
Handler Middleware catches any exceptions that occur in later calls.
Static Files Middleware is called early in the pipeline so that it can handle requests and short-circuit without
going through the remaining components. The Static Files Middleware provides no authorization checks.
Any files served by it, including those under wwwroot, are publicly available. For an approach to secure
static files, see Static files in ASP.NET Core.
If the request isn't handled by the Static Files Middleware, it's passed on to the Authentication Middleware
(UseAuthentication), which performs authentication. Authentication doesn't short-circuit unauthenticated
requests. Although Authentication Middleware authenticates requests, authorization (and rejection) occurs
only after MVC selects a specific Razor Page or MVC controller and action.
If the request isn't handled by Static Files Middleware, it's passed on to the Identity Middleware
(UseIdentity), which performs authentication. Identity doesn't short-circuit unauthenticated requests.
Although Identity authenticates requests, authorization (and rejection) occurs only after MVC selects a
specific controller and action.
The following example demonstrates a middleware order where requests for static files are handled by
Static Files Middleware before Response Compression Middleware. Static files aren't compressed with this
middleware order. The MVC responses from UseMvcWithDefaultRoute can be compressed.

{
// Static files not compressed by Static Files Middleware.
}
Use, Run, and Map

Configure the HTTP pipeline using Use , Run , and Map . The Use method can short-circuit the pipeline
(that is, if it doesn't call a next request delegate). Run is a convention, and some middleware components
may expose Run[Middleware] methods that run at the end of the pipeline.
Map extensions are used as a convention for branching the pipeline. Map* branches the request pipeline
based on matches of the given request path. If the request path starts with the given path, the branch is
executed.

{
{
{
});
}

{
{
});
}

{

{
});
}
}
The following table shows the requests and responses from http://localhost:1234 using the previous
code.
REQUEST RESPONSE
localhost:1234/map3 Hello from non-Map delegate.
When Mapis used, the matched path segment(s) are removed from HttpRequest.Path and appended to
HttpRequest.PathBase for each request.
MapWhen branches the request pipeline based on the result of the given predicate. Any predicate of type
Func<HttpContext, bool> can be used to map requests to a new branch of the pipeline. In the following
example, a predicate is used to detect the presence of a query string variable branch :
{
private static void HandleBranch(IApplicationBuilder app)
{
{
var branchVer = context.Request.Query["branch"];
await context.Response.WriteAsync($"Branch used = {branchVer}");
});
}

{
app.MapWhen(context => context.Request.Query.ContainsKey("branch"),
HandleBranch);

{
});
}
}
The following table shows the requests and responses from http://localhost:1234 using the previous
code.
REQUEST RESPONSE
localhost:1234/?branch=master Branch used = master
Map supports nesting, for example:
app.Map("/level1", level1App => {

level1App.Map("/level2a", level2AApp => {
// "/level1/level2a" processing
});
level1App.Map("/level2b", level2BApp => {
// "/level1/level2b" processing
});
});
Map can also match multiple segments at once:

{
private static void HandleMultiSeg(IApplicationBuilder app)
{
{
await context.Response.WriteAsync("Map multiple segments.");
});
}

{
app.Map("/map1/seg1", HandleMultiSeg);

{
await context.Response.WriteAsync("Hello from non-Map delegate.");
});
}
}
Built-in middleware
ASP.NET Core ships with the following middleware components. The Order column provides notes on the
middleware's placement in the request pipeline and under what conditions the middleware may terminate
the request and prevent other middleware from processing a request.
Authentication Provides authentication support. Before HttpContext.User is

needed. Terminal for OAuth callbacks.
Cookie Policy Tracks consent from users for storing Before middleware that issues
personal information and enforces cookies. Examples: Authentication,
minimum standards for cookie fields, Session, MVC (TempData).
such as secure and SameSite .
CORS Configures Cross-Origin Resource Before components that use CORS.

Sharing.
Diagnostics Configures diagnostics. Before components that generate

errors.
Forwarded Headers Forwards proxied headers onto the Before components that consume
current request. the updated fields. Examples: scheme,
host, client IP, method.
HTTP Method Override Allows an incoming POST request to Before components that consume
override the method. the updated method.
HTTPS Redirection Redirect all HTTP requests to HTTPS Before components that consume
(ASP.NET Core 2.1 or later). the URL.
HTTP Strict Transport Security (HSTS) Security enhancement middleware Before responses are sent and after
that adds a special response header components that modify requests.
(ASP.NET Core 2.1 or later). Examples: Forwarded Headers, URL
Rewriting.
MVC Processes requests with MVC/Razor Terminal if a request matches a route.

Pages (ASP.NET Core 2.0 or later).
OWIN Interop with OWIN-based apps, Terminal if the OWIN Middleware

servers, and middleware. fully processes the request.
Response Caching Provides support for caching Before components that require
responses. caching.
Response Compression Provides support for compressing Before components that require
responses. compression.
Request Localization Provides localization support. Before localization sensitive

components.
Routing Defines and constrains request Terminal for matching routes.

routes.
Session Provides support for managing user Before components that require
sessions. Session.
Static Files Provides support for serving static Terminal if a request matches a file.
files and directory browsing.
URL Rewriting Provides support for rewriting URLs Before components that consume
and redirecting requests. the URL.
WebSockets Enables the WebSockets protocol. Before components that are required
to accept WebSocket requests.
Write middleware
Middleware is generally encapsulated in a class and exposed with an extension method. Consider the
following middleware, which sets the culture for the current request from a query string:
{
{
{
{
}

return next();
});

{
});
}
}
The preceding sample code is used to demonstrate creating a middleware component. For ASP.NET Core's
built-in localization support, see Globalization and localization in ASP.NET Core.
You can test the middleware by passing in the culture, for example http://localhost:7997/?culture=no .
The following code moves the middleware delegate to a class:
using System.Globalization;
namespace Culture
{
public class RequestCultureMiddleware
{
public RequestCultureMiddleware(RequestDelegate next)

{
_next = next;
}
public async Task InvokeAsync(HttpContext context)

{
{

}
}
}
The middleware Task method's name must be Invoke . In ASP.NET Core 2.0 or later, the name can be
either Invoke or InvokeAsync .
The following extension method exposes the middleware through IApplicationBuilder:
namespace Culture
{
public static class RequestCultureMiddlewareExtensions
{
public static IApplicationBuilder UseRequestCulture(
{
return builder.UseMiddleware<RequestCultureMiddleware>();
}
}
}
The following code calls the middleware from Startup.Configure :

{
{
app.UseRequestCulture();

{
});
}
}
Middleware should follow the Explicit Dependencies Principle by exposing its dependencies in its
constructor. Middleware is constructed once per application lifetime. See the Per-request dependencies
section if you need to share services with middleware within a request.
Middleware components can resolve their dependencies from dependency injection (DI) through
constructor parameters. UseMiddleware<T> can also accept additional parameters directly.
Per-request dependencies
Because middleware is constructed at app startup, not per-request, scoped lifetime services used by
middleware constructors aren't shared with other dependency-injected types during each request. If you
must share a scoped service between your middleware and other types, add these services to the Invoke
method's signature. The Invoke method can accept additional parameters that are populated by DI:
public class CustomMiddleware

{
public CustomMiddleware(RequestDelegate next)

{
_next = next;
}
// IMyScopedService is injected into Invoke

public async Task Invoke(HttpContext httpContext, IMyScopedService svc)
{
svc.MyProperty = 1000;
}
}
Migrate HTTP handlers and modules to ASP.NET Core middleware
Factory-based middleware activation in ASP.NET
Core
By Luke Latham
IMiddlewareFactory/IMiddleware is an extensibility point for middleware activation.
UseMiddleware extension methods check if a middleware's registered type implements IMiddleware . If it does, the
IMiddlewareFactory instance registered in the container is used to resolve the IMiddleware implementation
instead of using the convention-based middleware activation logic. The middleware is registered as a scoped or
transient service in the app's service container.
Benefits:
Activation per request (injection of scoped services)
Strong typing of middleware
IMiddleware is activated per request, so scoped services can be injected into the middleware's constructor.
The sample app demonstrates middleware activated by:
Convention. For more information on conventional middleware activation, see the Middleware topic.
An IMiddleware implementation. The default MiddlewareFactory class activates the middleware.
The middleware implementations function identically and record the value provided by a query string parameter (
key ). The middlewares use an injected database context (a scoped service) to record the query string value in an
in-memory database.
IMiddleware
IMiddleware defines middleware for the app's request pipeline. The InvokeAsync(HttpContext, RequestDelegate)
method handles requests and returns a Task that represents the execution of the middleware.
Middleware activated by convention:
public class ConventionalMiddleware
{
public ConventionalMiddleware(RequestDelegate next)

{
_next = next;
}
public async Task InvokeAsync(HttpContext context, AppDbContext db)

{
var keyValue = context.Request.Query["key"];
if (!string.IsNullOrWhiteSpace(keyValue))
{
db.Add(new Request()
{
DT = DateTime.UtcNow,
MiddlewareActivation = "ConventionalMiddleware",
Value = keyValue
});
await db.SaveChangesAsync();
}
}
}
Middleware activated by MiddlewareFactory :
public class FactoryActivatedMiddleware : IMiddleware

{
public FactoryActivatedMiddleware(AppDbContext db)

{
_db = db;
}
public async Task InvokeAsync(HttpContext context, RequestDelegate next)

{
{
_db.Add(new Request()
{
MiddlewareActivation = "FactoryActivatedMiddleware",
Value = keyValue
});
}
await next(context);
}
}
Extensions are created for the middlewares:

public static class MiddlewareExtensions
{
public static IApplicationBuilder UseConventionalMiddleware(
{
return builder.UseMiddleware<ConventionalMiddleware>();
}
public static IApplicationBuilder UseFactoryActivatedMiddleware(

{
return builder.UseMiddleware<FactoryActivatedMiddleware>();
}
}
It isn't possible to pass objects to the factory-activated middleware with UseMiddleware :
public static IApplicationBuilder UseFactoryActivatedMiddleware(

this IApplicationBuilder builder, bool option)
{
// Passing 'option' as an argument throws a NotSupportedException at runtime.
return builder.UseMiddleware<FactoryActivatedMiddleware>(option);
}
The factory-activated middleware is added to the built-in container in Startup.cs:

{
{
});
options.UseInMemoryDatabase("InMemoryDb"));
services.AddTransient<FactoryActivatedMiddleware>();
}
Both middlewares are registered in the request processing pipeline in Configure :

{
{
}
else
{
app.UseHsts();
}
app.UseConventionalMiddleware();
app.UseFactoryActivatedMiddleware();
app.UseMvc();
}
IMiddlewareFactory
IMiddlewareFactory provides methods to create middleware. The middleware factory implementation is
registered in the container as a scoped service.
The default IMiddlewareFactory implementation, MiddlewareFactory, is found in the Microsoft.AspNetCore.Http
package.
Middleware activation with a third-party container in
ASP.NET Core
By Luke Latham
This article demonstrates how to use IMiddlewareFactory and IMiddleware as an extensibility point for
middleware activation with a third-party container. For introductory information on IMiddlewareFactory and
IMiddleware , see the Factory-based middleware activation topic.

The sample app demonstrates middleware activation by an IMiddlewareFactory implementation,
SimpleInjectorMiddlewareFactory . The sample uses the Simple Injector dependency injection ( DI ) container.
The sample's middleware implementation records the value provided by a query string parameter ( key ). The
middleware uses an injected database context (a scoped service) to record the query string value in an in-memory
database.
NOTE
The sample app uses Simple Injector purely for demonstration purposes. Use of Simple Injector isn't an endorsement.
Middleware activation approaches described in the Simple Injector documentation and GitHub issues are recommended by
the maintainers of Simple Injector. For more information, see the Simple Injector documentation and Simple Injector GitHub
repository.
IMiddlewareFactory
IMiddlewareFactory provides methods to create middleware.
In the sample app, a middleware factory is implemented to create an SimpleInjectorActivatedMiddleware instance.
The middleware factory uses the Simple Injector container to resolve the middleware:
public class SimpleInjectorMiddlewareFactory : IMiddlewareFactory

{
private readonly Container _container;
public SimpleInjectorMiddlewareFactory(Container container)

{
_container = container;
}
public IMiddleware Create(Type middlewareType)

{
return _container.GetInstance(middlewareType) as IMiddleware;
}
public void Release(IMiddleware middleware)

{
// The container is responsible for releasing resources.
}
}
IMiddleware
IMiddleware defines middleware for the app's request pipeline.
Middleware activated by an IMiddlewareFactory implementation
(Middleware/SimpleInjectorActivatedMiddleware.cs):
public class SimpleInjectorActivatedMiddleware : IMiddleware

{
public SimpleInjectorActivatedMiddleware(AppDbContext db)

{
_db = db;
}
public async Task InvokeAsync(HttpContext context, RequestDelegate next)

{
{
_db.Add(new Request()
{
MiddlewareActivation = "SimpleInjectorActivatedMiddleware",
Value = keyValue
});
}
await next(context);
}
}
An extension is created for the middleware (Middleware/MiddlewareExtensions.cs):
public static class MiddlewareExtensions

{
public static IApplicationBuilder UseSimpleInjectorActivatedMiddleware(
{
return builder.UseMiddleware<SimpleInjectorActivatedMiddleware>();
}
}
Startup.ConfigureServices must perform several tasks:

Set up the Simple Injector container.
Register the factory and middleware.
Make the app's database context available from the Simple Injector container for a Razor Page.
{
{
});
// Replace the default middleware factory with the

// SimpleInjectorMiddlewareFactory.
services.AddTransient<IMiddlewareFactory>(_ =>
{
return new SimpleInjectorMiddlewareFactory(_container);
});
// Wrap ASP.NET Core requests in a Simple Injector execution

// context.
services.UseSimpleInjectorAspNetRequestScoping(_container);
// Provide the database context from the Simple

// Injector container whenever it's requested from
// the default service container.
services.AddScoped<AppDbContext>(provider =>
_container.GetInstance<AppDbContext>());
_container.Options.DefaultScopedLifestyle = new AsyncScopedLifestyle();
_container.Register<AppDbContext>(() =>
{
var optionsBuilder = new DbContextOptionsBuilder<DbContext>();
optionsBuilder.UseInMemoryDatabase("InMemoryDb");
return new AppDbContext(optionsBuilder.Options);
}, Lifestyle.Scoped);
_container.Register<SimpleInjectorActivatedMiddleware>();
_container.Verify();
}
The middleware is registered in the request processing pipeline in Startup.Configure :

{
{
}
else
{
app.UseHsts();
}
app.UseSimpleInjectorActivatedMiddleware();
app.UseMvc();
}
Middleware
Factory-based middleware activation
Simple Injector GitHub repository
Simple Injector documentation
Static files in ASP.NET Core
By Rick Anderson and Scott Addie

Static files, such as HTML, CSS, images, and JavaScript, are assets an ASP.NET Core app serves directly to
clients. Some configuration is required to enable to serving of these files.
Serve static files

Static files are stored within your project's web root directory. The default directory is
<content_root>/wwwroot, but it can be changed via the UseWebRoot method. See Content root and Web
root for more information.
The app's web host must be made aware of the content root directory.
ASP.NET Core 2.x
ASP.NET Core 1.x
The WebHost.CreateDefaultBuilder method sets the content root to the current directory:

{
{
}

}
Static files are accessible via a path relative to the web root. For example, the Web Application project
template contains several folders within the wwwroot folder:
wwwroot
css
images
js
The URI format to access a file in the images subfolder is
http://<server_address>/images/<image_file_name>. For example,
http://localhost:9189/images/banner3.svg.
ASP.NET Core 2.x
ASP.NET Core 1.x
If targeting .NET Framework, add the Microsoft.AspNetCore.StaticFiles package to your project. If targeting
.NET Core, the Microsoft.AspNetCore.All metapackage includes this package.
Configure the middleware which enables the serving of static files.
Serve files inside of web root
Invoke the UseStaticFiles method within Startup.Configure :

{
}
The parameterless UseStaticFiles method overload marks the files in web root as servable. The following
markup references wwwroot/images/banner1.svg:
<img src="~/images/banner1.svg" alt="ASP.NET" class="img-responsive" />
Serve files outside of web root

Consider a directory hierarchy in which the static files to be served reside outside of the web root:
wwwroot
css
images
js
MyStaticFiles
images
banner1.svg
A request can access the banner1.svg file by configuring the static file middleware as follows:

{
app.UseStaticFiles(); // For the wwwroot folder
app.UseStaticFiles(new StaticFileOptions
{
FileProvider = new PhysicalFileProvider(
Path.Combine(Directory.GetCurrentDirectory(), "MyStaticFiles")),
RequestPath = "/StaticFiles"
});
}
In the preceding code, the MyStaticFiles directory hierarchy is exposed publicly via the StaticFiles URI
segment. A request to http://<server_address>/StaticFiles/images/banner1.svg serves the banner1.svg file.
The following markup references MyStaticFiles/images/banner1.svg:
<img src="~/StaticFiles/images/banner1.svg" alt="ASP.NET" class="img-responsive" />
Set HTTP response headers

A StaticFileOptions object can be used to set HTTP response headers. In addition to configuring static file
serving from the web root, the following code sets the Cache-Control header:
{
var cachePeriod = env.IsDevelopment() ? "600" : "604800";
{
OnPrepareResponse = ctx =>
{
// Requires the following import:
// using Microsoft.AspNetCore.Http;
ctx.Context.Response.Headers.Append("Cache-Control", $"public, max-age={cachePeriod}");
}
});
}
The HeaderDictionaryExtensions.Append method exists in the Microsoft.AspNetCore.Http package.

The files have been made publicly cacheable for 10 minutes (600 seconds) in the Development environment:
Static file authorization

The static file middleware doesn't provide authorization checks. Any files served by it, including those under
wwwroot, are publicly accessible. To serve files based on authorization:
Store them outside of wwwroot and any directory accessible to the static file middleware and
Serve them via an action method to which authorization is applied. Return a FileResult object:
[Authorize]
public IActionResult BannerImage()
{
var file = Path.Combine(Directory.GetCurrentDirectory(),
"MyStaticFiles", "images", "banner1.svg");
return PhysicalFile(file, "image/svg+xml");

}
Enable directory browsing

Directory browsing allows users of your web app to see a directory listing and files within a specified
directory. Directory browsing is disabled by default for security reasons (see Considerations). Enable directory
browsing by invoking the UseDirectoryBrowser method in Startup.Configure :
{
{
Path.Combine(Directory.GetCurrentDirectory(), "wwwroot", "images")),
RequestPath = "/MyImages"
});
app.UseDirectoryBrowser(new DirectoryBrowserOptions
{
});
}
Add required services by invoking the AddDirectoryBrowser method from Startup.ConfigureServices :

{
services.AddDirectoryBrowser();
}
The preceding code allows directory browsing of the wwwroot/images folder using the URL
http://<server_address>/MyImages, with links to each file and folder:
See Considerations on the security risks when enabling browsing.

Note the two UseStaticFiles calls in the following example. The first call enables the serving of static files in
the wwwroot folder. The second call enables directory browsing of the wwwroot/images folder using the URL
http://<server_address>/MyImages:
{
{
});
{
});
}
Serve a default document

Setting a default home page provides visitors a logical starting point when visiting your site. To serve a
default page without the user fully qualifying the URI, call the UseDefaultFiles method from
Startup.Configure :

{
}
IMPORTANT
UseDefaultFiles must be called before UseStaticFiles to serve the default file. UseDefaultFiles is a URL
rewriter that doesn't actually serve the file. Enable the static file middleware via UseStaticFiles to serve the file.
With UseDefaultFiles , requests to a folder search for:

default.htm
default.html
index.htm
index.html
The first file found from the list is served as though the request were the fully qualified URI. The browser URL
continues to reflect the URI requested.
The following code changes the default file name to mydefault.html:

{
// Serve my app-specific default file, if present.
DefaultFilesOptions options = new DefaultFilesOptions();
options.DefaultFileNames.Clear();
options.DefaultFileNames.Add("mydefault.html");
app.UseDefaultFiles(options);
}
UseFileServer
UseFileServer combines the functionality of UseStaticFiles , UseDefaultFiles , and UseDirectoryBrowser .
The following code enables the serving of static files and the default file. Directory browsing isn't enabled.
app.UseFileServer();
The following code builds upon the parameterless overload by enabling directory browsing:
app.UseFileServer(enableDirectoryBrowsing: true);
Consider the following directory hierarchy:

wwwroot
css
images
js
MyStaticFiles
images
banner1.svg
default.html
The following code enables static files, default files, and directory browsing of MyStaticFiles :

{
app.UseFileServer(new FileServerOptions
{
Path.Combine(Directory.GetCurrentDirectory(), "MyStaticFiles")),
RequestPath = "/StaticFiles",
EnableDirectoryBrowsing = true
});
}
AddDirectoryBrowser must be called when the EnableDirectoryBrowsing property value is true :

{
services.AddDirectoryBrowser();
}
Using the file hierarchy and preceding code, URLs resolve as follows:
URI RESPONSE
http://<server_address>/StaticFiles/images/banner1.svg MyStaticFiles/images/banner1.svg
http://<server_address>/StaticFiles MyStaticFiles/default.html
If no default-named file exists in the MyStaticFiles directory, http://<server_address>/StaticFiles returns the

directory listing with clickable links:
NOTE
UseDefaultFiles and UseDirectoryBrowser use the URL http://<server_address>/StaticFiles without the trailing
slash to trigger a client-side redirect to http://<server_address>/StaticFiles/. Notice the addition of the trailing slash.
Relative URLs within the documents are deemed invalid without a trailing slash.
FileExtensionContentTypeProvider
The FileExtensionContentTypeProvider class contains a Mappings property serving as a mapping of file
extensions to MIME content types. In the following sample, several file extensions are registered to known
MIME types. The .rtf extension is replaced, and .mp4 is removed.

{
// Set up custom content types - associating file extension to MIME type
var provider = new FileExtensionContentTypeProvider();
// Add new mappings
provider.Mappings[".myapp"] = "application/x-msdownload";
provider.Mappings[".htm3"] = "text/html";
provider.Mappings[".image"] = "image/png";
// Replace an existing mapping
provider.Mappings[".rtf"] = "application/x-msdownload";
// Remove MP4 videos.
provider.Mappings.Remove(".mp4");
{
RequestPath = "/MyImages",
ContentTypeProvider = provider
});
{
});
}
See MIME content types.

Non-standard content types
The static file middleware understands almost 400 known file content types. If the user requests a file of an
unknown file type, the static file middleware returns a HTTP 404 (Not Found) response. If directory browsing
is enabled, a link to the file is displayed. The URI returns an HTTP 404 error.
The following code enables serving unknown types and renders the unknown file as an image:

{
{
ServeUnknownFileTypes = true,
DefaultContentType = "image/png"
});
}
With the preceding code, a request for a file with an unknown content type is returned as an image.
WARNING
Enabling ServeUnknownFileTypes is a security risk. It's disabled by default, and its use is discouraged.
FileExtensionContentTypeProvider provides a safer alternative to serving files with non-standard extensions.
Considerations
WARNING
UseDirectoryBrowser and UseStaticFiles can leak secrets. Disabling directory browsing in production is highly
recommended. Carefully review which directories are enabled via UseStaticFiles or UseDirectoryBrowser . The
entire directory and its sub-directories become publicly accessible. Store files suitable for serving to the public in a
dedicated directory, such as <content_root>/wwwroot. Separate these files from MVC views, Razor Pages (2.x only),
configuration files, etc.
The URLs for content exposed with UseDirectoryBrowser and UseStaticFiles are subject to the case
sensitivity and character restrictions of the underlying file system. For example, Windows is case
insensitive—macOS and Linux aren't.
ASP.NET Core apps hosted in IIS use the ASP.NET Core Module to forward all requests to the app,
including static file requests. The IIS static file handler isn't used. It has no chance to handle requests
before they're handled by the module.
Complete the following steps in IIS Manager to remove the IIS static file handler at the server or
website level:
1. Navigate to the Modules feature.
2. Select StaticFileModule in the list.
3. Click Remove in the Actions sidebar.
WARNING
If the IIS static file handler is enabled and the ASP.NET Core Module is configured incorrectly, static files are served. This
happens, for example, if the web.config file isn't deployed.
Place code files (including .cs and .cshtml) outside of the app project's web root. A logical separation is
therefore created between the app's client-side content and server-based code. This prevents server-side
code from being leaked.
Middleware
Routing in ASP.NET Core
By Ryan Nowak, Steve Smith, and Rick Anderson

Routing functionality is responsible for mapping an incoming request to a route handler. Routes are defined in
the app and configured when the app starts. A route can optionally extract values from the URL contained in
the request, and these values can then be used for request processing. Using route information from the app,
the routing functionality is also able to generate URLs that map to route handlers. Therefore, routing can find a
route handler based on a URL or the URL corresponding to a given route handler based on route handler
information.
IMPORTANT
This document covers low-level ASP.NET Core routing. For information on ASP.NET Core MVC routing, see Routing to
controller actions in ASP.NET Core.
Routing basics
Routing uses routes (implementations of IRouter) to:
Map incoming requests to route handlers.
Generate URLs used in responses.
Generally, an app has a single collection of routes. When a request arrives, the route collection is processed in
order. The incoming request looks for a route that matches the request URL by calling the RouteAsync method
on each available route in the route collection. By contrast, a response can use routing to generate URLs (for
example, for redirection or links) based on route information and thus avoid having to hard-code URLs, which
helps maintainability.
Routing is connected to the middleware pipeline by the RouterMiddleware class. ASP.NET Core MVC adds
routing to the middleware pipeline as part of its configuration. To learn about using routing as a standalone
component, see Use Routing Middleware section.
URL matching
URL matching is the process by which routing dispatches an incoming request to a handler. This process is
generally based on data in the URL path but can be extended to consider any data in the request. The ability to
dispatch requests to separate handlers is key to scaling the size and complexity of an app.
Incoming requests enter the RouterMiddleware , which calls the RouteAsync method on each route in sequence.
The IRouter instance chooses whether to handle the request by setting the RouteContext.Handler to a non-null
RequestDelegate. If a route sets a handler for the request, route processing stops, and the handler is invoked to
process the request. If all routes are tried and no handler is found for the request, the middleware calls next,
and the next middleware in the request pipeline is invoked.
The primary input to RouteAsyncis the RouteContext.HttpContext associated with the current request. The
RouteContext.Handler and RouteContext.RouteData are outputs set after a route matches.
A match during RouteAsync also sets the properties of the RouteContext.RouteData to appropriate values based
on the request processing performed thus far. If a route matches a request, the RouteContext.RouteData
contains important state information about the result.
RouteData.Values is a dictionary of route values produced from the route. These values are usually determined
by tokenizing the URL and can be used to accept user input or to make further dispatching decisions inside the
app.
RouteData.DataTokens is a property bag of additional data related to the matched route. DataTokens are
provided to support associating state data with each route so that the app can make decisions later based on
which route matched. These values are developer-defined and do not affect the behavior of routing in any way.
Additionally, values stashed in data tokens can be of any type, in contrast to route values, which must be easily
convertible to and from strings.
RouteData.Routers is a list of the routes that took part in successfully matching the request. Routes can be
nested inside of one another. The Routers property reflects the path through the logical tree of routes that
resulted in a match. Generally, the first item in Routers is the route collection and should be used for URL
generation. The last item in Routers is the route handler that matched.
URL generation
URL generation is the process by which routing can create a URL path based on a set of route values. This
allows for a logical separation between your handlers and the URLs that access them.
URL generation follows a similar iterative process, but it starts with user or framework code calling into the
GetVirtualPath method of the route collection. Each route then has its GetVirtualPath method called in
sequence until a non-null VirtualPathData is returned.
The primary inputs to GetVirtualPath are:
VirtualPathContext.HttpContext
VirtualPathContext.Values
VirtualPathContext.AmbientValues
Routes primarily use the route values provided by the Values and AmbientValues to decide where it's possible
to generate a URL and what values to include. The AmbientValues are the set of route values that were
produced from matching the current request with the routing system. In contrast, Values are the route values
that specify how to generate the desired URL for the current operation. The HttpContext is provided in case a
route needs to obtain services or additional data associated with the current context.
TIP
Think of VirtualPathContext.Values as being a set of overrides for the VirtualPathContext.AmbientValues. URL generation
attempts to reuse route values from the current request to make it easy to generate URLs for links using the same route
or route values.
The output of GetVirtualPath is a VirtualPathData . VirtualPathData is a parallel of RouteData .

VirtualPathData contains the VirtualPath for the output URL and some additional properties that should be
set by the route.
The VirtualPathData.VirtualPath property contains the virtual path produced by the route. Depending on your
needs, you may need to process the path further. If you want to render the generated URL in HTML, prepend
the base path of the app.
The VirtualPathData.Router is a reference to the route that successfully generated the URL.
The VirtualPathData.DataTokens properties is a dictionary of additional data related to the route that generated
the URL. This is the parallel of RouteData.DataTokens.
Creating routes
Routing provides the Route class as the standard implementation of IRouter. Route uses the route template
syntax to define patterns that match against the URL path when RouteAsync is called. Route uses the same
route template to generate a URL when GetVirtualPath is called.
Most apps create routes by calling MapRoute or one of the similar extension methods defined on
IRouteBuilder. All of these methods create an instance of Route and add it to the route collection.
MapRoute doesn't take a route handler parameter. MapRoute only adds routes that are handled by the
DefaultHandler. Since the default handler is an IRouter , it may decide not to handle the request. For example,
ASP.NET Core MVC is typically configured as a default handler that only handles requests that match an
available controller and action. To learn more about routing to MVC, see Routing to controller actions in
ASP.NET Core.
The following code example is an example of a MapRoute call used by a typical ASP.NET Core MVC route
definition:
routes.MapRoute(
name: "default",
This template matches a URL path like /Products/Details/17 and extracts the route values
{ controller = Products, action = Details, id = 17 } . The route values are determined by splitting the URL
path into segments and matching each segment with the route parameter name in the route template. Route
parameters are named. They're defined by enclosing the parameter name in braces { ... } .
The preceding template could also match the URL path / and would produce the values
{ controller = Home, action = Index } . This occurs because the {controller} and {action} route parameters
have default values and the id route parameter is optional. An equals = sign followed by a value after the
route parameter name defines a default value for the parameter. A question mark ? after the route parameter
name defines the parameter as optional. Route parameters with a default value always produce a route value
when the route matches. Optional parameters don't produce a route value if there was no corresponding URL
path segment.
See route-template-reference for a thorough description of route template features and syntax.
This example includes a route constraint:
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id:int}");
This template matches a URL path like /Products/Details/17 but not /Products/Details/Apples . The route
parameter definition {id:int} defines a route constraint for the id route parameter. Route constraints
implement IRouteConstraint and inspect route values to verify them. In this example, the route value id must
be convertible to an integer. See route-constraint-reference for a more detailed explanation of route constraints
that are provided by the framework.
Additional overloads of MapRoute accept values for constraints , dataTokens , and defaults . These additional
parameters of MapRoute are defined as type object . The typical usage of these parameters is to pass an
anonymously-typed object, where the property names of the anonymous type match route parameter names.
The following two examples create equivalent routes:
routes.MapRoute(
name: "default_route",
template: "{controller}/{action}/{id?}",
defaults: new { controller = "Home", action = "Index" });
routes.MapRoute(
name: "default_route",
TIP
The inline syntax for defining constraints and defaults can be convenient for simple routes. However, there are features,
such as data tokens, that aren't supported by inline syntax.
The following example demonstrates a few more scenarios:
routes.MapRoute(
name: "blog",
template: "Blog/{*article}",
defaults: new { controller = "Blog", action = "ReadArticle" });
This template matches a URL path like and extracts the values
/Blog/All-About-Routing/Introduction
{ controller = Blog, action = ReadArticle, article = All-About-Routing/Introduction } . The default route
values for controller and action are produced by the route even though there are no corresponding route
parameters in the template. Default values can be specified in the route template. The article route
parameter is defined as a catch-all by the appearance of an asterisk * before the route parameter name.
Catch-all route parameters capture the remainder of the URL path and can also match the empty string.
This example adds route constraints and data tokens:
routes.MapRoute(
name: "us_english_products",
template: "en-US/Products/{id}",
defaults: new { controller = "Products", action = "Details" },
constraints: new { id = new IntRouteConstraint() },
dataTokens: new { locale = "en-US" });
This template matches a URL path like /en-US/Products/5 and extracts the values
{ controller = Products, action = Details, id = 5 } and the data tokens { locale = en-US } .
URL generation
The Route class can also perform URL generation by combining a set of route values with its route template.
This is logically the reverse process of matching the URL path.
TIP
To better understand URL generation, imagine what URL you want to generate and then think about how a route
template would match that URL. What values would be produced? This is the rough equivalent of how URL generation
works in the Route class.
This example uses a basic ASP.NET Core MVC style route:
routes.MapRoute(
name: "default",
With the route values { controller = Products, action = List } , this route generates the URL /Products/List .
The route values are substituted for the corresponding route parameters to form the URL path. Since id is an
optional route parameter, it's no problem that it doesn't have a value.
With the route values { controller = Home, action = Index } , this route generates the URL / . The route
values that were provided match the default values so that the segments corresponding to those values can be
safely omitted. Note that both URLs generated round-trip with this route definition and produce the same
route values that were used to generate the URL.
TIP
An app using ASP.NET Core MVC should use UrlHelper to generate URLs instead of calling into routing directly.
For more details about the URL generation process, see url-generation-reference.
Use Routing Middleware

Reference the Microsoft.AspNetCore.App metapackage in the app's project file.
Reference the Microsoft.AspNetCore.All metapackage in the app's project file.
Reference the Microsoft.AspNetCore.Routing in the app's project file.
Add routing to the service container in Startup.ConfigureServices :

{
services.AddRouting();
}

{
services.AddRouting();
}
Routes must be configured in the Startup.Configure method. The sample app uses these APIs:
RouteBuilder
Build
MapGet – Matches only HTTP GET requests.
UseRouter
var trackPackageRouteHandler = new RouteHandler(context =>

{
var routeValues = context.GetRouteData().Values;
return context.Response.WriteAsync(
$"Hello! Route values: {string.Join(", ", routeValues)}");
});
var routeBuilder = new RouteBuilder(app, trackPackageRouteHandler);
routeBuilder.MapRoute(
"Track Package Route",
"package/{operation:regex(^track|create|detonate$)}/{id:int}");
routeBuilder.MapGet("hello/{name}", context =>

{
var name = context.GetRouteValue("name");
// The route handler when HTTP GET "hello/<anything>" matches
// To match HTTP GET "hello/<anything>/<anything>,
// use routeBuilder.MapGet("hello/{*name}"
return context.Response.WriteAsync($"Hi, {name}!");
});
var routes = routeBuilder.Build();

app.UseRouter(routes);
var trackPackageRouteHandler = new RouteHandler(context =>

{
var routeValues = context.GetRouteData().Values;
return context.Response.WriteAsync(
$"Hello! Route values: {string.Join(", ", routeValues)}");
});
var routeBuilder = new RouteBuilder(app, trackPackageRouteHandler);
routeBuilder.MapRoute(
"Track Package Route",
"package/{operation:regex(^track|create|detonate$)}/{id:int}");
routeBuilder.MapGet("hello/{name}", context =>

{
var name = context.GetRouteValue("name");
// The route handler when HTTP GET "hello/<anything>" matches
// To match HTTP GET "hello/<anything>/<anything>,
// use routeBuilder.MapGet("hello/{*name}"
return context.Response.WriteAsync($"Hi, {name}!");
});
var routes = routeBuilder.Build();

app.UseRouter(routes);
The following table shows the responses with the given URIs.
URI RESPONSE
/package/create/3 Hello! Route values: [operation, create], [id, 3]
/package/track/-3 Hello! Route values: [operation, track], [id, -3]

URI RESPONSE
/package/track/-3/ Hello! Route values: [operation, track], [id, -3]
/package/track/ <Fall through, no match>
GET /hello/Joe Hi, Joe!
POST /hello/Joe <Fall through, matches HTTP GET only>
GET /hello/Joe/Smith <Fall through, no match>
If you're configuring a single route, call UseRouter passing in an IRouter instance. You won't need to use
RouteBuilder.
The framework provides a set of extension methods for creating routes, such as:
MapRoute
MapGet
MapPost
MapPut
MapDelete
MapVerb
Some of these methods, such as MapGet , require a RequestDelegate to be provided. The RequestDelegate is
used as the route handler when the route matches. Other methods in this family allow configuring a
middleware pipeline for use as the route handler. If the Map method doesn't accept a handler, such as
MapRoute , then it uses the DefaultHandler.
The Map[Verb] methods use constraints to limit the route to the HTTP Verb in the method name. For example,
see MapGet and MapVerb.
Route Template Reference

Tokens within curly braces ( { ... } ) define route parameters that are bound if the route is matched. You can
define more than one route parameter in a route segment, but they must be separated by a literal value. For
example, {controller=Home}{action=Index} isn't a valid route, since there's no literal value between
{controller} and {action} . These route parameters must have a name and may have additional attributes
specified.
Literal text other than route parameters (for example, {id} ) and the path separator / must match the text in
the URL. Text matching is case-insensitive and based on the decoded representation of the URLs path. To
match the literal route parameter delimiter { or } , escape it by repeating the character ( {{ or }} ).
URL patterns that attempt to capture a filename with an optional file extension have additional considerations.
For example, consider the template files/{filename}.{ext?} . When both filename and ext exist, both values
are populated. If only filename exists in the URL, the route matches because the trailing period . is optional.
The following URLs match this route:
/files/myFile.txt
/files/myFile
You can use the * character as a prefix to a route parameter to bind to the rest of the URI. This is called a
catch-all parameter. For example, blog/{*slug} matches any URI that starts with /blog and had any value
following it (which is assigned to the slug route value). Catch-all parameters can also match the empty string.
Route parameters may have default values, designated by specifying the default after the parameter name,
separated by an equals sign ( = ). For example, {controller=Home} defines Home as the default value for
controller . The default value is used if no value is present in the URL for the parameter. In addition to default
values, route parameters may be optional, specified by appending a question mark ( ? ) to the end of the
parameter name, as in id? . The difference between optional values and default route parameters is that a
route parameter with a default value always produces a value; an optional parameter has a value only when a
value is provided by the request URL.
Route parameters may also have constraints, which must match the route value bound from the URL. Adding a
colon : and constraint name after the route parameter name specifies an inline constraint on a route
parameter. If the constraint requires arguments, they're provided in enclosed in parentheses ( ) after the
constraint name. Multiple inline constraints can be specified by appending another colon : and constraint
name. The constraint name is passed to the IInlineConstraintResolver service to create an instance of
IRouteConstraint to use in URL processing. For example, the route template blog/{article:minlength(10)}
specifies a minlength constraint with the argument 10 . For more information on route constraints and a
listing of the constraints provided by the framework, see the Route constraint reference section.
The following table demonstrates some route templates and their behavior.
ROUTE TEMPLATE EXAMPLE MATCHING URL NOTES
hello /hello Only matches the single path /hello
{Page=Home} / Matches and sets Page to Home
{Page=Home} /Contact Matches and sets Page to Contact
{controller}/{action}/{id?} /Products/List Maps to Products controller and

List action
{controller}/{action}/{id?} /Products/Details/123 Maps to Products controller and

Details action. id set to 123
{controller=Home}/{action=Index}/{id?} / Maps to Home controller and Index

method; id is ignored.
Using a template is generally the simplest approach to routing. Constraints and defaults can also be specified
outside the route template.
TIP
Enable Logging to see how the built in routing implementations, such as Route , match requests.
Reserved routing names

The following keywords are reserved names and can't be used as route names or parameters:
action
area
controller
handler
page
Route constraint reference

Route constraints execute when a Route has matched the syntax of the incoming URL and tokenized the URL
path into route values. Route constraints generally inspect the route value associated via the route template
and make a simple yes/no decision about whether or not the value is acceptable. Some route constraints use
data outside the route value to consider whether the request can be routed. For example, the
HttpMethodRouteConstraint can accept or reject a request based on its HTTP verb.
WARNING
Avoid using constraints for input validation because doing so means that invalid input results in a 404 - Not Found
response instead of a 400 - Bad Request with an appropriate error message. Route constraints are used to
disambiguate between similar routes, not to validate the inputs for a particular route.
The following table demonstrates some route constraints and their expected behavior.
CONSTRAINT EXAMPLE EXAMPLE MATCHES NOTES
int {id:int} 123456789 , -123456789 Matches any integer
bool {active:bool} true , FALSE Matches true or false

(case-insensitive)
datetime {dob:datetime} 2016-12-31 , Matches a valid DateTime

2016-12-31 7:32pm value (in the invariant
culture - see warning)
decimal {price:decimal} 49.99 , -1,000.01 Matches a valid decimal

value (in the invariant
double {weight:double} 1.234 , -1,001.01e8 Matches a valid double

float {weight:float} 1.234 , -1,001.01e8 Matches a valid float

guid {id:guid} CD2C1638-1638-72D5- Matches a valid Guid

1638-DEADBEEF1638 value
,
{CD2C1638-1638-72D5-
1638-DEADBEEF1638}
long {ticks:long} 123456789 , -123456789 Matches a valid long

value
minlength(value) {username:minlength(4)} Rick String must be at least 4

characters
maxlength(value) {filename:maxlength(8)} Richard String must be no more

than 8 characters
CONSTRAINT EXAMPLE EXAMPLE MATCHES NOTES
length(length) {filename:length(12)} somefile.txt String must be exactly 12

characters long
length(min,max) {filename:length(8,16)} somefile.txt String must be at least 8

and no more than 16
characters long
min(value) {age:min(18)} 19 Integer value must be at

least 18
max(value) {age:max(120)} 91 Integer value must be no

more than 120
range(min,max) {age:range(18,120)} 91 Integer value must be at

least 18 but no more than
120
alpha {name:alpha} Rick String must consist of one

or more alphabetical
characters ( a - z , case-
insensitive)
regex(expression) {ssn:regex(^\\d{{3}}- 123-45-6789 String must match the

\\d{{2}}-\\d{{4}}$)} regular expression (see tips
about defining a regular
expression)
required {name:required} Rick Used to enforce that a non-

parameter value is present
during URL generation
Multiple, colon-delimited constraints can be applied to a single parameter. For example, the following
constraint restricts a parameter to an integer value of 1 or greater:
[Route("users/{id:int:min(1)}")]
public User GetUserById(int id) { }
WARNING
Route constraints that verify the URL and are converted to a CLR type (such as int or DateTime ) always use the
invariant culture. These constraints assume that the URL is non-localizable. The framework-provided route constraints
don't modify the values stored in route values. All route values parsed from the URL are stored as strings. For example,
the float constraint attempts to convert the route value to a float, but the converted value is used only to verify it
can be converted to a float.
Regular expressions
The ASP.NET Core framework adds
RegexOptions.IgnoreCase | RegexOptions.Compiled | RegexOptions.CultureInvariant to the regular expression
constructor. See RegexOptions for a description of these members.
Regular expressions use delimiters and tokens similar to those used by Routing and the C# language. Regular
expression tokens must be escaped. To use the regular expression ^\d{3}-\d{2}-\d{4}$ in Routing, the
expression must have the \ characters typed in as \\ in the C# source file to escape the \ string escape
character (unless using verbatim string literals. The { , } , [ and ] characters must be escaped by
doubling them to escape the Routing parameter delimiter characters. The table below shows a regular
expression and the escaped version.
EXPRESSION ESCAPED
^\d{3}-\d{2}-\d{4}$ ^\\d{{3}}-\\d{{2}}-\\d{{4}}$
^[a-z]{2}$ ^[[a-z]]{{2}}$
Regular expressions used in routing often start with the ^ character (match starting position of the string) and
end with the $ character (match ending position of the string). The ^ and $ characters ensure that the
regular expression match the entire route parameter value. Without the ^ and $ characters, the regular
expression match any substring within the string, which is often undesirable. The table below shows some
examples and explains why they match or fail to match.
EXPRESSION STRING MATCH COMMENT
[a-z]{2} hello Yes Substring matches
[a-z]{2} 123abc456 Yes Substring matches
[a-z]{2} mz Yes Matches expression
[a-z]{2} MZ Yes Not case sensitive
^[a-z]{2}$ hello No See ^ and $ above
^[a-z]{2}$ 123abc456 No See ^ and $ above
Refer to .NET Framework Regular Expressions for more information on regular expression syntax.
To constrain a parameter to a known set of possible values, use a regular expression. For example,
{action:regex(^(list|get|create)$)} only matches the action route value to list , get , or create . If
passed into the constraints dictionary, the string ^(list|get|create)$ is equivalent. Constraints that are passed
in the constraints dictionary (not inline within a template) that don't match one of the known constraints are
also treated as regular expressions.
URL Generation Reference

The following example shows how to generate a link to a route given a dictionary of route values and a
RouteCollection.
{
var dictionary = new RouteValueDictionary
{
{ "operation", "create" },
{ "id", 123}
};
var vpc = new VirtualPathContext(context, null, dictionary,

"Track Package Route");
var path = routes.GetVirtualPath(vpc).VirtualPath;
context.Response.ContentType = "text/html";
await context.Response.WriteAsync("Menu<hr/>");
$"<a href='{path}'>Create Package 123</a><br/>");
});

{
var dictionary = new RouteValueDictionary
{
{ "operation", "create" },
{ "id", 123}
};
var vpc = new VirtualPathContext(context, null, dictionary,

"Track Package Route");
var path = routes.GetVirtualPath(vpc).VirtualPath;
await context.Response.WriteAsync("Menu<hr/>");
$"<a href='{path}'>Create Package 123</a><br/>");
});
The VirtualPath generated at the end of the preceding sample is /package/create/123 . The dictionary supplies
the operation and id route values of the "Track Package Route" template, package/{operation}/{id} . For
details, see the sample code in the Use Routing Middleware section or the sample app.
The second parameter to the VirtualPathContext constructor is a collection of ambient values. Ambient values
provide convenience by limiting the number of values a developer must specify within a certain request
context. The current route values of the current request are considered ambient values for link generation. In an
ASP.NET Core MVC app if you are in the About action of the HomeController , you don't need to specify the
controller route value to link to the Index action—the ambient value of Home is used.
Ambient values that don't match a parameter are ignored, and ambient values are also ignored when an
explicitly-provided value overrides it, going from left to right in the URL.
Values that are explicitly provided but which don't match anything are added to the query string. The following
table shows the result when using the route template {controller}/{action}/{id?} .
AMBIENT VALUES EXPLICIT VALUES RESULT
controller="Home" action="About" /Home/About
controller="Home" controller="Order",action="About" /Order/About

AMBIENT VALUES EXPLICIT VALUES RESULT
controller="Home",color="Red" action="About" /Home/About
controller="Home" action="About",color="Red" /Home/About?color=Red
If a route has a default value that doesn't correspond to a parameter and that value is explicitly provided, it
must match the default value:
routes.MapRoute("blog_route", "blog/{*slug}",
defaults: new { controller = "Blog", action = "ReadPost" });
Link generation only generates a link for this route when the matching values for controller and action are
provided.
URL Rewriting Middleware in ASP.NET Core
By Luke Latham and Mikael Mengistu

URL rewriting is the act of modifying request URLs based on one or more predefined rules. URL rewriting
creates an abstraction between resource locations and their addresses so that the locations and addresses are not
tightly linked. There are several scenarios where URL rewriting is valuable:
Moving or replacing server resources temporarily or permanently while maintaining stable locators for those
resources.
Splitting request processing across different apps or across areas of one app.
Removing, adding, or reorganizing URL segments on incoming requests.
Optimizing public URLs for Search Engine Optimization (SEO ).
Permitting the use of friendly public URLs to help people predict the content they will find by following a link.
Redirecting insecure requests to secure endpoints.
Preventing image hotlinking.
You can define rules for changing the URL in several ways, including Regex, Apache mod_rewrite module rules,
IIS Rewrite Module rules, and using custom rule logic. This document introduces URL rewriting with instructions
on how to use URL Rewriting Middleware in ASP.NET Core apps.
NOTE
URL rewriting can reduce the performance of an app. Where feasible, you should limit the number and complexity of rules.
URL redirect and URL rewrite

The difference in wording between URL redirect and URL rewrite may seem subtle at first but has important
implications for providing resources to clients. ASP.NET Core's URL Rewriting Middleware is capable of meeting
the need for both.
A URL redirect is a client-side operation, where the client is instructed to access a resource at another address.
This requires a round-trip to the server. The redirect URL returned to the client appears in the browser's address
bar when the client makes a new request for the resource.
If /resource is redirected to /different-resource , the client requests /resource . The server responds that the
client should obtain the resource at /different-resource with a status code indicating that the redirect is either
temporary or permanent. The client executes a new request for the resource at the redirect URL.
When redirecting requests to a different URL, you indicate whether the redirect is permanent or temporary. The
301 (Moved Permanently) status code is used where the resource has a new, permanent URL and you wish to
instruct the client that all future requests for the resource should use the new URL. The client may cache the
response when a 301 status code is received. The 302 (Found) status code is used where the redirection is
temporary or generally subject to change, such that the client shouldn't store and reuse the redirect URL in the
future. For more information, see RFC 2616: Status Code Definitions.
A URL rewrite is a server-side operation to provide a resource from a different resource address. Rewriting a URL
doesn't require a round-trip to the server. The rewritten URL isn't returned to the client and won't appear in the
browser's address bar. When /resource is rewritten to /different-resource , the client requests /resource , and
the server internally fetches the resource at /different-resource . Although the client might be able to retrieve
the resource at the rewritten URL, the client won't be informed that the resource exists at the rewritten URL when
it makes its request and receives the response.
URL rewriting sample app

You can explore the features of the URL Rewriting Middleware with the URL rewriting sample app. The app
applies rewrite and redirect rules and shows the rewritten or redirected URL.
When to use URL Rewriting Middleware

Use URL Rewriting Middleware when you are unable to use the URL Rewrite module with IIS on Windows
Server, the Apache mod_rewrite module on Apache Server, URL rewriting on Nginx, or your app is hosted on
HTTP.sys server (formerly called WebListener). The main reasons to use the server-based URL rewriting
technologies in IIS, Apache, or Nginx are that the middleware doesn't support the full features of these modules
and the performance of the middleware probably won't match that of the modules. However, there are some
features of the server modules that don't work with ASP.NET Core projects, such as the IsFile and IsDirectory
constraints of the IIS Rewrite module. In these scenarios, use the middleware instead.
Package
To include the middleware in your project, add a reference to the Microsoft.AspNetCore.Rewrite package. This
feature is available for apps that target ASP.NET Core 1.1 or later.
Extension and options

Establish your URL rewrite and redirect rules by creating an instance of the RewriteOptions class with extension
methods for each of your rules. Chain multiple rules in the order that you would like them processed. The
RewriteOptions are passed into the URL Rewriting Middleware as it's added to the request pipeline with
app.UseRewriter(options); .
ASP.NET Core 2.x

ASP.NET Core 1.x

{
using (StreamReader apacheModRewriteStreamReader =
File.OpenText("ApacheModRewrite.txt"))
using (StreamReader iisUrlRewriteStreamReader =
File.OpenText("IISUrlRewrite.xml"))
{
var options = new RewriteOptions()
.AddRedirect("redirect-rule/(.*)", "redirected/$1")
.AddRewrite(@"^rewrite-rule/(\d+)/(\d+)", "rewritten?var1=$1&var2=$2",
skipRemainingRules: true)
.AddApacheModRewrite(apacheModRewriteStreamReader)
.AddIISUrlRewrite(iisUrlRewriteStreamReader)
.Add(MethodRules.RedirectXMLRequests)
.Add(new RedirectImageRequests(".png", "/png-images"))
.Add(new RedirectImageRequests(".jpg", "/jpg-images"));
app.UseRewriter(options);
}
app.Run(context => context.Response.WriteAsync(

$"Rewritten or Redirected Url: " +
$"{context.Request.Path + context.Request.QueryString}"));
}
URL redirect
Use AddRedirect to redirect requests. The first parameter contains your regex for matching on the path of the
incoming URL. The second parameter is the replacement string. The third parameter, if present, specifies the
status code. If you don't specify the status code, it defaults to 302 (Found), which indicates that the resource is
temporarily moved or replaced.
ASP.NET Core 2.x
ASP.NET Core 1.x
{
{
}

}
In a browser with developer tools enabled, make a request to the sample app with the path
/redirect-rule/1234/5678 . The regex matches the request path on redirect-rule/(.*) , and the path is replaced
with /redirected/1234/5678 . The redirect URL is sent back to the client with a 302 (Found) status code. The
browser makes a new request at the redirect URL, which appears in the browser's address bar. Since no rules in
the sample app match on the redirect URL, the second request receives a 200 (OK) response from the app and
the body of the response shows the redirect URL. A roundtrip is made to the server when a URL is redirected.
WARNING
Be cautious when establishing your redirect rules. Your redirect rules are evaluated on each request to the app, including
after a redirect. It's easy to accidently create a loop of infinite redirects.
Original Request: /redirect-rule/1234/5678
The part of the expression contained within parentheses is called a capture group. The dot ( . ) of the expression
means match any character. The asterisk ( * ) indicates match the preceding character zero or more times.
Therefore, the last two path segments of the URL, 1234/5678 , are captured by capture group (.*) . Any value
you provide in the request URL after redirect-rule/ is captured by this single capture group.
In the replacement string, captured groups are injected into the string with the dollar sign ( $ ) followed by the
sequence number of the capture. The first capture group value is obtained with $1 , the second with $2 , and
they continue in sequence for the capture groups in your regex. There's only one captured group in the redirect
rule regex in the sample app, so there's only one injected group in the replacement string, which is $1 . When the
rule is applied, the URL becomes /redirected/1234/5678 .
URL redirect to a secure endpoint
Use AddRedirectToHttps to redirect HTTP requests to the same host and path using HTTPS ( https:// ). If the
status code isn't supplied, the middleware defaults to 302 (Found). If the port isn't supplied, the middleware
defaults to null , which means the protocol changes to https:// and the client accesses the resource on port
443. The example shows how to set the status code to 301 (Moved Permanently) and change the port to 5001.

{
.AddRedirectToHttps(301, 5001);
}
Use AddRedirectToHttpsPermanent to redirect insecure requests to the same host and path with secure HTTPS
protocol ( https:// on port 443). The middleware sets the status code to 301 (Moved Permanently).

{
.AddRedirectToHttpsPermanent();
}
NOTE
When redirecting to HTTPS without the requirement for additional redirect rules, we recommend using HTTPS Redirection
Middleware. For more information, see the Enforce HTTPS topic.
The sample app is capable of demonstrating how to use AddRedirectToHttps or AddRedirectToHttpsPermanent .

Add the extension method to the RewriteOptions . Make an insecure request to the app at any URL. Dismiss the
browser security warning that the self-signed certificate is untrusted or create an exception to trust the certificate.
Original Request using AddRedirectToHttps(301, 5001) : http://localhost:5000/secure
Original Request using AddRedirectToHttpsPermanent : http://localhost:5000/secure

URL rewrite
Use AddRewrite to create a rule for rewriting URLs. The first parameter contains your regex for matching on the
incoming URL path. The second parameter is the replacement string. The third parameter,
skipRemainingRules: {true|false} , indicates to the middleware whether or not to skip additional rewrite rules if
the current rule is applied.
ASP.NET Core 2.x
ASP.NET Core 1.x

{
{
}

}
Original Request: /rewrite-rule/1234/5678

The first thing you notice in the regex is the carat ( ^ ) at the beginning of the expression. This means that
matching starts at the beginning of the URL path.
In the earlier example with the redirect rule, redirect-rule/(.*) , there's no carat at the start of the regex;
therefore, any characters may precede redirect-rule/ in the path for a successful match.
PATH MATCH
/redirect-rule/1234/5678 Yes
/my-cool-redirect-rule/1234/5678 Yes
/anotherredirect-rule/1234/5678 Yes
The rewrite rule, ^rewrite-rule/(\d+)/(\d+) , only matches paths if they start with rewrite-rule/ . Notice the
difference in matching between the rewrite rule below and the redirect rule above.
PATH MATCH
/rewrite-rule/1234/5678 Yes
/my-cool-rewrite-rule/1234/5678 No
/anotherrewrite-rule/1234/5678 No
Following the ^rewrite-rule/ portion of the expression, there are two capture groups, (\d+)/(\d+) . The \d
signifies match a digit (number ). The plus sign ( + ) means match one or more of the preceding character.
Therefore, the URL must contain a number followed by a forward-slash followed by another number. These
capture groups are injected into the rewritten URL as $1 and $2 . The rewrite rule replacement string places the
captured groups into the querystring. The requested path of /rewrite-rule/1234/5678 is rewritten to obtain the
resource at /rewritten?var1=1234&var2=5678 . If a querystring is present on the original request, it's preserved
when the URL is rewritten.
There's no roundtrip to the server to obtain the resource. If the resource exists, it's fetched and returned to the
client with a 200 (OK) status code. Because the client isn't redirected, the URL in the browser address bar doesn't
change. As far as the client is concerned, the URL rewrite operation never occurred.
NOTE
Use skipRemainingRules: true whenever possible, because matching rules is an expensive process and reduces app
response time. For the fastest app response:
Order your rewrite rules from the most frequently matched rule to the least frequently matched rule.
Skip the processing of the remaining rules when a match occurs and no additional rule processing is required.
Apache mod_rewrite
Apply Apache mod_rewrite rules with AddApacheModRewrite . Make sure that the rules file is deployed with the app.
For more information and examples of mod_rewrite rules, see Apache mod_rewrite.
ASP.NET Core 2.x
ASP.NET Core 1.x
A StreamReader is used to read the rules from the ApacheModRewrite.txt rules file.

{
{
}

}
The sample app redirects requests from /apache-mod-rules-redirect/(.\*) to /redirected?id=$1 . The response
status code is 302 (Found).
# Rewrite path with additional sub directory

RewriteRule ^/apache-mod-rules-redirect/(.*) /redirected?id=$1 [L,R=302]
Original Request: /apache-mod-rules-redirect/1234

Su p p o r t e d se r v e r v a r i a b l e s
The middleware supports the following Apache mod_rewrite server variables:

CONN_REMOTE_ADDR
HTTP_ACCEPT
HTTP_CONNECTION
HTTP_COOKIE
HTTP_FORWARDED
HTTP_HOST
HTTP_REFERER
HTTP_USER_AGENT
HTTPS
IPV6
QUERY_STRING
REMOTE_ADDR
REMOTE_PORT
REQUEST_FILENAME
REQUEST_METHOD
REQUEST_SCHEME
REQUEST_URI
SCRIPT_FILENAME
SERVER_ADDR
SERVER_PORT
SERVER_PROTOCOL
TIME
TIME_DAY
TIME_HOUR
TIME_MIN
TIME_MON
TIME_SEC
TIME_WDAY
TIME_YEAR
IIS URL Rewrite Module rules
To use rules that apply to the IIS URL Rewrite Module, use AddIISUrlRewrite . Make sure that the rules file is
deployed with the app. Don't direct the middleware to use your web.config file when running on Windows Server
IIS. With IIS, these rules should be stored outside of your web.config to avoid conflicts with the IIS Rewrite
module. For more information and examples of IIS URL Rewrite Module rules, see Using Url Rewrite Module 2.0
and URL Rewrite Module Configuration Reference.
ASP.NET Core 2.x
ASP.NET Core 1.x
A StreamReader is used to read the rules from the IISUrlRewrite.xml rules file.

{
{
}

}
The sample app rewrites requests from /iis-rules-rewrite/(.*) to /rewritten?id=$1 . The response is sent to the
client with a 200 (OK) status code.
<rewrite>
<rules>
<rule name="Rewrite segment to id querystring" stopProcessing="true">
<match url="îis-rules-rewrite/(.*)$" />
<action type="Rewrite" url="rewritten?id={R:1}" appendQueryString="false"/>
</rule>
</rules>
</rewrite>
Original Request: /iis-rules-rewrite/1234
If you have an active IIS Rewrite Module with server-level rules configured that would impact your app in
undesirable ways, you can disable the IIS Rewrite Module for an app. For more information, see Disabling IIS
modules.
Unsupported features
ASP.NET Core 2.x
ASP.NET Core 1.x
The middleware released with ASP.NET Core 2.x doesn't support the following IIS URL Rewrite Module features:
Outbound Rules
Custom Server Variables
Wildcards
LogRewrittenUrl
Supported server variables
The middleware supports the following IIS URL Rewrite Module server variables:
CONTENT_LENGTH
CONTENT_TYPE
HTTP_ACCEPT
HTTP_CONNECTION
HTTP_COOKIE
HTTP_HOST
HTTP_REFERER
HTTP_URL
HTTP_USER_AGENT
HTTPS
LOCAL_ADDR
QUERY_STRING
REMOTE_ADDR
REMOTE_PORT
REQUEST_FILENAME
REQUEST_URI
NOTE
You can also obtain an IFileProvider via a PhysicalFileProvider . This approach may provide greater flexibility for the
location of your rewrite rules files. Make sure that your rewrite rules files are deployed to the server at the path you
provide.
PhysicalFileProvider fileProvider = new PhysicalFileProvider(Directory.GetCurrentDirectory());
Method-based rule
Use Add(Action<RewriteContext> applyRule) to implement your own rule logic in a method. The RewriteContext
exposes the HttpContext for use in your method. The context.Result determines how additional pipeline
processing is handled.
CONTEX T.RESULT ACTION
RuleResult.ContinueRules (default) Continue applying rules

CONTEX T.RESULT ACTION
RuleResult.EndResponse Stop applying rules and send the response
RuleResult.SkipRemainingRules Stop applying rules and send the context to the next
middleware
ASP.NET Core 2.x

ASP.NET Core 1.x

{
{
}

}
The sample app demonstrates a method that redirects requests for paths that end with .xml. If you make a request
for /file.xml , it's redirected to /xmlfiles/file.xml . The status code is set to 301 (Moved Permanently). For a
redirect, you must explicitly set the status code of the response; otherwise, a 200 (OK) status code is returned and
the redirect won't occur on the client.
public static void RedirectXMLRequests(RewriteContext context)

{
var request = context.HttpContext.Request;
// Because we're redirecting back to the same app, stop

// processing if the request has already been redirected
if (request.Path.StartsWithSegments(new PathString("/xmlfiles")))
{
return;
}
if (request.Path.Value.EndsWith(".xml", StringComparison.OrdinalIgnoreCase))
{
var response = context.HttpContext.Response;
response.StatusCode = StatusCodes.Status301MovedPermanently;
context.Result = RuleResult.EndResponse;
response.Headers[HeaderNames.Location] =
"/xmlfiles" + request.Path + request.QueryString;
}
}
Original Request: /file.xml
IRule -based rule

Use Add(IRule) to implement your own rule logic in a class that derives from IRule . Using an IRule provides
greater flexibility over using the method-based rule approach. Your derived class may include a constructor, where
you can pass in parameters for the ApplyRule method.
ASP.NET Core 2.x
ASP.NET Core 1.x

{
{
}

}
The values of the parameters in the sample app for the extension and the newPath are checked to meet several
conditions. The extension must contain a value, and the value must be .png, .jpg, or .gif. If the newPath isn't valid,
an ArgumentException is thrown. If you make a request for image.png, it's redirected to /png-images/image.png . If
you make a request for image.jpg, it's redirected to /jpg-images/image.jpg . The status code is set to 301 (Moved
Permanently), and the context.Result is set to stop processing rules and send the response.
public class RedirectImageRequests : IRule
{
private readonly string _extension;
private readonly PathString _newPath;
public RedirectImageRequests(string extension, string newPath)

{
if (string.IsNullOrEmpty(extension))
{
throw new ArgumentException(nameof(extension));
}
if (!Regex.IsMatch(extension, @"^\.(png|jpg|gif)$"))
{
throw new ArgumentException("Invalid extension", nameof(extension));
}
if (!Regex.IsMatch(newPath, @"(/[A-Za-z0-9]+)+?"))
{
throw new ArgumentException("Invalid path", nameof(newPath));
}
_extension = extension;
_newPath = new PathString(newPath);
}
public void ApplyRule(RewriteContext context)

{
var request = context.HttpContext.Request;
// Because we're redirecting back to the same app, stop

// processing if the request has already been redirected
if (request.Path.StartsWithSegments(new PathString(_newPath)))
{
return;
}
if (request.Path.Value.EndsWith(_extension, StringComparison.OrdinalIgnoreCase))
{
response.StatusCode = StatusCodes.Status301MovedPermanently;
context.Result = RuleResult.EndResponse;
response.Headers[HeaderNames.Location] =
_newPath + request.Path + request.QueryString;
}
}
}
Original Request: /image.png
Original Request: /image.jpg

Regex examples
REGEX STRING & REPLACEMENT STRING &
GOAL MATCH EXAMPLE OUTPUT EXAMPLE
Rewrite path into querystring ^path/(.*)/(.*) path?var1=$1&var2=$2

/path/abc/123 /path?var1=abc&var2=123
Strip trailing slash (.*)/$ $1

/path/ /path
Enforce trailing slash (.*[^/])$ $1/

/path /path/
Avoid rewriting specific requests ^(.*)(?<!\.axd)$ or rewritten/$1

^(?!.*\.axd$)(.*)$ /rewritten/resource.htm
Yes: /resource.htm /resource.axd
No: /resource.axd
Rearrange URL segments path/(.*)/(.*)/(.*) path/$3/$2/$1

path/1/2/3 path/3/2/1
Replace a URL segment ^(.*)/segment2/(.*) $1/replaced/$2

/segment1/segment2/segment3 /segment1/replaced/segment3
Application Startup
Middleware
Regular expressions in .NET
Regular expression language - quick reference
Apache mod_rewrite
Using Url Rewrite Module 2.0 (for IIS )
URL Rewrite Module Configuration Reference
IIS URL Rewrite Module Forum
Keep a simple URL structure
10 URL Rewriting Tips and Tricks
To slash or not to slash
By Rick Anderson
ASP.NET Core configures app behavior based on the runtime environment using an environment variable.
Environments
ASP.NET Core reads the environment variable ASPNETCORE_ENVIRONMENT at app startup and stores the value in
IHostingEnvironment.EnvironmentName. You can set ASPNETCORE_ENVIRONMENT to any value, but three values are
supported by the framework: Development, Staging, and Production. If ASPNETCORE_ENVIRONMENT isn't set, it
defaults to Production .

{
{
}
if (env.IsProduction() || env.IsStaging() || env.IsEnvironment("Staging_2"))

{
app.UseHsts();
}
app.UseMvc();
}
The preceding code:

Calls UseDeveloperExceptionPage and UseBrowserLink when ASPNETCORE_ENVIRONMENT is set to
Development .
Calls UseExceptionHandler when the value of ASPNETCORE_ENVIRONMENT is set one of the following:
Staging
Production
Staging_2
The Environment Tag Helper uses the value of IHostingEnvironment.EnvironmentName to include or exclude
markup in the element:
@page
@inject Microsoft.AspNetCore.Hosting.IHostingEnvironment hostingEnv
@model AboutModel
@{
}
<p> ASPNETCORE_ENVIRONMENT = @hostingEnv.EnvironmentName</p>
On Windows and macOS, environment variables and values aren't case sensitive. Linux environment variables
and values are case sensitive by default.
Development
The development environment can enable features that shouldn't be exposed in production. For example, the
ASP.NET Core templates enable the developer exception page in the development environment.
The environment for local machine development can be set in the Properties\launchSettings.json file of the
project. Environment values set in launchSettings.json override values set in the system environment.
The following JSON shows three profiles from a launchSettings.json file:
{
"iisSettings": {
"windowsAuthentication": false,
"anonymousAuthentication": true,
"iisExpress": {
"applicationUrl": "http://localhost:54339/",
"sslPort": 0
}
},
"profiles": {
"IIS Express": {
"commandName": "IISExpress",
"launchBrowser": true,
"environmentVariables": {
"ASPNETCORE_My_Environment": "1",
"ASPNETCORE_DETAILEDERRORS": "1",
"ASPNETCORE_ENVIRONMENT": "Staging"
}
},
"EnvironmentsSample": {
"commandName": "Project",
},
"applicationUrl": "http://localhost:54340/"
},
"Kestrel Staging": {
"ASPNETCORE_My_Environment": "1",
"ASPNETCORE_DETAILEDERRORS": "1",
},
"applicationUrl": "http://localhost:51997/"
}
}
}
NOTE
The applicationUrl property in launchSettings.json can specify a list of server URLs. Use a semicolon between the
URLs in the list:
"EnvironmentsSample": {
"applicationUrl": "https://localhost:5001;http://localhost:5000",
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
When the app is launched with dotnet run, the first profile with "commandName": "Project" is used. The value of
commandName specifies the web server to launch. commandName can be any one of the following:
IIS Express
IIS
Project (which launches Kestrel)
When an app is launched with dotnet run:
launchSettings.json is read if available. environmentVariables settings in launchSettings.json override
environment variables.
The hosting environment is displayed.
The following output shows an app started with dotnet run:
PS C:\Websites\EnvironmentsSample> dotnet run

Using launch settings from C:\Websites\EnvironmentsSample\Properties\launchSettings.json...
Hosting environment: Staging
Content root path: C:\Websites\EnvironmentsSample
Now listening on: http://localhost:54340
Application started. Press Ctrl+C to shut down.
The Visual Studio project properties Debug tab provides a GUI to edit the launchSettings.json file:
Changes made to project profiles may not take effect until the web server is restarted. Kestrel must be restarted
before it can detect changes made to its environment.
WARNING
launchSettings.json shouldn't store secrets. The Secret Manager tool can be used to store secrets for local development.
When using Visual Studio Code, environment variables can be set in the .vscode/launch.json file. The following
example sets the environment to Development :
{
"version": "0.2.0",
"configurations": [
{
"name": ".NET Core Launch (web)",
... additional VS Code configuration settings ...
"env": {
}
}
]
}
A .vscode/launch.json file in the project isn't read when starting the app with dotnet run in the same way as
Properties/launchSettings.json. When launching an app in development that doesn't have a launchSettings.json
file, either set the environment with an environment variable or a command-line argument to the dotnet run
command.
Production
The production environment should be configured to maximize security, performance, and app robustness.
Some common settings that differ from development include:
Caching.
Client-side resources are bundled, minified, and potentially served from a CDN.
Diagnostic error pages disabled.
Friendly error pages enabled.
Production logging and monitoring enabled. For example, Application Insights.
Set the environment

It's often useful to set a specific environment for testing. If the environment isn't set, it defaults to Production ,
which disables most debugging features. The method for setting the environment depends on the operating
system.
Azure App Service
To set the environment in Azure App Service, perform the following steps:
1. Select the app from the App Services blade.
2. In the SETTINGS group, select the Application settings blade.
3. In the Application settings area, select Add new setting.
4. For Enter a name, provide ASPNETCORE_ENVIRONMENT . For Enter a value, provide the environment (for
example, Staging ).
5. Select the Slot Setting check box if you wish the environment setting to remain with the current slot when
deployment slots are swapped. For more information, see Azure Documentation: Which settings are
swapped?.
6. Select Save at the top of the blade.
Azure App Service automatically restarts the app after an app setting (environment variable) is added, changed,
or deleted in the Azure portal.
Windows
To set the ASPNETCORE_ENVIRONMENT for the current session when the app is started using dotnet run, the following
commands are used:
Command prompt
set ASPNETCORE_ENVIRONMENT=Development
PowerShell
$Env:ASPNETCORE_ENVIRONMENT = "Development"
These commands only take effect for the current window. When the window is closed, the
ASPNETCORE_ENVIRONMENT setting reverts to the default setting or machine value.
To set the value globally in Windows, use either of the following approaches:
Open the Control Panel > System > Advanced system settings and add or edit the
ASPNETCORE_ENVIRONMENT value:
Open an administrative command prompt and use the setx command or open an administrative
PowerShell command prompt and use [Environment]::SetEnvironmentVariable :
Command prompt
setx ASPNETCORE_ENVIRONMENT Development /M
The /M switch indicates to set the environment variable at the system level. If the /M switch isn't used,
the environment variable is set for the user account.
PowerShell
[Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development", "Machine")
The Machine option value indicates to set the environment variable at the system level. If the option value
is changed to User , the environment variable is set for the user account.
When the ASPNETCORE_ENVIRONMENT environment variable is set globally, it takes effect for dotnet run in any
command window opened after the value is set.
web.config
To set the ASPNETCORE_ENVIRONMENT environment variable with web.config, see the Setting environment variables
section of ASP.NET Core Module configuration reference. When the ASPNETCORE_ENVIRONMENT environment
variable is set with web.config, its value overrides a setting at the system level.
Per IIS Application Pool
To set the ASPNETCORE_ENVIRONMENT environment variable for an app running in an isolated Application Pool
(supported on IIS 10.0 or later), see the AppCmd.exe command section of the Environment Variables
<environmentVariables> topic. When the ASPNETCORE_ENVIRONMENT environment variable is set for an app pool,
its value overrides a setting at the system level.
IMPORTANT
When hosting an app in IIS and adding or changing the ASPNETCORE_ENVIRONMENT environment variable, use any one of
the following approaches to have the new value picked up by apps:
Restart an app's app pool.
Execute net stop was /y followed by net start w3svc from a command prompt.
Restart the server.
macOS
Setting the current environment for macOS can be performed in-line when running the app:
ASPNETCORE_ENVIRONMENT=Development dotnet run
Alternatively, set the environment with export prior to running the app:
export ASPNETCORE_ENVIRONMENT=Development
Machine-level environment variables are set in the .bashrc or .bash_profile file. Edit the file using any text editor.
Add the following statement:
export ASPNETCORE_ENVIRONMENT=Development
Linux
For Linux distros, use the export command at a command prompt for session-based variable settings and
bash_profile file for machine-level environment settings.
Configuration by environment
To load configuration by environment, we recommend:
appsettings files (*appsettings.<>.json). See Configuration: File configuration provider.
environment variables (set on each system where the app is hosted). See Configuration: File configuration
provider and Safe storage of app secrets in development: Environment variables.
Secret Manager (in the Development environment only). See Safe storage of app secrets in development in
ASP.NET Core.
Environment-based Startup class and methods

Startup class conventions
When an ASP.NET Core app starts, the Startup class bootstraps the app. The app can define separate Startup
classes for different environments (for example, StartupDevelopment ), and the appropriate Startup class is
selected at runtime. The class whose name suffix matches the current environment is prioritized. If a matching
Startup{EnvironmentName} class isn't found, the Startup class is used.
To implement environment-based Startup classes, create a Startup{EnvironmentName} class for each

environment in use and a fallback Startup class:
// Startup class to use in the Development environment
public class StartupDevelopment
{
{
...
}

{
...
}
}
// Startup class to use in the Production environment

public class StartupProduction
{
{
...
}

{
...
}
}
// Fallback Startup class

// Selected if the environment doesn't match a Startup{EnvironmentName} class
{
{
...
}

{
...
}
}
Use the UseStartup(IWebHostBuilder, String) overload that accepts an assembly name:

{
}
public static IWebHostBuilder CreateWebHostBuilder(string[] args)

{
var assemblyName = typeof(Startup).GetTypeInfo().Assembly.FullName;
return WebHost.CreateDefaultBuilder(args)
.UseStartup(assemblyName);
}
{
CreateWebHost(args).Run();
}
public static IWebHost CreateWebHost(string[] args)

{
.UseStartup(assemblyName)
.Build();
}

{
{

.UseStartup(assemblyName)
.Build();
host.Run();
}
}
Startup method conventions

Configure and ConfigureServices support environment-specific versions of the form
Configure<EnvironmentName> and Configure<EnvironmentName>Services :
{
{
}

{
StartupConfigureServices(services);
}
public void ConfigureStagingServices(IServiceCollection services)

{
StartupConfigureServices(services);
}
private void StartupConfigureServices(IServiceCollection services)

{
{
});
services.AddMvc()
}

{
{
}
if (env.IsProduction() || env.IsStaging() || env.IsEnvironment("Staging_2"))

{
app.UseHsts();
}
app.UseMvc();
}
public void ConfigureStaging(IApplicationBuilder app, IHostingEnvironment env)

{
if (!env.IsStaging())
{
throw new Exception("Not staging.");
}
app.UseHsts();
app.UseMvc();
}
}
IHostingEnvironment.EnvironmentName
By Luke Latham
App configuration in ASP.NET Core is based on key-value pairs established by configuration providers.
Configuration providers read configuration data into key-value pairs from a variety of configuration sources:
Azure Key Vault
Command-line arguments
Custom providers (installed or created)
Directory files
Environment variables
In-memory .NET objects
Settings files
Azure Key Vault
Settings files
Settings files
The options pattern is an extension of the configuration concepts described in this topic. Options uses classes to
represent groups of related settings. For more information on using the options pattern, see Options pattern in
ASP.NET Core.
The examples provided in this topic rely upon:
Setting the base path of the app with SetBasePath. SetBasePath is made available to an app by referencing the
Microsoft.Extensions.Configuration.FileExtensions package.
Resolving sections of configuration files with GetSection. GetSection is made available to an app by referencing
the Microsoft.Extensions.Configuration package.
Binding configuration to .NET classes with Bind and Get<T>. Bind and Get<T> are made available to an app
by referencing the Microsoft.Extensions.Configuration.Binder package. Get<T> is available in ASP.NET Core 1.1
or later.
These three packages are included in the Microsoft.AspNetCore.App metapackage.
These three packages are included in the Microsoft.AspNetCore.All metapackage.
Host vs. app configuration

Before the app is configured and started, a host is configured and launched. The host is responsible for app startup
and lifetime management. Both the app and the host are configured using the configuration providers described in
this topic. Host configuration key-value pairs become part of the app's global configuration. For more information
on how the configuration providers are used when the host is built and how configuration sources affect host
configuration, see Host in ASP.NET Core.
Security
Adopt the following best practices:
Never store passwords or other sensitive data in configuration provider code or in plain text configuration files.
Don't use production secrets in development or test environments.
Specify secrets outside of the project so that they can't be accidentally committed to a source code repository.
Learn more about how to use multiple environments and managing the safe storage of app secrets in development
with the Secret Manager (includes advice on using environment variables to store sensitive data). The Secret
Manager uses the File Configuration Provider to store user secrets in a JSON file on the local system. The File
Configuration Provider is described later in this topic.
Azure Key Vault is one option for the safe storage of app secrets. For more information, see Azure Key Vault
configuration provider in ASP.NET Core.
Hierarchical configuration data

The Configuration API is capable of maintaining hierarchical configuration data by flattening the hierarchical data
with the use of a delimiter in the configuration keys.
In the following JSON file, four keys exist in a structured hierarchy of two sections:
{
"section0": {
"key0": "value",
"key1": "value"
},
"section1": {
"key0": "value",
"key1": "value"
}
}
When the file is read into configuration, unique keys are created to maintain the original hierarchical data structure
of the configuration source. The sections and keys are flattened with the use of a colon ( : ) to maintain the original
structure:
section0:key0
section0:key1
section1:key0
section1:key1
GetSection and GetChildren methods are available to isolate sections and children of a section in the configuration
data. These methods are described later in GetSection, GetChildren, and Exists.
Conventions
At app startup, configuration sources are read in the order that their configuration providers are specified.
File Configuration Providers have the ability to reload configuration when an underlying settings file is changed
after app startup. The File Configuration Provider is described later in this topic.
IConfiguration is available in the app's Dependency Injection (DI) container. Configuration providers can't utilize DI,
as it's not available when they're set up by the host.
Configuration keys adopt the following conventions:
Keys are case-insensitive. For example, ConnectionString and connectionstring are treated as equivalent keys.
If a value for the same key is set by the same or different configuration providers, the last value set on the key is
the value used.
Hierarchical keys
Within the Configuration API, a colon separator ( : ) works on all platforms.
In environment variables, a colon separator may not work on all platforms. A double underscore ( __ ) is
supported by all platforms and is converted to a colon.
In Azure Key Vault, hierarchical keys use -- (two dashes) as a separator. You must provide code to
replace the dashes with a colon when the secrets are loaded into the app's configuration.
The ConfigurationBinder supports binding arrays to objects using array indices in configuration keys. Array
binding is described in the Bind an array to a class section.
Configuration values adopt the following conventions:
Values are strings.
Null values can't be stored in configuration or bound to objects.
Providers
The following table shows the configuration providers available to ASP.NET Core apps.
PROVIDER PROVIDES CONFIGURATION FROM…
Azure Key Vault Configuration Provider (Security topics) Azure Key Vault
Command-line Configuration Provider Command-line parameters
Custom configuration provider Custom source
Environment variables Configuration Provider Environment variables
File Configuration Provider Files (INI, JSON, XML)
Key-per-file Configuration Provider Directory files
Memory Configuration Provider In-memory collections
User secrets (Secret Manager) (Security topics) File in the user profile directory

Configuration sources are read in the order that their configuration providers are specified at startup. The
configuration providers described in this topic are described in alphabetical order, not in the order that your code
may arrange them. Order configuration providers in your code to suit your priorities for the underlying
configuration sources.
A typical sequence of configuration providers is:
1. Files (appsettings.json, appsettings.<Environment>.json, where <Environment> is the app's current hosting
environment)
2. User secrets (Secret Manager) (in the Development environment only)
3. Environment variables
4. Command-line arguments
It's a common practice to position the Command-line Configuration Provider last in a series of providers to allow
command-line arguments to override configuration set by the other providers.
This sequence of providers is put into place when you initialize a new WebHostBuilder with CreateDefaultBuilder.
For more information, see Web Host: Set up a host.
Call ConfigureAppConfiguration when building the Web Host to specify the app's configuration providers:
{
public static Dictionary<string, string> arrayDict = new Dictionary<string, string>
{
{"array:entries:0", "value0"},
{"array:entries:5", "value5"}
};

{
}

{
config.SetBasePath(Directory.GetCurrentDirectory());
config.AddInMemoryCollection(arrayDict);
config.AddJsonFile("json_array.json", optional: false, reloadOnChange: false);
config.AddJsonFile("starship.json", optional: false, reloadOnChange: false);
config.AddXmlFile("tvshow.xml", optional: false, reloadOnChange: false);
config.AddEFConfiguration(options => options.UseInMemoryDatabase("InMemoryDb"));
config.AddCommandLine(args);
})
}
ConfigureAppConfiguration is available in ASP.NET Core 2.1 or later.

This sequence of providers can be created for the app (not the host) with a ConfigurationBuilder and a call to its
Build method in Startup :
public Startup(IHostingEnvironment env)

{
var builder = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
.AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true,
reloadOnChange: true);
var appAssembly = Assembly.Load(new AssemblyName(env.ApplicationName));
if (appAssembly != null)
{
builder.AddUserSecrets(appAssembly, optional: true);
}
builder.AddEnvironmentVariables();
Configuration = builder.Build();
}

{
services.AddSingleton<IConfiguration>(Configuration);
}
In the preceding example, the environment name ( env.EnvironmentName ) and app assembly name (
env.ApplicationName) are provided by the IHostingEnvironment. For more information, see Use multiple
environments in ASP.NET Core.
Command-line Configuration Provider

The CommandLineConfigurationProvider loads configuration from command-line argument key-value pairs at
runtime.
To activate command-line configuration, call the AddCommandLine extension method on an instance of
ConfigurationBuilder.
AddCommandLine is automatically called when you initialize a new WebHostBuilder with CreateDefaultBuilder. For
more information, see Web Host: Set up a host.
CreateDefaultBuilder also loads:
Optional configuration from appsettings.json and appsettings.<Environment>.json.
User secrets (Secret Manager) (in the Development environment).
Environment variables.
CreateDefaultBuilder adds the Command-line Configuration Provider last. Command-line arguments passed at
runtime override configuration set by the other providers.
CreateDefaultBuilder acts when the host is constructed. Therefore, command-line configuration activated by
CreateDefaultBuilder can affect how the host is configured.
When building the host manually and not calling CreateDefaultBuilder , call the AddCommandLine extension method
on an instance of ConfigurationBuilder:
Call the provider last to allow the command-line arguments passed at runtime to override configuration set by
other configuration providers.
Apply the configuration to WebHostBuilder with the UseConfiguration method:
var config = new ConfigurationBuilder()

.AddCommandLine(args)
.Build();

.UseConfiguration(config)
.UseKestrel()
Example
The 2.x sample app takes advantage of the static convenience method CreateDefaultBuilder to build the host,
which includes a call to AddCommandLine.
The 1.x sample app calls AddCommandLine on a ConfigurationBuilder.
1. Open a command prompt in the project's directory.
2. Supply a command-line argument to the dotnet run command, dotnet run CommandLineKey=CommandLineValue .
3. After the app is running, open a browser to the app at http://localhost:5000 .
4. Observe that the output contains the key-value pair for the configuration command-line argument provided to
dotnet run .
Arguments
The value must follow an equals sign ( = ), or the key must have a prefix ( -- or / ) when the value follows a space.
The value can be null if an equals sign is used (for example, CommandLineKey= ).
KEY PREFIX EXAMPLE
No prefix CommandLineKey1=value1
Two dashes ( -- ) --CommandLineKey2=value2 , --CommandLineKey2 value2
Forward slash ( / ) /CommandLineKey3=value3 , /CommandLineKey3 value3
Within the same command, don't mix command-line argument key-value pairs that use an equals sign with key-
value pairs that use a space.
Example commands:
dotnet run CommandLineKey1=value --CommandLineKey2=value /CommandLineKey2=value

dotnet run --CommandLineKey1 value /CommandLineKey2 value
dotnet run CommandLineKey1= CommandLineKey2=value
Switch mappings
Switch mappings allow key name replacement logic. When you manually build configuration with a
ConfigurationBuilder, you can provide a dictionary of switch replacements to the AddCommandLine method.
When the switch mappings dictionary is used, the dictionary is checked for a key that matches the key provided by
a command-line argument. If the command-line key is found in the dictionary, the dictionary value (the key
replacement) is passed back to set the key-value pair into the app's configuration. A switch mapping is required for
any command-line key prefixed with a single dash ( - ).
Switch mappings dictionary key rules:
Switches must start with a dash ( - ) or double-dash ( -- ).
The switch mappings dictionary must not contain duplicate keys.
{
{
}

{
var switchMappings = new Dictionary<string, string>
{
{ "-CLKey1", "CommandLineKey1" },
{ "-CLKey2", "CommandLineKey2" }
};

.AddCommandLine(args, switchMappings)
.Build();
return WebHost.CreateDefaultBuilder()
}
}
As shown in the preceding example, the call to CreateDefaultBuilder shouldn't pass arguments when switch
mappings are used. CreateDefaultBuilder method's AddCommandLine call doesn't include mapped switches, and
there's no way to pass the switch mapping dictionary to CreateDefaultBuilder . If the arguments include a mapped
switch and are passed to CreateDefaultBuilder , its AddCommandLine provider fails to initialize with a
FormatException. The solution is not to pass the arguments to CreateDefaultBuilder but instead to allow the
ConfigurationBuilder method's AddCommandLine method to process both the arguments and the switch mapping
dictionary.

{
{
};

.Build();

.UseKestrel()
.Start();
using (host)
{
Console.ReadLine();
}
}
After the switch mappings dictionary is created, it contains the data shown in the following table.
KEY VALUE
-CLKey1 CommandLineKey1
If the switch-mapped keys are used when starting the app, configuration receives the configuration value on the
key supplied by the dictionary:
dotnet run -CLKey1=value1 -CLKey2=value2
After running the preceding command, configuration contains the values shown in the following table.
KEY VALUE
CommandLineKey1 value1
Environment Variables Configuration Provider

The EnvironmentVariablesConfigurationProvider loads configuration from environment variable key-value pairs at
runtime.
To activate environment variables configuration, call the AddEnvironmentVariables extension method on an
instance of ConfigurationBuilder.
When working with hierarchical keys in environment variables, a colon separator ( : ) may not work on all
platforms. A double underscore ( __ ) is supported by all platforms and is replaced by a colon.
Azure App Service permits you to set environment variables in the Azure Portal that can override app configuration
using the Environment Variables Configuration Provider. For more information, see Azure Apps: Override app
configuration using the Azure Portal.
AddEnvironmentVariables is automatically called when you initialize a new WebHostBuilder with
CreateDefaultBuilder. For more information, see Web Host: Set up a host.
Command-line arguments.
The Environment Variable Configuration Provider is called after configuration is established from user secrets and
appsettings files. Calling the provider in this position allows the environment variables read at runtime to override
configuration set by user secrets and appsettings files.
You can also directly call the AddEnvironmentVariables extension method on an instance of ConfigurationBuilder:
.AddEnvironmentVariables()
.Build();

.UseKestrel()
Example
which includes a call to AddEnvironmentVariables .
The 1.x sample app calls AddEnvironmentVariables on a ConfigurationBuilder .
1. Run the sample app. Open a browser to the app at http://localhost:5000 .
2. Observe that the output contains the key-value pair for the environment variable ENVIRONMENT . The value
reflects the environment in which the app is running, typically Development when running locally.
To keep the list of environment variables rendered by the app short, the app filters environment variables to those
that start with the following:
ASPNETCORE_
urls
Logging
ENVIRONMENT
contentRoot
AllowedHosts
applicationName
CommandLine
If you wish to expose all of the environment variables available to the app, change the FilteredConfiguration in
Pages/Index.cshtml.cs to the following:
If you wish to expose all of the environment variables available to the app, change the FilteredConfiguration in
Controllers/HomeController.cs to the following:
FilteredConfiguration = _config.AsEnumerable();
Prefixes
Environment variables loaded into the app's configuration are filtered when you supply a prefix to the
AddEnvironmentVariables method. For example, to filter environment variables on the prefix CUSTOM_ , supply the
prefix to the configuration provider:

.AddEnvironmentVariables("CUSTOM_")
.Build();
The prefix is stripped off when the configuration key-value pairs are created.
The static convenience method CreateDefaultBuilder creates a WebHostBuilder to establish the app's host. When
WebHostBuilder is created, it finds its host configuration in environment variables prefixed with ASPNETCORE_ .
Connection string prefixes

The Configuration API has special processing rules for four connection string environment variables involved in
configuring Azure connection strings for the app environment. Environment variables with the prefixes shown in
the table are loaded into the app if no prefix is supplied to AddEnvironmentVariables .
CONNECTION STRING PREFIX PROVIDER
CUSTOMCONNSTR_ Custom provider
MYSQLCONNSTR_ MySQL
SQLAZURECONNSTR_ Azure SQL Database
SQLCONNSTR_ SQL Server
When an environment variable is discovered and loaded into configuration with any of the four prefixes shown in
the table:
The configuration key is created by removing the environment variable prefix and adding a configuration key
section ( ConnectionStrings ).
A new configuration key-value pair is created that represents the database connection provider (except for
CUSTOMCONNSTR_ , which has no stated provider ).
ENVIRONMENT VARIABLE KEY CONVERTED CONFIGURATION KEY PROVIDER CONFIGURATION ENTRY
CUSTOMCONNSTR_<KEY> ConnectionStrings:<KEY> Configuration entry not created.
MYSQLCONNSTR_<KEY> ConnectionStrings:<KEY> Key:

ConnectionStrings:
<KEY>_ProviderName
:
Value: MySql.Data.MySqlClient
SQLAZURECONNSTR_<KEY> ConnectionStrings:<KEY> Key:

ConnectionStrings:
<KEY>_ProviderName
:
Value: System.Data.SqlClient
SQLCONNSTR_<KEY> ConnectionStrings:<KEY> Key:

ConnectionStrings:
<KEY>_ProviderName
:
File Configuration Provider

FileConfigurationProvider is the base class for loading configuration from the file system. The following
configuration providers are dedicated to specific file types:
INI Configuration Provider
JSON Configuration Provider
XML Configuration Provider
The IniConfigurationProvider loads configuration from INI file key-value pairs at runtime.
To activate INI file configuration, call the AddIniFile extension method on an instance of ConfigurationBuilder.
The colon can be used to as a section delimiter in INI file configuration.
Overloads permit specifying:
Whether the file is optional.
Whether the configuration is reloaded if the file changes.
The IFileProvider used to access the file.
When calling CreateDefaultBuilder , call UseConfiguration with the configuration:

{
{
}

{
.AddIniFile("config.ini", optional: true, reloadOnChange: true)
.Build();
}
}
When creating a WebHostBuilder directly, call UseConfiguration with the configuration:


.Build();

.UseKestrel()
A generic example of an INI configuration file:

[section0]
key0=value
key1=value
[section1]
subsection:key=value
[section2:subsection0]
key=value
key=value
The previous configuration file loads the following keys with value :
section0:key0
section0:key1
section1:subsection:key
section2:subsection0:key
The JsonConfigurationProvider loads configuration from JSON file key-value pairs during runtime.
To activate JSON file configuration, call the AddJsonFile extension method on an instance of ConfigurationBuilder.
AddJsonFile is automatically called twice when you initialize a new WebHostBuilder with CreateDefaultBuilder.
The method is called to load configuration from:
appsettings.json – This file is read first. The environment version of the file can override the values provided by
the appsettings.json file.
appsettings.<Environment>.json – The environment version of the file is loaded based on the
IHostingEnvironment.EnvironmentName.
The JSON Configuration Provider is established first. Therefore, user secrets, environment variables, and
command-line arguments override configuration set by the appsettings files.
You can also directly call the AddJsonFile extension method on an instance of ConfigurationBuilder.
{
{
}

{
.AddJsonFile("config.json", optional: true, reloadOnChange: true)
.Build();
}
}


.Build();

.UseKestrel()
Example
which includes two calls to AddJsonFile . Configuration is loaded from appsettings.json and appsettings.
<Environment>.json.
The 1.x sample app calls AddJsonFile twice on a ConfigurationBuilder . Configuration is loaded from
appsettings.json and appsettings.<Environment>.json.
2. Observe that the output contains key-value pairs for the configuration shown in the table depending on the
environment. Logging configuration keys use the colon ( : ) as a hierarchical separator.
KEY DEVELOPMENT VALUE PRODUCTION VALUE
Logging:LogLevel:System Information Information
Logging:LogLevel:Microsoft Information Information
Logging:LogLevel:Default Debug Error
AllowedHosts * *

The XmlConfigurationProvider loads configuration from XML file key-value pairs at runtime.
To activate XML file configuration, call the AddXmlFile extension method on an instance of ConfigurationBuilder.
The root node of the configuration file is ignored when the configuration key-value pairs are created. Don't specify
a Document Type Definition (DTD ) or namespace in the file.

{
{
}

{
.AddXmlFile("config.xml", optional: true, reloadOnChange: true)
.Build();
}
}


.Build();

.UseKestrel()
XML configuration files can use distinct element names for repeating sections:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<section0>
<key0>value</key0>
<key1>value</key1>
</section0>
<section1>
<key0>value</key0>
<key1>value</key1>
</section1>
</configuration>
section0:key0
section0:key1
section1:key0
section1:key1
Repeating elements that use the same element name work if the name attribute is used to distinguish the elements:

<configuration>
<section name="section0">
<key name="key0">value</key>
</section>
</section>
</configuration>
section:section0:key:key0
Attributes can be used to supply values:

<configuration>
<key attribute="value" />
<section>
</section>
</configuration>
key:attribute
section:key:attribute
Key-per-file Configuration Provider

The KeyPerFileConfigurationProvider uses a directory's files as configuration key-value pairs. The key is the file
name. The value contains the file's contents. The Key-per-file Configuration Provider is used in Docker hosting
scenarios.
To activate key-per-file configuration, call the AddKeyPerFile extension method on an instance of
ConfigurationBuilder. The directoryPath to the files must be an absolute path.
An Action<KeyPerFileConfigurationSource> delegate that configures the source.
Whether the directory is optional and the path to the directory.

{
{
}

{
var path = Path.Combine(Directory.GetCurrentDirectory(), "path/to/files");
.AddKeyPerFile(directoryPath: path, optional: true)
.Build();
}
}

.Build();

.UseKestrel()
Memory Configuration Provider

The MemoryConfigurationProvider uses an in-memory collection as configuration key-value pairs.
To activate in-memory collection configuration, call the AddInMemoryCollection extension method on an instance
of ConfigurationBuilder.
The configuration provider can be initialized with an IEnumerable<KeyValuePair<String,String>> .
{
{
}

{
var dict = new Dictionary<string, string>
{
{"MemoryCollectionKey1", "value1"},
{"MemoryCollectionKey2", "value2"}
};

.AddInMemoryCollection(dict)
.Build();
}
}


{
};

.Build();

.UseKestrel()
GetValue
ConfigurationBinder.GetValue<T> extracts a value from configuration with a specified key and converts it to the
specified type. An overload permits you to provide a default value if the key isn't found.
The following example extracts the string value from configuration with the key NumberKey , types the value as an
int , and stores the value in the variable intValue . If NumberKey isn't found in the configuration keys, intValue
receives the default value of 99 :
var intValue = config.GetValue<int>("NumberKey", 99);
GetSection, GetChildren, and Exists

For the examples that follow, consider the following JSON file. Four keys are found across two sections, one of
which includes a pair of subsections:
{
"section0": {
"key0": "value",
"key1": "value"
},
"section1": {
"key0": "value",
"key1": "value"
},
"section2": {
"subsection0" : {
"key0": "value",
"key1": "value"
},
"subsection1" : {
"key0": "value",
"key1": "value"
}
}
}
When the file is read into configuration, the following unique hierarchical keys are created to hold the configuration
values:
section0:key0
section0:key1
section1:key0
section1:key1
section2:subsection0:key0
GetSection
IConfiguration.GetSection extracts a configuration subsection with the specified subsection key.
To return an IConfigurationSection containing only the key-value pairs in section1 , call GetSection and supply the
section name:
var configSection = _config.GetSection("section1");
Similarly, to obtain the values for keys in section2:subsection0 , call GetSection and supply the section path:
var configSection = _config.GetSection("section2:subsection0");
GetSection never returns null . If a matching section isn't found, an empty IConfigurationSection is returned.
GetChildren
A call to IConfiguration.GetChildren on section2 obtains an IEnumerable<IConfigurationSection> that includes:
subsection0
subsection1
var children = configSection.GetChildren();
Exists
Use ConfigurationExtensions.Exists to determine if a configuration section exists:
var sectionExists = _config.GetSection("section2:subsection2").Exists();
Given the example data, sectionExists is false because there isn't a section2:subsection2 section in the
configuration data.
Bind to a class
Configuration can be bound to classes that represent groups of related settings using the options pattern. For more
information, see Options pattern in ASP.NET Core.
Configuration values are returned as strings, but calling Bind enables the construction of POCO objects.
The sample app contains a Starship model (Models/Starship.cs):
public class Starship

{
public string Registry { get; set; }
public string Class { get; set; }
public decimal Length { get; set; }
public bool Commissioned { get; set; }
}

{
}
The starship section of the starship.json file creates the configuration when the sample app uses the JSON
Configuration Provider to load the configuration:
{
"starship": {
"name": "USS Enterprise",
"registry": "NCC-1701",
"class": "Constitution",
"length": 304.8,
"commissioned": false
},
"trademark": "Paramount Pictures Corp. http://www.paramount.com"
}
{
"starship": {
"length": 304.8,
},
}
The following configuration key-value pairs are created:
KEY VALUE
starship:name USS Enterprise
starship:registry NCC-1701
starship:class Constitution
starship:length 304.8
starship:commissioned False
trademark Paramount Pictures Corp. http://www.paramount.com
The sample app calls GetSection with the starship key. The starship key-value pairs are isolated. The Bind
method is called on the subsection passing in an instance of the Starship class. After binding the instance values,
the instance is assigned to a property for rendering:
var starship = new Starship();

_config.GetSection("starship").Bind(starship);
Starship = starship;

viewModel.Starship = starship;
Bind to an object graph

Bind is capable of binding an entire POCO object graph.
The sample contains a TvShow model whose object graph includes Metadata and Actors classes
(Models/TvShow.cs):
public class TvShow
{
public Metadata Metadata { get; set; }
public Actors Actors { get; set; }
public string Legal { get; set; }
}
public class Metadata

{
public string Series { get; set; }
public DateTime AirDate { get; set; }
public int Episodes { get; set; }
}
public class Actors

{
public string Names { get; set; }
}
public class TvShow

{
}

{
}
public class Actors

{
}
The sample app has a tvshow.xml file containing the configuration data:

<configuration>
<tvshow>
<metadata>
<series>Dr. Who</series>
<title>The Sun Makers</title>
<airdate>11/26/1977</airdate>
<episodes>4</episodes>
</metadata>
<actors>
<names>Tom Baker, Louise Jameson, John Leeson</names>
</actors>
<legal>(c)1977 BBC https://www.bbc.co.uk/programmes/b006q2x0</legal>
</tvshow>
</configuration>
<configuration>
<tvshow>
<metadata>
</metadata>
<actors>
</actors>
</tvshow>
</configuration>
Configuration is bound to the entire TvShow object graph with the Bind method. The bound instance is assigned
to a property for rendering:
var tvShow = new TvShow();

_config.GetSection("tvshow").Bind(tvShow);
TvShow = tvShow;

viewModel.TvShow = tvShow;
ConfigurationBinder.Get<T> binds and returns the specified type. Get<T> is more convenient than using Bind .
The following code shows how to use Get<T> with the preceding example, which allows the bound instance to be
directly assigned to the property used for rendering:
TvShow = _config.GetSection("tvshow").Get<TvShow>();
viewModel.TvShow = _config.GetSection("tvshow").Get<TvShow>();
Bind an array to a class

The sample app demonstrates the concepts explained in this section.
The Bind supports binding arrays to objects using array indices in configuration keys. Any array format that
exposes a numeric key segment ( :0: , :1: , … :{n}: ) is capable of array binding to a POCO class array.
NOTE
Binding is provided by convention. Custom configuration providers aren't required to implement array binding.
In-memory array processing

Consider the configuration keys and values shown in the following table.
KEY VALUE
array:0 value0
KEY VALUE
array:1 value1
array:2 value2
array:4 value4
array:5 value5
These keys and values are loaded in the sample app using the Memory Configuration Provider:

{
{
};

{
}

{
})
}
{
{
var arrayDict = new Dictionary<string, string>
{
};

.AddInMemoryCollection(arrayDict)
.AddJsonFile("json_array.json", optional: false, reloadOnChange: false)
reloadOnChange: true)
.AddJsonFile("starship.json", optional: false, reloadOnChange: false)
.AddXmlFile("tvshow.xml", optional: false, reloadOnChange: false)
.AddEFConfiguration(options => options.UseInMemoryDatabase("InMemoryDb"))
.AddCommandLine(Program.Args);
}
The array skips a value for index #3. The configuration binder isn't capable of binding null values or creating null
entries in bound objects, which becomes clear in a moment when the result of binding this array to an object is
demonstrated.
In the sample app, a POCO class is available to hold the bound configuration data:
public class ArrayExample

{
public string[] Entries { get; set; }
}

{
}
The configuration data is bound to the object:
var arrayExample = new ArrayExample();

_config.GetSection("array").Bind(arrayExample);
ConfigurationBinder.Get<T> syntax can also be used, which results in more compact code:
ArrayExample = _config.GetSection("array").Get<ArrayExample>();
viewModel.ArrayExample = _config.GetSection("array").Get<ArrayExample>();
The bound object, an instance of ArrayExample , receives the array data from configuration.
ARRAYEXAMPLES.ENTRIES INDEX ARRAYEXAMPLES.ENTRIES VALUE
0 value0
1 value1
2 value2
3 value4
4 value5
Index #3 in the bound object holds the configuration data for the array:4 configuration key and its value of
value4 . When configuration data containing an array is bound, the array indices in the configuration keys are
merely used to iterate the configuration data when creating the object. A null value can't be retained in
configuration data, and a null-valued entry isn't created in a bound object when an array in configuration keys skip
one or more indices.
The missing configuration item for index #3 can be supplied before binding to the ArrayExamples instance by any
configuration provider that produces the correct key-value pair in configuration. If the sample included an
additional JSON Configuration Provider with the missing key-value pair, the ArrayExamples.Entries matches the
complete configuration array:
missing_value.json:
{
"array:entries:3": "value3"
}
In ConfigureAppConfiguration :
config.AddJsonFile("missing_value.json", optional: false, reloadOnChange: false);
In the Startup constructor:
.AddJsonFile("missing_value.json", optional: false, reloadOnChange: false);
The key-value pair shown in the table is loaded into configuration.
KEY VALUE
array:entries:3 value3
If the ArrayExamples class instance is bound after the JSON Configuration Provider includes the entry for index #3,
the ArrayExamples.Entries array includes the value.
0 value0
1 value1
2 value2
3 value3
4 value4
5 value5
JSON array processing

If a JSON file contains an array, configuration keys are created for the array elements with a zero-based section
index. In the following configuration file, subsection is an array:
{
"json_array": {
"key": "valueA",
"subsection": [
"valueB",
"valueC",
"valueD"
]
}
}
{
"json_array": {
"key": "valueA",
"subsection": [
"valueB",
"valueC",
"valueD"
]
}
}
The JSON Configuration Provider reads the configuration data into the following key-value pairs:
KEY VALUE
json_array:key valueA
json_array:subsection:0 valueB
json_array:subsection:1 valueC
json_array:subsection:2 valueD
In the sample app, the following POCO class is available to bind the configuration key-value pairs:
public class JsonArrayExample
{
public string Key { get; set; }
public string[] Subsection { get; set; }
}

{
}
After binding, JsonArrayExample.Key holds the value valueA . The subsection values are stored in the POCO array
property, Subsection .
JSONARRAYEXAMPLE.SUBSECTION INDEX JSONARRAYEXAMPLE.SUBSECTION VALUE
0 valueB
1 valueC
2 valueD
Custom configuration provider

The sample app demonstrates how to create a basic configuration provider that reads configuration key-value pairs
from a database using Entity Framework (EF ).
The provider has the following characteristics:
The EF in-memory database is used for demonstration purposes. To use a database that requires a connection
string, implement a secondary ConfigurationBuilder to supply the connection string from another configuration
provider.
The provider reads a database table into configuration at startup. The provider doesn't query the database on a
per-key basis.
Reload-on-change isn't implemented, so updating the database after the app starts has no effect on the app's
configuration.
Define an EFConfigurationValue entity for storing configuration values in the database.
Models/EFConfigurationValue.cs:
public class EFConfigurationValue

{
public string Id { get; set; }
public string Value { get; set; }
}

{
}
Add an EFConfigurationContext to store and access the configured values.
EFConfigurationProvider/EFConfigurationContext.cs:
public class EFConfigurationContext : DbContext

{
public EFConfigurationContext(DbContextOptions options) : base(options)
{
}
public DbSet<EFConfigurationValue> Values { get; set; }

}

{
{
}

}
Create a class that implements IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.cs:
public class EFConfigurationSource : IConfigurationSource

{
private readonly Action<DbContextOptionsBuilder> _optionsAction;
public EFConfigurationSource(Action<DbContextOptionsBuilder> optionsAction)

{
_optionsAction = optionsAction;
}
public IConfigurationProvider Build(IConfigurationBuilder builder)

{
return new EFConfigurationProvider(_optionsAction);
}
}

{

{
}

{
}
}
Create the custom configuration provider by inheriting from ConfigurationProvider. The configuration provider
initializes the database when it's empty.
EFConfigurationProvider/EFConfigurationProvider.cs:
public class EFConfigurationProvider : ConfigurationProvider
{
public EFConfigurationProvider(Action<DbContextOptionsBuilder> optionsAction)
{
OptionsAction = optionsAction;
}
Action<DbContextOptionsBuilder> OptionsAction { get; }
// Load config data from EF DB.

public override void Load()
{
var builder = new DbContextOptionsBuilder<EFConfigurationContext>();
OptionsAction(builder);
using (var dbContext = new EFConfigurationContext(builder.Options))

{
dbContext.Database.EnsureCreated();
Data = !dbContext.Values.Any()
? CreateAndSaveDefaultValues(dbContext)
: dbContext.Values.ToDictionary(c => c.Id, c => c.Value);
}
}
private static IDictionary<string, string> CreateAndSaveDefaultValues(

EFConfigurationContext dbContext)
{
// Quotes (c)2005 Universal Pictures: Serenity
// https://www.uphe.com/movies/serenity
var configValues = new Dictionary<string, string>
{
{ "quote1", "I aim to misbehave." },
{ "quote2", "I swallowed a bug." },
{ "quote3", "You can't stop the signal, Mal." }
};
dbContext.Values.AddRange(configValues
.Select(kvp => new EFConfigurationValue
{
Id = kvp.Key,
Value = kvp.Value
})
.ToArray());
dbContext.SaveChanges();
return configValues;
}
}
{
{
}

{

{
}
}

{
{
};
{
Id = kvp.Key,
Value = kvp.Value
})
.ToArray());
}
}
An AddEFConfiguration extension method permits adding the configuration source to a ConfigurationBuilder .

Extensions/EntityFrameworkExtensions.cs:
public static class EntityFrameworkExtensions
{
public static IConfigurationBuilder AddEFConfiguration(
this IConfigurationBuilder builder,
Action<DbContextOptionsBuilder> optionsAction)
{
return builder.Add(new EFConfigurationSource(optionsAction));
}
}

{
{
}
}
The following code shows how to use the custom EFConfigurationProvider in Program.cs:

{
{
};

{
}

{
})
}
{
{
{
};

}
Access configuration during startup

Inject IConfiguration into the Startup constructor to access configuration values in Startup.ConfigureServices . To
access configuration in Startup.Configure , either inject IConfiguration directly into the method or use the instance
from the constructor:

{
public Startup(IConfiguration config)

{
_config = config;
}

{
var value = _config["key"];
}
public void Configure(IApplicationBuilder app, IConfiguration config)

{
var value = config["key"];
}
}
For an example of accessing configuration using startup convenience methods, see App startup: Convenience
methods.
Access configuration in a Razor Pages page or MVC view

To access configuration settings in a Razor Pages page or an MVC view, add a using directive (C# reference: using
directive) for the Microsoft.Extensions.Configuration namespace and inject IConfiguration into the page or view.
In a Razor Pages page:
@page
@model IndexModel
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration
<!DOCTYPE html>
<html lang="en">
<head>
<title>Index Page</title>
</head>
<body>
<h1>Access configuration in a Razor Pages page</h1>
<p>Configuration value for 'key': @Configuration["key"]</p>
</body>
</html>
In an MVC view:
<!DOCTYPE html>
<html lang="en">
<head>
<title>Index View</title>
</head>
<body>
<h1>Access configuration in an MVC view</h1>
</body>
</html>
Add configuration from an external assembly

An IHostingStartup implementation allows adding enhancements to an app at startup from an external assembly
outside of the app's Startup class. For more information, see Enhance an app from an external assembly in
ASP.NET Core with IHostingStartup.
Options pattern in ASP.NET Core
Deep Dive into Microsoft Configuration
By Luke Latham
App configuration in ASP.NET Core is based on key-value pairs established by configuration providers.
Configuration providers read configuration data into key-value pairs from a variety of configuration
sources:
Azure Key Vault
Directory files
Settings files
Azure Key Vault
Settings files
Settings files
The options pattern is an extension of the configuration concepts described in this topic. Options uses
classes to represent groups of related settings. For more information on using the options pattern, see
Options pattern in ASP.NET Core.
The examples provided in this topic rely upon:
Setting the base path of the app with SetBasePath. SetBasePath is made available to an app by
referencing the Microsoft.Extensions.Configuration.FileExtensions package.
Resolving sections of configuration files with GetSection. GetSection is made available to an app by
referencing the Microsoft.Extensions.Configuration package.
Binding configuration to .NET classes with Bind and Get<T>. Bind and Get<T> are made available to
an app by referencing the Microsoft.Extensions.Configuration.Binder package. Get<T> is available in
ASP.NET Core 1.1 or later.
These three packages are included in the Microsoft.AspNetCore.App metapackage.
These three packages are included in the Microsoft.AspNetCore.All metapackage.
Host vs. app configuration
Before the app is configured and started, a host is configured and launched. The host is responsible for app
startup and lifetime management. Both the app and the host are configured using the configuration
providers described in this topic. Host configuration key-value pairs become part of the app's global
configuration. For more information on how the configuration providers are used when the host is built and
how configuration sources affect host configuration, see Host in ASP.NET Core.
Security
Adopt the following best practices:
Never store passwords or other sensitive data in configuration provider code or in plain text
configuration files.
Don't use production secrets in development or test environments.
Specify secrets outside of the project so that they can't be accidentally committed to a source code
repository.
Learn more about how to use multiple environments and managing the safe storage of app secrets in
development with the Secret Manager (includes advice on using environment variables to store sensitive
data). The Secret Manager uses the File Configuration Provider to store user secrets in a JSON file on the
local system. The File Configuration Provider is described later in this topic.
Azure Key Vault is one option for the safe storage of app secrets. For more information, see Azure Key Vault
configuration provider in ASP.NET Core.
Hierarchical configuration data

The Configuration API is capable of maintaining hierarchical configuration data by flattening the
hierarchical data with the use of a delimiter in the configuration keys.
In the following JSON file, four keys exist in a structured hierarchy of two sections:
{
"section0": {
"key0": "value",
"key1": "value"
},
"section1": {
"key0": "value",
"key1": "value"
}
}
When the file is read into configuration, unique keys are created to maintain the original hierarchical data
structure of the configuration source. The sections and keys are flattened with the use of a colon ( : ) to
maintain the original structure:
section0:key0
section0:key1
section1:key0
section1:key1
GetSection and GetChildren methods are available to isolate sections and children of a section in the
configuration data. These methods are described later in GetSection, GetChildren, and Exists.
Conventions
At app startup, configuration sources are read in the order that their configuration providers are specified.
File Configuration Providers have the ability to reload configuration when an underlying settings file is
changed after app startup. The File Configuration Provider is described later in this topic.
IConfiguration is available in the app's Dependency Injection (DI) container. Configuration providers can't
utilize DI, as it's not available when they're set up by the host.
Configuration keys adopt the following conventions:
Keys are case-insensitive. For example, ConnectionString and connectionstring are treated as
equivalent keys.
If a value for the same key is set by the same or different configuration providers, the last value set on
the key is the value used.
Hierarchical keys
Within the Configuration API, a colon separator ( : ) works on all platforms.
In environment variables, a colon separator may not work on all platforms. A double underscore (
__ ) is supported by all platforms and is converted to a colon.
In Azure Key Vault, hierarchical keys use -- (two dashes) as a separator. You must provide code
to replace the dashes with a colon when the secrets are loaded into the app's configuration.
The ConfigurationBinder supports binding arrays to objects using array indices in configuration keys.
Array binding is described in the Bind an array to a class section.
Configuration values adopt the following conventions:
Values are strings.
Null values can't be stored in configuration or bound to objects.
Providers
The following table shows the configuration providers available to ASP.NET Core apps.
Key-per-file Configuration Provider Directory files
Configuration sources are read in the order that their configuration providers are specified at startup. The
configuration providers described in this topic are described in alphabetical order, not in the order that your
code may arrange them. Order configuration providers in your code to suit your priorities for the
underlying configuration sources.
A typical sequence of configuration providers is:
1. Files (appsettings.json, appsettings.<Environment>.json, where <Environment> is the app's current
hosting environment)
2. User secrets (Secret Manager) (in the Development environment only)
3. Environment variables
4. Command-line arguments
It's a common practice to position the Command-line Configuration Provider last in a series of providers to
allow command-line arguments to override configuration set by the other providers.
This sequence of providers is put into place when you initialize a new WebHostBuilder with
Call ConfigureAppConfiguration when building the Web Host to specify the app's configuration providers:
{
{
};

{
}

{
})
}
ConfigureAppConfiguration is available in ASP.NET Core 2.1 or later.

This sequence of providers can be created for the app (not the host) with a ConfigurationBuilder and a call
to its Build method in Startup :

{
reloadOnChange: true);
var appAssembly = Assembly.Load(new AssemblyName(env.ApplicationName));
if (appAssembly != null)
{
builder.AddUserSecrets(appAssembly, optional: true);
}
}

{
services.AddSingleton<IConfiguration>(Configuration);
}
In the preceding example, the environment name ( env.EnvironmentName ) and app assembly name (
env.ApplicationName) are provided by the IHostingEnvironment. For more information, see Use multiple
environments in ASP.NET Core.
Command-line Configuration Provider

The CommandLineConfigurationProvider loads configuration from command-line argument key-value
pairs at runtime.
AddCommandLine is automatically called when you initialize a new WebHostBuilder with
CreateDefaultBuilder adds the Command-line Configuration Provider last. Command-line arguments
passed at runtime override configuration set by the other providers.
CreateDefaultBuilder acts when the host is constructed. Therefore, command-line configuration activated
by CreateDefaultBuilder can affect how the host is configured.
When building the host manually and not calling CreateDefaultBuilder , call the AddCommandLine extension
method on an instance of ConfigurationBuilder:
Call the provider last to allow the command-line arguments passed at runtime to override configuration set
by other configuration providers.

.Build();

.UseKestrel()
Example
The 2.x sample app takes advantage of the static convenience method CreateDefaultBuilder to build the
host, which includes a call to AddCommandLine.
The 1.x sample app calls AddCommandLine on a ConfigurationBuilder.
1. Open a command prompt in the project's directory.
2. Supply a command-line argument to the dotnet run command,
dotnet run CommandLineKey=CommandLineValue .
3. After the app is running, open a browser to the app at http://localhost:5000 .
4. Observe that the output contains the key-value pair for the configuration command-line argument
provided to dotnet run .
Arguments
The value must follow an equals sign ( = ), or the key must have a prefix ( -- or / ) when the value follows
a space. The value can be null if an equals sign is used (for example, CommandLineKey= ).
KEY PREFIX EXAMPLE
No prefix CommandLineKey1=value1
Two dashes ( -- ) --CommandLineKey2=value2 ,

--CommandLineKey2 value2
Forward slash ( / ) /CommandLineKey3=value3 , /CommandLineKey3 value3
Within the same command, don't mix command-line argument key-value pairs that use an equals sign with
key-value pairs that use a space.
Example commands:
dotnet run CommandLineKey1=value --CommandLineKey2=value /CommandLineKey2=value

dotnet run --CommandLineKey1 value /CommandLineKey2 value
dotnet run CommandLineKey1= CommandLineKey2=value
Switch mappings
Switch mappings allow key name replacement logic. When you manually build configuration with a
ConfigurationBuilder, you can provide a dictionary of switch replacements to the AddCommandLine
method.
When the switch mappings dictionary is used, the dictionary is checked for a key that matches the key
provided by a command-line argument. If the command-line key is found in the dictionary, the dictionary
value (the key replacement) is passed back to set the key-value pair into the app's configuration. A switch
mapping is required for any command-line key prefixed with a single dash ( - ).
Switch mappings dictionary key rules:
Switches must start with a dash ( - ) or double-dash ( -- ).
The switch mappings dictionary must not contain duplicate keys.
{
{
}

{
{
};

.Build();
return WebHost.CreateDefaultBuilder()
}
}
As shown in the preceding example, the call to CreateDefaultBuilder shouldn't pass arguments when
switch mappings are used. CreateDefaultBuilder method's AddCommandLine call doesn't include mapped
switches, and there's no way to pass the switch mapping dictionary to CreateDefaultBuilder . If the
arguments include a mapped switch and are passed to CreateDefaultBuilder , its AddCommandLine provider
fails to initialize with a FormatException. The solution is not to pass the arguments to CreateDefaultBuilder
but instead to allow the ConfigurationBuilder method's AddCommandLine method to process both the
arguments and the switch mapping dictionary.

{
{
};

.Build();

.UseKestrel()
.Start();
using (host)
{
Console.ReadLine();
}
}
After the switch mappings dictionary is created, it contains the data shown in the following table.
KEY VALUE
If the switch-mapped keys are used when starting the app, configuration receives the configuration value
on the key supplied by the dictionary:
dotnet run -CLKey1=value1 -CLKey2=value2
After running the preceding command, configuration contains the values shown in the following table.
KEY VALUE
Environment Variables Configuration Provider

The EnvironmentVariablesConfigurationProvider loads configuration from environment variable key-value
pairs at runtime.
To activate environment variables configuration, call the AddEnvironmentVariables extension method on an
When working with hierarchical keys in environment variables, a colon separator ( : ) may not work on all
platforms. A double underscore ( __ ) is supported by all platforms and is replaced by a colon.
Azure App Service permits you to set environment variables in the Azure Portal that can override app
configuration using the Environment Variables Configuration Provider. For more information, see Azure
Apps: Override app configuration using the Azure Portal.
AddEnvironmentVariables is automatically called when you initialize a new WebHostBuilder with
The Environment Variable Configuration Provider is called after configuration is established from user
secrets and appsettings files. Calling the provider in this position allows the environment variables read at
runtime to override configuration set by user secrets and appsettings files.
You can also directly call the AddEnvironmentVariables extension method on an instance of
ConfigurationBuilder:
.Build();

.UseKestrel()
Example
host, which includes a call to AddEnvironmentVariables .
The 1.x sample app calls AddEnvironmentVariables on a ConfigurationBuilder .
2. Observe that the output contains the key-value pair for the environment variable ENVIRONMENT . The
value reflects the environment in which the app is running, typically Development when running locally.
To keep the list of environment variables rendered by the app short, the app filters environment variables to
those that start with the following:
ASPNETCORE_
urls
Logging
ENVIRONMENT
contentRoot
AllowedHosts
applicationName
CommandLine
If you wish to expose all of the environment variables available to the app, change the
FilteredConfiguration in Pages/Index.cshtml.cs to the following:
If you wish to expose all of the environment variables available to the app, change the
FilteredConfiguration in Controllers/HomeController.cs to the following:
FilteredConfiguration = _config.AsEnumerable();
Prefixes
Environment variables loaded into the app's configuration are filtered when you supply a prefix to the
AddEnvironmentVariables method. For example, to filter environment variables on the prefix CUSTOM_ ,
supply the prefix to the configuration provider:

.AddEnvironmentVariables("CUSTOM_")
.Build();
The prefix is stripped off when the configuration key-value pairs are created.
The static convenience method CreateDefaultBuilder creates a WebHostBuilder to establish the app's host.
When WebHostBuilder is created, it finds its host configuration in environment variables prefixed with
ASPNETCORE_ .
Connection string prefixes
The Configuration API has special processing rules for four connection string environment variables
involved in configuring Azure connection strings for the app environment. Environment variables with the
prefixes shown in the table are loaded into the app if no prefix is supplied to AddEnvironmentVariables .
CONNECTION STRING PREFIX PROVIDER
CUSTOMCONNSTR_ Custom provider
MYSQLCONNSTR_ MySQL
SQLAZURECONNSTR_ Azure SQL Database
SQLCONNSTR_ SQL Server
When an environment variable is discovered and loaded into configuration with any of the four prefixes
shown in the table:
The configuration key is created by removing the environment variable prefix and adding a
configuration key section ( ConnectionStrings ).
A new configuration key-value pair is created that represents the database connection provider (except
for CUSTOMCONNSTR_ , which has no stated provider).
ENVIRONMENT VARIABLE KEY CONVERTED CONFIGURATION KEY PROVIDER CONFIGURATION ENTRY
CUSTOMCONNSTR_<KEY> ConnectionStrings:<KEY> Configuration entry not created.
MYSQLCONNSTR_<KEY> ConnectionStrings:<KEY> Key:

ConnectionStrings:
<KEY>_ProviderName
:
Value: MySql.Data.MySqlClient
SQLAZURECONNSTR_<KEY> ConnectionStrings:<KEY> Key:

ConnectionStrings:
<KEY>_ProviderName
:
SQLCONNSTR_<KEY> ConnectionStrings:<KEY> Key:

ConnectionStrings:
<KEY>_ProviderName
:
File Configuration Provider

FileConfigurationProvider is the base class for loading configuration from the file system. The following
configuration providers are dedicated to specific file types:
The IniConfigurationProvider loads configuration from INI file key-value pairs at runtime.
To activate INI file configuration, call the AddIniFile extension method on an instance of
The colon can be used to as a section delimiter in INI file configuration.

{
{
}

{
.Build();
}
}


.Build();

.UseKestrel()
A generic example of an INI configuration file:

[section0]
key0=value
key1=value
[section1]
subsection:key=value
key=value
key=value
section0:key0
section0:key1
section1:subsection:key
The JsonConfigurationProvider loads configuration from JSON file key-value pairs during runtime.
To activate JSON file configuration, call the AddJsonFile extension method on an instance of
AddJsonFile is automatically called twice when you initialize a new WebHostBuilder with
CreateDefaultBuilder. The method is called to load configuration from:
appsettings.json – This file is read first. The environment version of the file can override the values
provided by the appsettings.json file.
appsettings.<Environment>.json – The environment version of the file is loaded based on the
IHostingEnvironment.EnvironmentName.
The JSON Configuration Provider is established first. Therefore, user secrets, environment variables, and
command-line arguments override configuration set by the appsettings files.
You can also directly call the AddJsonFile extension method on an instance of ConfigurationBuilder.
{
{
}

{
.Build();
}
}


.Build();

.UseKestrel()
Example
host, which includes two calls to AddJsonFile . Configuration is loaded from appsettings.json and
appsettings.<Environment>.json.
The 1.x sample app calls AddJsonFile twice on a ConfigurationBuilder . Configuration is loaded from
appsettings.json and appsettings.<Environment>.json.
2. Observe that the output contains key-value pairs for the configuration shown in the table depending on
the environment. Logging configuration keys use the colon ( : ) as a hierarchical separator.
KEY DEVELOPMENT VALUE PRODUCTION VALUE
Logging:LogLevel:System Information Information
Logging:LogLevel:Microsoft Information Information
Logging:LogLevel:Default Debug Error
AllowedHosts * *

The XmlConfigurationProvider loads configuration from XML file key-value pairs at runtime.
To activate XML file configuration, call the AddXmlFile extension method on an instance of
The root node of the configuration file is ignored when the configuration key-value pairs are created. Don't
specify a Document Type Definition (DTD ) or namespace in the file.

{
{
}

{
.Build();
}
}


.Build();

.UseKestrel()
XML configuration files can use distinct element names for repeating sections:
<configuration>
<section0>
<key0>value</key0>
<key1>value</key1>
</section0>
<section1>
<key0>value</key0>
<key1>value</key1>
</section1>
</configuration>
section0:key0
section0:key1
section1:key0
section1:key1
Repeating elements that use the same element name work if the name attribute is used to distinguish the
elements:

<configuration>
</section>
</section>
</configuration>
Attributes can be used to supply values:

<configuration>
<section>
</section>
</configuration>
key:attribute
section:key:attribute
Key-per-file Configuration Provider

The KeyPerFileConfigurationProvider uses a directory's files as configuration key-value pairs. The key is the
file name. The value contains the file's contents. The Key-per-file Configuration Provider is used in Docker
hosting scenarios.
To activate key-per-file configuration, call the AddKeyPerFile extension method on an instance of
ConfigurationBuilder. The directoryPath to the files must be an absolute path.
An Action<KeyPerFileConfigurationSource> delegate that configures the source.
Whether the directory is optional and the path to the directory.

{
{
}

{
.Build();
}
}

.Build();

.UseKestrel()
Memory Configuration Provider

The MemoryConfigurationProvider uses an in-memory collection as configuration key-value pairs.
To activate in-memory collection configuration, call the AddInMemoryCollection extension method on an
The configuration provider can be initialized with an IEnumerable<KeyValuePair<String,String>> .
{
{
}

{
{
};

.Build();
}
}


{
};

.Build();

.UseKestrel()
GetValue
ConfigurationBinder.GetValue<T> extracts a value from configuration with a specified key and converts it
to the specified type. An overload permits you to provide a default value if the key isn't found.
The following example extracts the string value from configuration with the key NumberKey , types the value
as an int , and stores the value in the variable intValue . If NumberKey isn't found in the configuration keys,
intValue receives the default value of 99 :
var intValue = config.GetValue<int>("NumberKey", 99);
GetSection, GetChildren, and Exists

For the examples that follow, consider the following JSON file. Four keys are found across two sections,
one of which includes a pair of subsections:
{
"section0": {
"key0": "value",
"key1": "value"
},
"section1": {
"key0": "value",
"key1": "value"
},
"section2": {
"subsection0" : {
"key0": "value",
"key1": "value"
},
"subsection1" : {
"key0": "value",
"key1": "value"
}
}
}
When the file is read into configuration, the following unique hierarchical keys are created to hold the
configuration values:
section0:key0
section0:key1
section1:key0
section1:key1
GetSection
IConfiguration.GetSection extracts a configuration subsection with the specified subsection key.
To return an IConfigurationSection containing only the key-value pairs in section1 , call GetSection and
supply the section name:
Similarly, to obtain the values for keys in section2:subsection0 , call GetSection and supply the section
path:
var configSection = _config.GetSection("section2:subsection0");
GetSection never returns null . If a matching section isn't found, an empty IConfigurationSection is
returned.
GetChildren
A call to IConfiguration.GetChildren on section2 obtains an IEnumerable<IConfigurationSection> that
includes:
subsection0
subsection1
var children = configSection.GetChildren();
Exists
Use ConfigurationExtensions.Exists to determine if a configuration section exists:
var sectionExists = _config.GetSection("section2:subsection2").Exists();
Given the example data, sectionExists is false because there isn't a section2:subsection2 section in the
configuration data.
Bind to a class
Configuration can be bound to classes that represent groups of related settings using the options pattern.
For more information, see Options pattern in ASP.NET Core.
Configuration values are returned as strings, but calling Bind enables the construction of POCO objects.
The sample app contains a Starship model (Models/Starship.cs):

{
}

{
}
The starship section of the starship.json file creates the configuration when the sample app uses the JSON
Configuration Provider to load the configuration:
{
"starship": {
"length": 304.8,
},
}
{
"starship": {
"length": 304.8,
},
}
The following configuration key-value pairs are created:
KEY VALUE
starship:name USS Enterprise
starship:registry NCC-1701
starship:class Constitution
starship:length 304.8
starship:commissioned False
trademark Paramount Pictures Corp. http://www.paramount.com
The sample app calls GetSection with the starship key. The starship key-value pairs are isolated. The
Bind method is called on the subsection passing in an instance of the Starship class. After binding the
instance values, the instance is assigned to a property for rendering:

Starship = starship;

viewModel.Starship = starship;
Bind to an object graph

Bind is capable of binding an entire POCO object graph.
The sample contains a TvShow model whose object graph includes Metadata and Actors classes
(Models/TvShow.cs):
public class TvShow
{
}

{
}
public class Actors

{
}
public class TvShow

{
}

{
}
public class Actors

{
}
The sample app has a tvshow.xml file containing the configuration data:

<configuration>
<tvshow>
<metadata>
</metadata>
<actors>
</actors>
</tvshow>
</configuration>
<configuration>
<tvshow>
<metadata>
</metadata>
<actors>
</actors>
</tvshow>
</configuration>
Configuration is bound to the entire TvShow object graph with the Bind method. The bound instance is
assigned to a property for rendering:

TvShow = tvShow;

viewModel.TvShow = tvShow;
ConfigurationBinder.Get<T> binds and returns the specified type. Get<T> is more convenient than using
Bind . The following code shows how to use Get<T> with the preceding example, which allows the bound
instance to be directly assigned to the property used for rendering:
TvShow = _config.GetSection("tvshow").Get<TvShow>();
viewModel.TvShow = _config.GetSection("tvshow").Get<TvShow>();
Bind an array to a class

The sample app demonstrates the concepts explained in this section.
The Bind supports binding arrays to objects using array indices in configuration keys. Any array format that
exposes a numeric key segment ( :0: , :1: , … :{n}: ) is capable of array binding to a POCO class array.
NOTE
Binding is provided by convention. Custom configuration providers aren't required to implement array binding.
In-memory array processing

Consider the configuration keys and values shown in the following table.
KEY VALUE
array:0 value0
KEY VALUE
array:1 value1
array:2 value2
array:4 value4
array:5 value5
These keys and values are loaded in the sample app using the Memory Configuration Provider:

{
{
};

{
}

{
})
}
{
{
{
};

}
The array skips a value for index #3. The configuration binder isn't capable of binding null values or creating
null entries in bound objects, which becomes clear in a moment when the result of binding this array to an
object is demonstrated.
In the sample app, a POCO class is available to hold the bound configuration data:

{
}

{
}
The configuration data is bound to the object:
var arrayExample = new ArrayExample();

_config.GetSection("array").Bind(arrayExample);
ConfigurationBinder.Get<T> syntax can also be used, which results in more compact code:
ArrayExample = _config.GetSection("array").Get<ArrayExample>();
viewModel.ArrayExample = _config.GetSection("array").Get<ArrayExample>();
The bound object, an instance of ArrayExample , receives the array data from configuration.
0 value0
1 value1
2 value2
3 value4
4 value5
Index #3 in the bound object holds the configuration data for the array:4 configuration key and its value
of value4 . When configuration data containing an array is bound, the array indices in the configuration
keys are merely used to iterate the configuration data when creating the object. A null value can't be
retained in configuration data, and a null-valued entry isn't created in a bound object when an array in
configuration keys skip one or more indices.
The missing configuration item for index #3 can be supplied before binding to the ArrayExamples instance
by any configuration provider that produces the correct key-value pair in configuration. If the sample
included an additional JSON Configuration Provider with the missing key-value pair, the
ArrayExamples.Entries matches the complete configuration array:
missing_value.json:
{
"array:entries:3": "value3"
}
In ConfigureAppConfiguration :
config.AddJsonFile("missing_value.json", optional: false, reloadOnChange: false);
In the Startup constructor:
.AddJsonFile("missing_value.json", optional: false, reloadOnChange: false);
The key-value pair shown in the table is loaded into configuration.
KEY VALUE
array:entries:3 value3
If the ArrayExamples class instance is bound after the JSON Configuration Provider includes the entry for
index #3, the ArrayExamples.Entries array includes the value.
0 value0
1 value1
2 value2
3 value3
4 value4
5 value5
JSON array processing

If a JSON file contains an array, configuration keys are created for the array elements with a zero-based
section index. In the following configuration file, subsection is an array:
{
"json_array": {
"key": "valueA",
"subsection": [
"valueB",
"valueC",
"valueD"
]
}
}
{
"json_array": {
"key": "valueA",
"subsection": [
"valueB",
"valueC",
"valueD"
]
}
}
The JSON Configuration Provider reads the configuration data into the following key-value pairs:
KEY VALUE
json_array:key valueA
json_array:subsection:0 valueB
json_array:subsection:1 valueC
json_array:subsection:2 valueD
In the sample app, the following POCO class is available to bind the configuration key-value pairs:
{
}

{
}
After binding, JsonArrayExample.Key holds the value valueA . The subsection values are stored in the POCO
array property, Subsection .
JSONARRAYEXAMPLE.SUBSECTION INDEX JSONARRAYEXAMPLE.SUBSECTION VALUE
0 valueB
1 valueC
2 valueD
Custom configuration provider

The sample app demonstrates how to create a basic configuration provider that reads configuration key-
value pairs from a database using Entity Framework (EF ).
The provider has the following characteristics:
The EF in-memory database is used for demonstration purposes. To use a database that requires a
connection string, implement a secondary ConfigurationBuilder to supply the connection string from
another configuration provider.
The provider reads a database table into configuration at startup. The provider doesn't query the
database on a per-key basis.
Reload-on-change isn't implemented, so updating the database after the app starts has no effect on the
app's configuration.
Define an EFConfigurationValue entity for storing configuration values in the database.
Models/EFConfigurationValue.cs:

{
}

{
}
Add an EFConfigurationContext to store and access the configured values.
EFConfigurationProvider/EFConfigurationContext.cs:

{
{
}

}

{
{
}

}
Create a class that implements IConfigurationSource.

EFConfigurationProvider/EFConfigurationSource.cs:

{

{
}

{
}
}

{

{
}

{
}
}
Create the custom configuration provider by inheriting from ConfigurationProvider. The configuration
provider initializes the database when it's empty.
EFConfigurationProvider/EFConfigurationProvider.cs:
{
{
}

{

{
}
}

{
{
};
{
Id = kvp.Key,
Value = kvp.Value
})
.ToArray());
}
}
{
{
}

{

{
}
}

{
{
};
{
Id = kvp.Key,
Value = kvp.Value
})
.ToArray());
}
}
An AddEFConfiguration extension method permits adding the configuration source to a

ConfigurationBuilder .
Extensions/EntityFrameworkExtensions.cs:
{
{
}
}

{
{
}
}
The following code shows how to use the custom EFConfigurationProvider in Program.cs:

{
{
};

{
}

{
})
}
{
{
{
};

}
Access configuration during startup

Inject IConfigurationinto the Startup constructor to access configuration values in
Startup.ConfigureServices . To access configuration in Startup.Configure , either inject IConfiguration
directly into the method or use the instance from the constructor:

{
public Startup(IConfiguration config)

{
_config = config;
}

{
var value = _config["key"];
}
public void Configure(IApplicationBuilder app, IConfiguration config)

{
var value = config["key"];
}
}
For an example of accessing configuration using startup convenience methods, see App startup:
Convenience methods.
Access configuration in a Razor Pages page or MVC view

To access configuration settings in a Razor Pages page or an MVC view, add a using directive (C# reference:
using directive) for the Microsoft.Extensions.Configuration namespace and inject IConfiguration into the
page or view.
In a Razor Pages page:
@page
@model IndexModel
<!DOCTYPE html>
<html lang="en">
<head>
<title>Index Page</title>
</head>
<body>
<h1>Access configuration in a Razor Pages page</h1>
</body>
</html>
In an MVC view:
<!DOCTYPE html>
<html lang="en">
<head>
<title>Index View</title>
</head>
<body>
<h1>Access configuration in an MVC view</h1>
</body>
</html>
Add configuration from an external assembly

An IHostingStartup implementation allows adding enhancements to an app at startup from an external
assembly outside of the app's Startup class. For more information, see Enhance an app from an external
assembly in ASP.NET Core with IHostingStartup.
Deep Dive into Microsoft Configuration
By Luke Latham
The options pattern uses classes to represent groups of related settings. When configuration settings are isolated
by scenario into separate classes, the app adheres to two important software engineering principles:
The Interface Segregation Principle (ISP ): Scenarios (classes) that depend on configuration settings depend
only on the configuration settings that they use.
Separation of Concerns: Settings for different parts of the app aren't dependent or coupled to one another.
View or download sample code (how to download) This article is easier to follow with the sample app.
Prerequisites
Reference the Microsoft.AspNetCore.App metapackage or add a package reference to the
Microsoft.Extensions.Options.ConfigurationExtensions package.
Reference the Microsoft.AspNetCore.All metapackage or add a package reference to the
Microsoft.Extensions.Options.ConfigurationExtensions package.
Add a package reference to the Microsoft.Extensions.Options.ConfigurationExtensions package.
Basic options configuration

Basic options configuration is demonstrated as Example #1 in the sample app.
An options class must be non-abstract with a public parameterless constructor. The following class, MyOptions ,
has two properties, Option1 and Option2 . Setting default values is optional, but the class constructor in the
following example sets the default value of Option1 . Option2 has a default value set by initializing the property
directly (Models/MyOptions.cs):
public class MyOptions

{
public MyOptions()
{
// Set default value.
Option1 = "value1_from_ctor";
}
public string Option1 { get; set; }

public int Option2 { get; set; } = 5;
}
The MyOptions class is added to the service container with Configure<TOptions>(IServiceCollection,

IConfiguration) and bound to configuration:
// Example #1: Basic options

// Register the Configuration instance which MyOptions binds against.
services.Configure<MyOptions>(Configuration);
The following page model uses constructor dependency injection with IOptions<TOptions> to access the
settings (Pages/Index.cshtml.cs):
private readonly MyOptions _options;
public IndexModel(
IOptions<MyOptions> optionsAccessor,
IOptions<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig,
IOptions<MySubOptions> subOptionsAccessor,
IOptionsSnapshot<MyOptions> snapshotOptionsAccessor,
IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
_options = optionsAccessor.Value;
_optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.Value;
_subOptions = subOptionsAccessor.Value;
_snapshotOptions = snapshotOptionsAccessor.Value;
_named_options_1 = namedOptionsAccessor.Get("named_options_1");
}
// Example #1: Simple options

var option1 = _options.Option1;
var option2 = _options.Option2;
SimpleOptions = $"option1 = {option1}, option2 = {option2}";
The sample's appsettings.json file specifies values for option1 and option2 :
{
"option1": "value1_from_json",
"option2": -1,
"subsection": {
"suboption1": "subvalue1_from_json",
"suboption2": 200
},
"Logging": {
"LogLevel": {
}
},
"AllowedHosts": "*"
}
When the app is run, the page model's OnGet method returns a string showing the option class values:
option1 = value1_from_json, option2 = -1

NOTE
When using a custom ConfigurationBuilder to load options configuration from a settings file, confirm that the base path is
set correctly:
var configBuilder = new ConfigurationBuilder()

.AddJsonFile("appsettings.json", optional: true);
var config = configBuilder.Build();
services.Configure<MyOptions>(config);
Explicitly setting the base path isn't required when loading options configuration from the settings file via
CreateDefaultBuilder.
Configure simple options with a delegate

Configuring simple options with a delegate is demonstrated as Example #2 in the sample app.
Use a delegate to set options values. The sample app uses the MyOptionsWithDelegateConfig class
(Models/MyOptionsWithDelegateConfig.cs):
public class MyOptionsWithDelegateConfig

{
public MyOptionsWithDelegateConfig()
{
// Set default value.
Option1 = "value1_from_ctor";
}
public string Option1 { get; set; }

public int Option2 { get; set; } = 5;
}
In the following code, a second IConfigureOptions<TOptions> service is added to the service container. It uses a
delegate to configure the binding with MyOptionsWithDelegateConfig :
// Example #2: Options bound and configured by a delegate

services.Configure<MyOptionsWithDelegateConfig>(myOptions =>
{
myOptions.Option1 = "value1_configured_by_delegate";
myOptions.Option2 = 500;
});
Index.cshtml.cs:
private readonly MyOptionsWithDelegateConfig _optionsWithDelegateConfig;

public IndexModel(
{
}
// Example #2: Options configured by delegate

var delegate_config_option1 = _optionsWithDelegateConfig.Option1;
var delegate_config_option2 = _optionsWithDelegateConfig.Option2;
SimpleOptionsWithDelegateConfig =
$"delegate_option1 = {delegate_config_option1}, " +
$"delegate_option2 = {delegate_config_option2}";
You can add multiple configuration providers. Configuration providers are available in NuGet packages. They're
applied in order that they're registered.
Each call to Configure<TOptions> adds an IConfigureOptions<TOptions> service to the service container. In the
preceding example, the values of Option1 and Option2 are both specified in appsettings.json, but the values of
Option1 and Option2 are overridden by the configured delegate.
When more than one configuration service is enabled, the last configuration source specified wins and sets the
configuration value. When the app is run, the page model's OnGet method returns a string showing the option
class values:
delegate_option1 = value1_configured_by_delgate, delegate_option2 = 500
Suboptions configuration
Suboptions configuration is demonstrated as Example #3 in the sample app.
Apps should create options classes that pertain to specific scenario groups (classes) in the app. Parts of the app
that require configuration values should only have access to the configuration values that they use.
When binding options to configuration, each property in the options type is bound to a configuration key of the
form property[:sub-property:] . For example, the MyOptions.Option1 property is bound to the key Option1 ,
which is read from the option1 property in appsettings.json.
In the following code, a third IConfigureOptions<TOptions> service is added to the service container. It binds
MySubOptions to the section subsection of the appsettings.json file:
// Example #3: Sub-options

// Bind options using a sub-section of the appsettings.json file.
services.Configure<MySubOptions>(Configuration.GetSection("subsection"));
The GetSection extension method requires the Microsoft.Extensions.Options.ConfigurationExtensions NuGet

package. If the app uses the Microsoft.AspNetCore.App metapackage (ASP.NET Core 2.1 or later), the package
is automatically included.
The sample's appsettings.json file defines a subsection member with keys for suboption1 and suboption2 :
{
"option1": "value1_from_json",
"option2": -1,
"subsection": {
"suboption1": "subvalue1_from_json",
"suboption2": 200
},
"Logging": {
"LogLevel": {
}
},
"AllowedHosts": "*"
}
The MySubOptions class defines properties, SubOption1 and SubOption2 , to hold the options values
(Models/MySubOptions.cs):
public class MySubOptions

{
public MySubOptions()
{
// Set default values.
SubOption1 = "value1_from_ctor";
SubOption2 = 5;
}
public string SubOption1 { get; set; }

public int SubOption2 { get; set; }
}
The page model's OnGet method returns a string with the options values (Pages/Index.cshtml.cs):
private readonly MySubOptions _subOptions;
public IndexModel(
{
}
// Example #3: Sub-options

var subOption1 = _subOptions.SubOption1;
var subOption2 = _subOptions.SubOption2;
SubOptions = $"subOption1 = {subOption1}, subOption2 = {subOption2}";
When the app is run, the OnGet method returns a string showing the sub-option class values:
subOption1 = subvalue1_from_json, subOption2 = 200
Options provided by a view model or with direct view injection

Options provided by a view model or with direct view injection is demonstrated as Example #4 in the sample
app.
Options can be supplied in a view model or by injecting IOptions<TOptions> directly into a view
(Pages/Index.cshtml.cs):
private readonly MyOptions _options;
public IndexModel(
{
}
// Example #4: Bind options directly to the page

MyOptions = _options;
For direct injection, inject IOptions<MyOptions> with an @inject directive:
@page
@model IndexModel
@using Microsoft.Extensions.Options
@using UsingOptionsSample.Models
@inject IOptions<MyOptions> OptionsAccessor
@{
ViewData["Title"] = "Using Options Sample";
}
When the app is run, the options values are shown in the rendered page:
Reload configuration data with IOptionsSnapshot
Reloading configuration data with IOptionsSnapshot is demonstrated in Example #5 in the sample app.
IOptionsSnapshot supports reloading options with minimal processing overhead.
Options are computed once per request when accessed and cached for the lifetime of the request.
IOptionsSnapshot is a snapshot of IOptionsMonitor<TOptions> and updates automatically whenever the
monitor triggers changes based on the data source changing.
The following example demonstrates how a new IOptionsSnapshot is created after appsettings.json changes
(Pages/Index.cshtml.cs). Multiple requests to the server return constant values provided by the appsettings.json
file until the file is changed and configuration reloads.
private readonly MyOptions _snapshotOptions;
public IndexModel(
{
}
// Example #5: Snapshot options

var snapshotOption1 = _snapshotOptions.Option1;
var snapshotOption2 = _snapshotOptions.Option2;
SnapshotOptions =
$"snapshot option1 = {snapshotOption1}, " +
$"snapshot option2 = {snapshotOption2}";
The following image shows the initial option1 and option2 values loaded from the appsettings.json file:
snapshot option1 = value1_from_json, snapshot option2 = -1
Change the values in the appsettings.json file to value1_from_json UPDATED and 200 . Save the appsettings.json
file. Refresh the browser to see that the options values are updated:
snapshot option1 = value1_from_json UPDATED, snapshot option2 = 200
Named options support with IConfigureNamedOptions

Named options support with IConfigureNamedOptions is demonstrated as Example #6 in the sample app.
Named options support allows the app to distinguish between named options configurations. In the sample app,
named options are declared with the OptionsServiceCollectionExtensions.Configure<TOptions>
(IServiceCollection, String, Action<TOptions>) which in turn calls the extension method
ConfigureNamedOptions<TOptions>.Configure method:
// Example #6: Named options (named_options_1)

// Register the ConfigurationBuilder instance which MyOptions binds against.
// Specify that the options loaded from configuration are named
// "named_options_1".
services.Configure<MyOptions>("named_options_1", Configuration);
// Example #6: Named options (named_options_2)

// Specify that the options loaded from the MyOptions class are named
// "named_options_2".
// Use a delegate to configure option values.
services.Configure<MyOptions>("named_options_2", myOptions =>
{
myOptions.Option1 = "named_options_2_value1_from_action";
});
The sample app accesses the named options with IOptionsSnapshot<TOptions>.Get (Pages/Index.cshtml.cs):
private readonly MyOptions _named_options_1;

private readonly MyOptions _named_options_2;
public IndexModel(
{
}
// Example #6: Named options
var named_options_1 =
$"named_options_1: option1 = {_named_options_1.Option1}, " +
$"option2 = {_named_options_1.Option2}";
var named_options_2 =
$"named_options_2: option1 = {_named_options_2.Option1}, " +
$"option2 = {_named_options_2.Option2}";
NamedOptions = $"{named_options_1} {named_options_2}";
Running the sample app, the named options are returned:
named_options_1: option1 = value1_from_json, option2 = -1

named_options_2: option1 = named_options_2_value1_from_action, option2 = 5
named_options_1 values are provided from configuration, which are loaded from the appsettings.json file.
named_options_2 values are provided by:
The named_options_2 delegate in ConfigureServices for Option1 .
The default value for Option2 provided by the MyOptions class.
Configure all named options instances with the OptionsServiceCollectionExtensions.ConfigureAll method. The
following code configures Option1 for all named configuration instances with a common value. Add the
following code manually to the Configure method:
services.ConfigureAll<MyOptions>(myOptions =>
{
myOptions.Option1 = "ConfigureAll replacement value";
});
Running the sample app after adding the code produces the following result:
named_options_1: option1 = ConfigureAll replacement value, option2 = -1

named_options_2: option1 = ConfigureAll replacement value, option2 = 5
NOTE
All options are named instances. Existing IConfigureOption instances are treated as targeting the
Options.DefaultName instance, which is string.Empty . IConfigureNamedOptions also implements
IConfigureOptions . The default implementation of the IOptionsFactory<TOptions> (reference source has logic to use
each appropriately. The null named option is used to target all of the named instances instead of a specific named
instance (ConfigureAll and PostConfigureAll use this convention).
Options validation
Options validation allows you to validate options when options are configured. Call Validate with a validation
method that returns true if options are valid and false if they aren't valid:
// Registration
services.AddOptions<MyOptions>("optionalOptionsName")
.Configure(o => { }) // Configure the options
.Validate(o => YourValidationShouldReturnTrueIfValid(o),
"custom error");
// Consumption
var monitor = services.BuildServiceProvider()
.GetService<IOptionsMonitor<MyOptions>>();
try
{
var options = monitor.Get("optionalOptionsName");
}
catch (OptionsValidationException e)
{
// e.OptionsName returns "optionalOptionsName"
// e.OptionsType returns typeof(MyOptions)
// e.Failures returns a list of errors, which would contain
// "custom error"
}
The preceding example sets the named options instance to optionalOptionsName . The default options instance is
Options.DefaultName .
Validation runs when the options instance is created. Your options instance is guaranteed to pass validation the
first time it's accessed.
IMPORTANT
Options validation doesn't guard against options modifications after the options are initially configured and validated.
The method accepts a Func<TOptions,

Validate bool> . To fully customize validation, implement
IValidateOptions<TOptions> , which allows:
Validation of multiple options types:

class ValidateTwo : IValidateOptions<Option1>, IValidationOptions<Option2>
Validation that depends on another option type:
public DependsOnAnotherOptionValidator(IOptions<AnotherOption> options)
IValidateOptions validates:
A specific named options instance.
All options when name is null .
Return a ValidateOptionsResult from your implementation of the interface:
public interface IValidateOptions<TOptions> where TOptions : class

{
ValidateOptionsResult Validate(string name, TOptions options);
}
Eager validation (fail fast at startup) and data annotation-based validation are scheduled for a future release.
IPostConfigureOptions
Set postconfiguration with IPostConfigureOptions<TOptions>. Postconfiguration runs after all
IConfigureOptions<TOptions> configuration occurs:
services.PostConfigure<MyOptions>(myOptions =>
{
myOptions.Option1 = "post_configured_option1_value";
});
PostConfigure<TOptions> is available to post-configure named options:
services.PostConfigure<MyOptions>("named_options_1", myOptions =>

{
});
Use PostConfigureAll<TOptions> to post-configure all named configuration instances:
services.PostConfigureAll<MyOptions>(myOptions =>
{
});
Options factory, monitoring, and cache

IOptionsMonitor is used for notifications when TOptions instances change. IOptionsMonitor supports
reloadable options, change notifications, and IPostConfigureOptions .
IOptionsFactory<TOptions> is responsible for creating new options instances. It has a single Create method.
The default implementation takes all registered IConfigureOptions and IPostConfigureOptions and runs all the
configures first, followed by the post-configures. It distinguishes between IConfigureNamedOptions and
IConfigureOptions and only calls the appropriate interface.
IOptionsMonitorCache<TOptions> is used by IOptionsMonitor to cache TOptions instances. The

IOptionsMonitorCache invalidates options instances in the monitor so that the value is recomputed ( TryRemove).
Values can be manually introduced as well with TryAdd. The Clear method is used when all named instances
should be recreated on demand.
Accessing options during startup

IOptions can be used in Startup.Configure , since services are built before the Configure method executes.
public void Configure(IApplicationBuilder app, IOptions<MyOptions> optionsAccessor)

{
var option1 = optionsAccessor.Value.Option1;
}
IOptions shouldn't be used in Startup.ConfigureServices . An inconsistent options state may exist due to the
ordering of service registrations.
Logging in ASP.NET Core
By Steve Smith and Tom Dykstra

ASP.NET Core supports a logging API that works with a variety of logging providers. Built-in providers let you
send logs to one or more destinations, and you can plug in a third-party logging framework. This article shows
how to use the built-in logging API and providers in your code.
For information on stdout logging when hosting with IIS, see Troubleshoot ASP.NET Core on IIS. For
information on stdout logging with Azure App Service, see Troubleshoot ASP.NET Core on Azure App Service.
How to create logs

To create logs, implement an ILogger<TCategoryName> object from the dependency injection container:
public class TodoController : Controller

{
private readonly ITodoRepository _todoRepository;
private readonly ILogger _logger;
public TodoController(ITodoRepository todoRepository,

ILogger<TodoController> logger)
{
_todoRepository = todoRepository;
_logger = logger;
}

{

{
_logger = logger;
}
Then call logging methods on that logger object:
public IActionResult GetById(string id)

{
_logger.LogInformation(LoggingEvents.GetItem, "Getting item {ID}", id);
var item = _todoRepository.Find(id);
if (item == null)
{
_logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({ID}) NOT FOUND", id);
return NotFound();
}
return new ObjectResult(item);
}
{
if (item == null)
{
return NotFound();
}
}
This example creates logs with the TodoController class as the category. Categories are explained later in this
article.
ASP.NET Core doesn't provide async logger methods because logging should be so fast that it isn't worth the
cost of using async. If you're in a situation where that's not true, consider changing the way you log. If your data
store is slow, write the log messages to a fast store first, then move them to a slow store later. For example, log
to a message queue that's read and persisted to slow storage by another process.
How to add providers

A logging provider takes the messages that you create with an ILogger object and displays or stores them. For
example, the Console provider displays messages on the console, and the Azure App Service provider can store
them in Azure blob storage.
To use a provider, call the provider's Add<ProviderName> extension method in Program.cs:

{
var webHost = new WebHostBuilder()
.UseKestrel()
{
var env = hostingContext.HostingEnvironment;
config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
.AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, reloadOnChange:
true);
config.AddEnvironmentVariables();
})
.ConfigureLogging((hostingContext, logging) =>
{
logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
logging.AddConsole();
logging.AddDebug();
})
.Build();
webHost.Run();
}
The default project template enables the Console and Debug logging providers with a call to the
CreateDefaultBuilder extension method in Program.cs:
{
}

.Build();
A logging provider takes the messages that you create with an ILogger object and displays or stores them. For
example, the Console provider displays messages on the console, and the Azure App Service provider can store
them in Azure blob storage.
To use a provider, install its NuGet package and call the provider's extension method on an instance of
ILoggerFactory, as shown in the following example:
public void Configure(IApplicationBuilder app,

IHostingEnvironment env,
{
loggerFactory
.AddConsole()
.AddDebug();
ASP.NET Core dependency injection (DI) provides the ILoggerFactory instance. The AddConsole and AddDebug
extension methods are defined in the Microsoft.Extensions.Logging.Console and
Microsoft.Extensions.Logging.Debug packages. Each extension method calls the ILoggerFactory.AddProvider
method, passing in an instance of the provider.
NOTE
The 1.x sample app adds logging providers in the Startup.Configure method. If you want to obtain log output from
code that executes earlier, add logging providers in the Startup class constructor.
Learn more about the built-in logging providers and find links to third-party logging providers later in the
article.
Configuration
Logging provider configuration is provided by one or more configuration providers:
File formats (INI, JSON, and XML ).
In-memory .NET objects.
The unencrypted Secret Manager storage.
An encrypted user store, such as Azure Key Vault.
Custom providers (installed or created).
For example, logging configuration is commonly provided by the Logging section of app settings files. The
following example shows the contents of a typical appsettings.Development.json file:
{
"Logging": {
"LogLevel": {
"Default": "Debug",
"System": "Information",
"Microsoft": "Information"
},
"Console":
{
"IncludeScopes": true
}
}
}
LogLevel keys represent log names. The Default key applies to logs not explicitly listed. The value represents
the log level applied to the given log. Log keys that set IncludeScopes ( Console in the example), specify if log
scopes are enabled for the indicated log.
{
"Logging": {
"LogLevel": {
"Default": "Debug",
}
}
}
LogLevel keys represent log names. The Default key applies to logs not explicitly listed. The value represents
the log level applied to the given log.
For information on implementing configuration providers, see Configuration in ASP.NET Core.
Sample logging output

With the sample code shown in the preceding section, you'll see logs in the console when you run from the
command line. Here's an example of console output:
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
Request starting HTTP/1.1 GET http://localhost:5000/api/todo/0
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) -
ModelState is Valid
info: TodoApi.Controllers.TodoController[1002]
Getting item 0
warn: TodoApi.Controllers.TodoController[4000]
GetById(0) NOT FOUND
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
Executing HttpStatusCodeResult, setting HTTP status code 404
Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 42.9286ms
Request finished in 148.889ms 404
These logs were created by going to http://localhost:5000/api/todo/0 , which triggers execution of both
ILogger calls shown in the preceding section.
Here's an example of the same logs as they appear in the Debug window when you run the sample application
in Visual Studio:
Microsoft.AspNetCore.Hosting.Internal.WebHost:Information: Request starting HTTP/1.1 GET
http://localhost:53104/api/todo/0
Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker:Information: Executing action method
TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
TodoApi.Controllers.TodoController:Information: Getting item 0
TodoApi.Controllers.TodoController:Warning: GetById(0) NOT FOUND
Microsoft.AspNetCore.Mvc.StatusCodeResult:Information: Executing HttpStatusCodeResult, setting HTTP status
code 404
Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker:Information: Executed action
TodoApi.Controllers.TodoController.GetById (TodoApi) in 152.5657ms
Microsoft.AspNetCore.Hosting.Internal.WebHost:Information: Request finished in 316.3195ms 404
The logs that were created by the ILogger calls shown in the preceding section begin with
"TodoApi.Controllers.TodoController". The logs that begin with "Microsoft" categories are from ASP.NET Core.
ASP.NET Core itself and your application code are using the same logging API and the same logging providers.
The remainder of this article explains some details and options for logging.
NuGet packages
The ILogger and ILoggerFactory interfaces are in Microsoft.Extensions.Logging.Abstractions, and default
implementations for them are in Microsoft.Extensions.Logging.
Log category
A category is included with each log that you create. You specify the category when you create an ILogger
object. The category may be any string, but a convention is to use the fully qualified name of the class from
which the logs are written. For example: "TodoApi.Controllers.TodoController".
You can specify the category as a string or use an extension method that derives the category from the type. To
specify the category as a string, call CreateLogger on an ILoggerFactory instance, as shown below.

{

ILoggerFactory logger)
{
_logger = logger.CreateLogger("TodoApiSample.Controllers.TodoController");
}

{

ILoggerFactory logger)
{
_logger = logger.CreateLogger("TodoApiSample.Controllers.TodoController");
}
Most of the time, it will be easier to use ILogger<T> , as in the following example.
{

{
_logger = logger;
}

{

{
_logger = logger;
}
This is equivalent to calling CreateLogger with the fully qualified type name of T .
Log level
Each time you write a log, you specify its LogLevel. The log level indicates the degree of severity or importance.
For example, you might write an Information log when a method ends normally, a Warning log when a method
returns a 404 return code, and an Error log when you catch an unexpected exception.
In the following code example, the names of the methods (for example, LogWarning ) specify the log level. The
first parameter is the Log event ID. The second parameter is a message template with placeholders for
argument values provided by the remaining method parameters. The method parameters are explained in more
detail later in this article.

{
if (item == null)
{
return NotFound();
}
}
{
if (item == null)
{
return NotFound();
}
}
Log methods that include the level in the method name are extension methods for ILogger. Behind the scenes,
these methods call a Log method that takes a LogLevel parameter. You can call the Log method directly rather
than one of these extension methods, but the syntax is relatively complicated. For more information, see the
ILogger interface and the logger extensions source code.
ASP.NET Core defines the following log levels, ordered here from least to highest severity.
Trace = 0
For information that's valuable only to a developer debugging an issue. These messages may contain
sensitive application data and so shouldn't be enabled in a production environment. Disabled by default.
Example: Credentials: {"User":"someuser", "Password":"P@ssword"}
Debug = 1
For information that has short-term usefulness during development and debugging. Example:
Entering method Configure with flag set to true. You typically wouldn't enable Debug level logs in
production unless you are troubleshooting, due to the high volume of logs.
Information = 2
For tracking the general flow of the application. These logs typically have some long-term value. Example:
Request received for path /api/todo
Warning = 3
For abnormal or unexpected events in the application flow. These may include errors or other conditions
that don't cause the application to stop, but which may need to be investigated. Handled exceptions are a
common place to use the Warning log level. Example: FileNotFoundException for file quotes.txt.
Error = 4
For errors and exceptions that cannot be handled. These messages indicate a failure in the current activity
or operation (such as the current HTTP request), not an application-wide failure. Example log message:
Cannot insert record due to duplicate key violation.
Critical = 5
For failures that require immediate attention. Examples: data loss scenarios, out of disk space.
You can use the log level to control how much log output is written to a particular storage medium or display
window. For example, in production you might want all logs of Information level and lower to go to a volume
data store, and all logs of Warning level and higher to go to a value data store. During development, you might
normally send logs of Warning or higher severity to the console. Then when you need to troubleshoot, you can
add Debug level. The Log filtering section later in this article explains how to control which log levels a provider
handles.
The ASP.NET Core framework writes Debug level logs for framework events. The log examples earlier in this
article excluded logs below Information level, so no Debug level logs were shown. Here's an example of
console logs if you run the sample application configured to show Debug and higher logs for the console
provider.
Request starting HTTP/1.1 GET http://localhost:62555/api/todo/0
dbug: Microsoft.AspNetCore.Routing.Tree.TreeRouter[1]
Request successfully matched the route with name 'GetTodo' and template 'api/Todo/{id}'.
dbug: Microsoft.AspNetCore.Mvc.Internal.ActionSelector[2]
Action 'TodoApi.Controllers.TodoController.Update (TodoApi)' with id '089d59b6-92ec-472d-b552-
cc613dfd625d' did not match the constraint 'Microsoft.AspNetCore.Mvc.Internal.HttpMethodActionConstraint'
dbug: Microsoft.AspNetCore.Mvc.Internal.ActionSelector[2]
Action 'TodoApi.Controllers.TodoController.Delete (TodoApi)' with id 'f3476abe-4bd9-4ad3-9261-
3ead09607366' did not match the constraint 'Microsoft.AspNetCore.Mvc.Internal.HttpMethodActionConstraint'
dbug: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
Executing action TodoApi.Controllers.TodoController.GetById (TodoApi)
Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) -
ModelState is Valid
Getting item 0
dbug: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
Executed action method TodoApi.Controllers.TodoController.GetById (TodoApi), returned result
Microsoft.AspNetCore.Mvc.NotFoundResult.
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
Executing HttpStatusCodeResult, setting HTTP status code 404
Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 0.8788ms
dbug: Microsoft.AspNetCore.Server.Kestrel[9]
Connection id "0HL6L7NEFF2QD" completed keep alive response.
Request finished in 2.7286ms 404
Log event ID
Each time you write a log, you can specify an event ID. The sample app does this by using a locally-defined
LoggingEvents class:

{
if (item == null)
{
return NotFound();
}
}
public class LoggingEvents
{
public const int GenerateItems = 1000;
public const int ListItems = 1001;
public const int GetItem = 1002;
public const int InsertItem = 1003;
public const int UpdateItem = 1004;
public const int DeleteItem = 1005;
public const int GetItemNotFound = 4000;

public const int UpdateItemNotFound = 4001;
}

{
if (item == null)
{
return NotFound();
}
}
public class LoggingEvents

{
public const int GenerateItems = 1000;
public const int ListItems = 1001;
public const int GetItem = 1002;
public const int InsertItem = 1003;
public const int UpdateItem = 1004;
public const int DeleteItem = 1005;
public const int GetItemNotFound = 4000;

public const int UpdateItemNotFound = 4001;
}
An event ID is an integer value that you can use to associate a set of logged events with one another. For
instance, a log for adding an item to a shopping cart could be event ID 1000 and a log for completing a
purchase could be event ID 1001.
In logging output, the event ID may be stored in a field or included in the text message, depending on the
provider. The Debug provider doesn't show event IDs, but the console provider shows them in brackets after the
category:
Getting item invalidid
GetById(invalidid) NOT FOUND
Log message template

Each time you write a log message, you provide a message template. The message template can be a string or it
can contain named placeholders into which argument values are placed. The template isn't a format string, and
placeholders should be named, not numbered.
{
if (item == null)
{
return NotFound();
}
}

{
if (item == null)
{
return NotFound();
}
}
The order of placeholders, not their names, determines which parameters are used to provide their values. If you
have the following code:
string p1 = "parm1";
string p2 = "parm2";
_logger.LogInformation("Parameter values: {p2}, {p1}", p1, p2);
The resulting log message looks like this:
Parameter values: parm1, parm2
The logging framework does message formatting in this way to make it possible for logging providers to
implement semantic logging, also known as structured logging. Because the arguments themselves are passed
to the logging system, not just the formatted message template, logging providers can store the parameter
values as fields in addition to the message template. If you're directing your log output to Azure Table Storage
and your logger method call looks like this:
_logger.LogInformation("Getting item {ID} at {RequestTime}", id, DateTime.Now);
Each Azure Table entity can have ID and RequestTime properties, which simplifies queries on log data. You can
find all logs within a particular RequestTime range without the need to parse the time out of the text message.
Logging exceptions
The logger methods have overloads that let you pass in an exception, as in the following example:
{
_logger.LogWarning(LoggingEvents.GetItemNotFound, ex, "GetById({ID}) NOT FOUND", id);
return NotFound();
}

{
_logger.LogWarning(LoggingEvents.GetItemNotFound, ex, "GetById({ID}) NOT FOUND", id);
return NotFound();
}
Different providers handle the exception information in different ways. Here's an example of Debug provider
output from the code shown above.
TodoApi.Controllers.TodoController:Warning: GetById(036dd898-fb01-47e8-9a65-f92eb73cf924) NOT FOUND
System.Exception: Item not found exception.

at TodoApi.Controllers.TodoController.GetById(String id) in
C:\logging\sample\src\TodoApi\Controllers\TodoController.cs:line 226
Log filtering
You can specify a minimum log level for a specific provider and category or for all providers or all categories.
Any logs below the minimum level aren't passed to that provider, so they don't get displayed or stored.
If you want to suppress all logs, you can specify LogLevel.None as the minimum log level. The integer value of
LogLevel.None is 6, which is higher than LogLevel.Critical (5 ).
Create filter rules in configuration

The project templates create code that calls CreateDefaultBuilder to set up logging for the Console and Debug
providers. The CreateDefaultBuilder method also sets up logging to look for configuration in a Logging
section, using code like the following:
{
var webHost = new WebHostBuilder()
.UseKestrel()
{
var env = hostingContext.HostingEnvironment;
.AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, reloadOnChange:
true);
config.AddEnvironmentVariables();
})
{
logging.AddDebug();
})
.Build();
webHost.Run();
}
The configuration data specifies minimum log levels by provider and category, as in the following example:
{
"Logging": {
"Debug": {
"LogLevel": {
"Default": "Information"
}
},
"Console": {
"LogLevel": {
"Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
"Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
"Microsoft.AspNetCore.Mvc.Razor": "Error",
"Default": "Information"
}
},
"LogLevel": {
"Default": "Debug"
}
}
}
This JSON creates six filter rules, one for the Debug provider, four for the Console provider, and one that applies
to all providers. You'll see later how just one of these rules is chosen for each provider when an ILogger object
is created.
Filter rules in code
You can register filter rules in code, as shown in the following example:
.ConfigureLogging(logging =>
logging.AddFilter("System", LogLevel.Debug)
.AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Trace))
.Build();
The second AddFilter specifies the Debug provider by using its type name. The first AddFilter applies to all
providers because it doesn't specify a provider type.
How filtering rules are applied
The configuration data and the AddFilter code shown in the preceding examples create the rules shown in the
following table. The first six come from the configuration example and the last two come from the code example.
CATEGORIES THAT BEGIN

NUMBER PROVIDER WITH ... MINIMUM LOG LEVEL
1 Debug All categories Information
2 Console Microsoft.AspNetCore.Mvc. Warning

Razor.Internal
3 Console Microsoft.AspNetCore.Mvc. Debug

Razor.Razor
4 Console Microsoft.AspNetCore.Mvc. Error

Razor
5 Console All categories Information
6 All providers All categories Debug
7 All providers System Debug
8 Debug Microsoft Trace
When you create an ILogger object to write logs with, the ILoggerFactory object selects a single rule per
provider to apply to that logger. All messages written by that ILogger object are filtered based on the selected
rules. The most specific rule possible for each provider and category pair is selected from the available rules.
The following algorithm is used for each provider when an ILogger is created for a given category:
Select all rules that match the provider or its alias. If none are found, select all rules with an empty provider.
From the result of the preceding step, select rules with longest matching category prefix. If none are found,
select all rules that don't specify a category.
If multiple rules are selected take the last one.
If no rules are selected, use MinimumLevel .
For example, suppose you have the preceding list of rules and you create an ILogger object for category
"Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine":
For the Debug provider, rules 1, 6, and 8 apply. Rule 8 is most specific, so that's the one selected.
For the Console provider, rules 3, 4, 5, and 6 apply. Rule 3 is most specific.
When you create logs with an ILogger for category "Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine", logs
of Trace level and above will go to the Debug provider, and logs of Debug level and above will go to the
Console provider.
Provider aliases
You can use the type name to specify a provider in configuration, but each provider defines a shorter alias that's
easier to use. For the built-in providers, use the following aliases:
Console
Debug
EventLog
AzureAppServices
TraceSource
EventSource
Default minimum level
There's a minimum level setting that takes effect only if no rules from configuration or code apply for a given
provider and category. The following example shows how to set the minimum level:
.ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
.Build();
If you don't explicitly set the minimum level, the default value is Information , which means that Trace and
Debug logs are ignored.
Filter functions
You can write code in a filter function to apply filtering rules. A filter function is invoked for all providers and
categories that don't have rules assigned to them by configuration or code. Code in the function has access to
the provider type, category, and log level to decide whether or not a message should be logged. For example:
.ConfigureLogging(logBuilder =>
{
logBuilder.AddFilter((provider, category, logLevel) =>
{
if (provider == "Microsoft.Extensions.Logging.Console.ConsoleLoggerProvider" &&
category == "TodoApiSample.Controllers.TodoController")
{
return false;
}
return true;
});
})
.Build();
Some logging providers let you specify when logs should be written to a storage medium or ignored based on
log level and category.
The AddConsole and AddDebug extension methods provide overloads that let you pass in filtering criteria. The
following sample code causes the console provider to ignore logs below Warning level, while the Debug
provider ignores logs that the framework creates.
{
loggerFactory
.AddConsole(LogLevel.Warning)
.AddDebug((category, logLevel) => (category.Contains("TodoApi") && logLevel >= LogLevel.Trace));
The AddEventLog method has an overload that takes an EventLogSettings instance, which may contain a
filtering function in its Filter property. The TraceSource provider doesn't provide any of those overloads, since
its logging level and other parameters are based on the SourceSwitch and TraceListener it uses.
You can set filtering rules for all providers that are registered with an ILoggerFactory instance by using the
WithFilter extension method. The example below limits framework logs (category begins with "Microsoft" or
"System") to warnings while letting the app log at debug level.

{
loggerFactory
.WithFilter(new FilterLoggerSettings
{
{ "Microsoft", LogLevel.Warning },
{ "System", LogLevel.Warning },
{ "ToDoApi", LogLevel.Debug }
})
.AddConsole()
.AddDebug();
If you want to use filtering to prevent all logs from being written for a particular category, you can specify
LogLevel.None as the minimum log level for that category. The integer value of LogLevel.None is 6, which is
higher than LogLevel.Critical (5).
The WithFilter extension method is provided by the Microsoft.Extensions.Logging.Filter NuGet package. The
method returns a new ILoggerFactory instance that will filter the log messages passed to all logger providers
registered with it. It doesn't affect any other ILoggerFactory instances, including the original ILoggerFactory
instance.
Log scopes
You can group a set of logical operations within a scope in order to attach the same data to each log that's
created as part of that set. For example, you might want every log created as part of processing a transaction to
include the transaction ID.
A scope is an IDisposable type that's returned by the ILogger.BeginScope<TState> method and lasts until it's
disposed. You use a scope by wrapping your logger calls in a using block, as shown here:
{
TodoItem item;
using (_logger.BeginScope("Message attached to logs created in the using block"))
{
item = _todoRepository.Find(id);
if (item == null)
{
return NotFound();
}
}
}
The following code enables scopes for the console provider:

Program.cs:

{
logging.AddConsole(options => options.IncludeScopes = true);
logging.AddDebug();
})
NOTE
Configuring the IncludeScopes console logger option is required to enable scope-based logging.
For information on configuration, see the Configuration section.
Program.cs:

{
logging.AddConsole(options => options.IncludeScopes = true);
logging.AddDebug();
})
NOTE
Configuring the IncludeScopes console logger option is required to enable scope-based logging.
Startup.cs:

{
loggerFactory
.AddConsole(includeScopes: true)
.AddDebug();
Each log message includes the scoped information:

=> RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApi.Controllers.TodoController.GetById
(TodoApi) => Message attached to logs created in the using block
Getting item 0
=> RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApi.Controllers.TodoController.GetById
(TodoApi) => Message attached to logs created in the using block
Built-in logging providers

ASP.NET Core ships the following providers:
Console
Debug
EventSource
EventLog
TraceSource
Azure App Service
Console provider
The Microsoft.Extensions.Logging.Console provider package sends log output to the console.
loggerFactory.AddConsole();
AddConsole overloads let you pass in an a minimum log level, a filter function, and a boolean that indicates
whether scopes are supported. Another option is to pass in an IConfiguration object, which can specify scopes
support and logging levels.
If you are considering the console provider for use in production, be aware that it has a significant impact on
performance.
When you create a new project in Visual Studio, the AddConsole method looks like this:
loggerFactory.AddConsole(Configuration.GetSection("Logging"));
This code refers to the Logging section of the appSettings.json file:
{
"Logging": {
"Console": {
"IncludeScopes": false
},
"LogLevel": {
"Default": "Debug",
}
}
}
The settings shown limit framework logs to warnings while allowing the app to log at debug level, as explained
in the Log filtering section. For more information, see Configuration.
Debug provider
The Microsoft.Extensions.Logging.Debug provider package writes log output by using the
System.Diagnostics.Debug class ( Debug.WriteLine method calls).
On Linux, this provider writes logs to /var/log/message.
logging.AddDebug();
loggerFactory.AddDebug();
AddDebug overloads let you pass in a minimum log level or a filter function.
EventSource provider
For apps that target ASP.NET Core 1.1.0 or later, the Microsoft.Extensions.Logging.EventSource provider
package can implement event tracing. On Windows, it uses ETW. The provider is cross-platform, but there are
no event collection and display tools yet for Linux or macOS.
logging.AddEventSourceLogger();
loggerFactory.AddEventSourceLogger();
A good way to collect and view logs is to use the PerfView utility. There are other tools for viewing ETW logs,
but PerfView provides the best experience for working with the ETW events emitted by ASP.NET.
To configure PerfView for collecting events logged by this provider, add the string
*Microsoft-Extensions-Logging to the Additional Providers list. ( Don't miss the asterisk at the start of the
string.)
Windows EventLog provider

The Microsoft.Extensions.Logging.EventLog provider package sends log output to the Windows Event Log.
logging.AddEventLog();
loggerFactory.AddEventLog();
AddEventLog overloads let you pass in EventLogSettings or a minimum log level.

TraceSource provider
The Microsoft.Extensions.Logging.TraceSource provider package uses the System.Diagnostics.TraceSource
libraries and providers.
logging.AddTraceSource(sourceSwitchName);
loggerFactory.AddTraceSource(sourceSwitchName);
AddTraceSource overloads let you pass in a source switch and a trace listener.
To use this provider, an application has to run on the .NET Framework (rather than .NET Core). The provider lets
you route messages to a variety of listeners, such as the TextWriterTraceListener used in the sample application.
The following example configures a TraceSource provider that logs Warning and higher messages to the
console window.

{
loggerFactory
.AddDebug();
// add Trace Source logging

var testSwitch = new SourceSwitch("sourceSwitch", "Logging Sample");
testSwitch.Level = SourceLevels.Warning;
loggerFactory.AddTraceSource(testSwitch,
new TextWriterTraceListener(writer: Console.Out));
Azure App Service provider

The Microsoft.Extensions.Logging.AzureAppServices provider package writes logs to text files in an Azure App
Service app's file system and to blob storage in an Azure Storage account. The provider package is available for
apps targeting .NET Core 1.1 or later.
If targeting .NET Core, note the following points:
The provider package is included in the ASP.NET Core Microsoft.AspNetCore.All metapackage but not in the
Microsoft.AspNetCore.App metapackage.
Don't explicitly call AddAzureWebAppDiagnostics. The provider is automatically made available to the app
when the app is deployed to Azure App Service.
If targeting .NET Framework or referencing the Microsoft.AspNetCore.App metapackage, add the provider
package to the project. Invoke AddAzureWebAppDiagnostics on an ILoggerFactory instance:
logging.AddAzureWebAppDiagnostics();
loggerFactory.AddAzureWebAppDiagnostics();
An AddAzureWebAppDiagnostics overload lets you pass in AzureAppServicesDiagnosticsSettings with which

you can override default settings, such as the logging output template, blob name, and file size limit. (Output
template is a message template that's applied to all logs on top of the one that you provide when you call an
ILogger method.)
When you deploy to an App Service app, the app honors the settings in the Diagnostic Logs section of the App
Service page of the Azure portal. When these settings are updated, the changes take effect immediately without
requiring a restart or redeployment of the app.
The default location for log files is in the D:\home\LogFiles\Application folder, and the default file name is
diagnostics-yyyymmdd.txt. The default file size limit is 10 MB, and the default maximum number of files retained
is 2. The default blob name is {app -name}{timestamp }/yyyy/mm/dd/hh/{guid }-applicationLog.txt. For more
information about default behavior, see AzureAppServicesDiagnosticsSettings.
The provider only works when the project runs in the Azure environment. It has no effect when the project is run
locally—it doesn't write to local files or local development storage for blobs.
Third-party logging providers

Third-party logging frameworks that work with ASP.NET Core:
elmah.io (GitHub repo)
Gelf (GitHub repo)
JSNLog (GitHub repo)
KissLog.net (GitHub repo)
Loggr (GitHub repo)
NLog (GitHub repo)
Serilog (GitHub repo)
Some third-party frameworks can perform semantic logging, also known as structured logging.
Using a third-party framework is similar to using one of the built-in providers:
1. Add a NuGet package to your project.
2. Call an extension method on ILoggerFactory .
For more information, see each framework's documentation.
Azure log streaming

Azure log streaming enables you to view log activity in real time from:
The application server
The web server
Failed request tracing
To configure Azure log streaming:
Navigate to the Diagnostics Logs page from your application's portal page
Set Application Logging (Filesystem ) to on.
Navigate to the Log Streaming page to view application messages. They're logged by application through the
ILogger interface.
Azure Application Insights trace logging
The Application Insights SDK is capable of collecting trace telemetry from logs generated via the ASP.NET Core
logging infrastructure. For more information, see Application Insights for ASP.NET Core and
Microsoft/ApplicationInsights-aspnetcore Wiki: Logging.
High-performance logging with LoggerMessage in ASP.NET Core
High-performance logging with LoggerMessage in
ASP.NET Core
By Luke Latham
LoggerMessage features create cacheable delegates that require fewer object allocations and reduced
computational overhead compared to logger extension methods, such as LogInformation , LogDebug , and
LogError . For high-performance logging scenarios, use the LoggerMessage pattern.
LoggerMessage provides the following performance advantages over Logger extension methods:
Logger extension methods require "boxing" (converting) value types, such as int , into object . The
LoggerMessage pattern avoids boxing by using static Action fields and extension methods with strongly-typed
parameters.
Logger extension methods must parse the message template (named format string) every time a log message
is written. LoggerMessage only requires parsing a template once when the message is defined.
The sample app demonstrates LoggerMessage features with a basic quote tracking system. The app adds and
deletes quotes using an in-memory database. As these operations occur, log messages are generated using the
LoggerMessage pattern.
LoggerMessage.Define
Define(LogLevel, EventId, String) creates an Action delegate for logging a message. Define overloads permit
passing up to six type parameters to a named format string (template).
The string provided to the Define method is a template and not an interpolated string. Placeholders are filled in
the order that the types are specified. Placeholder names in the template should be descriptive and consistent
across templates. They serve as property names within structured log data. We recommend Pascal casing for
placeholder names. For example, {Count} , {FirstName} .
Each log message is an Action held in a static field created by LoggerMessage.Define . For example, the sample app
creates a field to describe a log message for a GET request for the Index page (Internal/LoggerExtensions.cs):
private static readonly Action<ILogger, Exception> _indexPageRequested;
For the Action , specify:

The log level.
A unique event identifier (EventId) with the name of the static extension method.
The message template (named format string).
A request for the Index page of the sample app sets the:
Log level to Information .
Event id to 1 with the name of the IndexPageRequested method.
Message template (named format string) to a string.
_indexPageRequested = LoggerMessage.Define(
LogLevel.Information,
new EventId(1, nameof(IndexPageRequested)),
"GET request for Index page");
Structured logging stores may use the event name when it's supplied with the event id to enrich logging. For
example, Serilog uses the event name.
The Action is invoked through a strongly-typed extension method. The IndexPageRequested method logs a
message for an Index page GET request in the sample app:
public static void IndexPageRequested(this ILogger logger)

{
_indexPageRequested(logger, null);
}
IndexPageRequested is called on the logger in the OnGetAsync method in Pages/Index.cshtml.cs:

{
_logger.IndexPageRequested();
Quotes = await _db.Quotes.AsNoTracking().ToListAsync();

}
Inspect the app's console output:
info: LoggerMessageSample.Pages.IndexModel[1]
=> RequestId:0HL90M6E7PHK4:00000001 RequestPath:/ => /Index
GET request for Index page
To pass parameters to a log message, define up to six types when creating the static field. The sample app logs a
string when adding a quote by defining a string type for the Action field:
private static readonly Action<ILogger, string, Exception> _quoteAdded;
The delegate's log message template receives its placeholder values from the types provided. The sample app
defines a delegate for adding a quote where the quote parameter is a string :
_quoteAdded = LoggerMessage.Define<string>(
new EventId(2, nameof(QuoteAdded)),
"Quote added (Quote = '{Quote}')");
The static extension method for adding a quote, QuoteAdded , receives the quote argument value and passes it to
the Action delegate:
public static void QuoteAdded(this ILogger logger, string quote)

{
_quoteAdded(logger, quote, null);
}
In the Index page's page model (Pages/Index.cshtml.cs), QuoteAdded is called to log the message:
public async Task<IActionResult> OnPostAddQuoteAsync()
{
_db.Quotes.Add(Quote);
_logger.QuoteAdded(Quote.Text);
}
Inspect the app's console output:
=> RequestId:0HL90M6E7PHK5:0000000A RequestPath:/ => /Index
Quote added (Quote = 'You can avoid reality, but you cannot avoid the consequences of avoiding reality.
- Ayn Rand')
The sample app implements a try – catch pattern for quote deletion. An informational message is logged for a
successful delete operation. An error message is logged for a delete operation when an exception is thrown. The
log message for the unsuccessful delete operation includes the exception stack trace (Internal/LoggerExtensions.cs):
private static readonly Action<ILogger, string, int, Exception> _quoteDeleted;

private static readonly Action<ILogger, int, Exception> _quoteDeleteFailed;
_quoteDeleted = LoggerMessage.Define<string, int>(

new EventId(4, nameof(QuoteDeleted)),
"Quote deleted (Quote = '{Quote}' Id = {Id})");
_quoteDeleteFailed = LoggerMessage.Define<int>(
LogLevel.Error,
new EventId(5, nameof(QuoteDeleteFailed)),
"Quote delete failed (Id = {Id})");
Note how the exception is passed to the delegate in QuoteDeleteFailed :
public static void QuoteDeleted(this ILogger logger, string quote, int id)
{
_quoteDeleted(logger, quote, id, null);
}
public static void QuoteDeleteFailed(this ILogger logger, int id, Exception ex)
{
_quoteDeleteFailed(logger, id, ex);
}
In the page model for the Index page, a successful quote deletion calls the QuoteDeleted method on the logger.
When a quote isn't found for deletion, an ArgumentNullException is thrown. The exception is trapped by the try –
catch statement and logged by calling the QuoteDeleteFailed method on the logger in the catch block
(Pages/Index.cshtml.cs):
public async Task<IActionResult> OnPostDeleteQuoteAsync(int id)
{
var quote = await _db.Quotes.FindAsync(id);
// DO NOT use this approach in production code!

// You should check quote to see if it's null before removing
// it and saving changes to the database. A try-catch is used
// here for demonstration purposes of LoggerMessage features.
try
{
_db.Quotes.Remove(quote);
_logger.QuoteDeleted(quote.Text, id);
}
catch (ArgumentNullException ex)
{
_logger.QuoteDeleteFailed(id, ex);
}
}
When a quote is successfully deleted, inspect the app's console output:
Quote deleted (Quote = 'You can avoid reality, but you cannot avoid the consequences of avoiding
reality. - Ayn Rand' Id = 1)
When quote deletion fails, inspect the app's console output. Note that the exception is included in the log message:
fail: LoggerMessageSample.Pages.IndexModel[5]
Quote delete failed (Id = 999)
System.ArgumentNullException: Value cannot be null.
Parameter name: entity
at Microsoft.EntityFrameworkCore.Utilities.Check.NotNull[T](T value, String parameterName)
at Microsoft.EntityFrameworkCore.DbContext.Remove[TEntity](TEntity entity)
at Microsoft.EntityFrameworkCore.Internal.InternalDbSet`1.Remove(TEntity entity)
at LoggerMessageSample.Pages.IndexModel.<OnPostDeleteQuoteAsync>d__14.MoveNext() in
<PATH>\sample\Pages\Index.cshtml.cs:line 87
LoggerMessage.DefineScope
DefineScope(String) creates a Func delegate for defining a log scope. DefineScope overloads permit passing up to
three type parameters to a named format string (template).
As is the case with the Define method, the string provided to the DefineScope method is a template and not an
interpolated string. Placeholders are filled in the order that the types are specified. Placeholder names in the
template should be descriptive and consistent across templates. They serve as property names within structured
log data. We recommend Pascal casing for placeholder names. For example, {Count} , {FirstName} .
Define a log scope to apply to a series of log messages using the DefineScope(String) method.
The sample app has a Clear All button for deleting all of the quotes in the database. The quotes are deleted by
removing them one at a time. Each time a quote is deleted, the QuoteDeleted method is called on the logger. A log
scope is added to these log messages.
Enable IncludeScopes in the console logger section of appsettings.json:
{
"Logging": {
"Console": {
"IncludeScopes": true
},
"LogLevel": {
}
},
"AllowedHosts": "*"
}
To create a log scope, add a field to hold a Func delegate for the scope. The sample app creates a field called
_allQuotesDeletedScope ( Internal/LoggerExtensions.cs):
private static Func<ILogger, int, IDisposable> _allQuotesDeletedScope;
Use DefineScope to create the delegate. Up to three types can be specified for use as template arguments when
the delegate is invoked. The sample app uses a message template that includes the number of deleted quotes (an
int type):
_allQuotesDeletedScope = LoggerMessage.DefineScope<int>("All quotes deleted (Count = {Count})");
Provide a static extension method for the log message. Include any type parameters for named properties that
appear in the message template. The sample app takes in a count of quotes to delete and returns
_allQuotesDeletedScope :
public static IDisposable AllQuotesDeletedScope(this ILogger logger, int count)

{
return _allQuotesDeletedScope(logger, count);
}
The scope wraps the logging extension calls in a using block:
public async Task<IActionResult> OnPostDeleteAllQuotesAsync()

{
var quoteCount = await _db.Quotes.CountAsync();
using (_logger.AllQuotesDeletedScope(quoteCount))
{
foreach (Quote quote in _db.Quotes)
{
_db.Quotes.Remove(quote);
_logger.QuoteDeleted(quote.Text, quote.Id);
}
}
}
Inspect the log messages in the app's console output. The following result shows three quotes deleted with the log
scope message included:
=> RequestId:0HL90M6E7PHK5:0000002E RequestPath:/ => /Index => All quotes deleted (Count = 3)
Quote deleted (Quote = 'Quote 1' Id = 2)
Logging
Handle errors in ASP.NET Core
By Steve Smith and Tom Dykstra

This article covers common approaches to handling errors in ASP.NET Core apps.
The Developer Exception Page

To configure an app to display a page that shows detailed information about exceptions, use the Developer
Exception Page. The page is made available by the Microsoft.AspNetCore.Diagnostics package, which is available
in the Microsoft.AspNetCore.App metapackage. Add a line to the Startup.Configure method:
Exception Page. The page is made available by the Microsoft.AspNetCore.Diagnostics package, which is available
in the Microsoft.AspNetCore.All metapackage. Add a line to the Startup.Configure method:
Exception Page. The page is made available by adding a package reference for the
Microsoft.AspNetCore.Diagnostics package in the project file. Add a line to the Startup.Configure method:

{
env.EnvironmentName = EnvironmentName.Production;
{
}
else
{
app.UseExceptionHandler("/error");
}
Place the call to UseDeveloperExceptionPage in front of any middleware where you want to catch exceptions,
such as app.UseMvc .
WARNING
Enable the Developer Exception Page only when the app is running in the Development environment. You don't want
to share detailed exception information publicly when the app runs in production. Learn more about configuring
environments.
To see the Developer Exception Page, run the sample app with the environment set to Development and add
?throw=true to the base URL of the app. The page includes several tabs with information about the exception
and the request. The first tab includes a stack trace:
The next tab shows the query string parameters, if any:
If the request has cookies, they appear on the Cookies tab. Headers are seen in the last tab:
Configure a custom exception handling page
Configure an exception handler page to use when the app isn't running in the Development environment:

{
env.EnvironmentName = EnvironmentName.Production;
{
}
else
{
}
In a Razor Pages app, the dotnet new Razor Pages template provides an Error page and an error PageModel class
in the Pages folder.
In an MVC app, don't decorate the error handler action method with HTTP method attributes, such as HttpGet .
Explicit verbs prevent some requests from reaching the method. Allow anonymous access to the method so that
unauthenticated users are able to receive the error view.
For example, the following error handler method is provided by the dotnet new MVC template and appears in
the Home controller:
[AllowAnonymous]
public IActionResult Error()
{
return View(new ErrorViewModel
{ RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier });
}
Configure status code pages

By default, an app doesn't provide a rich status code page for HTTP status codes, such as 404 Not Found. To
provide status code pages, use Status Code Pages Middleware.
The middleware is made available by the Microsoft.AspNetCore.Diagnostics package, which is available in the
The middleware is made available by the Microsoft.AspNetCore.Diagnostics package, which is available in the
Microsoft.AspNetCore.All metapackage.
The middleware is made available by adding a package reference for the Microsoft.AspNetCore.Diagnostics
package in the project file.
Add a line to the Startup.Configure method:
app.UseStatusCodePages();
UseStatusCodePages should be called before request handling middlewares in the pipeline (for example, Static
Files Middleware and MVC Middleware).
By default, Status Code Pages Middleware adds text-only handlers for common status codes, such as 404:
The middleware supports several extension methods. One method takes a lambda expression:
// Expose the members of the 'Microsoft.AspNetCore.Http' namespace

// at the top of the file:
app.UseStatusCodePages(async context =>
{
context.HttpContext.Response.ContentType = "text/plain";
await context.HttpContext.Response.WriteAsync(
"Status code page, status code: " +
context.HttpContext.Response.StatusCode);
});
Another method takes a content type and format string:
app.UseStatusCodePages("text/plain", "Status code page, status code: {0}");
There are also redirect and re-execute extension methods. The redirect method sends a 302 Found status code to
the client and redirects the client to the provided location URL template. The template may include a {0}
placeholder for the status code. URLs starting with ~ have the base path prepended. A URL that doesn't start
with ~ is used as is.
app.UseStatusCodePagesWithRedirects("/error/{0}");
The re-execute method returns the original status code to the client and specifies that the response body should
be generated by re-executing the request pipeline using an alternate path. This path may contain a {0}
placeholder for the status code:
app.UseStatusCodePagesWithReExecute("/error/{0}");
Status code pages can be disabled for specific requests in a Razor Pages handler method or in an MVC controller.
To disable status code pages, attempt to retrieve the IStatusCodePagesFeature from the request's
HttpContext.Features collection and disable the feature if it's available:
var statusCodePagesFeature = HttpContext.Features.Get<IStatusCodePagesFeature>();
if (statusCodePagesFeature != null)
{
statusCodePagesFeature.Enabled = false;
}
If using a UseStatusCodePages* overload that points to an endpoint within the app, create an MVC view or Razor
Page for the endpoint. For example, the dotnet new template for a Razor Pages app produces the following page
and page model class:
Error.cshtml:
@page
@model ErrorModel
@{
ViewData["Title"] = "Error";
}
<h1 class="text-danger">Error.</h1>
<h2 class="text-danger">An error occurred while processing your request.</h2>
@if (Model.ShowRequestId)
{
<p>
<strong>Request ID:</strong> <code>@Model.RequestId</code>
</p>
}
<h3>Development Mode</h3>
<p>
Swapping to <strong>Development</strong> environment will display more detailed
information about the error that occurred.
</p>
<p>
<strong>Development environment should not be enabled in deployed applications
</strong>, as it can result in sensitive information from exceptions being
displayed to end users. For local debugging, development environment can be
enabled by setting the <strong>ASPNETCORE_ENVIRONMENT</strong> environment
variable to <strong>Development</strong>, and restarting the application.
</p>
Error.cshtml.cs:
public class ErrorModel : PageModel

{
public string RequestId { get; set; }
public bool ShowRequestId => !string.IsNullOrEmpty(RequestId);
[ResponseCache(Duration = 0, Location = ResponseCacheLocation.None,

NoStore = true)]
public void OnGet()
{
RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier;
}
}
Exception-handling code
Code in exception handling pages can throw exceptions. It's often a good idea for production error pages to
consist of purely static content.
Also, be aware that once the headers for a response have been sent, you can't change the response's status code,
nor can any exception pages or handlers run. The response must be completed or the connection aborted.
Server exception handling

In addition to the exception handling logic in your app, the server hosting your app performs some exception
handling. If the server catches an exception before the headers are sent, the server sends a 500 Internal Server
Error response with no body. If the server catches an exception after the headers have been sent, the server
closes the connection. Requests that aren't handled by your app are handled by the server. Any exception that
occurs is handled by the server's exception handling. Any configured custom error pages or exception handling
middleware or filters don't affect this behavior.
Startup exception handling

Only the hosting layer can handle exceptions that take place during app startup. Using the Web Host, you can
configure how the host behaves in response to errors during startup with the captureStartupErrors and
detailedErrors keys.
Hosting can only show an error page for a captured startup error if the error occurs after host address/port
binding. If any binding fails for any reason, the hosting layer logs a critical exception, the dotnet process crashes,
and no error page is displayed when the app is running on the Kestrel server.
When running on IIS or IIS Express, a 502.5 Process Failure is returned by the ASP.NET Core Module if the
process can't be started. For information on troubleshooting startup issues when hosting with IIS, see
Troubleshoot ASP.NET Core on IIS. For information on troubleshooting startup issues with Azure App Service,
see Troubleshoot ASP.NET Core on Azure App Service.
ASP.NET Core MVC error handling

MVC apps have some additional options for handling errors, such as configuring exception filters and performing
model validation.
Exception filters
Exception filters can be configured globally or on a per-controller or per-action basis in an MVC app. These filters
handle any unhandled exception that occurs during the execution of a controller action or another filter. These
filters aren't called otherwise. To learn more, see Filters.
TIP
Exception filters are good for trapping exceptions that occur within MVC actions, but they're not as flexible as error
handling middleware. Generally prefer the use of middleware, and use filters only where you need to perform error
handling differently based on which MVC action is chosen.
Handling model state errors

Model validation occurs prior to invoking each controller action, and it's the action method's responsibility to
inspect ModelState.IsValid and react appropriately.
Some apps choose to follow a standard convention for dealing with model validation errors, in which case a filter
may be an appropriate place to implement such a policy. You should test how your actions behave with invalid
model states. Learn more in Test controller logic.
Common errors reference for Azure App Service and IIS with ASP.NET Core
.NET apps configure and launch a host. The host is responsible for app startup and lifetime management. Two
host APIs are available for use:
Web Host – Suitable for hosting web apps.
Generic Host (ASP.NET Core 2.1 or later) – Suitable for hosting non-web apps (for example, apps that run
background tasks). In a future release, the Generic Host will be suitable for hosting any kind of app,
including web apps. The Generic Host will eventually replace the Web Host.
For hosting ASP.NET Core web apps, developers should use the Web Host based on IWebHostBuilder. For
hosting non-web apps, developers should use the Generic Host based on HostBuilder.
Background tasks with hosted services in ASP.NET Core
Learn how to implement background tasks with hosted services in ASP.NET Core.
Enhance an app from an external assembly in ASP.NET Core with IHostingStartup
Discover how to enhance an ASP.NET Core app from a referenced or unreferenced assembly using an
IHostingStartup implementation.
ASP.NET Core Web Host
By Luke Latham
ASP.NET Core apps configure and launch a host. The host is responsible for app startup and lifetime
management. At a minimum, the host configures a server and a request processing pipeline. This topic covers the
ASP.NET Core Web Host (IWebHostBuilder), which is useful for hosting web apps. For coverage of the .NET
Generic Host (IHostBuilder), see .NET Generic Host.
Set up a host
Create a host using an instance of IWebHostBuilder. This is typically performed in the app's entry point, the Main
method. In the project templates, Main is located in Program.cs. A typical Program.cs calls CreateDefaultBuilder
to start setting up a host:

{
{
}

}
CreateDefaultBuilder performs the following tasks:

Configures Kestrel as the web server and configures the server using the app's hosting configuration
providers. For the Kestrel default options, see Kestrel web server implementation in ASP.NET Core.
Sets the content root to the path returned by Directory.GetCurrentDirectory.
Loads host configuration from:
Environment variables prefixed with ASPNETCORE_ (for example, ASPNETCORE_ENVIRONMENT ).
Loads app configuration from:
appsettings.json.
appsettings.{Environment}.json.
User secrets when the app runs in the Development environment using the entry assembly.
Configures logging for console and debug output. Logging includes log filtering rules specified in a Logging
configuration section of an appsettings.json or appsettings.{Environment}.json file.
When running behind IIS, enables IIS integration. Configures the base path and port the server listens on
when using the ASP.NET Core Module. The module creates a reverse proxy between IIS and Kestrel. Also
configures the app to capture startup errors. For the IIS default options, see Host ASP.NET Core on Windows
with IIS.
Sets ServiceProviderOptions.ValidateScopes to true if the app's environment is Development. For more
information, see Scope validation.
The configuration defined by CreateDefaultBuilder can be overridden and augmented by
ConfigureAppConfiguration, ConfigureLogging, and other methods and extension methods of IWebHostBuilder.
A few examples follow:
ConfigureAppConfiguration is used to specify additional IConfiguration for the app. The following
ConfigureAppConfiguration call adds a delegate to include app configuration in the appsettings.xml file.
ConfigureAppConfiguration may be called multiple times. Note that this configuration doesn't apply to the
host (for example, server URLs or environment). See the Host configuration values section.
{
config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
})
...
The following ConfigureLogging call adds a delegate to configure the minimum logging level
(SetMinimumLevel) to LogLevel.Warning. This setting overrides the settings in
appsettings.Development.json ( LogLevel.Debug ) and appsettings.Production.json ( LogLevel.Error )
configured by CreateDefaultBuilder . ConfigureLogging may be called multiple times.
.ConfigureLogging(logging =>
{
logging.SetMinimumLevel(LogLevel.Warning);
})
...
The following call to ConfigureKestrel overrides the default Limits.MaxRequestBodySize of 30,000,000

bytes established when Kestrel was configured by CreateDefaultBuilder :
.ConfigureKestrel((context, options) =>
{
options.Limits.MaxRequestBodySize = 20000000;
});
...
The following call to UseKestrel overrides the default Limits.MaxRequestBodySize of 30,000,000 bytes
established when Kestrel was configured by CreateDefaultBuilder :
.UseKestrel(options =>
{
options.Limits.MaxRequestBodySize = 20000000;
});
...
The content root determines where the host searches for content files, such as MVC view files. When the app is
started from the project's root folder, the project's root folder is used as the content root. This is the default used
in Visual Studio and the dotnet new templates.
For more information on app configuration, see Configuration in ASP.NET Core.
NOTE
As an alternative to using the static CreateDefaultBuilder method, creating a host from WebHostBuilder is a supported
approach with ASP.NET Core 2.x. For more information, see the ASP.NET Core 1.x tab.
Create a host using an instance of WebHostBuilder. Creating a host is typically performed in the app's entry point,
the Main method. In the project templates, Main is located in Program.cs:

{
{
}

.Build();
}
WebHostBuilder requires a server that implements IServer. The built-in servers are Kestrel and HTTP.sys (prior to
the release of ASP.NET Core 2.0, HTTP.sys was called WebListener). In this example, the UseKestrel extension
method specifies the Kestrel server.
The content root determines where the host searches for content files, such as MVC view files. The default content
root is obtained for UseContentRoot by Directory.GetCurrentDirectory. When the app is started from the project's
root folder, the project's root folder is used as the content root. This is the default used in Visual Studio and the
dotnet new templates.
To use IIS as a reverse proxy, call UseIISIntegration as part of building the host. UseIISIntegration doesn't
configure a server, like UseKestrel does. UseIISIntegration configures the base path and port the server listens
on when using the ASP.NET Core Module to create a reverse proxy between Kestrel and IIS. To use IIS with
ASP.NET Core, UseKestrel and UseIISIntegration must be specified. UseIISIntegration only activates when
running behind IIS or IIS Express. For more information, see ASP.NET Core Module and ASP.NET Core Module
configuration reference.
A minimal implementation that configures a host (and an ASP.NET Core app) includes specifying a server and
configuration of the app's request pipeline:

.UseKestrel()
.Configure(app =>
{
app.Run(context => context.Response.WriteAsync("Hello World!"));
})
.Build();
host.Run();
When setting up a host, Configure and ConfigureServices methods can be provided. If a Startup class is
specified, it must define a Configure method. For more information, see Application startup in ASP.NET Core.
Multiple calls to ConfigureServices append to one another. Multiple calls to Configure or UseStartup on the
WebHostBuilder replace previous settings.
Host configuration values

WebHostBuilder relies on the following approaches to set the host configuration values:
Host builder configuration, which includes environment variables with the format
ASPNETCORE_{configurationKey} . For example, ASPNETCORE_ENVIRONMENT .
Extensions such as UseContentRoot and UseConfiguration (see the Override configuration section).
UseSetting and the associated key. When setting a value with UseSetting , the value is set as a string
regardless of the type.
The host uses whichever option sets a value last. For more information, see Override configuration in the next
section.
Application Key (Name )
The IHostingEnvironment.ApplicationName property is automatically set when UseStartup or Configure is called
during host construction. The value is set to the name of the assembly containing the app's entry point. To set the
value explicitly, use the WebHostDefaults.ApplicationKey:
Key: applicationName
Type: string
Default: The name of the assembly containing the app's entry point.
Set using: UseSetting
Environment variable: ASPNETCORE_APPLICATIONKEY
.UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

.UseSetting("applicationName", "CustomApplicationName")
Capture Startup Errors

This setting controls the capture of startup errors.
Key: captureStartupErrors
Type: bool ( true or 1 )
Default: Defaults to false unless the app runs with Kestrel behind IIS, where the default is true .
Set using: CaptureStartupErrors
Environment variable: ASPNETCORE_CAPTURESTARTUPERRORS
When false , errors during startup result in the host exiting. When true , the host captures exceptions during
startup and attempts to start the server.
.CaptureStartupErrors(true)

.CaptureStartupErrors(true)
Content Root
This setting determines where ASP.NET Core begins searching for content files, such as MVC views.
Key: contentRoot
Type: string
Default: Defaults to the folder where the app assembly resides.
Set using: UseContentRoot
Environment variable: ASPNETCORE_CONTENTROOT
The content root is also used as the base path for the Web Root setting. If the path doesn't exist, the host fails to
start.
.UseContentRoot("c:\\<content-root>")

Detailed Errors
Determines if detailed errors should be captured.
Key: detailedErrors
Default: false
Environment variable: ASPNETCORE_DETAILEDERRORS
When enabled (or when the Environment is set to Development ), the app captures detailed exceptions.
.UseSetting(WebHostDefaults.DetailedErrorsKey, "true")

.UseSetting(WebHostDefaults.DetailedErrorsKey, "true")
Environment
Sets the app's environment.
Key: environment
Type: string
Default: Production
Set using: UseEnvironment
Environment variable: ASPNETCORE_ENVIRONMENT
The environment can be set to any value. Framework-defined values include Development , Staging , and
Production . Values aren't case sensitive. By default, the Environment is read from the ASPNETCORE_ENVIRONMENT
environment variable. When using Visual Studio, environment variables may be set in the launchSettings.json file.
.UseEnvironment(EnvironmentName.Development)

Hosting Startup Assemblies

Sets the app's hosting startup assemblies.
Key: hostingStartupAssemblies
Type: string
Default: Empty string
Environment variable: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES
A semicolon-delimited string of hosting startup assemblies to load on startup.
Although the configuration value defaults to an empty string, the hosting startup assemblies always include the
app's assembly. When hosting startup assemblies are provided, they're added to the app's assembly for loading
when the app builds its common services during startup.
.UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")
HTTPS Port
Set the HTTPS redirect port. Used in enforcing HTTPS.
Key: https_port Type: string Default: A default value isn't set. Set using: UseSetting Environment variable:
ASPNETCORE_HTTPS_PORT
.UseSetting("https_port", "8080")
Hosting Startup Exclude Assemblies

DESCRIPTION
Key: hostingStartupExcludeAssemblies
Type: string
Default: Empty string
Environment variable: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES
A semicolon-delimited string of hosting startup assemblies to exclude on startup.
.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")
Prefer Hosting URLs

Indicates whether the host should listen on the URLs configured with the WebHostBuilder instead of those
configured with the IServer implementation.
Key: preferHostingUrls
Default: true
Set using: PreferHostingUrls
Environment variable: ASPNETCORE_PREFERHOSTINGURLS
.PreferHostingUrls(false)
Prevent Hosting Startup

Prevents the automatic loading of hosting startup assemblies, including hosting startup assemblies configured by
the app's assembly. For more information, see Enhance an app from an external assembly in ASP.NET Core with
IHostingStartup.
Key: preventHostingStartup
Default: false
Environment variable: ASPNETCORE_PREVENTHOSTINGSTARTUP
.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")
Server URLs
Indicates the IP addresses or host addresses with ports and protocols that the server should listen on for
requests.
Key: urls
Type: string
Default: http://localhost:5000
Set using: UseUrls
Environment variable: ASPNETCORE_URLS
Set to a semicolon-separated (;) list of URL prefixes to which the server should respond. For example,
http://localhost:123 . Use "*" to indicate that the server should listen for requests on any IP address or
hostname using the specified port and protocol (for example, http://*:5000 ). The protocol ( http:// or
https:// ) must be included with each URL. Supported formats vary between servers.
.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002")
Kestrel has its own endpoint configuration API. For more information, see Kestrel web server implementation in
ASP.NET Core.

.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002")
Shutdown Timeout
Specifies the amount of time to wait for the web host to shut down.
Key: shutdownTimeoutSeconds
Type: int
Default: 5
Set using: UseShutdownTimeout
Environment variable: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS
Although the key accepts an int with UseSetting(for example,
.UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10") ), the UseShutdownTimeout extension method takes a
TimeSpan.
During the timeout period, hosting:
Triggers IApplicationLifetime.ApplicationStopping.
Attempts to stop hosted services, logging any errors for services that fail to stop.
If the timeout period expires before all of the hosted services stop, any remaining active services are stopped
when the app shuts down. The services stop even if they haven't finished processing. If services require additional
time to stop, increase the timeout.
.UseShutdownTimeout(TimeSpan.FromSeconds(10))
Startup Assembly
Determines the assembly to search for the Startup class.
Key: startupAssembly
Type: string
Default: The app's assembly
Set using: UseStartup
Environment variable: ASPNETCORE_STARTUPASSEMBLY
The assembly by name ( string ) or type ( TStartup ) can be referenced. If multiple UseStartup methods are
called, the last one takes precedence.
.UseStartup("StartupAssemblyName")
.UseStartup<TStartup>()

.UseStartup("StartupAssemblyName")

.UseStartup<TStartup>()
Web Root
Sets the relative path to the app's static assets.
Key: webroot
Type: string
Default: If not specified, the default is "(Content Root)/wwwroot", if the path exists. If the path doesn't exist, then
a no-op file provider is used.
Set using: UseWebRoot
Environment variable: ASPNETCORE_WEBROOT
.UseWebRoot("public")

.UseWebRoot("public")
Override configuration
Use Configuration to configure the web host. In the following example, host configuration is optionally specified
in a hostsettings.json file. Any configuration loaded from the hostsettings.json file may be overridden by
command-line arguments. The built configuration (in config ) is used to configure the host with
UseConfiguration. IWebHostBuilder configuration is added to the app's configuration, but the converse isn't true
— ConfigureAppConfiguration doesn't affect the IWebHostBuilder configuration.
Overriding the configuration provided by UseUrls with hostsettings.json config first, command-line argument
config second:

{
{
}

{
.AddJsonFile("hostsettings.json", optional: true)
.Build();
.Configure(app =>
{
app.Run(context =>
context.Response.WriteAsync("Hello, World!"));
})
.Build();
}
}
hostsettings.json:
{
urls: "http://*:5005"
}
Overriding the configuration provided by UseUrls with hostsettings.json config first, command-line argument
config second:
{
{
.AddJsonFile("hostsettings.json", optional: true)
.Build();

.UseKestrel()
.Configure(app =>
{
app.Run(context =>
context.Response.WriteAsync("Hello, World!"));
})
.Build();
host.Run();
}
}
hostsettings.json:
{
urls: "http://*:5005"
}
NOTE
The UseConfiguration extension method isn't currently capable of parsing a configuration section returned by GetSection
(for example, .UseConfiguration(Configuration.GetSection("section")) . The GetSection method filters the
configuration keys to the section requested but leaves the section name on the keys (for example, section:urls ,
section:environment ). The UseConfiguration method expects the keys to match the WebHostBuilder keys (for
example, urls , environment ). The presence of the section name on the keys prevents the section's values from
configuring the host. This issue will be addressed in an upcoming release. For more information and workarounds, see
Passing configuration section into WebHostBuilder.UseConfiguration uses full keys.
UseConfiguration only copies keys from the provided IConfiguration to the host builder configuration. Therefore,
setting reloadOnChange: true for JSON, INI, and XML settings files has no effect.
To specify the host run on a particular URL, the desired value can be passed in from a command prompt when
executing dotnet run. The command-line argument overrides the urls value from the hostsettings.json file, and
the server listens on port 8080:
dotnet run --urls "http://*:8080"
Manage the host

Run
The Run method starts the web app and blocks the calling thread until the host is shut down:
host.Run();
Start
Run the host in a non-blocking manner by calling its Start method:
using (host)
{
host.Start();
Console.ReadLine();
}
If a list of URLs is passed to the Start method, it listens on the URLs specified:
var urls = new List<string>()

{
"http://*:5000",
"http://localhost:5001"
};

.UseKestrel()
.Start(urls.ToArray());
using (host)
{
Console.ReadLine();
}
The app can initialize and start a new host using the pre-configured defaults of CreateDefaultBuilder using a
static convenience method. These methods start the server without console output and with WaitForShutdown
wait for a break (Ctrl-C/SIGINT or SIGTERM ):
Start(RequestDelegate app)
Start with a RequestDelegate :
using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))

{
Console.WriteLine("Use Ctrl-C to shutdown the host...");
host.WaitForShutdown();
}
Make a request in the browser to http://localhost:5000 to receive the response "Hello World!" WaitForShutdown
blocks until a break (Ctrl-C/SIGINT or SIGTERM ) is issued. The app displays the Console.WriteLine message and
waits for a keypress to exit.
Start(string url, RequestDelegate app)
Start with a URL and RequestDelegate :
using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))

{
}
Produces the same result as Start(RequestDelegate app), except the app responds on http://localhost:8080 .
Start(Action<IRouteBuilder> routeBuilder)
Use an instance of IRouteBuilder (Microsoft.AspNetCore.Routing) to use routing middleware:
using (var host = WebHost.Start(router => router

.MapGet("hello/{name}", (req, res, data) =>
res.WriteAsync($"Hello, {data.Values["name"]}!"))
.MapGet("buenosdias/{name}", (req, res, data) =>
res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
.MapGet("throw/{message?}", (req, res, data) =>
throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
.MapGet("{greeting}/{name}", (req, res, data) =>
res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
.MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
}
Use the following browser requests with the example:
REQUEST RESPONSE
http://localhost:5000/hello/Martin Hello, Martin!
http://localhost:5000/buenosdias/Catrina Buenos dias, Catrina!
http://localhost:5000/throw/ooops! Throws an exception with string "ooops!"
http://localhost:5000/throw Throws an exception with string "Uh oh!"
http://localhost:5000/Sante/Kevin Sante, Kevin!
http://localhost:5000 Hello World!
WaitForShutdown blocks until a break (Ctrl-C/SIGINT or SIGTERM ) is issued. The app displays the
Console.WriteLine message and waits for a keypress to exit.
Start(string url, Action<IRouteBuilder> routeBuilder)

Use a URL and an instance of IRouteBuilder :
using (var host = WebHost.Start("http://localhost:8080", router => router

.MapGet("hello/{name}", (req, res, data) =>
res.WriteAsync($"Hello, {data.Values["name"]}!"))
.MapGet("buenosdias/{name}", (req, res, data) =>
res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
.MapGet("throw/{message?}", (req, res, data) =>
throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
.MapGet("{greeting}/{name}", (req, res, data) =>
res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
.MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
Console.WriteLine("Use Ctrl-C to shut down the host...");
}
Produces the same result as Start(Action<IRouteBuilder> routeBuilder), except the app responds at
http://localhost:8080 .
StartWith(Action<IApplicationBuilder> app)
Provide a delegate to configure an IApplicationBuilder :
using (var host = WebHost.StartWith(app =>

app.Use(next =>
{
return async context =>
{
await context.Response.WriteAsync("Hello World!");
};
})))
{
}
Make a request in the browser to http://localhost:5000 to receive the response "Hello World!" WaitForShutdown
blocks until a break (Ctrl-C/SIGINT or SIGTERM ) is issued. The app displays the Console.WriteLine message and
waits for a keypress to exit.
StartWith(string url, Action<IApplicationBuilder> app)
Provide a URL and a delegate to configure an IApplicationBuilder :
using (var host = WebHost.StartWith("http://localhost:8080", app =>

app.Use(next =>
{
return async context =>
{
};
})))
{
}
Produces the same result as StartWith(Action<IApplicationBuilder> app), except the app responds on
http://localhost:8080 .
Run
The Run method starts the web app and blocks the calling thread until the host is shut down:
host.Run();
Start
Run the host in a non-blocking manner by calling its Start method:
using (host)
{
host.Start();
Console.ReadLine();
}
If a list of URLs is passed to the Start method, it listens on the URLs specified:
var urls = new List<string>()

{
"http://*:5000",
"http://localhost:5001"
};

.UseKestrel()
.Start(urls.ToArray());
using (host)
{
Console.ReadLine();
}
IHostingEnvironment interface
The IHostingEnvironment interface provides information about the app's web hosting environment. Use
constructor injection to obtain the IHostingEnvironment in order to use its properties and extension methods:
public class CustomFileReader

{
public CustomFileReader(IHostingEnvironment env)

{
_env = env;
}
public string ReadFile(string filePath)

{
var fileProvider = _env.WebRootFileProvider;
// Process the file here
}
}
A convention-based approach can be used to configure the app at startup based on the environment.
Alternatively, inject the IHostingEnvironment into the Startup constructor for use in ConfigureServices :
{
{
HostingEnvironment = env;
}

{
if (HostingEnvironment.IsDevelopment())
{
// Development configuration
}
else
{
// Staging/Production configuration
}
var contentRootPath = HostingEnvironment.ContentRootPath;

}
}
NOTE
In addition to the IsDevelopment extension method, IHostingEnvironment offers IsStaging , IsProduction , and
IsEnvironment(string environmentName) methods. For more information, see Use multiple environments in ASP.NET
Core.
The IHostingEnvironment service can also be injected directly into the Configure method for setting up the
processing pipeline:

{
{
// In Development, use the developer exception page
}
else
{
// In Staging/Production, route exceptions to /error
}
var contentRootPath = env.ContentRootPath;

}
IHostingEnvironment can be injected into the Invoke method when creating custom middleware:
public async Task Invoke(HttpContext context, IHostingEnvironment env)
{
{
// Configure middleware for Development
}
else
{
// Configure middleware for Staging/Production
}
var contentRootPath = env.ContentRootPath;

}
IApplicationLifetime interface
IApplicationLifetime allows for post-startup and shutdown activities. Three properties on the interface are
cancellation tokens used to register Action methods that define startup and shutdown events.
CANCELLATION TOKEN TRIGGERED WHEN…
ApplicationStarted The host has fully started.
ApplicationStopped The host is completing a graceful shutdown. All requests

should be processed. Shutdown blocks until this event
completes.
ApplicationStopping The host is performing a graceful shutdown. Requests may

still be processing. Shutdown blocks until this event
completes.
{
public void Configure(IApplicationBuilder app, IApplicationLifetime appLifetime)
{
appLifetime.ApplicationStarted.Register(OnStarted);
appLifetime.ApplicationStopping.Register(OnStopping);
appLifetime.ApplicationStopped.Register(OnStopped);
Console.CancelKeyPress += (sender, eventArgs) =>

{
appLifetime.StopApplication();
// Don't terminate the process immediately, wait for the Main thread to exit gracefully.
eventArgs.Cancel = true;
};
}
private void OnStarted()

{
// Perform post-startup activities here
}
private void OnStopping()

{
// Perform on-stopping activities here
}
private void OnStopped()

{
// Perform post-stopped activities here
}
}
StopApplication requests termination of the app. The following class uses StopApplication to gracefully shut
down an app when the class's Shutdown method is called:
public class MyClass

{
private readonly IApplicationLifetime _appLifetime;
public MyClass(IApplicationLifetime appLifetime)

{
_appLifetime = appLifetime;
}
public void Shutdown()

{
_appLifetime.StopApplication();
}
}
Scope validation
CreateDefaultBuilder sets ServiceProviderOptions.ValidateScopes to true if the app's environment is
Development.
When ValidateScopes is set to true , the default service provider performs checks to verify that:
Scoped services aren't directly or indirectly resolved from the root service provider.
Scoped services aren't directly or indirectly injected into singletons.
The root service provider is created when BuildServiceProvider is called. The root service provider's lifetime
corresponds to the app/server's lifetime when the provider starts with the app and is disposed when the app
shuts down.
Scoped services are disposed by the container that created them. If a scoped service is created in the root
container, the service's lifetime is effectively promoted to singleton because it's only disposed by the root
container when app/server is shut down. Validating service scopes catches these situations when
BuildServiceProvider is called.
To always validate scopes, including in the Production environment, configure the ServiceProviderOptions with
UseDefaultServiceProvider on the host builder:
.UseDefaultServiceProvider((context, options) => {
options.ValidateScopes = true;
})
Troubleshooting System.ArgumentException
The following only applies to ASP.NET Core 2.0 apps when the app doesn't call UseStartup or Configure
.
A host may be built by injecting IStartup directly into the dependency injection container rather than calling
UseStartup or Configure :
services.AddSingleton<IStartup, Startup>();
If the host is built this way, the following error may occur:
Unhandled Exception: System.ArgumentException: A valid non-empty application name must be provided.
This occurs because the app name (the name of the current assembly) is required to scan for
HostingStartupAttributes . If the app manually injects IStartup into the dependency injection container, add the
following call to WebHostBuilder with the assembly name specified:
.UseSetting("applicationName", "AssemblyName")
Alternatively, add a dummy Configure to the WebHostBuilder , which sets the app name automatically:
.Configure(_ => { })
For more information, see Announcements: Microsoft.Extensions.PlatformAbstractions has been removed

(comment) and the StartupInjection sample.
Host ASP.NET Core on Windows with IIS
Host ASP.NET Core on Linux with Nginx
Host ASP.NET Core on Linux with Apache
Host ASP.NET Core in a Windows Service
.NET Generic Host
By Luke Latham
.NET Core apps configure and launch a host. The host is responsible for app startup and lifetime management.
This topic covers the ASP.NET Core Generic Host (HostBuilder), which is useful for hosting apps that don't
process HTTP requests. For coverage of the Web Host (WebHostBuilder), see ASP.NET Core Web Host.
The goal of the Generic Host is to decouple the HTTP pipeline from the Web Host API to enable a wider array of
host scenarios. Messaging, background tasks, and other non-HTTP workloads based on the Generic Host benefit
from cross-cutting capabilities, such as configuration, dependency injection (DI), and logging.
The Generic Host is new in ASP.NET Core 2.1 and isn't suitable for web hosting scenarios. For web hosting
scenarios, use the Web Host. The Generic Host is under development to replace the Web Host in a future release
and act as the primary host API in both HTTP and non-HTTP scenarios.
When running the sample app in Visual Studio Code, use an external or integrated terminal. Don't run the
sample in an internalConsole .
To set the console in Visual Studio Code:
1. Open the .vscode/launch.json file.
2. In the .NET Core Launch (console) configuration, locate the console entry. Set the value to either
externalTerminal or integratedTerminal .
Introduction
The Generic Host library is available in the Microsoft.Extensions.Hosting namespace and provided by the
Microsoft.Extensions.Hosting package. The Microsoft.Extensions.Hosting package is included in the
Microsoft.AspNetCore.App metapackage (ASP.NET Core 2.1 or later).
IHostedService is the entry point to code execution. Each IHostedService implementation is executed in the order
of service registration in ConfigureServices. StartAsync is called on each IHostedService when the host starts,
and StopAsync is called in reverse registration order when the host shuts down gracefully.
Set up a host
IHostBuilder is the main component that libraries and apps use to initialize, build, and run the host:
public static async Task Main(string[] args)

{
var host = new HostBuilder()
.Build();
await host.RunAsync();
}
Host configuration
HostBuilder relies on the following approaches to set the host configuration values:
Configuration builder
Extension method configuration
Configuration builder
Host builder configuration is created by calling ConfigureHostConfiguration on the IHostBuilder implementation.
ConfigureHostConfiguration uses an IConfigurationBuilder to create an IConfiguration for the host. The
configuration builder initializes the IHostingEnvironment for use in the app's build process.
Environment variable configuration isn't added by default. Call AddEnvironmentVariables on the host builder to
configure the host from environment variables. AddEnvironmentVariables accepts an optional user-defined prefix.
The sample app uses a prefix of PREFIX_ . The prefix is removed when the environment variables are read. When
the sample app's host is configured, the environment variable value for PREFIX_ENVIRONMENT becomes the host
configuration value for the environment key.
During development when using Visual Studio or running an app with dotnet run , environment variables may
be set in the Properties/launchSettings.json file. In Visual Studio Code, environment variables may be set in the
.vscode/launch.json file during development. For more information, see Use multiple environments in ASP.NET
Core.
ConfigureHostConfiguration can be called multiple times with additive results. The host uses whichever option
sets a value last.
hostsettings.json:
{
"environment": "Development"
}
Example HostBuilder configuration using ConfigureHostConfiguration :

.ConfigureHostConfiguration(configHost =>
{
configHost.SetBasePath(Directory.GetCurrentDirectory());
configHost.AddJsonFile("hostsettings.json", optional: true);
configHost.AddEnvironmentVariables(prefix: "PREFIX_");
configHost.AddCommandLine(args);
})
NOTE
The AddConfiguration extension method isn't currently capable of parsing a configuration section returned by GetSection
(for example, .AddConfiguration(Configuration.GetSection("section")) . The GetSection method filters the
configuration keys to the section requested but leaves the section name on the keys (for example, section:environment ).
The AddConfiguration method expects the keys to match the HostBuilder keys (for example, environment ). The
presence of the section name on the keys prevents the section's values from configuring the host. This issue will be
addressed in an upcoming release. For more information and workarounds, see Passing configuration section into
WebHostBuilder.UseConfiguration uses full keys.
Extension method configuration

Extension methods are called on the IHostBuilder implementation to configure the content root and the
environment.
Application Key (Name)
The IHostingEnvironment.ApplicationName property is set from host configuration during host construction. To
set the value explicitly, use the HostDefaults.ApplicationKey:
Key: applicationName
Type: string
Default: The name of the assembly containing the app's entry point.
Set using: HostBuilderContext.HostingEnvironment.ApplicationName
Environment variable: <PREFIX_>APPLICATIONKEY ( <PREFIX_> is optional and user-defined)

.ConfigureAppConfiguration((hostContext, configApp) =>
{
hostContext.HostingEnvironment.ApplicationName = "CustomApplicationName";
})
Content Root
This setting determines where the host begins searching for content files.
Key: contentRoot
Type: string
Default: Defaults to the folder where the app assembly resides.
Set using: UseContentRoot
Environment variable: <PREFIX_>CONTENTROOT ( <PREFIX_> is optional and user-defined)
If the path doesn't exist, the host fails to start.

Environment
Sets the app's environment.
Key: environment
Type: string
Default: Production
Set using: UseEnvironment
Environment variable: <PREFIX_>ENVIRONMENT ( <PREFIX_> is optional and user-defined)
The environment can be set to any value. Framework-defined values include Development , Staging , and
Production . Values aren't case sensitive.

ConfigureAppConfiguration
App builder configuration is created by calling ConfigureAppConfiguration on the IHostBuilder implementation.
ConfigureAppConfiguration uses an IConfigurationBuilder to create an IConfiguration for the app.
ConfigureAppConfiguration can be called multiple times with additive results. The app uses whichever option sets
a value last. The configuration created by ConfigureAppConfiguration is available at
HostBuilderContext.Configuration for subsequent operations and in Services.
Example app configuration using ConfigureAppConfiguration :
.ConfigureAppConfiguration((hostContext, configApp) =>
{
configApp.SetBasePath(Directory.GetCurrentDirectory());
configApp.AddJsonFile("appsettings.json", optional: true);
configApp.AddJsonFile(
$"appsettings.{hostContext.HostingEnvironment.EnvironmentName}.json",
optional: true);
configApp.AddEnvironmentVariables(prefix: "PREFIX_");
configApp.AddCommandLine(args);
})
appsettings.json:
{
"Logging": {
"LogLevel": {
}
},
"AllowedHosts": "*"
}
appsettings.Development.json:
{
"Logging": {
"LogLevel": {
"Default": "Debug",
}
}
}
appsettings.Production.json:
{
"Logging": {
"LogLevel": {
"Default": "Error",
}
}
}
NOTE
The AddConfiguration extension method isn't currently capable of parsing a configuration section returned by GetSection
(for example, .AddConfiguration(Configuration.GetSection("section")) . The GetSection method filters the
configuration keys to the section requested but leaves the section name on the keys (for example,
section:Logging:LogLevel:Default ). The AddConfiguration method expects an exact match to configuration keys (for
example, Logging:LogLevel:Default ). The presence of the section name on the keys prevents the section's values from
configuring the app. This issue will be addressed in an upcoming release. For more information and workarounds, see
Passing configuration section into WebHostBuilder.UseConfiguration uses full keys.
To move settings files to the output directory, specify the settings files as MSBuild project items in the project file.
The sample app moves its JSON app settings files and hostsettings.json with the following <Content:> item:
<ItemGroup>
<Content Include="**\*.json" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>
ConfigureServices
ConfigureServices adds services to the app's dependency injection container. ConfigureServices can be called
multiple times with additive results.
A hosted service is a class with background task logic that implements the IHostedService interface. For more
information, see Background tasks with hosted services in ASP.NET Core.
The sample app uses the AddHostedService extension method to add a service for lifetime events,
LifetimeEventsHostedService , and a timed background task, TimedHostedService , to the app:

.ConfigureServices((hostContext, services) =>
{
services.AddLogging();
services.AddHostedService<LifetimeEventsHostedService>();
services.AddHostedService<TimedHostedService>();
})
ConfigureLogging
ConfigureLogging adds a delegate for configuring the provided ILoggingBuilder. ConfigureLogging may be called
multiple times with additive results.

.ConfigureLogging((hostContext, configLogging) =>
{
configLogging.AddConsole();
configLogging.AddDebug();
})
UseConsoleLifetime
UseConsoleLifetime listens for Ctrl+C /SIGINT or SIGTERM and calls StopApplication to start the shutdown
process. UseConsoleLifetime unblocks extensions such as RunAsync and WaitForShutdownAsync.
ConsoleLifetime is pre-registered as the default lifetime implementation. The last lifetime registered is used.

.UseConsoleLifetime()
Container configuration
To support plugging in other containers, the host can accept an IServiceProviderFactory. Providing a factory isn't
part of the DI container registration but is instead a host intrinsic used to create the concrete DI container.
UseServiceProviderFactory(IServiceProviderFactory<TContainerBuilder>) overrides the default factory used to
create the app's service provider.
Custom container configuration is managed by the ConfigureContainer method. ConfigureContainer provides a
strongly-typed experience for configuring the container on top of the underlying host API. ConfigureContainer
can be called multiple times with additive results.
Create a service container for the app:
namespace GenericHostSample
{
internal class ServiceContainer
{
}
}
Provide a service container factory:
using System;
namespace GenericHostSample
{
internal class ServiceContainerFactory : IServiceProviderFactory<ServiceContainer>
{
public ServiceContainer CreateBuilder(IServiceCollection services)
{
return new ServiceContainer();
}
public IServiceProvider CreateServiceProvider(ServiceContainer containerBuilder)

{
throw new NotImplementedException();
}
}
}
Use the factory and configure the custom service container for the app:

.UseServiceProviderFactory<ServiceContainer>(new ServiceContainerFactory())
.ConfigureContainer<ServiceContainer>((hostContext, container) =>
{
})
Extensibility
Host extensibility is performed with extension methods on IHostBuilder . The following example shows how an
extension method extends an IHostBuilder implementation with the TimedHostedService example demonstrated
in Background tasks with hosted services in ASP.NET Core.

.UseHostedService<TimedHostedService>()
.Build();
await host.StartAsync();
An app establishes the UseHostedService extension method to register the hosted service passed in T :
using System;
using Microsoft.Extensions.Hosting;
public static class Extensions

{
public static IHostBuilder UseHostedService<T>(this IHostBuilder hostBuilder)
where T : class, IHostedService, IDisposable
{
return hostBuilder.ConfigureServices(services =>
services.AddHostedService<T>());
}
}
Manage the host

The IHost implementation is responsible for starting and stopping the IHostedService implementations that are
registered in the service container.
Run
Run runs the app and blocks the calling thread until the host is shut down:

{
public void Main(string[] args)
{
.Build();
host.Run();
}
}
RunAsync
RunAsync runs the app and returns a Task that completes when the cancellation token or shutdown is triggered:

{
{
.Build();
await host.RunAsync();
}
}
RunConsoleAsync
RunConsoleAsync enables console support, builds and starts the host, and waits for Ctrl+C /SIGINT or
SIGTERM to shut down.
{
{
var hostBuilder = new HostBuilder();
await hostBuilder.RunConsoleAsync();
}
}
Start and StopAsync

Start starts the host synchronously.
StopAsync(TimeSpan) attempts to stop the host within the provided timeout.

{
{
.Build();
using (host)
{
host.Start();
await host.StopAsync(TimeSpan.FromSeconds(5));
}
}
}
StartAsync and StopAsync

StartAsync starts the app.
StopAsync stops the app.

{
{
.Build();
using (host)
{
await host.StopAsync();
}
}
}
WaitForShutdown
WaitForShutdown is triggered via the IHostLifetime, such as ConsoleLifetime (listens for Ctrl+C /SIGINT or
SIGTERM ). WaitForShutdown calls StopAsync.
{
public void Main(string[] args)
{
.Build();
using (host)
{
host.Start();
}
}
}
WaitForShutdownAsync
WaitForShutdownAsync returns a Task that completes when shutdown is triggered via the given token and calls
StopAsync.

{
{
.Build();
using (host)
{
await host.WaitForShutdownAsync();
}
}
}
External control
External control of the host can be achieved using methods that can be called externally:
{
private IHost _host;
public Program()
{
_host = new HostBuilder()
.Build();
}
public async Task StartAsync()

{
_host.StartAsync();
}
public async Task StopAsync()

{
using (_host)
{
await _host.StopAsync(TimeSpan.FromSeconds(5));
}
}
}
IHostLifetime.WaitForStartAsync is called at the start of StartAsync, which waits until it's complete before
continuing. This can be used to delay startup until signaled by an external event.
IHostingEnvironment interface
IHostingEnvironment provides information about the app's hosting environment. Use constructor injection to
obtain the IHostingEnvironment in order to use its properties and extension methods:

{
public MyClass(IHostingEnvironment env)

{
_env = env;
}
public void DoSomething()

{
var environmentName = _env.EnvironmentName;
}
}
IApplicationLifetime interface
IApplicationLifetime allows for post-startup and shutdown activities, including graceful shutdown requests. Three
properties on the interface are cancellation tokens used to register Action methods that define startup and
shutdown events.
ApplicationStarted The host has fully started.

ApplicationStopped The host is completing a graceful shutdown. All requests

should be processed. Shutdown blocks until this event
completes.
ApplicationStopping The host is performing a graceful shutdown. Requests may

still be processing. Shutdown blocks until this event
completes.
Constructor-inject the IApplicationLifetime service into any class. The sample app uses constructor injection into
a LifetimeEventsHostedService class (an IHostedService implementation) to register the events.
LifetimeEventsHostedService.cs:
internal class LifetimeEventsHostedService : IHostedService

{
public LifetimeEventsHostedService(
ILogger<LifetimeEventsHostedService> logger, IApplicationLifetime appLifetime)
{
_logger = logger;
}
public Task StartAsync(CancellationToken cancellationToken)

{
_appLifetime.ApplicationStarted.Register(OnStarted);
_appLifetime.ApplicationStopping.Register(OnStopping);
_appLifetime.ApplicationStopped.Register(OnStopped);
return Task.CompletedTask;
}
public Task StopAsync(CancellationToken cancellationToken)

{
}
private void OnStarted()

{
_logger.LogInformation("OnStarted has been called.");
// Perform post-startup activities here

}
private void OnStopping()

{
_logger.LogInformation("OnStopping has been called.");
// Perform on-stopping activities here

}
private void OnStopped()

{
_logger.LogInformation("OnStopped has been called.");
// Perform post-stopped activities here

}
}
StopApplication requests termination of the app. The following class uses StopApplication to gracefully shut
down an app when the class's Shutdown method is called:

{
public MyClass(IApplicationLifetime appLifetime)

{
}
public void Shutdown()

{
_appLifetime.StopApplication();
}
}
Background tasks with hosted services in ASP.NET Core
Hosting repo samples on GitHub
Background tasks with hosted services in ASP.NET
Core
By Luke Latham
In ASP.NET Core, background tasks can be implemented as hosted services. A hosted service is a class with
background task logic that implements the IHostedService interface. This topic provides three hosted service
examples:
Background task that runs on a timer.
Hosted service that activates a scoped service. The scoped service can use dependency injection.
Queued background tasks that run sequentially.
The sample app is provided in two versions:
Web Host – The Web Host is useful for hosting web apps. The example code shown in this topic is from the
Web Host version of the sample. For more information, see the Web Host topic.
Generic Host – The Generic Host is new in ASP.NET Core 2.1. For more information, see the Generic Host
topic.
Package
Microsoft.Extensions.Hosting package.
IHostedService interface
Hosted services implement the IHostedService interface. The interface defines two methods for objects that are
managed by the host:
StartAsync(CancellationToken) - StartAsync contains the logic to start the background task. When using
the Web Host, StartAsync is called after the server has started and IApplicationLifetime.ApplicationStarted
is triggered. When using the Generic Host, StartAsync is called before ApplicationStarted is triggered.
StopAsync(CancellationToken) - Triggered when the host is performing a graceful shutdown. StopAsync
contains the logic to end the background task and dispose of any unmanaged resources. If the app shuts
down unexpectedly (for example, the app's process fails), StopAsync might not be called.
The hosted service is activated once at app startup and gracefully shutdown at app shutdown. When IDisposable
is implemented, resources can be disposed when the service container is disposed. If an error is thrown during
background task execution, Dispose should be called even if StopAsync isn't called.
Timed background tasks

A timed background task makes use of the System.Threading.Timer class. The timer triggers the task's DoWork
method. The timer is disabled on StopAsync and disposed when the service container is disposed on Dispose :
internal class TimedHostedService : IHostedService, IDisposable
{
private Timer _timer;
public TimedHostedService(ILogger<TimedHostedService> logger)

{
_logger = logger;
}

{
_logger.LogInformation("Timed Background Service is starting.");
_timer = new Timer(DoWork, null, TimeSpan.Zero,

TimeSpan.FromSeconds(5));
}
private void DoWork(object state)

{
_logger.LogInformation("Timed Background Service is working.");
}

{
_logger.LogInformation("Timed Background Service is stopping.");
_timer?.Change(Timeout.Infinite, 0);
}
public void Dispose()

{
_timer?.Dispose();
}
}
The service is registered in Startup.ConfigureServices with the AddHostedService extension method:
services.AddHostedService<TimedHostedService>();
Consuming a scoped service in a background task

To use scoped services within an IHostedService , create a scope. No scope is created for a hosted service by
default.
The scoped background task service contains the background task's logic. In the following example, an ILogger is
injected into the service:
internal interface IScopedProcessingService
{
void DoWork();
}
internal class ScopedProcessingService : IScopedProcessingService

{
public ScopedProcessingService(ILogger<ScopedProcessingService> logger)

{
_logger = logger;
}
public void DoWork()

{
_logger.LogInformation("Scoped Processing Service is working.");
}
}
The hosted service creates a scope to resolve the scoped background task service to call its DoWork method:
internal class ConsumeScopedServiceHostedService : IHostedService
{
public ConsumeScopedServiceHostedService(IServiceProvider services,

ILogger<ConsumeScopedServiceHostedService> logger)
{
Services = services;
_logger = logger;
}
public IServiceProvider Services { get; }

{
"Consume Scoped Service Hosted Service is starting.");
DoWork();
}
private void DoWork()

{
"Consume Scoped Service Hosted Service is working.");
using (var scope = Services.CreateScope())

{
var scopedProcessingService =
scope.ServiceProvider
.GetRequiredService<IScopedProcessingService>();
scopedProcessingService.DoWork();
}
}

{
"Consume Scoped Service Hosted Service is stopping.");
}
}
The services are registered in Startup.ConfigureServices . The IHostedService implementation is registered with
the AddHostedService extension method:
services.AddHostedService<ConsumeScopedServiceHostedService>();
services.AddScoped<IScopedProcessingService, ScopedProcessingService>();
Queued background tasks

A background task queue is based on the .NET 4.x QueueBackgroundWorkItem (tentatively scheduled to be built-
in for ASP.NET Core 3.0):
public interface IBackgroundTaskQueue
{
void QueueBackgroundWorkItem(Func<CancellationToken, Task> workItem);
Task<Func<CancellationToken, Task>> DequeueAsync(

CancellationToken cancellationToken);
}
public class BackgroundTaskQueue : IBackgroundTaskQueue

{
private ConcurrentQueue<Func<CancellationToken, Task>> _workItems =
new ConcurrentQueue<Func<CancellationToken, Task>>();
private SemaphoreSlim _signal = new SemaphoreSlim(0);
public void QueueBackgroundWorkItem(

Func<CancellationToken, Task> workItem)
{
if (workItem == null)
{
throw new ArgumentNullException(nameof(workItem));
}
_workItems.Enqueue(workItem);
_signal.Release();
}
public async Task<Func<CancellationToken, Task>> DequeueAsync(

CancellationToken cancellationToken)
{
await _signal.WaitAsync(cancellationToken);
_workItems.TryDequeue(out var workItem);
return workItem;
}
}
In QueueHostedService , background tasks in the queue are dequeued and executed as a BackgroundService, which
is a base class for implementing a long running IHostedService :
public class QueuedHostedService : BackgroundService
{
public QueuedHostedService(IBackgroundTaskQueue taskQueue,

{
TaskQueue = taskQueue;
_logger = loggerFactory.CreateLogger<QueuedHostedService>();
}
public IBackgroundTaskQueue TaskQueue { get; }
protected async override Task ExecuteAsync(

{
_logger.LogInformation("Queued Hosted Service is starting.");
while (!cancellationToken.IsCancellationRequested)
{
var workItem = await TaskQueue.DequeueAsync(cancellationToken);
try
{
await workItem(cancellationToken);
}
{
_logger.LogError(ex,
$"Error occurred executing {nameof(workItem)}.");
}
}
_logger.LogInformation("Queued Hosted Service is stopping.");

}
}
The services are registered in Startup.ConfigureServices . The IHostedService implementation is registered with
the AddHostedService extension method:
services.AddHostedService<QueuedHostedService>();
services.AddSingleton<IBackgroundTaskQueue, BackgroundTaskQueue>();
In the Index page model class, the IBackgroundTaskQueue is injected into the constructor and assigned to Queue :
public IndexModel(IBackgroundTaskQueue queue,

IApplicationLifetime appLifetime,
ILogger<IndexModel> logger)
{
Queue = queue;
_logger = logger;
}
public IBackgroundTaskQueue Queue { get; }
When the Add Task button is selected on the Index page, the OnPostAddTask method is executed.
QueueBackgroundWorkItem is called to enqueue the work item:
public IActionResult OnPostAddTask()
{
Queue.QueueBackgroundWorkItem(async token =>
{
var guid = Guid.NewGuid().ToString();
for (int delayLoop = 0; delayLoop < 3; delayLoop++)

{
$"Queued Background Task {guid} is running. {delayLoop}/3");
await Task.Delay(TimeSpan.FromSeconds(5), token);
}
$"Queued Background Task {guid} is complete. 3/3");
});
}
Implement background tasks in microservices with IHostedService and the BackgroundService class
System.Threading.Timer
Enhance an app from an external assembly in
ASP.NET Core with IHostingStartup
By Luke Latham
An IHostingStartup (hosting startup) implementation adds enhancements to an app at startup from an external
assembly. For example, an external library can use a hosting startup implementation to provide additional
configuration providers or services to an app. IHostingStartup is available in ASP.NET Core 2.0 or later.
HostingStartup attribute
A HostingStartup attribute indicates the presence of a hosting startup assembly to activate at runtime.
The entry assembly or the assembly containing the Startup class is automatically scanned for the
HostingStartup attribute. The list of assemblies to search for HostingStartup attributes is loaded at runtime from
configuration in the WebHostDefaults.HostingStartupAssembliesKey. The list of assemblies to exclude from
discovery is loaded from the WebHostDefaults.HostingStartupExcludeAssembliesKey. For more information, see
Web Host: Hosting Startup Assemblies and Web Host: Hosting Startup Exclude Assemblies.
In the following example, the namespace of the hosting startup assembly is StartupEnhancement . The class
containing the hosting startup code is StartupEnhancementHostingStartup :
[assembly: HostingStartup(typeof(StartupEnhancement.StartupEnhancementHostingStartup))]
The HostingStartup attribute is typically located in the hosting startup assembly's IHostingStartup
implementation class file.
Discover loaded hosting startup assemblies

To discover loaded hosting startup assemblies, enable logging and check the app's logs. Errors that occur when
loading assemblies are logged. Loaded hosting startup assemblies are logged at the Debug level, and all errors
are logged.
Disable automatic loading of hosting startup assemblies

To disable automatic loading of hosting startup assemblies, use one of the following approaches:
To prevent all hosting startup assemblies from loading, set one of the following to true or 1 :
Prevent Hosting Startup host configuration setting.
ASPNETCORE_PREVENTHOSTINGSTARTUP environment variable.
To prevent specific hosting startup assemblies from loading, set one of the following to a semicolon-delimited
string of hosting startup assemblies to exclude at startup:
Hosting Startup Exclude Assemblies host configuration setting.
ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES environment variable.
To disable automatic loading of hosting startup assemblies, set one of the following to true or 1 :
Prevent Hosting Startup host configuration setting.
ASPNETCORE_PREVENTHOSTINGSTARTUP environment variable.
If both the host configuration setting and the environment variable are set, the host setting controls the behavior.
Disabling hosting startup assemblies using the host setting or environment variable disables the assembly
globally and may disable several characteristics of an app.
Project
Create a hosting startup with either of the following project types:
Class library
Console app without an entry point
Class library
A hosting startup enhancement can be provided in a class library. The library contains a HostingStartup
attribute.
The sample code includes a Razor Pages app, HostingStartupApp, and a class library, HostingStartupLibrary. The
class library:
Contains a hosting startup class, ServiceKeyInjection , which implements IHostingStartup .
ServiceKeyInjection adds a pair of service strings to the app's configuration using the in-memory
configuration provider (AddInMemoryCollection).
Includes a HostingStartup attribute that identifies the hosting startup's namespace and class.
The ServiceKeyInjectionclass's Configure method uses an IWebHostBuilder to add enhancements to an app.
IHostingStartup.Configure in the hosting startup assembly is called by the runtime before Startup.Configure in
user code, which allows user code to overwrite any configuration provided by the hosting startup assembly.
HostingStartupLibrary/ServiceKeyInjection.cs:
[assembly: HostingStartup(typeof(HostingStartupLibrary.ServiceKeyInjection))]
namespace HostingStartupLibrary
{
public class ServiceKeyInjection : IHostingStartup
{
public void Configure(IWebHostBuilder builder)
{
builder.ConfigureAppConfiguration(config =>
{
{
{"DevAccount_FromLibrary", "DEV_1111111-1111"},
{"ProdAccount_FromLibrary", "PROD_2222222-2222"}
};
config.AddInMemoryCollection(dict);
});
}
}
}
The app's Index page reads and renders the configuration values for the two keys set by the class library's hosting
startup assembly:
HostingStartupApp/Pages/Index.cshtml.cs:
{
public IndexModel(IConfiguration config)
{
ServiceKey_Development_Library = config["DevAccount_FromLibrary"];
ServiceKey_Production_Library = config["ProdAccount_FromLibrary"];
ServiceKey_Development_Package = config["DevAccount_FromPackage"];
ServiceKey_Production_Package = config["ProdAccount_FromPackage"];
}
public string ServiceKey_Development_Library { get; private set; }

public string ServiceKey_Production_Library { get; private set; }
public string ServiceKey_Development_Package { get; private set; }
public string ServiceKey_Production_Package { get; private set; }
public void OnGet()

{
}
}
The sample code also includes a NuGet package project that provides a separate hosting startup,
HostingStartupPackage. The package has the same characteristics of the class library described earlier. The
package:
Contains a hosting startup class, ServiceKeyInjection , which implements IHostingStartup .
ServiceKeyInjection adds a pair of service strings to the app's configuration.
Includes a HostingStartup attribute.
HostingStartupPackage/ServiceKeyInjection.cs:
[assembly: HostingStartup(typeof(HostingStartupPackage.ServiceKeyInjection))]
namespace HostingStartupPackage
{
public class ServiceKeyInjection : IHostingStartup
{
{
builder.ConfigureAppConfiguration(config =>
{
{
{"DevAccount_FromPackage", "DEV_3333333-3333"},
{"ProdAccount_FromPackage", "PROD_4444444-4444"}
};
config.AddInMemoryCollection(dict);
});
}
}
}
The app's Index page reads and renders the configuration values for the two keys set by the package's hosting
startup assembly:
HostingStartupApp/Pages/Index.cshtml.cs:
{
public IndexModel(IConfiguration config)
{
ServiceKey_Development_Library = config["DevAccount_FromLibrary"];
ServiceKey_Production_Library = config["ProdAccount_FromLibrary"];
ServiceKey_Development_Package = config["DevAccount_FromPackage"];
ServiceKey_Production_Package = config["ProdAccount_FromPackage"];
}
public string ServiceKey_Development_Library { get; private set; }

public string ServiceKey_Production_Library { get; private set; }
public string ServiceKey_Development_Package { get; private set; }
public string ServiceKey_Production_Package { get; private set; }
public void OnGet()

{
}
}
Console app without an entry point

This approach is only available for .NET Core apps, not .NET Framework.
A dynamic hosting startup enhancement that doesn't require a compile-time reference for activation can be
provided in a console app without an entry point. The app contains a HostingStartup attribute. To create a
dynamic hosting startup:
1. An implementation library is created from the class that contains the IHostingStartup implementation. The
implementation library is treated as a normal package.
2. A console app without an entry point references the implementation library package. A console app is used
because:
A dependencies file is a runnable app asset, so a library can't furnish a dependencies file.
A library can't be added directly to the runtime package store, which requires a runnable project that
targets the shared runtime.
3. The console app is published to obtain the hosting startup's dependencies. A consequence of publishing the
console app is that unused dependencies are trimmed from the dependencies file.
4. The app and its dependencies file is placed into the runtime package store. To discover the hosting startup
assembly and its dependencies file, they're referenced in a pair of environment variables.
The console app references the Microsoft.AspNetCore.Hosting.Abstractions package:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.Hosting.Abstractions"
Version="2.1.1" />
</ItemGroup>
</Project>
A HostingStartup attribute identifies a class as an implementation of IHostingStartup for loading and execution
when building the IWebHost. In the following example, the namespace is StartupEnhancement , and the class is
StartupEnhancementHostingStartup :
[assembly: HostingStartup(typeof(StartupEnhancement.StartupEnhancementHostingStartup))]
A class implements IHostingStartup . The class's Configure method uses an IWebHostBuilder to add
enhancements to an app. IHostingStartup.Configure in the hosting startup assembly is called by the runtime
before Startup.Configure in user code, which allows user code to overwrite any configuration provided by the
hosting startup assembly.
namespace StartupEnhancement
{
public class StartupEnhancementHostingStartup : IHostingStartup
{
{
// Use the IWebHostBuilder to add app enhancements.
}
}
}
When building an IHostingStartup project, the dependencies file (*.deps.json) sets the runtime location of the
assembly to the bin folder:
"targets": {
".NETCoreApp,Version=v2.1": {
"StartupEnhancement/1.0.0": {
"dependencies": {
"Microsoft.AspNetCore.Hosting.Abstractions": "2.1.1"
},
"runtime": {
"StartupEnhancement.dll": {}
}
}
}
}
Only part of the file is shown. The assembly name in the example is StartupEnhancement .
Specify the hosting startup assembly

For either a class library- or console app-supplied hosting startup, specify the hosting startup assembly's name in
the ASPNETCORE_HOSTINGSTARTUPASSEMBLIES environment variable. The environment variable is a semicolon-
delimited list of assemblies.
Only hosting startup assemblies are scanned for the HostingStartup attribute. For the sample app,
HostingStartupApp, to discover the hosting startups described earlier, the environment variable is set to the
following value:
HostingStartupLibrary;HostingStartupPackage;StartupDiagnostics
A hosting startup assembly can also be set using the Hosting Startup Assemblies host configuration setting.
When multiple hosting startup assembles are present, their Configure methods are executed in the order that the
assemblies are listed.
Activation
Options for hosting startup activation are:
Runtime store – Activation doesn't require a compile-time reference for activation. The sample app places the
hosting startup assembly and dependencies files into a folder, deployment, to facilitate deployment of the
hosting startup in a multimachine environment. The deployment folder also includes a PowerShell script that
creates or modifies environment variables on the deployment system to enable the hosting startup.
Compile-time reference required for activation
NuGet package
Project bin folder
Runtime store
The hosting startup implementation is placed in the runtime store. A compile-time reference to the assembly isn't
required by the enhanced app.
After the hosting startup is built, the hosting startup's project file serves as the manifest file for the dotnet store
command.
dotnet store --manifest <PROJECT_FILE> --runtime <RUNTIME_IDENTIFIER>
This command places the hosting startup assembly and other dependencies that aren't part of the shared
framework in the user profile's runtime store at:
Windows
macOS
Linux
%USERPROFILE%\.dotnet\store\x64\<TARGET_FRAMEWORK_MONIKER>\<ENHANCEMENT_ASSEMBLY_NAME>\
<ENHANCEMENT_VERSION>\lib\<TARGET_FRAMEWORK_MONIKER>\
If you desire to place the assembly and dependencies for global use, add the -o|--output option to the
dotnet store command with the following path:
Windows
macOS
Linux
%PROGRAMFILES%\dotnet\store\x64\<TARGET_FRAMEWORK_MONIKER>\<ENHANCEMENT_ASSEMBLY_NAME>\
<ENHANCEMENT_VERSION>\lib\<TARGET_FRAMEWORK_MONIKER>\
Modify and place the hosting startup's dependencies file

The runtime location is specified in the *.deps.json file. To activate the enhancement, the runtime element must
specify the location of the enhancement's runtime assembly. Prefix the runtime location with
lib/<TARGET_FRAMEWORK_MONIKER>/ :
"targets": {
".NETCoreApp,Version=v2.1": {
"StartupEnhancement/1.0.0": {
"dependencies": {
"Microsoft.AspNetCore.Hosting.Abstractions": "2.1.1"
},
"runtime": {
"lib/netcoreapp2.1/StartupEnhancement.dll": {}
}
}
}
}
In the sample code (StartupDiagnostics project), modification of the *.deps.json file is performed by a PowerShell
script. The PowerShell script is automatically triggered by a build target in the project file.
The implementation's *.deps.json file must be in an accessible location.
For per-user use, place the file in the additonalDeps folder of the user profile's .dotnet settings:
Windows
macOS
Linux
%USERPROFILE%\.dotnet\x64\additionalDeps\<ENHANCEMENT_ASSEMBLY_NAME>\shared\Microsoft.NETCore.App\
<SHARED_FRAMEWORK_VERSION>\
For global use, place the file in the additonalDeps folder of the .NET Core installation:
Windows
macOS
Linux
%PROGRAMFILES%\dotnet\additionalDeps\<ENHANCEMENT_ASSEMBLY_NAME>\shared\Microsoft.NETCore.App\
<SHARED_FRAMEWORK_VERSION>\
The shared framework version reflects the version of the shared runtime that the target app uses. The shared
runtime is shown in the *.runtimeconfig.json file. In the sample app (HostingStartupApp), the shared runtime is
specified in the HostingStartupApp.runtimeconfig.json file.
List the hosting startup's dependencies file
The location of the implementation's *.deps.json file is listed in the DOTNET_ADDITIONAL_DEPS environment variable.
If the file is placed in the user profile's .dotnet folder, set the environment variable's value to:
Windows
macOS
Linux
%USERPROFILE%\.dotnet\x64\additionalDeps\
If the file is placed in the .NET Core installation for global use, provide the full path to the file:
Windows
macOS
Linux
%PROGRAMFILES%\dotnet\additionalDeps\<ENHANCEMENT_ASSEMBLY_NAME>\shared\Microsoft.NETCore.App\
<SHARED_FRAMEWORK_VERSION>\<ENHANCEMENT_ASSEMBLY_NAME>.deps.json
For the sample app (HostingStartupApp) to find the dependencies file (HostingStartupApp.runtimeconfig.json),
the dependencies file is placed in the user's profile.
Windows
macOS
Linux
Set the DOTNET_ADDITIONAL_DEPS environment variable to the following value:
%UserProfile%\.dotnet\x64\additionalDeps\StartupDiagnostics\
For examples of how to set environment variables for various operating systems, see Use multiple environments.
Deployment
To facilitate the deployment of a hosting startup in a multimachine environment, the sample app creates a
deployment folder in published output that contains:
The hosting startup assembly.
The hosting startup dependencies file.
A PowerShell script that creates or modifies the ASPNETCORE_HOSTINGSTARTUPASSEMBLIES and
DOTNET_ADDITIONAL_DEPS to support the activation of the hosting startup. Run the script from an administrative
PowerShell command prompt on the deployment system.
NuGet package
A hosting startup enhancement can be provided in a NuGet package. The package has a HostingStartup
attribute. The hosting startup types provided by the package are made available to the app using either of the
following approaches:
The enhanced app's project file makes a package reference for the hosting startup in the app's project file (a
compile-time reference). With the compile-time reference in place, the hosting startup assembly and all of its
dependencies are incorporated into the app's dependency file (*.deps.json). This approach applies to a hosting
startup assembly package published to nuget.org.
The hosting startup's dependencies file is made available to the enhanced app as described in the Runtime
store section (without a compile-time reference).
For more information on NuGet packages and the runtime store, see the following topics:
How to Create a NuGet Package with Cross Platform Tools
Publishing packages
Runtime package store
Project bin folder
A hosting startup enhancement can be provided by a bin-deployed assembly in the enhanced app. The hosting
startup types provided by the assembly are made available to the app using either of the following approaches:
The enhanced app's project file makes an assembly reference to the hosting startup (a compile-time
reference). With the compile-time reference in place, the hosting startup assembly and all of its dependencies
are incorporated into the app's dependency file (*.deps.json). This approach applies when the deployment
scenario calls for moving the compiled hosting startup library's assembly (DLL file) to the consuming project
or to a location accessible by the consuming project and a compile-time reference is made to the hosting
startup's assembly.
The hosting startup's dependencies file is made available to the enhanced app as described in the Runtime
store section (without a compile-time reference).
Sample code
The sample code (how to download) demonstrates hosting startup implementation scenarios:
Two hosting startup assemblies (class libraries) set a pair of in-memory configuration key-value pairs each:
NuGet package (HostingStartupPackage)
Class library ( HostingStartupLibrary)
A hosting startup is activated from a runtime store-deployed assembly ( StartupDiagnostics). The assembly
adds two middlewares to the app at startup that provide diagnostic information on:
Registered services
Address (scheme, host, path base, path, query string)
Connection (remote IP, remote port, local IP, local port, client certificate)
Request headers
To run the sample:
Activation from a NuGet package
1. Compile the HostingStartupPackage package with the dotnet pack command.
2. Add the package's assembly name of the HostingStartupPackage to the
ASPNETCORE_HOSTINGSTARTUPASSEMBLIES environment variable.
3. Compile and run the app. A package reference is present in the enhanced app (a compile-time reference).
A <PropertyGroup> in the app's project file specifies the package project's output
(../HostingStartupPackage/bin/Debug) as a package source. This allows the app to use the package
without uploading the package to nuget.org. For more information, see the notes in the
HostingStartupApp's project file.
<PropertyGroup>
<RestoreSources>$(RestoreSources);https://api.nuget.org/v3/index.json;../HostingStartupPackage/bin/Deb
ug</RestoreSources>
</PropertyGroup>
4. Observe that the service configuration key values rendered by the Index page match the values set by the
package's ServiceKeyInjection.Configure method.
If you make changes to the HostingStartupPackage project and recompile it, clear the local NuGet package
caches to ensure that the HostingStartupApp receives the updated package and not a stale package from the local
cache. To clear the local NuGet caches, execute the following dotnet nuget locals command:
dotnet nuget locals all --clear
Activation from a class library

1. Compile the HostingStartupLibrary class library with the dotnet build command.
2. Add the class library's assembly name of HostingStartupLibrary to the
ASPNETCORE_HOSTINGSTARTUPASSEMBLIES environment variable.
3. bin-deploy the class library's assembly to the app by copying the HostingStartupLibrary.dll file from the
class library's compiled output to the app's bin/Debug folder.
4. Compile and run the app. An <ItemGroup> in the app's project file references the class library's assembly
(.\bin\Debug\netcoreapp2.1\HostingStartupLibrary.dll) (a compile-time reference). For more information,
see the notes in the HostingStartupApp's project file.
<ItemGroup>
<Reference Include=".\bin\Debug\netcoreapp2.1\HostingStartupLibrary.dll">
<HintPath>.\bin\Debug\netcoreapp2.1\HostingStartupLibrary.dll</HintPath>
<SpecificVersion>False</SpecificVersion>
</Reference>
</ItemGroup>
5. Observe that the service configuration key values rendered by the Index page match the values set by the
class library's ServiceKeyInjection.Configure method.
Activation from a runtime store-deployed assembly

1. The StartupDiagnostics project uses PowerShell to modify its StartupDiagnostics.deps.json file. PowerShell
is installed by default on Windows starting with Windows 7 SP1 and Windows Server 2008 R2 SP1. To
obtain PowerShell on other platforms, see Installing Windows PowerShell.
2. Build the StartupDiagnostics project. After the project is built, a build target in the project file
automatically:
Triggers the PowerShell script to modify the StartupDiagnostics.deps.json file.
Moves the StartupDiagnostics.deps.json file to the user profile's additionalDeps folder.
3. Execute the dotnet store command at a command prompt in the hosting startup's directory to store the
assembly and its dependencies in the user profile's runtime store:
dotnet store --manifest StartupDiagnostics.csproj --runtime <RID>
For Windows, the command uses the win7-x64 runtime identifier (RID ). When providing the hosting
startup for a different runtime, substitute the correct RID.
4. Set the environment variables:
Add the assembly name of StartupDiagnostics to the ASPNETCORE_HOSTINGSTARTUPASSEMBLIES
environment variable.
On Windows, set the DOTNET_ADDITIONAL_DEPS environment variable to
%UserProfile%\.dotnet\x64\additionalDeps\StartupDiagnostics\ . On macOS/Linux, set the
DOTNET_ADDITIONAL_DEPS environment variable to
/Users/<USER>/.dotnet/x64/additionalDeps/StartupDiagnostics/ , where <USER> is the user profile that
contains the hosting startup.
5. Run the sample app.
6. Request the /services endpoint to see the app's registered services. Request the /diag endpoint to see
the diagnostic information.
Web server implementations in ASP.NET Core
By Tom Dykstra, Steve Smith, Stephen Halter, and Chris Ross

An ASP.NET Core app runs with an in-process HTTP server implementation. The server implementation listens
for HTTP requests and surfaces them to the app as sets of request features composed into an HttpContext.
ASP.NET Core ships two server implementations:
Kestrel is the default, cross-platform HTTP server for ASP.NET Core.
HTTP.sys is a Windows-only HTTP server based on the HTTP.sys kernel driver and HTTP Server API.
(HTTP.sys is called WebListener in ASP.NET Core 1.x.)
Kestrel
Kestrel is the default web server included in ASP.NET Core project templates.
Kestrel can be used by itself or with a reverse proxy server, such as IIS, Nginx, or Apache. A reverse proxy server
receives HTTP requests from the Internet and forwards them to Kestrel after some preliminary handling.
Either configuration—with or without a reverse proxy server—is a valid and supported hosting configuration for
ASP.NET Core 2.0 or later apps. For more information, see When to use Kestrel with a reverse proxy.
If the app only accepts requests from an internal network, Kestrel can be used by itself.
If the app is exposed to the Internet, Kestrel must use IIS, Nginx, or Apache as a reverse proxy server. A reverse
proxy server receives HTTP requests from the Internet and forwards them to Kestrel after some preliminary
handling, as shown in the following diagram:
The most important reason for using a reverse proxy for edge deployments (exposed to traffic from the Internet)
is security. The 1.x versions of Kestrel don't have important security features to defend against attacks from the
Internet. This includes, but isn't limited to, appropriate timeouts, request size limits, and concurrent connection
limits.
For more information, see When to use Kestrel with a reverse proxy.
IIS, Nginx, and Apache can't be used without Kestrel or a custom server implementation. ASP.NET Core was
designed to run in its own process so that it can behave consistently across platforms. IIS, Nginx, and Apache
dictate their own startup procedure and environment. To use these server technologies directly, ASP.NET Core
would need to adapt to the requirements of each server. Using a web server implementation, such as Kestrel,
ASP.NET Core has control over the startup process and environment when hosted on different server
technologies.
IIS with Kestrel
When using IIS or IIS Express as a reverse proxy for ASP.NET Core, the ASP.NET Core app runs in a process
separate from the IIS worker process. In the IIS process, the ASP.NET Core Module coordinates the reverse
proxy relationship. The primary functions of the ASP.NET Core Module are to start the ASP.NET Core app,
restart the app when it crashes, and forward HTTP traffic to the app. For more information, see ASP.NET Core
Module.
Nginx with Kestrel
For information on how to use Nginx on Linux as a reverse proxy server for Kestrel, see Host on Linux with
Nginx.
Apache with Kestrel
For information on how to use Apache on Linux as a reverse proxy server for Kestrel, see Host on Linux with
Apache.
HTTP.sys
If ASP.NET Core apps are run on Windows, HTTP.sys is an alternative to Kestrel. Kestrel is generally
recommended for best performance. HTTP.sys can be used in scenarios where the app is exposed to the Internet
and required capabilities are supported by HTTP.sys but not Kestrel. For information on HTTP.sys, see HTTP.sys.
HTTP.sys can also be used for apps that are only exposed to an internal network.
HTTP.sys is named WebListener in ASP.NET Core 1.x. If ASP.NET Core apps are run on Windows, WebListener
is an alternative for scenarios where IIS isn't available to host apps.
WebListener can also be used in place of Kestrel for apps that are only exposed to an internal network, if required
capabilities are supported by WebListener but not Kestrel. For information on WebListener, see WebListener.
ASP.NET Core server infrastructure

The IApplicationBuilder available in the Startup.Configure method exposes the ServerFeatures property of type
IFeatureCollection. Kestrel and HTTP.sys (WebListener in ASP.NET Core 1.x) only expose a single feature each,
IServerAddressesFeature, but different server implementations may expose additional functionality.
IServerAddressesFeature can be used to find out which port the server implementation has bound at runtime.
Custom servers
If the built-in servers don't meet the app's requirements, a custom server implementation can be created. The
Open Web Interface for .NET (OWIN ) guide demonstrates how to write a Nowin-based IServer implementation.
Only the feature interfaces that the app uses require implementation, though at a minimum IHttpRequestFeature
and IHttpResponseFeature must be supported.
Server startup
When using Visual Studio, Visual Studio for Mac, or Visual Studio Code, the server is launched when the app is
started by the Integrated Development Environment (IDE ). In Visual Studio on Windows, launch profiles can be
used to start the app and server with either IIS Express/ASP.NET Core Module or the console. In Visual Studio
Code, the app and server are started by Omnisharp, which activates the CoreCLR debugger. Using Visual Studio
for Mac, the app and server are started by the Mono Soft-Mode Debugger.
When launching an app from a command prompt in the project's folder,dotnet run launches the app and server
(Kestrel and HTTP.sys only). The configuration is specified by the -c|--configuration option, which is set to either
Debug (default) or Release . If launch profiles are present in a launchSettings.json file, use the
--launch-profile <NAME> option to set the launch profile (for example, Development or Production ). For more
information, see the dotnet run and .NET Core distribution packaging topics.
HTTP/2 support
HTTP/2 is supported with ASP.NET Core in the following deployment scenarios:
Kestrel
Operating system
Windows Server 2012 R2/Windows 8.1 or later
Linux with OpenSSL 1.0.2 or later (for example, Ubuntu 16.04 or later)
HTTP/2 will be supported on macOS in a future release.
Target framework: .NET Core 2.2 or later
HTTP.sys
Windows Server 2016/Windows 10 or later
Target framework: Not applicable to HTTP.sys deployments.
IIS (in-process)
Windows Server 2016/Windows 10 or later; IIS 10 or later
IIS (out-of-process)
Edge connections use HTTP/2, but the reverse proxy connection to Kestrel uses HTTP/1.1.
Target framework: Not applicable to IIS out-of-process deployments.
HTTP.sys
Target framework: Not applicable to HTTP.sys deployments.
IIS (out-of-process)
Edge connections use HTTP/2, but the reverse proxy connection to Kestrel uses HTTP/1.1.
Target framework: Not applicable to IIS out-of-process deployments.
An HTTP/2 connection must use Application-Layer Protocol Negotiation (ALPN ) and TLS 1.2 or later. For more
information, see the topics that pertain to your server deployment scenarios.
Kestrel web server implementation in ASP.NET Core
ASP.NET Core Module
Host ASP.NET Core on Azure App Service
HTTP.sys web server implementation in ASP.NET Core (for ASP.NET Core 1.x, see WebListener web server
implementation in ASP.NET Core)
Kestrel web server implementation in ASP.NET Core
By Tom Dykstra, Chris Ross, and Stephen Halter

Kestrel is a cross-platform web server for ASP.NET Core. Kestrel is the web server that's included by default in
ASP.NET Core project templates.
Kestrel supports the following features:
HTTPS
Opaque upgrade used to enable WebSockets
Unix sockets for high performance behind Nginx
HTTP/2 (except on macOS†)
†HTTP/2 will be supported on macOS in a future release.
HTTPS
Opaque upgrade used to enable WebSockets
Unix sockets for high performance behind Nginx
Kestrel is supported on all platforms and versions that .NET Core supports.
HTTP/2 support
HTTP/2 is available for ASP.NET Core apps if the following base requirements are met:
Operating system†
Windows Server 2012 R2/Windows 8.1 or later
Linux with OpenSSL 1.0.2 or later (for example, Ubuntu 16.04 or later)
Application-Layer Protocol Negotiation (ALPN ) connection
TLS 1.2 or later connection
†HTTP/2 will be supported on macOS in a future release.
If an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/2 .
HTTP/2 is disabled by default. For more information on configuration, see the Kestrel options and Endpoint
configuration sections.
When to use Kestrel with a reverse proxy

You can use Kestrel by itself or with a reverse proxy server, such as IIS, Nginx, or Apache. A reverse proxy
server receives HTTP requests from the Internet and forwards them to Kestrel after some preliminary
handling.
Either configuration—with or without a reverse proxy server—is a valid and supported hosting configuration
for ASP.NET Core 2.0 or later apps.
If an app accepts requests only from an internal network, Kestrel can be used directly as the app's server.
If you expose your app to the Internet, use IIS, Nginx, or Apache as a reverse proxy server. A reverse proxy
server receives HTTP requests from the Internet and forwards them to Kestrel after some preliminary
handling.
A reverse proxy is required for edge deployments (exposed to traffic from the Internet) for security reasons.
The 1.x versions of Kestrel don't have a full complement of defenses against attacks, such as appropriate
timeouts, size limits, and concurrent connection limits.
A reverse proxy scenario exists when there are multiple apps that share the same IP and port running on a
single server. Kestrel doesn't support this scenario because Kestrel doesn't support sharing the same IP and
port among multiple processes. When Kestrel is configured to listen on a port, Kestrel handles all of the traffic
for that port regardless of requests' host header. A reverse proxy that can share ports has the ability to forward
requests to Kestrel on a unique IP and port.
Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice:
It can limit the exposed public surface area of the apps that it hosts.
It provides an additional layer of configuration and defense.
It might integrate better with existing infrastructure.
It simplifies load balancing and SSL configuration. Only the reverse proxy server requires an SSL
certificate, and that server can communicate with your app servers on the internal network using plain
HTTP.
WARNING
If not using a reverse proxy with host filtering enabled, host filtering must be enabled.
How to use Kestrel in ASP.NET Core apps

The Microsoft.AspNetCore.Server.Kestrel package is included in the Microsoft.AspNetCore.App metapackage
(ASP.NET Core 2.1 or later).
ASP.NET Core project templates use Kestrel by default. In Program.cs, the template code calls
CreateDefaultBuilder, which calls UseKestrel behind the scenes.
{
}

To provide additional configuration after calling CreateDefaultBuilder , use ConfigureKestrel :

{
// Set properties and call methods on options
});
To provide additional configuration after calling CreateDefaultBuilder , call UseKestrel:

{
// Set properties and call methods on options
})
.Build();
Install the Microsoft.AspNetCore.Server.Kestrel NuGet package.

Call the UseKestrel extension method on WebHostBuilder in the Main method, specifying any Kestrel options
required, as shown in the next section.

{
Console.WriteLine("Running demo with Kestrel.");

.Build();
var builder = new WebHostBuilder()

{
if (config["threadCount"] != null)
{
options.ThreadCount = int.Parse(config["threadCount"]);
}
})
.UseUrls("http://localhost:5000");
var host = builder.Build();

host.Run();
}
Kestrel options
The Kestrel web server has constraint configuration options that are especially useful in Internet-facing
deployments. A few important limits that can be customized:
Set these and other constraints on the Limits property of the KestrelServerOptions class. The Limits property
holds an instance of the KestrelServerLimits class.
MaxConcurrentConnections
MaxConcurrentUpgradedConnections
The maximum number of concurrent open TCP connections can be set for the entire app with the following
code:

{
options.Limits.MaxConcurrentConnections = 100;
});
{
options.Limits.MaxConcurrentUpgradedConnections = 100;
options.Limits.MaxRequestBodySize = 10 * 1024;
options.Limits.MinRequestBodyDataRate =
new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
options.Limits.MinResponseDataRate =
options.Listen(IPAddress.Loopback, 5000);
options.Listen(IPAddress.Loopback, 5001, listenOptions =>
{
listenOptions.UseHttps("testCert.pfx", "testPassword");
});
});
There's a separate limit for connections that have been upgraded from HTTP or HTTPS to another protocol
(for example, on a WebSockets request). After a connection is upgraded, it isn't counted against the
MaxConcurrentConnections limit.

{
});
{
{
});
});
The maximum number of connections is unlimited (null) by default.

MaxRequestBodySize
The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.
The recommended approach to override the limit in an ASP.NET Core MVC app is to use the
RequestSizeLimit attribute on an action method:
[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()
Here's an example that shows how to configure the constraint for the app on every request:

{
});
{
{
});
});
You can override the setting on a specific request in middleware:

{
context.Features.Get<IHttpMaxRequestBodySizeFeature>()
.MaxRequestBodySize = 10 * 1024;
context.Features.Get<IHttpMinRequestBodyDataRateFeature>()
.MinDataRate = new MinDataRate(bytesPerSecond: 100,
gracePeriod: TimeSpan.FromSeconds(10));
context.Features.Get<IHttpMinResponseDataRateFeature>()
An exception is thrown if you attempt to configure the limit on a request after the app has started to read the
request. There's an IsReadOnly property that indicates if the MaxRequestBodySize property is in read-only state,
meaning it's too late to configure the limit.
MinRequestBodyDataRate
MinResponseDataRate
Kestrel checks every second if data is arriving at the specified rate in bytes/second. If the rate drops below the
minimum, the connection is timed out. The grace period is the amount of time that Kestrel gives the client to
increase its send rate up to the minimum; the rate isn't checked during that time. The grace period helps avoid
dropping connections that are initially sending data at a slow rate due to TCP slow -start.
The default minimum rate is 240 bytes/second with a 5 second grace period.
A minimum rate also applies to the response. The code to set the request limit and the response limit is the
same except for having RequestBody or Response in the property and interface names.
Here's an example that shows how to configure the minimum data rates in Program.cs:

{
});
{
{
});
});
You can configure the rates per request in middleware:

{
context.Features.Get<IHttpMinRequestBodyDataRateFeature>()
context.Features.Get<IHttpMinResponseDataRateFeature>()
Maximum streams per connection

Http2.MaxStreamsPerConnection limits the number of concurrent request streams per HTTP/2 connection.
Excess streams are refused.

{
options.Limits.Http2.MaxStreamsPerConnection = 100;
});
The default value is 100.

Header table size
The HPACK decoder decompresses HTTP headers for HTTP/2 connections. Http2.HeaderTableSize limits the
size of the header compression table that the HPACK decoder uses. The value is provided in octets and must be
greater than zero (0).

{
options.Limits.Http2.HeaderTableSize = 4096;
});
The default value is 4096.

Maximum frame size
Http2.MaxFrameSize indicates the maximum size of the HTTP/2 connection frame payload to receive. The value
is provided in octets and must be between 2^14 (16,384) and 2^24-1 (16,777,215).

{
options.Limits.Http2.MaxFrameSize = 16384;
});
The default value is 2^14 (16,384).

For information about other Kestrel options and limits, see:
KestrelServerOptions
KestrelServerLimits
ListenOptions
For information about Kestrel options and limits, see:
KestrelServerOptions class
KestrelServerLimits
Endpoint configuration
By default, ASP.NET Core binds to http://localhost:5000 . Call Listen or ListenUnixSocket methods on
KestrelServerOptions to configure URL prefixes and ports for Kestrel. UseUrls , the --urls command-line
argument, urls host configuration key, and the ASPNETCORE_URLS environment variable also work but have the
limitations noted later in this section.
The urls host configuration key must come from the host configuration, not the app configuration. Adding a
urls key and value to appsettings.json doesn't affect host configuration because the host is completely
initialized by the time the configuration is read from the configuration file. However, a urls key in
appsettings.json can be used with UseConfiguration on the host builder to configure the host:

.AddJsonFile("appSettings.json", optional: true, reloadOnChange: true)
.Build();

.UseKestrel()
.Build();
By default, ASP.NET Core binds to:

http://localhost:5000
https://localhost:5001 (when a local development certificate is present)
A development certificate is created:

When the .NET Core SDK is installed.
The dev-certs tool is used to create a certificate.
Some browsers require that you grant explicit permission to the browser to trust the local development
certificate.
ASP.NET Core 2.1 and later project templates configure apps to run on HTTPS by default and include HTTPS
redirection and HSTS support.
Call Listen or ListenUnixSocket methods on KestrelServerOptions to configure URL prefixes and ports for
Kestrel.
UseUrls , the --urls command-line argument, urls host configuration key, and the ASPNETCORE_URLS
environment variable also work but have the limitations noted later in this section (a default certificate must be
available for HTTPS endpoint configuration).
ASP.NET Core 2.1 KestrelServerOptions configuration:
ConfigureEndpointDefaults(Action<ListenOptions>)
Specifies a configuration Action to run for each specified endpoint. Calling ConfigureEndpointDefaults
multiple times replaces prior Action s with the last Action specified.
ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)
Specifies a configuration Action to run for each HTTPS endpoint. Calling ConfigureHttpsDefaults multiple
times replaces prior Action s with the last Action specified.
Configure (IConfiguration)
Creates a configuration loader for setting up Kestrel that takes an IConfiguration as input. The configuration
must be scoped to the configuration section for Kestrel.
ListenOptions.UseHttps
Configure Kestrel to use HTTPS.
ListenOptions.UseHttps extensions:
UseHttps – Configure Kestrel to use HTTPS with the default certificate. Throws an exception if no default
certificate is configured.
UseHttps(string fileName)
UseHttps(string fileName, string password)
UseHttps(string fileName, string password, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(StoreName storeName, string subject)
UseHttps(StoreName storeName, string subject, bool allowInvalid)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location,
Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(X509Certificate2 serverCertificate)
UseHttps(X509Certificate2 serverCertificate, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(Action<HttpsConnectionAdapterOptions> configureOptions)
ListenOptions.UseHttps parameters:
filename is the path and file name of a certificate file, relative to the directory that contains the app's
content files.
password is the password required to access the X.509 certificate data.
configureOptions is an Action to configure the HttpsConnectionAdapterOptions . Returns the ListenOptions
.
storeName is the certificate store from which to load the certificate.
subject is the subject name for the certificate.
allowInvalid indicates if invalid certificates should be considered, such as self-signed certificates.
location is the store location to load the certificate from.
serverCertificate is the X.509 certificate.
In production, HTTPS must be explicitly configured. At a minimum, a default certificate must be provided.
Supported configurations described next:
No configuration
Replace the default certificate from configuration
Change the defaults in code
No configuration
Kestrel listens on http://localhost:5000 and https://localhost:5001 (if a default cert is available).
Specify URLs using the:
ASPNETCORE_URLS environment variable.
--urls command-line argument.
urls host configuration key.
UseUrls extension method.
For more information, see Server URLs and Override configuration.

The value provided using these approaches can be one or more HTTP and HTTPS endpoints (HTTPS if a
default cert is available). Configure the value as a semicolon-separated list (for example,
"Urls": "http://localhost:8000;http://localhost:8001" ).
Replace the default certificate from configuration

WebHost.CreateDefaultBuilder calls serverOptions.Configure(context.Configuration.GetSection("Kestrel")) by
default to load Kestrel configuration. A default HTTPS app settings configuration schema is available for
Kestrel. Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk
or from a certificate store.
In the following appsettings.json example:
Set AllowInvalid to true to permit the use of invalid certificates (for example, self-signed certificates).
Any HTTPS endpoint that doesn't specify a certificate (HttpsDefaultCert in the example that follows) falls
back to the cert defined under Certificates > Default or the development certificate.
{
"Kestrel": {
"EndPoints": {
"Http": {
"Url": "http://localhost:5000"
},
"HttpsInlineCertFile": {
"Url": "https://localhost:5001",
"Certificate": {
"Path": "<path to .pfx file>",
"Password": "<certificate password>"
}
},
"HttpsInlineCertStore": {
"Certificate": {
"Subject": "<subject; required>",
"Store": "<certificate store; defaults to My>",
"Location": "<location; defaults to CurrentUser>",
"AllowInvalid": "<true or false; defaults to false>"
}
},
"HttpsDefaultCert": {
"Url": "https://localhost:5003"
},
"Https": {
"Url": "https://*:5004",
"Certificate": {
}
}
},
"Certificates": {
"Default": {
}
}
}
}
An alternative to using Path and Password for any certificate node is to specify the certificate using certificate
store fields. For example, the Certificates > Default certificate can be specified as:
"Default": {
"Subject": "<subject; required>",
"Store": "<cert store; defaults to My>",
"Location": "<location; defaults to CurrentUser>",
"AllowInvalid": "<true or false; defaults to false>"
}
Schema notes:
Endpoints names are case-insensitive. For example, HTTPS and Https are valid.
The Url parameter is required for each endpoint. The format for this parameter is the same as the top-
level Urls configuration parameter except that it's limited to a single value.
These endpoints replace those defined in the top-level Urls configuration rather than adding to them.
Endpoints defined in code via Listen are cumulative with the endpoints defined in the configuration
section.
The Certificate section is optional. If the Certificate section isn't specified, the defaults defined in
earlier scenarios are used. If no defaults are available, the server throws an exception and fails to start.
The Certificate section supports both Path–Password and Subject–Store certificates.
Any number of endpoints may be defined in this way so long as they don't cause port conflicts.
options.Configure(context.Configuration.GetSection("Kestrel")) returns a KestrelConfigurationLoader
with an .Endpoint(string name, options => { }) method that can be used to supplement a configured
endpoint's settings:
options.Configure(context.Configuration.GetSection("Kestrel"))
.Endpoint("HTTPS", opt =>
{
opt.HttpsOptions.SslProtocols = SslProtocols.Tls12;
});
You can also directly access KestrelServerOptions.ConfigurationLoader to keep iterating on the existing
loader, such as the one provided by WebHost.CreateDefaultBuilder.
The configuration section for each endpoint is a available on the options in the Endpoint method so
that custom settings may be read.
Multiple configurations may be loaded by calling
options.Configure(context.Configuration.GetSection("Kestrel")) again with another section. Only the
last configuration is used, unless Load is explicitly called on prior instances. The metapackage doesn't
call Load so that its default configuration section may be replaced.
KestrelConfigurationLoader mirrors the Listen family of APIs from KestrelServerOptions as
Endpoint overloads, so code and config endpoints may be configured in the same place. These
overloads don't use names and only consume default settings from configuration.
Change the defaults in code
ConfigureEndpointDefaults and can be used to change default settings for
ConfigureHttpsDefaults
ListenOptions and HttpsConnectionAdapterOptions , including overriding the default certificate specified in the
prior scenario. ConfigureEndpointDefaults and ConfigureHttpsDefaults should be called before any endpoints
are configured.
options.ConfigureEndpointDefaults(opt =>
{
opt.NoDelay = true;
});
options.ConfigureHttpsDefaults(httpsOptions =>
{
httpsOptions.SslProtocols = SslProtocols.Tls12;
});
Kestrel support for SNI

Server Name Indication (SNI) can be used to host multiple domains on the same IP address and port. For SNI
to function, the client sends the host name for the secure session to the server during the TLS handshake so
that the server can provide the correct certificate. The client uses the furnished certificate for encrypted
communication with the server during the secure session that follows the TLS handshake.
Kestrel supports SNI via the ServerCertificateSelector callback. The callback is invoked once per connection
to allow the app to inspect the host name and select the appropriate certificate.
SNI support requires:
Running on target framework netcoreapp2.1 . On netcoreapp2.0 and net461 , the callback is invoked but
the name is always null . The name is also null if the client doesn't provide the host name parameter in
the TLS handshake.
All websites run on the same Kestrel instance. Kestrel doesn't support sharing an IP address and port across
multiple instances without a reverse proxy.

{
options.ListenAnyIP(5005, listenOptions =>
{
listenOptions.UseHttps(httpsOptions =>
{
var localhostCert = CertificateLoader.LoadFromStoreCert(
"localhost", "My", StoreLocation.CurrentUser,
allowInvalid: true);
var exampleCert = CertificateLoader.LoadFromStoreCert(
"example.com", "My", StoreLocation.CurrentUser,
var subExampleCert = CertificateLoader.LoadFromStoreCert(
"sub.example.com", "My", StoreLocation.CurrentUser,
var certs = new Dictionary<string, X509Certificate2>(
StringComparer.OrdinalIgnoreCase);
certs["localhost"] = localhostCert;
certs["example.com"] = exampleCert;
certs["sub.example.com"] = subExampleCert;
httpsOptions.ServerCertificateSelector = (connectionContext, name) =>

{
if (name != null && certs.TryGetValue(name, out var cert))
{
return cert;
}
return exampleCert;
};
});
});
});
.UseKestrel((context, options) =>
{
options.ListenAnyIP(5005, listenOptions =>
{
listenOptions.UseHttps(httpsOptions =>
{
var localhostCert = CertificateLoader.LoadFromStoreCert(
"localhost", "My", StoreLocation.CurrentUser,
var exampleCert = CertificateLoader.LoadFromStoreCert(
"example.com", "My", StoreLocation.CurrentUser,
var subExampleCert = CertificateLoader.LoadFromStoreCert(
"sub.example.com", "My", StoreLocation.CurrentUser,
var certs = new Dictionary<string, X509Certificate2>(
StringComparer.OrdinalIgnoreCase);
certs["localhost"] = localhostCert;
certs["example.com"] = exampleCert;
certs["sub.example.com"] = subExampleCert;
httpsOptions.ServerCertificateSelector = (connectionContext, name) =>

{
if (name != null && certs.TryGetValue(name, out var cert))
{
return cert;
}
return exampleCert;
};
});
});
})
.Build();
Bind to a TCP socket

The Listen method binds to a TCP socket, and an options lambda permits SSL certificate configuration:

{
}

{
{
});
});
{
}

{
{
});
});
The example configures SSL for an endpoint with ListenOptions. Use the same API to configure other Kestrel
settings for specific endpoints.
On Windows, self-signed certificates can be created using the New -SelfSignedCertificate PowerShell cmdlet.
For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.
On macOS, Linux, and Windows, certificates can be created using OpenSSL.
Bind to a Unix socket
Listen on a Unix socket with ListenUnixSocket for improved performance with Nginx, as shown in this
example:

{
options.ListenUnixSocket("/tmp/kestrel-test.sock");
options.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions =>
{
listenOptions.UseHttps("testCert.pfx", "testpassword");
});
});
{
options.ListenUnixSocket("/tmp/kestrel-test.sock");
options.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions =>
{
listenOptions.UseHttps("testCert.pfx", "testpassword");
});
});
Port 0
When the port number 0 is specified, Kestrel dynamically binds to an available port. The following example
shows how to determine which port Kestrel actually bound at runtime:
{
var serverAddressesFeature =
app.ServerFeatures.Get<IServerAddressesFeature>();

{
await context.Response
.WriteAsync("<!DOCTYPE html><html lang=\"en\"><head>" +
"<title></title></head><body><p>Hosted by Kestrel</p>");
if (serverAddressesFeature != null)
{
.WriteAsync("<p>Listening on the following addresses: " +
string.Join(", ", serverAddressesFeature.Addresses) +
"</p>");
}
await context.Response.WriteAsync("<p>Request URL: " +

$"{context.Request.GetDisplayUrl()}<p>");
});
}
When the app is run, the console window output indicates the dynamic port where the app can be reached:
Listening on the following addresses: http://127.0.0.1:48508
Limitations
Configure endpoints with the following approaches:
UseUrls
--urls command-line argument
urls host configuration key
ASPNETCORE_URLS environment variable
These methods are useful for making code work with servers other than Kestrel. However, be aware of the
following limitations:
SSL can't be used with these approaches unless a default certificate is provided in the HTTPS endpoint
configuration (for example, using KestrelServerOptions configuration or a configuration file as shown
earlier in this topic).
When both the Listen and UseUrls approaches are used simultaneously, the Listen endpoints override
the UseUrls endpoints.
IIS endpoint configuration
When using IIS, the URL bindings for IIS override bindings are set by either Listen or UseUrls . For more
information, see the ASP.NET Core Module topic.
By default, ASP.NET Core binds to http://localhost:5000 . Configure URL prefixes and ports for Kestrel using:
UseUrls extension method
--urls command-line argument
urls host configuration key
ASP.NET Core configuration system, including ASPNETCORE_URLS environment variable
For more information on these methods, see Hosting.
IIS endpoint configuration
When using IIS, the URL bindings for IIS override bindings set by UseUrls . For more information, see the
ASP.NET Core Module topic.
ListenOptions.Protocols
The Protocols property establishes the HTTP protocols ( HttpProtocols ) enabled on a connection endpoint or
for the server. Assign a value to the Protocols property from the HttpProtocols enum.
HTTPPROTOCOLS ENUM VALUE CONNECTION PROTOCOL PERMITTED
Http1 HTTP/1.1 only. Can be used with or without TLS.
Http2 HTTP/2 only. Primarily used with TLS. May be used without
TLS only if the client supports a Prior Knowledge mode.
Http1AndHttp2 HTTP/1.1 and HTTP/2. Requires a TLS and Application-Layer

Protocol Negotiation (ALPN) connection to negotiate
HTTP/2; otherwise, the connection defaults to HTTP/1.1.
The default protocol is HTTP/1.1.

TLS restrictions for HTTP/2:
TLS version 1.2 or later
Renegotiation disabled
Compression disabled
Minimum ephemeral key exchange sizes:
Elliptic curve Diffie-Hellman (ECDHE ) [ RFC4492] – 224 bits minimum
Finite field Diffie-Hellman (DHE ) [ TLS12 ] – 2048 bits minimum
Cipher suite not blacklisted
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [ TLS-ECDHE ] with the P -256 elliptic curve [ FIPS186 ] is supported by
default.
The following example permits HTTP/1.1 and HTTP/2 connections on port 8000. Connections are secured by
TLS with a supplied certificate:

{
options.Listen(IPAddress.Any, 8000, listenOptions =>
{
listenOptions.Protocols = HttpProtocols.Http1AndHttp2;
});
}
Optionally create an IConnectionAdapter implementation to filter TLS handshakes on a per-connection basis

for specific ciphers:
{
options.Listen(IPAddress.Any, 8000, listenOptions =>
{
listenOptions.Protocols = HttpProtocols.Http1AndHttp2;
listenOptions.ConnectionAdapters.Add(new TlsFilterAdapter());
});
}
private class TlsFilterAdapter : IConnectionAdapter

{
public bool IsHttps => false;
public Task<IAdaptedConnection> OnConnectionAsync(ConnectionAdapterContext context)

{
var tlsFeature = context.Features.Get<ITlsHandshakeFeature>();
// Throw NotSupportedException for any cipher algorithm that you don't

// wish to support. Alternatively, define and compare
// ITlsHandshakeFeature.CipherAlgorithm to a list of acceptable cipher
// suites.
//
// A ITlsHandshakeFeature.CipherAlgorithm of CipherAlgorithmType.Null
// indicates that no cipher algorithm supported by Kestrel matches the
// requested algorithm(s).
if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
{
throw new NotSupportedException("Prohibited cipher: " + tlsFeature.CipherAlgorithm);
}
return Task.FromResult<IAdaptedConnection>(new AdaptedConnection(context.ConnectionStream));

}
private class AdaptedConnection : IAdaptedConnection

{
public AdaptedConnection(Stream adaptedStream)
{
ConnectionStream = adaptedStream;
}
public Stream ConnectionStream { get; }

{
}
}
}
Set the protocol from configuration

WebHost.CreateDefaultBuilder calls serverOptions.Configure(context.Configuration.GetSection("Kestrel")) by
default to load Kestrel configuration.
In the following appsettings.json example, a default connection protocol (HTTP/1.1 and HTTP/2) is established
for all of Kestrel's endpoints:
{
"Kestrel": {
"EndPointDefaults": {
"Protocols": "Http1AndHttp2"
}
}
}
The following configuration file example establishes a connection protocol for a specific endpoint:
{
"Kestrel": {
"EndPoints": {
"HttpsDefaultCert": {
"Protocols": "Http1AndHttp2"
}
}
}
}
Protocols specified in code override values set by configuration.
Transport configuration
With the release of ASP.NET Core 2.1, Kestrel's default transport is no longer based on Libuv but instead
based on managed sockets. This is a breaking change for ASP.NET Core 2.0 apps upgrading to 2.1 that call
WebHostBuilderLibuvExtensions.UseLibuv and depend on either of the following packages:
Microsoft.AspNetCore.Server.Kestrel (direct package reference)
Microsoft.AspNetCore.App
For ASP.NET Core 2.1 or later projects that use the Microsoft.AspNetCore.App metapackage and require the
use of Libuv:
Add a dependency for the Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv package to the app's
project file:
<PackageReference Include="Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv"
Version="<LATEST_VERSION>" />
Call WebHostBuilderLibuvExtensions.UseLibuv:

{
{
}

.UseLibuv()
}
URL prefixes
When using UseUrls , --urls command-line argument, urls host configuration key, or ASPNETCORE_URLS
environment variable, the URL prefixes can be in any of the following formats.
Only HTTP URL prefixes are valid. Kestrel doesn't support SSL when configuring URL bindings using
UseUrls .
IPv4 address with port number
http://65.55.39.10:80/
0.0.0.0 is a special case that binds to all IPv4 addresses.

http://[0:0:0:0:0:ffff:4137:270a]:80/
[::] is the IPv6 equivalent of IPv4 0.0.0.0 .

Host name with port number
http://contoso.com:80/
http://*:80/
Host names, * , and + , aren't special. Anything not recognized as a valid IP address or localhost
binds to all IPv4 and IPv6 IPs. To bind different host names to different ASP.NET Core apps on the
same port, use HTTP.sys or a reverse proxy server, such as IIS, Nginx, or Apache.
WARNING
If not using a reverse proxy with host filtering enabled, enable host filtering.
Host localhost name with port number or loopback IP with port number
http://localhost:5000/
http://[::1]:5000/
When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. If the
requested port is in use by another service on either loopback interface, Kestrel fails to start. If either
loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported),
Kestrel logs a warning.
https://65.55.39.10:443/
0.0.0.0 is a special case that binds to all IPv4 addresses.

http://[0:0:0:0:0:ffff:4137:270a]:80/
https://[0:0:0:0:0:ffff:4137:270a]:443/
[::] is the IPv6 equivalent of IPv4 0.0.0.0 .

Host name with port number
http://contoso.com:80/
http://*:80/
https://contoso.com:443/
https://*:443/
Host names, * , and + aren't special. Anything that isn't a recognized IP address or localhost binds to
all IPv4 and IPv6 IPs. To bind different host names to different ASP.NET Core apps on the same port,
use WebListener or a reverse proxy server, such as IIS, Nginx, or Apache.
Host localhost name with port number or loopback IP with port number
http://localhost:5000/
http://[::1]:5000/
When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. If the
requested port is in use by another service on either loopback interface, Kestrel fails to start. If either
loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported),
Kestrel logs a warning.
Unix socket
http://unix:/run/dan-live.sock
Port 0
When the port number is 0 is specified, Kestrel dynamically binds to an available port. Binding to port 0 is
allowed for any host name or IP except for localhost .
When the app is run, the console window output indicates the dynamic port where the app can be reached:
Now listening on: http://127.0.0.1:48508
URL prefixes for SSL

If calling the UseHttps extension method, be sure to include URL prefixes with https: :

{
options.UseHttps("testCert.pfx", "testPassword");
})
.UseUrls("http://localhost:5000", "https://localhost:5001")
.Build();
NOTE
HTTPS and HTTP can't be hosted on the same port.
On Windows, self-signed certificates can be created using the New -SelfSignedCertificate PowerShell cmdlet.
For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.
Host filtering
While Kestrel supports configuration based on prefixes such as http://example.com:5000 , Kestrel largely
ignores the host name. Host localhost is a special case used for binding to loopback addresses. Any host
other than an explicit IP address binds to all public IP addresses. None of this information is used to validate
request Host headers.
As a workaround, host behind a reverse proxy with host header filtering. This is the only supported scenario
for Kestrel in ASP.NET Core 1.x.
As a workaround, use middleware to filter requests by the Host header:
using Microsoft.Extensions.Primitives;
using Microsoft.Net.Http.Headers;
using System;
// A normal middleware would provide an options type, config binding, extension methods, etc..
// This intentionally does all of the work inside of the middleware so it can be
// easily copy-pasted into docs and other projects.
public class HostFilteringMiddleware
{
private readonly IList<string> _hosts;
private readonly ILogger<HostFilteringMiddleware> _logger;
public HostFilteringMiddleware(RequestDelegate next, IConfiguration config,

ILogger<HostFilteringMiddleware> logger)
{
if (config == null)
{
throw new ArgumentNullException(nameof(config));
}
_next = next ?? throw new ArgumentNullException(nameof(next));

_logger = logger ?? throw new ArgumentNullException(nameof(logger));
// A semicolon separated list of host names without the port numbers.

// IPv6 addresses must use the bounding brackets and be in their normalized form.
_hosts = config["AllowedHosts"]?.Split(new[] { ';' }, StringSplitOptions.RemoveEmptyEntries);
if (_hosts == null || _hosts.Count == 0)
{
throw new InvalidOperationException("No configuration entry found for AllowedHosts.");
}
}
public Task Invoke(HttpContext context)

{
if (!ValidateHost(context))
{
{
context.Response.StatusCode = 400;
_logger.LogDebug("Request rejected due to incorrect Host header.");
}
return _next(context);
}
// This does not duplicate format validations that are expected to be performed by the host.
private bool ValidateHost(HttpContext context)
{
StringSegment host = context.Request.Headers[HeaderNames.Host].ToString().Trim();
if (StringSegment.IsNullOrEmpty(host))
{
// Http/1.0 does not require the Host header.
// Http/1.1 requires the header but the value may be empty.
return true;
}
// Drop the port
var colonIndex = host.LastIndexOf(':');
// IPv6 special case

if (host.StartsWith("[", StringComparison.Ordinal))
{
var endBracketIndex = host.IndexOf(']');
if (endBracketIndex < 0)
{
// Invalid format
return false;
}
if (colonIndex < endBracketIndex)
{
// No port, just the IPv6 Host
colonIndex = -1;
}
}
if (colonIndex > 0)
{
host = host.Subsegment(0, colonIndex);
}
foreach (var allowedHost in _hosts)

{
if (StringSegment.Equals(allowedHost, host, StringComparison.OrdinalIgnoreCase))
{
return true;
}
// Sub-domain wildcards: *.example.com

if (allowedHost.StartsWith("*.", StringComparison.Ordinal) && host.Length >=
allowedHost.Length)
{
// .example.com
var allowedRoot = new StringSegment(allowedHost, 1, allowedHost.Length - 1);
var hostRoot = host.Subsegment(host.Length - allowedRoot.Length, allowedRoot.Length);

if (hostRoot.Equals(allowedRoot, StringComparison.OrdinalIgnoreCase))
{
return true;
}
}
}
return false;
}
}
}
Register the preceding HostFilteringMiddleware in Startup.Configure . Note that the ordering of middleware
registration is important. Registration should occur immediately after Diagnostic Middleware registration (for
example, app.UseExceptionHandler ).

{
{
}
else
{
}
app.UseMiddleware<HostFilteringMiddleware>();
}
The middleware expects an AllowedHosts key in appsettings.json/appsettings.<EnvironmentName>.json. The

value is a semicolon-delimited list of host names without port numbers:
As a workaround, use Host Filtering Middleware. Host Filtering Middleware is provided by the
Microsoft.AspNetCore.HostFiltering package, which is included in the Microsoft.AspNetCore.App
metapackage (ASP.NET Core 2.1 or later). The middleware is added by CreateDefaultBuilder, which calls
AddHostFiltering:

{
{
}

}
Host Filtering Middleware is disabled by default. To enable the middleware, define an AllowedHosts key in
appsettings.json/appsettings.<EnvironmentName>.json. The value is a semicolon-delimited list of host names
without port numbers:
appsettings.json:
{
"AllowedHosts": "example.com;localhost"
}
NOTE
Forwarded Headers Middleware also has an ForwardedHeadersOptions.AllowedHosts option. Forwarded Headers
Middleware and Host Filtering Middleware have similar functionality for different scenarios. Setting AllowedHosts with
Forwarded Headers Middleware is appropriate when the Host header isn't preserved while forwarding requests with a
reverse proxy server or load balancer. Setting AllowedHosts with Host Filtering Middleware is appropriate when Kestrel
is used as an edge server or when the Host header is directly forwarded.
For more information on Forwarded Headers Middleware, see Configure ASP.NET Core to work with proxy servers and
load balancers.
Enforce HTTPS
Kestrel source code
RFC 7230: Message Syntax and Routing (Section 5.4: Host)
Configure ASP.NET Core to work with proxy servers and load balancers
ASP.NET Core Module
By Tom Dykstra, Rick Strahl, and Chris Ross

The ASP.NET Core Module allows ASP.NET Core apps to run behind IIS in a reverse proxy configuration. IIS
provides advanced web app security and manageability features.
Supported Windows versions:
Windows 7 or later
Windows Server 2008 R2 or later
The ASP.NET Core Module only works with Kestrel. The module is incompatible with HTTP.sys (formerly
called WebListener).
ASP.NET Core Module description

The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to redirect web requests to
backend ASP.NET Core apps. Many native modules, such as Windows Authentication, remain active. To learn
more about IIS modules active with the module, see IIS modules.
Because ASP.NET Core apps run in a process separate from the IIS worker process, the module also handles
process management. The module starts the process for the ASP.NET Core app when the first request arrives
and restarts the app if it crashes. This is essentially the same behavior as seen with ASP.NET 4.x apps that run
in-process in IIS that are managed by the Windows Process Activation Service (WAS ).
The following diagram illustrates the relationship between IIS, the ASP.NET Core Module, and ASP.NET Core
apps:
Requests arrive from the web to the kernel-mode HTTP.sys driver. The driver routes the requests to IIS on the
website's configured port, usually 80 (HTTP ) or 443 (HTTPS ). The module forwards the requests to Kestrel on
a random port for the app, which isn't port 80/443.
The module specifies the port via an environment variable at startup, and the IIS Integration Middleware
configures the server to listen on http://localhost:{port} . Additional checks are performed, and requests
that don't originate from the module are rejected. The module doesn't support HTTPS forwarding, so requests
are forwarded over HTTP even if received by IIS over HTTPS.
After Kestrel picks up a request from the module, the request is pushed into the ASP.NET Core middleware
pipeline. The middleware pipeline handles the request and passes it on as an HttpContext instance to the
app's logic. The app's response is passed back to IIS, which pushes it back out to the HTTP client that initiated
the request.
The ASP.NET Core Module has a few other functions. The module can:
Set environment variables for the worker process.
Log stdout output to file storage for troubleshooting startup issues.
Forward Windows authentication tokens.
How to install and use the ASP.NET Core Module

For detailed instructions on how to install and use the ASP.NET Core Module, see Host on Windows with IIS.
For information on configuring the module, see the ASP.NET Core Module configuration reference.
ASP.NET Core Module GitHub repository (source code)
HTTP.sys web server implementation in ASP.NET
Core
By Tom Dykstra, Chris Ross, and Luke Latham
NOTE
This topic applies to ASP.NET Core 2.0 or later. In earlier versions of ASP.NET Core, HTTP.sys is named WebListener.
HTTP.sys is a web server for ASP.NET Core that only runs on Windows. HTTP.sys is an alternative to Kestrel
and offers some features that Kestrel doesn't provide.
IMPORTANT
HTTP.sys is incompatible with the ASP.NET Core Module and can't be used with IIS or IIS Express.
HTTP.sys supports the following features:

Windows Authentication
Port sharing
HTTPS with SNI
HTTP/2 over TLS (Windows 10 or later)
Direct file transmission
Response caching
WebSockets (Windows 8 or later)
Supported Windows versions:
Windows 7 or later
When to use HTTP.sys

HTTP.sys is useful for deployments where:
There's a need to expose the server directly to the Internet without using IIS.
An internal deployment requires a feature not available in Kestrel, such as Windows Authentication.
HTTP.sys is mature technology that protects against many types of attacks and provides the robustness,
security, and scalability of a full-featured web server. IIS itself runs as an HTTP listener on top of HTTP.sys.
HTTP/2 support
HTTP/2 is enabled for ASP.NET Core apps if the following base requirements are met:
Application-Layer Protocol Negotiation (ALPN ) connection
If an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/2 .
If an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/1.1 .
HTTP/2 is enabled by default. If an HTTP/2 connection isn't established, the connection falls back to HTTP/1.1.
In a future release of Windows, HTTP/2 configuration flags will be available, including the ability to disable
HTTP/2 with HTTP.sys.
Kernel mode authentication with Kerberos

HTTP.sys delegates to kernel mode authentication with the Kerberos authentication protocol. User mode
authentication isn't supported with Kerberos and HTTP.sys. The machine account must be used to decrypt the
Kerberos token/ticket that's obtained from Active Directory and forwarded by the client to the server to
authenticate the user. Register the Service Principal Name (SPN ) for the host, not the user of the app.
How to use HTTP.sys

Configure the ASP.NET Core app to use HTTP.sys
1. A package reference in the project file isn't required when using the Microsoft.AspNetCore.App
metapackage (nuget.org) (ASP.NET Core 2.1 or later). When not using the Microsoft.AspNetCore.App
metapackage, add a package reference to Microsoft.AspNetCore.Server.HttpSys.
2. Call the UseHttpSys extension method when building the web host, specifying any required HTTP.sys
options:

.UseHttpSys(options =>
{
// The following options are set to default values.
options.Authentication.Schemes = AuthenticationSchemes.None;
options.Authentication.AllowAnonymous = true;
options.MaxConnections = null;
options.MaxRequestBodySize = 30000000;
options.UrlPrefixes.Add("http://localhost:5000");
});
Additional HTTP.sys configuration is handled through registry settings.

HTTP.sys options
PROPERTY DESCRIPTION DEFAULT

AllowSynchronousIO Control whether synchronous true

input/output is allowed for the
HttpContext.Request.Body and
HttpContext.Response.Body .
Authentication.AllowAnonymous Allow anonymous requests. true
Authentication.Schemes Specify the allowed authentication None

schemes. May be modified at any
time prior to disposing the listener.
Values are provided by the
AuthenticationSchemes enum:
Basic , Kerberos , Negotiate ,
None , and NTLM .
EnableResponseCaching Attempt kernel-mode caching for true

responses with eligible headers. The
response may not include
Set-Cookie , Vary , or Pragma
headers. It must include a
Cache-Control header that's
public and either a
shared-max-age or max-age
value, or an Expires header.
MaxAccepts The maximum number of 5 × Environment.

concurrent accepts. ProcessorCount
MaxConnections The maximum number of null

concurrent connections to accept. (unlimited)
Use -1 for infinite. Use null to
use the registry's machine-wide
setting.
MaxRequestBodySize See the MaxRequestBodySize 30000000 bytes

section. (~28.6 MB)
RequestQueueLimit The maximum number of requests 1000

that can be queued.
ThrowWriteExceptions Indicate if response body writes that false

fail due to client disconnects should (complete normally)
throw exceptions or complete
normally.
Timeouts Expose the HTTP.sys

TimeoutManager configuration,
which may also be configured in the
registry. Follow the API links to learn
more about each setting, including
default values:
TimeoutManager.DrainEntity
Body – Time allowed for the
HTTP Server API to drain the
entity body on a Keep-Alive
connection.
TimeoutManager.EntityBody
– Time allowed for the
request entity body to arrive.
TimeoutManager.HeaderWai
t – Time allowed for the
HTTP Server API to parse the
request header.
TimeoutManager.IdleConnec
tion – Time allowed for an
idle connection.
TimeoutManager.MinSendBy
tesPerSecond – The
minimum send rate for the
response.
TimeoutManager.RequestQu
eue – Time allowed for the
request to remain in the
request queue before the
app picks it up.
UrlPrefixes Specify the UrlPrefixCollection to

register with HTTP.sys. The most
useful is UrlPrefixCollection.Add,
which is used to add a prefix to the
collection. These may be modified at
any time prior to disposing the
listener.
MaxRequestBodySize
The maximum allowed size of any request body in bytes. When set to null , the maximum request body
size is unlimited. This limit has no effect on upgraded connections, which are always unlimited.
The recommended method to override the limit in an ASP.NET Core MVC app for a single
IActionResult is to use the RequestSizeLimitAttribute attribute on an action method:
[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()
An exception is thrown if the app attempts to configure the limit on a request after the app has started
reading the request. An IsReadOnly property can be used to indicate if the MaxRequestBodySize property
is in a read-only state, meaning it's too late to configure the limit.
If the app should override MaxRequestBodySize per-request, use the IHttpMaxRequestBodySizeFeature:
public void Configure(IApplicationBuilder app, IHostingEnvironment env,
ILogger<Startup> logger)
{
{
var serverAddressesFeature = app.ServerFeatures.Get<IServerAddressesFeature>();

var addresses = string.Join(", ", serverAddressesFeature?.Addresses);
logger.LogInformation($"Addresses: {addresses}");
});
{
}
else
{
app.UseHsts();
}
// Enable HTTPS Redirection Middleware when hosting the app securely.

//app.UseHttpsRedirection();
app.UseMvc();
}
3. If using Visual Studio, make sure the app isn't configured to run IIS or IIS Express.
In Visual Studio, the default launch profile is for IIS Express. To run the project as a console app, manually
change the selected profile, as shown in the following screen shot:
Configure Windows Server

1. If the app is a framework-dependent deployment, install .NET Core, .NET Framework, or both (if the app
is a .NET Core app targeting the .NET Framework).
.NET Core – If the app requires .NET Core, obtain and run the .NET Core installer from .NET All
Downloads.
.NET Framework – If the app requires .NET Framework, see .NET Framework: Installation guide to
find installation instructions. Install the required .NET Framework. The installer for the latest .NET
Framework can be found at .NET All Downloads.
2. Configure URLs and ports for the app.
By default, ASP.NET Core binds to http://localhost:5000 . To configure URL prefixes and ports, options
include using:
UseUrls
urls command-line argument
ASPNETCORE_URLS environment variable
UrlPrefixes
The following code example shows how to use UrlPrefixes:

{
// The following options are set to default values.
options.Authentication.Schemes = AuthenticationSchemes.None;
options.Authentication.AllowAnonymous = true;
options.MaxConnections = null;
options.MaxRequestBodySize = 30000000;
options.UrlPrefixes.Add("http://localhost:5000");
});
An advantage of UrlPrefixes is that an error message is generated immediately for improperly

formatted prefixes.
The settings in UrlPrefixes override UseUrls / urls / ASPNETCORE_URLS settings. Therefore, an advantage
of UseUrls , urls , and the ASPNETCORE_URLS environment variable is that it's easier to switch between
Kestrel and HTTP.sys. For more information on UseUrls , urls , and ASPNETCORE_URLS , see the Host in
ASP.NET Core topic.
HTTP.sys uses the HTTP Server API UrlPrefix string formats.
WARNING
Top-level wildcard bindings ( http://*:80/ and http://+:80 ) should not be used. Top-level wildcard bindings
can open up your app to security vulnerabilities. This applies to both strong and weak wildcards. Use explicit host
names rather than wildcards. Subdomain wildcard binding (for example, *.mysub.com ) doesn't have this security
risk if you control the entire parent domain (as opposed to *.com , which is vulnerable). See rfc7230 section-5.4
3. Preregister URL prefixes to bind to HTTP.sys and set up x.509 certificates.

If URL prefixes aren't preregistered in Windows, run the app with administrator privileges. The only
exception is when binding to localhost using HTTP (not HTTPS ) with a port number greater than 1024.
In that case, administrator privileges aren't required.
a. The built-in tool for configuring HTTP.sys is netsh.exe. netsh.exe is used to reserve URL prefixes
and assign X.509 certificates. The tool requires administrator privileges.
The following example shows the commands to reserve URL prefixes for ports 80 and 443:
netsh http add urlacl url=http://+:80/ user=Users

netsh http add urlacl url=https://+:443/ user=Users
The following example shows how to assign an X.509 certificate:
netsh http add sslcert ipport=0.0.0.0:443 certhash=MyCertHash_Here appid="{00000000-0000-0000-

0000-000000000000}"
Reference documentation for netsh.exe:
Netsh Commands for Hypertext Transfer Protocol (HTTP )
UrlPrefix Strings
b. Create self-signed X.509 certificates, if required.
On Windows, self-signed certificates can be created using the New -SelfSignedCertificate
PowerShell cmdlet. For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.
4. Open firewall ports to allow traffic to reach HTTP.sys. Use netsh.exe or PowerShell cmdlets.
Proxy server and load balancer scenarios

For apps hosted by HTTP.sys that interact with requests from the Internet or a corporate network, additional
configuration might be required when hosting behind proxy servers and load balancers. For more information,
see Configure ASP.NET Core to work with proxy servers and load balancers.
HTTP Server API
aspnet/HttpSysServer GitHub repository (source code)
Session and app state in ASP.NET Core
By Rick Anderson, Steve Smith, Diana LaRose, and Luke Latham

HTTP is a stateless protocol. Without taking additional steps, HTTP requests are independent messages that don't
retain user values or app state. This article describes several approaches to preserve user data and app state
between requests.
State management
State can be stored using several approaches. Each approach is described later in this topic.
STORAGE APPROACH STORAGE MECHANISM
Cookies HTTP cookies (may include data stored using server-side app
code)
Session state HTTP cookies and server-side app code
TempData HTTP cookies or session state
Query strings HTTP query strings
Hidden fields HTTP form fields
HttpContext.Items Server-side app code
Cache Server-side app code
Dependency Injection Server-side app code
Cookies
Cookies store data across requests. Because cookies are sent with every request, their size should be kept to a
minimum. Ideally, only an identifier should be stored in a cookie with the data stored by the app. Most browsers
restrict cookie size to 4096 bytes. Only a limited number of cookies are available for each domain.
Because cookies are subject to tampering, they must be validated by the app. Cookies can be deleted by users and
expire on clients. However, cookies are generally the most durable form of data persistence on the client.
Cookies are often used for personalization, where content is customized for a known user. The user is only
identified and not authenticated in most cases. The cookie can store the user's name, account name, or unique
user ID (such as a GUID ). You can then use the cookie to access the user's personalized settings, such as their
preferred website background color.
Be mindful of the European Union General Data Protection Regulations (GDPR ) when issuing cookies and
dealing with privacy concerns. For more information, see General Data Protection Regulation (GDPR ) support in
ASP.NET Core.
Session state
Session state is an ASP.NET Core scenario for storage of user data while the user browses a web app. Session
state uses a store maintained by the app to persist data across requests from a client. The session data is backed
by a cache and considered ephemeral data—the site should continue to function without the session data.
NOTE
Session isn't supported in SignalR apps because a SignalR Hub may execute independent of an HTTP context. For example,
this can occur when a long polling request is held open by a hub beyond the lifetime of the request's HTTP context.
ASP.NET Core maintains session state by providing a cookie to the client that contains a session ID, which is sent
to the app with each request. The app uses the session ID to fetch the session data.
Session state exhibits the following behaviors:
Because the session cookie is specific to the browser, sessions aren't shared across browsers.
Session cookies are deleted when the browser session ends.
If a cookie is received for an expired session, a new session is created that uses the same session cookie.
Empty sessions aren't retained—the session must have at least one value set into it to persist the session
across requests. When a session isn't retained, a new session ID is generated for each new request.
The app retains a session for a limited time after the last request. The app either sets the session timeout or
uses the default value of 20 minutes. Session state is ideal for storing user data that's specific to a particular
session but where the data doesn't require permanent storage across sessions.
Session data is deleted either when the ISession.Clear implementation is called or when the session expires.
There's no default mechanism to inform app code that a client browser has been closed or when the session
cookie is deleted or expired on the client.
WARNING
Don't store sensitive data in session state. The user might not close the browser and clear the session cookie. Some
browsers maintain valid session cookies across browser windows. A session might not be restricted to a single user—the
next user might continue to browse the app with the same session cookie.
The in-memory cache provider stores session data in the memory of the server where the app resides. In a server
farm scenario:
Use sticky sessions to tie each session to a specific app instance on an individual server. Azure App Service uses
Application Request Routing (ARR ) to enforce sticky sessions by default. However, sticky sessions can affect
scalability and complicate web app updates. A better approach is to use a Redis or SQL Server distributed
cache, which doesn't require sticky sessions. For more information, see Work with a distributed cache.
The session cookie is encrypted via IDataProtector. Data Protection must be properly configured to read
session cookies on each machine. For more information, see Data Protection in ASP.NET Core and Key
storage providers.
Configure session state
The Microsoft.AspNetCore.Session package, which is included in the Microsoft.AspNetCore.App metapackage,
provides middleware for managing session state. To enable the session middleware, Startup must contain:
The Microsoft.AspNetCore.Session package provides middleware for managing session state. To enable the
session middleware, Startup must contain:
Any of the IDistributedCache memory caches. The IDistributedCache implementation is used as a backing
store for session. For more information, see Work with a distributed cache.
A call to AddSession in ConfigureServices .
A call to UseSession in Configure .
The following code shows how to set up the in-memory session provider with a default in-memory
implementation of IDistributedCache :

{
{
{
});
services.AddDistributedMemoryCache();
services.AddSession(options =>
{
// Set a short timeout for easy testing.
options.IdleTimeout = TimeSpan.FromSeconds(10);
options.Cookie.HttpOnly = true;
});
services.AddMvc()
}

{
{
}
else
{
app.UseHsts();
}
app.UseSession();
app.UseHttpContextItemsMiddleware();
app.UseMvc();
}
}
{
{
{
// Set a short timeout for easy testing.
options.CookieHttpOnly = true;
});
services.AddMvc();
}

{
app.UseSession();
app.UseHttpContextItemsMiddleware();
{
routes.MapRoute(
name: "default",
});
}
}
The order of middleware is important. In the preceding example, an InvalidOperationException exception occurs
when UseSession is invoked after UseMvc . For more information, see Middleware Ordering.
HttpContext.Session is available after session state is configured.
HttpContext.Session can't be accessed before UseSession has been called.
A new session with a new session cookie can't be created after the app has begun writing to the response stream.
The exception is recorded in the web server log and not displayed in the browser.
Load session state asynchronously
The default session provider in ASP.NET Core loads session records from the underlying IDistributedCache
backing store asynchronously only if the ISession.LoadAsync method is explicitly called before the TryGetValue,
Set, or Remove methods. If LoadAsync isn't called first, the underlying session record is loaded synchronously,
which can incur a performance penalty at scale.
To have apps enforce this pattern, wrap the DistributedSessionStore and DistributedSession implementations
with versions that throw an exception if the LoadAsync method isn't called before TryGetValue , Set , or Remove .
Register the wrapped versions in the services container.
Session options
To override session defaults, use SessionOptions.
OPTION DESCRIPTION
Cookie Determines the settings used to create the cookie. Name

defaults to SessionDefaults.CookieName (
.AspNetCore.Session ). Path defaults to
SessionDefaults.CookiePath ( / ). SameSite defaults to
SameSiteMode.Lax ( 1 ). HttpOnly defaults to true .
IsEssential defaults to false .
OPTION DESCRIPTION
IdleTimeout The IdleTimeout indicates how long the session can be idle
before its contents are abandoned. Each session access resets
the timeout. Note this only applies to the content of the
session, not the cookie. The default is 20 minutes.
IOTimeout The maximim amount of time allowed to load a session from

the store or to commit it back to the store. Note this may
only apply to asynchronous operations. This timeout can be
disabled using InfiniteTimeSpan. The default is 1 minute.
Session uses a cookie to track and identify requests from a single browser. By default, this cookie is named
.AspNetCore.Session , and it uses a path of / . Because the cookie default doesn't specify a domain, it isn't made
available to the client-side script on the page (because HttpOnly defaults to true ).
OPTION DESCRIPTION
CookieDomain Determines the domain used to create the cookie.

CookieDomain isn't set by default.
CookieHttpOnly Determines if the browser should allow the cookie to be

accessed by client-side JavaScript. The default is true , which
means the cookie is only passed to HTTP requests and isn't
made available to script on the page.
CookieName Determines the cookie name used to persist the session ID.
The default is SessionDefaults.CookieName (
.AspNetCore.Session ).
CookiePath Determines the path used to create the cookie. Defaults to

SessionDefaults.CookiePath ( / ).
CookieSecure Determines if the cookie should only be transmitted on

HTTPS requests. The default is CookieSecurePolicy.None ( 2 ).
IdleTimeout The IdleTimeout indicates how long the session can be idle
before its contents are abandoned. Each session access resets
the timeout. Note this only applies to the content of the
session, not the cookie. The default is 20 minutes.
Session uses a cookie to track and identify requests from a single browser. By default, this cookie is named
.AspNet.Session , and it uses a path of / .
To override cookie session defaults, use SessionOptions :

{
{
});
services.AddMvc()
{
options.Cookie.Name = ".AdventureWorks.Session";
});
}

{
{
options.CookieName = ".AdventureWorks.Session";
});
services.AddMvc();
}
The app uses the IdleTimeout property to determine how long a session can be idle before its contents in the
server's cache are abandoned. This property is independent of the cookie expiration. Each request that passes
through the Session Middleware resets the timeout.
Session state is non-locking. If two requests simultaneously attempt to modify the contents of a session, the last
request overrides the first. Session is implemented as a coherent session, which means that all the contents are
stored together. When two requests seek to modify different session values, the last request may override session
changes made by the first.
Set and get Session values
Session state is accessed from a Razor Pages PageModel class or MVC Controller class with HttpContext.Session.
This property is an ISession implementation.
The ISession implementation provides several extension methods to set and retreive integer and string values.
The extension methods are in the Microsoft.AspNetCore.Http namespace (add a
using Microsoft.AspNetCore.Http; statement to gain access to the extension methods) when the
Microsoft.AspNetCore.Http.Extensions package is referenced by the project. Both packages are included in the
The ISession implementation provides several extension methods to set and retreive integer and string values.
The extension methods are in the Microsoft.AspNetCore.Http namespace (add a
using Microsoft.AspNetCore.Http; statement to gain access to the extension methods) when the
Microsoft.AspNetCore.Http.Extensions package is referenced by the project.
ISession extension methods:
Get(ISession, String)
GetInt32(ISession, String)
GetString(ISession, String)
SetInt32(ISession, String, Int32)
SetString(ISession, String, String)
The following example retrieves the session value for the IndexModel.SessionKeyName key ( _Name in the sample
app) in a Razor Pages page:
@page
@using Microsoft.AspNetCore.Http
@model IndexModel
...
Name: @HttpContext.Session.GetString(IndexModel.SessionKeyName)
The following example shows how to set and get an integer and a string:

{
public const string SessionKeyName = "_Name";
public const string SessionKeyAge = "_Age";
const string SessionKeyTime = "_Time";
public string SessionInfo_Name { get; private set; }

public string SessionInfo_Age { get; private set; }
public string SessionInfo_CurrentTime { get; private set; }
public string SessionInfo_SessionTime { get; private set; }
public string SessionInfo_MiddlewareValue { get; private set; }
public void OnGet()

{
// Requires: using Microsoft.AspNetCore.Http;
if (string.IsNullOrEmpty(HttpContext.Session.GetString(SessionKeyName)))
{
HttpContext.Session.SetString(SessionKeyName, "The Doctor");
HttpContext.Session.SetInt32(SessionKeyAge, 773);
}
var name = HttpContext.Session.GetString(SessionKeyName);

var age = HttpContext.Session.GetInt32(SessionKeyAge);
{
const string SessionKeyName = "_Name";
const string SessionKeyYearsMember = "_YearsMember";
const string SessionKeyDate = "_Date";

{
// Requires using Microsoft.AspNetCore.Http;
HttpContext.Session.SetString(SessionKeyName, "Rick");
HttpContext.Session.SetInt32(SessionKeyYearsMember, 3);
return RedirectToAction("SessionNameYears");
}
public IActionResult SessionNameYears()

{
var name = HttpContext.Session.GetString(SessionKeyName);
var yearsMember = HttpContext.Session.GetInt32(SessionKeyYearsMember);
return Content($"Name: \"{name}\", Membership years: \"{yearsMember}\"");

}
All session data must be serialized to enable a distributed cache scenario, even when using the in-memory cache.
Minimal string and number serializers are provided (see the methods and extension methods of ISession).
Complex types must be serialized by the user using another mechanism, such as JSON.
Add the following extension methods to set and get serializable objects:
public static class SessionExtensions

{
public static void Set<T>(this ISession session, string key, T value)
{
session.SetString(key, JsonConvert.SerializeObject(value));
}
public static T Get<T>(this ISession session, string key)

{
var value = session.GetString(key);
return value == null ? default(T) :

JsonConvert.DeserializeObject<T>(value);
}
}
public static class SessionExtensions

{
public static void Set<T>(this ISession session, string key, T value)
{
session.SetString(key, JsonConvert.SerializeObject(value));
}
public static T Get<T>(this ISession session,string key)

{
var value = session.GetString(key);
return value == null ? default(T) :
JsonConvert.DeserializeObject<T>(value);
}
}
The following example shows how to set and get a serializable object with the extension methods:
// Requires you add the Set and Get extension method mentioned in the topic.
if (HttpContext.Session.Get<DateTime>(SessionKeyTime) == default(DateTime))
{
HttpContext.Session.Set<DateTime>(SessionKeyTime, currentTime);
}
public IActionResult SetDate()

{
// Requires you add the Set extension method mentioned in the topic.
HttpContext.Session.Set<DateTime>(SessionKeyDate, DateTime.Now);
return RedirectToAction("GetDate");
}
public IActionResult GetDate()

{
// Requires you add the Get extension method mentioned in the topic.
var date = HttpContext.Session.Get<DateTime>(SessionKeyDate);
var sessionTime = date.TimeOfDay.ToString();
var currentTime = DateTime.Now.TimeOfDay.ToString();
return Content($"Current time: {currentTime} - "

+ $"session time: {sessionTime}");
}
TempData
ASP.NET Core exposes the TempData property of a Razor Pages page model or TempData of an MVC controller.
This property stores data until it's read. The Keep and Peek methods can be used to examine the data without
deletion. TempData is particularly useful for redirection when data is required for more than a single request.
TempData is implemented by TempData providers using either cookies or session state.
TempData providers
In ASP.NET Core 2.0 or later, the cookie-based TempData provider is used by default to store TempData in
cookies.
The cookie data is encrypted using IDataProtector, encoded with Base64UrlTextEncoder, then chunked. Because
the cookie is chunked, the single cookie size limit found in ASP.NET Core 1.x doesn't apply. The cookie data isn't
compressed because compressing encrypted data can lead to security problems such as the CRIME and BREACH
attacks. For more information on the cookie-based TempData provider, see CookieTempDataProvider.
In ASP.NET Core 1.0 and 1.1, the session state TempData provider is the default provider.
Choose a TempData provider
Choosing a TempData provider involves several considerations, such as:
1. Does the app already use session state? If so, using the session state TempData provider has no additional cost
to the app (aside from the size of the data).
2. Does the app use TempData only sparingly for relatively small amounts of data (up to 500 bytes)? If so, the
cookie TempData provider adds a small cost to each request that carries TempData. If not, the session state
TempData provider can be beneficial to avoid round-tripping a large amount of data in each request until the
TempData is consumed.
3. Does the app run in a server farm on multiple servers? If so, there's no additional configuration required to use
the cookie TempData provider outside of Data Protection (see Data Protection and Key storage providers).
NOTE
Most web clients (such as web browsers) enforce limits on the maximum size of each cookie, the total number of cookies, or
both. When using the cookie TempData provider, verify the app won't exceed these limits. Consider the total size of the
data. Account for increases in cookie size due to encryption and chunking.
Configure the TempData provider

The cookie-based TempData provider is enabled by default.
To enable the session-based TempData provider, use the AddSessionStateTempDataProvider extension method:

{
{
});
services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_1)
.AddSessionStateTempDataProvider();
services.AddSession();
}

{
{
}
else
{
app.UseHsts();
}
app.UseSession();
app.UseMvc();
}
The following Startup class code configures the session-based TempData provider:
{
services.AddMvc();
services.AddSession();
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)

{
app.UseSession();
{
routes.MapRoute(
name: "default",
});
}
The order of middleware is important. In the preceding example, an InvalidOperationException exception occurs
when UseSession is invoked after UseMvc . For more information, see Middleware Ordering.
IMPORTANT
If targeting .NET Framework and using the session-based TempData provider, add the Microsoft.AspNetCore.Session
package to the project.
Query strings
A limited amount of data can be passed from one request to another by adding it to the new request's query
string. This is useful for capturing state in a persistent manner that allows links with embedded state to be shared
through email or social networks. Because URL query strings are public, never use query strings for sensitive
data.
In addition to unintended sharing, including data in query strings can create opportunities for Cross-Site Request
Forgery (CSRF ) attacks, which can trick users into visiting malicious sites while authenticated. Attackers can then
steal user data from the app or take malicious actions on behalf of the user. Any preserved app or session state
must protect against CSRF attacks. For more information, see Prevent Cross-Site Request Forgery (XSRF/CSRF )
attacks.
Hidden fields
Data can be saved in hidden form fields and posted back on the next request. This is common in multi-page
forms. Because the client can potentially tamper with the data, the app must always revalidate the data stored in
hidden fields.
HttpContext.Items
The HttpContext.Items collection is used to store data while processing a single request. The collection's contents
are discarded after a request is processed. The Items collection is often used to allow components or middleware
to communicate when they operate at different points in time during a request and have no direct way to pass
parameters.
In the following example, middleware adds isVerified to the Items collection.
{
// perform some verification
context.Items["isVerified"] = true;
});
Later in the pipeline, another middleware can access the value of isVerified :

{
await context.Response.WriteAsync($"Verified: {context.Items["isVerified"]}");
});
For middleware that's only used by a single app, string keys are acceptable. Middleware shared between app
instances should use unique object keys to avoid key collisions. The following example shows how to use a unique
object key defined in a middleware class:
public class HttpContextItemsMiddleware

{
public static readonly object HttpContextItemsMiddlewareKey = new Object();
public HttpContextItemsMiddleware(RequestDelegate next)

{
_next = next;
}

{
httpContext.Items[HttpContextItemsMiddlewareKey] = "K-9";
}
}
public static class HttpContextItemsMiddlewareExtensions

{
public static IApplicationBuilder
UseHttpContextItemsMiddleware(this IApplicationBuilder builder)
{
return builder.UseMiddleware<HttpContextItemsMiddleware>();
}
}
// You may need to install the Microsoft.AspNetCore.Http.Abstractions package
public class HttpContextItemsMiddleware
{
public static readonly object HttpContextItemsMiddlewareKey = new Object();
public HttpContextItemsMiddleware(RequestDelegate next)

{
_next = next;
}

{
httpContext.Items[HttpContextItemsMiddlewareKey] = "K-9";
}
}
public static class HttpContextItemsMiddlewareExtensions

{
public static IApplicationBuilder
UseHttpContextItemsMiddleware(this IApplicationBuilder builder)
{
return builder.UseMiddleware<HttpContextItemsMiddleware>();
}
}
Other code can access the value stored in HttpContext.Items using the key exposed by the middleware class:
HttpContext.Items
.TryGetValue(HttpContextItemsMiddleware.HttpContextItemsMiddlewareKey,
out var middlewareSetValue);
SessionInfo_MiddlewareValue =
middlewareSetValue?.ToString() ?? "Middleware value not set!";
public IActionResult GetMiddlewareValue()

{
var middlewareSetValue =
HttpContext.Items[HttpContextItemsMiddleware.HttpContextItemsMiddlewareKey];
return Content($"Value: {middlewareSetValue}");

}
This approach also has the advantage of eliminating the use of key strings in the code.
Cache
Caching is an efficient way to store and retrieve data. The app can control the lifetime of cached items.
Cached data isn't associated with a specific request, user, or session. Be careful not to cache user-specific data
that may be retrieved by other users' requests.
For more information, see the Cache responses topic.
Dependency Injection
Use Dependency Injection to make data available to all users:
1. Define a service containing the data. For example, a class named MyAppData is defined:
public class MyAppData
{
// Declare properties and methods
}
2. Add the service class to Startup.ConfigureServices :

{
services.AddSingleton<MyAppData>();
}
3. Consume the data service class:

{
public IndexModel(MyAppData myService)
{
// Do something with the service
// Examples: Read data, store in a field or property
}
}

{
public HomeController(MyAppData myService)
{
// Do something with the service
// Examples: Read data, store in a field or property
}
}
Common errors
"Unable to resolve service for type 'Microsoft.Extensions.Caching.Distributed.IDistributedCache' while
attempting to activate 'Microsoft.AspNetCore.Session.DistributedSessionStore'."
This is usually caused by failing to configure at least one IDistributedCache implementation. For more
information, see Work with a distributed cache and Cache in-memory.
In the event that the session middleware fails to persist a session (for example, if the backing store isn't
available), the middleware logs the exception and the request continues normally. This leads to
unpredictable behavior.
For example, a user stores a shopping cart in session. The user adds an item to the cart but the commit
fails. The app doesn't know about the failure so it reports to the user that the item was added to their cart,
which isn't true.
The recommended approach to check for errors is to call await feature.Session.CommitAsync(); from app
code when the app is done writing to the session. CommitAsync throws an exception if the backing store is
unavailable. If CommitAsync fails, the app can process the exception. LoadAsync throws under the same
conditions where the data store is unavailable.
Host ASP.NET Core in a web farm
File Providers in ASP.NET Core
By Steve Smith and Luke Latham

ASP.NET Core abstracts file system access through the use of File Providers. File Providers are used throughout
the ASP.NET Core framework:
IHostingEnvironment exposes the app's content root and web root as IFileProvider types.
Static Files Middleware uses File Providers to locate static files.
Razor uses File Providers to locate pages and views.
.NET Core tooling uses File Providers and glob patterns to specify which files should be published.
File Provider interfaces

The primary interface is IFileProvider. IFileProvider exposes methods to:
Obtain file information (IFileInfo).
Obtain directory information ( IDirectoryContents).
Set up change notifications (using an IChangeToken).
IFileInfo provides methods and properties for working with files:
Exists
IsDirectory
Name
Length (in bytes)
LastModified date
You can read from the file using the IFileInfo.CreateReadStream method.
The sample app demonstrates how to configure a File Provider in Startup.ConfigureServices for use throughout
the app via dependency injection.
File Provider implementations

Three implementations of IFileProvider are available.
IMPLEMENTATION DESCRIPTION
PhysicalFileProvider The physical provider is used to access the system's physical

files.
ManifestEmbeddedFileProvider The manifest embedded provider is used to access files

embedded in assemblies.
CompositeFileProvider The composite provider is used to provide combined access to

files and directories from one or more other providers.
IMPLEMENTATION DESCRIPTION
PhysicalFileProvider The physical provider is used to access the system's physical

files.
EmbeddedFileProvider The embedded provider is used to access files embedded in

assemblies.
CompositeFileProvider The composite provider is used to provide combined access to

files and directories from one or more other providers.
PhysicalFileProvider
The PhysicalFileProvider provides access to the physical file system. PhysicalFileProvider uses the System.IO.File
type (for the physical provider) and scopes all paths to a directory and its children. This scoping prevents access to
the file system outside of the specified directory and its children. When instantiating this provider, a directory path
is required and serves as the base path for all requests made using the provider. You can instantiate a
PhysicalFileProvider provider directly, or you can request an IFileProvider in a constructor through dependency
injection.
Static types
The following code shows how to create a PhysicalFileProvider and use it to obtain directory contents and file
information:
var provider = new PhysicalFileProvider(applicationRoot);

var contents = provider.GetDirectoryContents(string.Empty);
var fileInfo = provider.GetFileInfo("wwwroot/js/site.js");
Types in the preceding example:

provider is an IFileProvider .
contents is an IDirectoryContents .
fileInfo is an IFileInfo .
The File Provider can be used to iterate through the directory specified by applicationRoot or call GetFileInfo to
obtain a file's information. The File Provider has no access outside of the applicationRoot directory.
The sample app creates the provider in the app's Startup.ConfigureServices class using
IHostingEnvironment.ContentRootFileProvider:
var physicalProvider = _env.ContentRootFileProvider;
Obtain File Provider types with dependency injection

Inject the provider into any class constructor and assign it to a local field. Use the field throughout the class's
methods to access files.
In the sample app, the IndexModel class receives an IFileProvider instance to obtain directory contents for the
app's base path.
Pages/Index.cshtml.cs:
{
private readonly IFileProvider _fileProvider;
public IndexModel(IFileProvider fileProvider)

{
_fileProvider = fileProvider;
}
public IDirectoryContents DirectoryContents { get; private set; }
public void OnGet()

{
DirectoryContents = _fileProvider.GetDirectoryContents(string.Empty);
}
}
The IDirectoryContents are iterated in the page.

Pages/Index.cshtml:
<ul>
@foreach (var item in Model.DirectoryContents)
{
if (item.IsDirectory)
{
<li><strong>@item.Name</strong></li>
}
else
{
<li>@item.Name - @item.Length bytes</li>
}
}
</ul>
In the sample app, the HomeController class receives an IFileProvider instance to obtain directory contents for
the app's base path.
Controllers/HomeController.cs:

{
public HomeController(IFileProvider fileProvider)

{
_fileProvider = fileProvider;
}

{
var contents = _fileProvider.GetDirectoryContents(string.Empty);
return View(contents);
}
}
The IDirectoryContents are iterated in the view.

Views/Home/Index.cshtml:
<ul>
@foreach (IFileInfo item in Model)
{
if (item.IsDirectory)
{
<li><strong>@item.Name</strong></li>
}
else
{
<li>@item.Name - @item.Length bytes</li>
}
}
</ul>
ManifestEmbeddedFileProvider
The ManifestEmbeddedFileProvider is used to access files embedded within assemblies. The
ManifestEmbeddedFileProvider uses a manifest compiled into the assembly to reconstruct the original paths of the
embedded files.
NOTE
The ManifestEmbeddedFileProvider is available in ASP.NET Core 2.1 or later. To access files embedded in assemblies in
ASP.NET Core 2.0 or earlier, see the ASP.NET Core 1.x version of this topic.
To generate a manifest of the embedded files, set the <GenerateEmbeddedFilesManifest> property to true . Specify
the files to embed with <EmbeddedResource>:
<PropertyGroup>
<GenerateEmbeddedFilesManifest>true</GenerateEmbeddedFilesManifest>
</PropertyGroup>
<ItemGroup>
</ItemGroup>
<ItemGroup>
<EmbeddedResource Include="Resource.txt" />
</ItemGroup>
</Project>
Use glob patterns to specify one or more files to embed into the assembly.
The sample app creates an ManifestEmbeddedFileProvider and passes the currently executing assembly to its
constructor.
Startup.cs:
var manifestEmbeddedProvider =
new ManifestEmbeddedFileProvider(Assembly.GetEntryAssembly());
Additional overloads allow you to:

Specify a relative file path.
Scope files to a last modified date.
Name the embedded resource containing the embedded file manifest.
OVERLOAD DESCRIPTION
ManifestEmbeddedFileProvider(Assembly, String) Accepts an optional root relative path parameter. Specify the
root to scope calls to GetDirectoryContents to those
resources under the provided path.
ManifestEmbeddedFileProvider(Assembly, String, Accepts an optional root relative path parameter and a

DateTimeOffset) lastModified date (DateTimeOffset) parameter. The
lastModified date scopes the last modification date for the
IFileInfo instances returned by the IFileProvider.
ManifestEmbeddedFileProvider(Assembly, String, String, Accepts an optional root relative path, lastModified date,
DateTimeOffset) and manifestName parameters. The manifestName
represents the name of the embedded resource containing
the manifest.
EmbeddedFileProvider
The EmbeddedFileProvider is used to access files embedded within assemblies. Specify the files to embed with the
<EmbeddedResource> property in the project file:
<ItemGroup>
<EmbeddedResource Include="Resource.txt" />
</ItemGroup>
Use glob patterns to specify one or more files to embed into the assembly.
The sample app creates an EmbeddedFileProvider and passes the currently executing assembly to its constructor.
Startup.cs:
var embeddedProvider = new EmbeddedFileProvider(Assembly.GetEntryAssembly());
Embedded resources don't expose directories. Rather, the path to the resource (via its namespace) is embedded in
its filename using . separators. In the sample app, the baseNamespace is FileProviderSample. .
The EmbeddedFileProvider(Assembly, String) constructor accepts an optional baseNamespace parameter. Specify
the base namespace to scope calls to GetDirectoryContents to those resources under the provided namespace.
CompositeFileProvider
The CompositeFileProvider combines IFileProvider instances, exposing a single interface for working with files
from multiple providers. When creating the CompositeFileProvider , pass one or more IFileProvider instances to
its constructor.
In the sample app, a PhysicalFileProvider and a ManifestEmbeddedFileProvider provide files to a
CompositeFileProvider registered in the app's service container:
var physicalProvider = _env.ContentRootFileProvider;

var manifestEmbeddedProvider =
new ManifestEmbeddedFileProvider(Assembly.GetEntryAssembly());
var compositeProvider =
new CompositeFileProvider(physicalProvider, manifestEmbeddedProvider);
services.AddSingleton<IFileProvider>(compositeProvider);
In the sample app, a PhysicalFileProvider and an EmbeddedFileProvider provide files to a CompositeFileProvider
registered in the app's service container:
var physicalProvider = _hostingEnvironment.ContentRootFileProvider;

var embeddedProvider = new EmbeddedFileProvider(Assembly.GetEntryAssembly());
var compositeProvider = new CompositeFileProvider(physicalProvider, embeddedProvider);
services.AddSingleton<IFileProvider>(compositeProvider);
Watch for changes

The IFileProvider.Watch method provides a scenario to watch one or more files or directories for changes. Watch
accepts a path string, which can use glob patterns to specify multiple files. Watch returns an IChangeToken. The
change token exposes:
HasChanged: A property that can be inspected to determine if a change has occurred.
RegisterChangeCallback: Called when changes are detected to the specified path string. Each change token only
calls its associated callback in response to a single change. To enable constant monitoring, use a
TaskCompletionSource (shown below ) or recreate IChangeToken instances in response to changes.
In the sample app, the WatchConsole console app is configured to display a message whenever a text file is
modified:
private static PhysicalFileProvider _fileProvider =

new PhysicalFileProvider(Directory.GetCurrentDirectory());

{
Console.WriteLine("Monitoring quotes.txt for changes (Ctrl-c to quit)...");
while (true)
{
MainAsync().GetAwaiter().GetResult();
}
}
private static async Task MainAsync()

{
IChangeToken token = _fileProvider.Watch("quotes.txt");
var tcs = new TaskCompletionSource<object>();
token.RegisterChangeCallback(state =>
((TaskCompletionSource<object>)state).TrySetResult(null), tcs);
await tcs.Task.ConfigureAwait(false);
Console.WriteLine("quotes.txt changed");
}
private static PhysicalFileProvider _fileProvider =
new PhysicalFileProvider(Directory.GetCurrentDirectory());

{
Console.WriteLine("Monitoring quotes.txt for changes (Ctrl-c to quit)...");
while (true)
{
MainAsync().GetAwaiter().GetResult();
}
}
private static async Task MainAsync()

{
IChangeToken token = _fileProvider.Watch("quotes.txt");
var tcs = new TaskCompletionSource<object>();
token.RegisterChangeCallback(state =>
((TaskCompletionSource<object>)state).TrySetResult(null), tcs);
await tcs.Task.ConfigureAwait(false);
Console.WriteLine("quotes.txt changed");
}
Some file systems, such as Docker containers and network shares, may not reliably send change notifications. Set
the DOTNET_USE_POLLING_FILE_WATCHER environment variable to 1 or true to poll the file system for changes every
four seconds (not configurable).
Glob patterns
File system paths use wildcard patterns called glob (or globbing ) patterns. Specify groups of files with these
patterns. The two wildcard characters are * and ** :
*
Matches anything at the current folder level, any filename, or any file extension. Matches are terminated by / and
. characters in the file path.
**
Matches anything across multiple directory levels. Can be used to recursively match many files within a directory
hierarchy.
Glob pattern examples
directory/file.txt
Matches a specific file in a specific directory.
directory/*.txt
Matches all files with .txt extension in a specific directory.
directory/*/appsettings.json
Matches all appsettings.json files in directories exactly one level below the directory folder.
directory/**/*.txt
Matches all files with .txt extension found anywhere under the directory folder.
By Steve Smith, Scott Addie, and Luke Latham

The repository pattern is a design pattern that isolates data access behind interface abstractions. Connecting to
the database and manipulating data storage objects is performed through methods provided by the interface's
implementation. Consequently, there's no need for calling code to deal with database concerns, such as
connections, commands, and readers.
Implementation of the repository pattern with ASP.NET Core has the following benefits:
Organization of the app is less complex with no direct interdependency between the business and data access
layers.
It's easier to reuse database access code because the code is centrally managed by one or more repositories.
The business domain can be independently unit tested from the database layer.
The sample app uses the repository pattern to initialize and display a list of movie character names. The app uses
Entity Framework Core and an ApplicationDbContext class for its data persistence, but the database
infrastructure isn't apparent where the data is accessed. Data access and database objects are abstracted behind a
repository.
Repository interface
A repository interface defines the properties and methods for implementation. In the sample app, the repository
interface for movie character data is ICharacterRepository . ICharacterRepository defines the ListAll and Add
methods required to work with Character instances in the app:
public interface ICharacterRepository

{
IEnumerable<Character> ListAll();
void Add(Character character);
}
public interface ICharacterRepository

{
IEnumerable<Character> ListAll();
void Add(Character character);
}
Character is defined as:

public class Character
{
public Character(string name)
{
Name = name;
}
[Key]
public Guid Id { get; private set; } = Guid.NewGuid();
public string Name { get; private set; } = String.Empty;
}
public class Character

{
public Character(string name)
{
Name = name;
}
private Character()
{
}
[Key]
public Guid Id { get; private set; } = Guid.NewGuid();
public string Name { get; private set; } = String.Empty;
}
Repository concrete type

The interface is implemented by a concrete type. In the sample app, CharacterRepository manages the database
context and implements the ListAll and Add methods:
public class CharacterRepository : ICharacterRepository

{
private readonly ApplicationDbContext _dbContext;
public CharacterRepository(ApplicationDbContext dbContext)

{
_dbContext = dbContext;
}
public IEnumerable<Character> ListAll()

{
return _dbContext.Characters.AsEnumerable();
}
public void Add(Character character)

{
_dbContext.Characters.Add(character);
_dbContext.SaveChanges();
}
}
public class CharacterRepository : ICharacterRepository
{
private readonly ApplicationDbContext _dbContext;
public CharacterRepository(ApplicationDbContext dbContext)

{
_dbContext = dbContext;
}
public IEnumerable<Character> ListAll()

{
return _dbContext.Characters.AsEnumerable();
}
public void Add(Character character)

{
_dbContext.Characters.Add(character);
_dbContext.SaveChanges();
}
}
Register the repository service

The repository and database context are registered with the service container in Startup.ConfigureServices . In
the sample app, ApplicationDbContext is configured with the call to the extension method AddDbContext.
ICharacterRepository is registered as a scoped service:

{
// Add database services.
options.UseInMemoryDatabase("InMemoryDb")
);

{
});
// Register application services.

services.AddScoped<ICharacterRepository, CharacterRepository>();
}

{
// Add database services.
options.UseInMemoryDatabase()
);

services.AddMvc();
// Register application services.

services.AddScoped<ICharacterRepository, CharacterRepository>();
}
Inject an instance of the repository
In a class where database access is required, an instance of the repository is requested via the constructor and
assigned to a private field for use by class methods. In the sample app, ICharacterRepository is used to:
Populate the database if no characters exist.
Obtain a list of the characters for display.
Notice how the calling code only interacts with the interface's implementation, CharacterRepository . Calling code
doesn't use the ApplicationDbContext directly:

{
private readonly ICharacterRepository _characterRepository;
public IndexModel(ICharacterRepository characterRepository)

{
_characterRepository = characterRepository;
}
public IEnumerable<Character> Characters { get; set; }
public void OnGet()

{
PopulateCharactersIfNoneExist();
Characters = _characterRepository.ListAll();
}
private void PopulateCharactersIfNoneExist()

{
if (!_characterRepository.ListAll().Any())
{
_characterRepository.Add(new Character("Darth Maul"));
_characterRepository.Add(new Character("Darth Vader"));
_characterRepository.Add(new Character("Yoda"));
_characterRepository.Add(new Character("Mace Windu"));
}
}
}
{
private readonly ICharacterRepository _characterRepository;
public HomeController(ICharacterRepository characterRepository)

{
_characterRepository = characterRepository;
}

{
PopulateCharactersIfNoneExist();
var characters = _characterRepository.ListAll();
return View(characters);
}
private void PopulateCharactersIfNoneExist()

{
if (!_characterRepository.ListAll().Any())
{
_characterRepository.Add(new Character("Darth Maul"));
_characterRepository.Add(new Character("Darth Vader"));
_characterRepository.Add(new Character("Yoda"));
_characterRepository.Add(new Character("Mace Windu"));
}
}
}
Generic repository interface

This topic and its sample app demonstrate the simplest implementation of the repository pattern, where one
repository is created for each business object. If the app grows beyond a few objects, a generic repository
interface may reduce the amount of code required to implement the repository pattern. For more information,
see DevIQ: Repository Pattern: Generic Repository Interface.
DevIQ: Repository Pattern
Dependency injection
Dependency injection into controllers
Inversion of Control Containers and the Dependency Injection Pattern
Globalization and localization in ASP.NET Core
By Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana, and Hisham Bin Ateya
Creating a multilingual website with ASP.NET Core will allow your site to reach a wider audience. ASP.NET
Core provides services and middleware for localizing into different languages and cultures.
Internationalization involves Globalization and Localization. Globalization is the process of designing apps that
support different cultures. Globalization adds support for input, display, and output of a defined set of
language scripts that relate to specific geographic areas.
Localization is the process of adapting a globalized app, which you have already processed for localizability, to
a particular culture/locale. For more information see Globalization and localization terms near the end of
this document.
App localization involves the following:
1. Make the app's content localizable
2. Provide localized resources for the languages and cultures you support
3. Implement a strategy to select the language/culture for each request
Make the app's content localizable

Introduced in ASP.NET Core, IStringLocalizer and IStringLocalizer<T> were architected to improve
productivity when developing localized apps. IStringLocalizer uses the ResourceManager and
ResourceReader to provide culture-specific resources at run time. The simple interface has an indexer and an
IEnumerable for returning localized strings. IStringLocalizer doesn't require you to store the default language
strings in a resource file. You can develop an app targeted for localization and not need to create resource files
early in development. The code below shows how to wrap the string "About Title" for localization.
using Microsoft.Extensions.Localization;
namespace Localization.StarterWeb.Controllers
{
public class AboutController : Controller
{
private readonly IStringLocalizer<AboutController> _localizer;
public AboutController(IStringLocalizer<AboutController> localizer)

{
_localizer = localizer;
}
[HttpGet]
public string Get()
{
return _localizer["About Title"];
}
}
}
In the code above, the IStringLocalizer<T> implementation comes from Dependency Injection. If the localized
value of "About Title" isn't found, then the indexer key is returned, that is, the string "About Title". You can leave
the default language literal strings in the app and wrap them in the localizer, so that you can focus on
developing the app. You develop your app with your default language and prepare it for the localization step
without first creating a default resource file. Alternatively, you can use the traditional approach and provide a
key to retrieve the default language string. For many developers the new workflow of not having a default
language .resx file and simply wrapping the string literals can reduce the overhead of localizing an app. Other
developers will prefer the traditional work flow as it can make it easier to work with longer string literals and
make it easier to update localized strings.
Use the IHtmlLocalizer<T> implementation for resources that contain HTML. IHtmlLocalizer HTML encodes
arguments that are formatted in the resource string, but doesn't HTML encode the resource string itself. In the
sample highlighted below, only the value of name parameter is HTML encoded.
using System;
using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc.Localization;
namespace Localization.StarterWeb.Controllers
{
public class BookController : Controller
{
private readonly IHtmlLocalizer<BookController> _localizer;
public BookController(IHtmlLocalizer<BookController> localizer)

{
}
public IActionResult Hello(string name)

{
ViewData["Message"] = _localizer["<b>Hello</b><i> {0}</i>", name];
return View();
}
Note: You generally want to only localize text and not HTML.
At the lowest level, you can get IStringLocalizerFactory out of Dependency Injection:
{
public class TestController : Controller
{
private readonly IStringLocalizer _localizer;
private readonly IStringLocalizer _localizer2;
public TestController(IStringLocalizerFactory factory)

{
var type = typeof(SharedResource);
var assemblyName = new AssemblyName(type.GetTypeInfo().Assembly.FullName);
_localizer = factory.Create(type);
_localizer2 = factory.Create("SharedResource", assemblyName.Name);
}
public IActionResult About()

{
ViewData["Message"] = _localizer["Your application description page."]
+ " loc 2: " + _localizer2["Your application description page."];
The code above demonstrates each of the two factory create methods.
You can partition your localized strings by controller, area, or have just one container. In the sample app, a
dummy class named SharedResource is used for shared resources.
// Dummy class to group shared resources
namespace Localization.StarterWeb
{
public class SharedResource
{
}
}
Some developers use the Startup class to contain global or shared strings. In the sample below, the
InfoController and the SharedResource localizers are used:
public class InfoController : Controller

{
private readonly IStringLocalizer<InfoController> _localizer;
private readonly IStringLocalizer<SharedResource> _sharedLocalizer;
public InfoController(IStringLocalizer<InfoController> localizer,

IStringLocalizer<SharedResource> sharedLocalizer)
{
_sharedLocalizer = sharedLocalizer;
}
public string TestLoc()

{
string msg = "Shared resx: " + _sharedLocalizer["Hello!"] +
" Info resx " + _localizer["Hello!"];
return msg;
}
View localization
The IViewLocalizer service provides localized strings for a view. The ViewLocalizer class implements this
interface and finds the resource location from the view file path. The following code shows how to use the
default implementation of IViewLocalizer :
@using Microsoft.AspNetCore.Mvc.Localization
@inject IViewLocalizer Localizer
@{
ViewData["Title"] = Localizer["About"];
}
<h2>@ViewData["Title"].</h2>
<h3>@ViewData["Message"]</h3>
<p>@Localizer["Use this area to provide additional information."]</p>
The default implementation of IViewLocalizer finds the resource file based on the view's file name. There's no
option to use a global shared resource file. ViewLocalizer implements the localizer using IHtmlLocalizer , so
Razor doesn't HTML encode the localized string. You can parameterize resource strings and IViewLocalizer
will HTML encode the parameters, but not the resource string. Consider the following Razor markup:
@Localizer["<i>Hello</i> <b>{0}!</b>", UserManager.GetUserName(User)]
A French resource file could contain the following:
KEY VALUE
<i>Hello</i> <b>{0}!</b> <i>Bonjour</i> <b>{0} !</b>
The rendered view would contain the HTML markup from the resource file.
Note: You generally want to only localize text and not HTML.
To use a shared resource file in a view, inject IHtmlLocalizer<T> :
@using Localization.StarterWeb.Services

@inject IHtmlLocalizer<SharedResource> SharedLocalizer
@{
ViewData["Title"] = Localizer["About"];
}
<h1>@SharedLocalizer["Hello!"]</h1>
DataAnnotations localization
DataAnnotations error messages are localized with IStringLocalizer<T> . Using the option
ResourcesPath = "Resources" , the error messages in RegisterViewModel can be stored in either of the following
paths:
Resources/ViewModels.Account.RegisterViewModel.fr.resx
Resources/ViewModels/Account/RegisterViewModel.fr.resx
public class RegisterViewModel
{
[Required(ErrorMessage = "The Email field is required.")]
[EmailAddress(ErrorMessage = "The Email field is not a valid email address.")]
[Display(Name = "Email")]
public string Email { get; set; }
[Required(ErrorMessage = "The Password field is required.")]

[StringLength(8, ErrorMessage = "The {0} must be at least {2} characters long.", MinimumLength = 6)]
[DataType(DataType.Password)]
[Display(Name = "Password")]
public string Password { get; set; }
[Display(Name = "Confirm password")]
[Compare("Password", ErrorMessage = "The password and confirmation password do not match.")]
public string ConfirmPassword { get; set; }
}
In ASP.NET Core MVC 1.1.0 and higher, non-validation attributes are localized. ASP.NET Core MVC 1.0 does
not look up localized strings for non-validation attributes.
Using one resource string for multiple classes
The following code shows how to use one resource string for validation attributes with multiple classes:

{
services.AddMvc()
.AddDataAnnotationsLocalization(options => {
options.DataAnnotationLocalizerProvider = (type, factory) =>
factory.Create(typeof(SharedResource));
});
}
In the preceeding code, SharedResource is the class corresponding to the resx where your validation messages
are stored. With this approach, DataAnnotations will only use SharedResource , rather than the resource for
each class.
Provide localized resources for the languages and cultures you

support
SupportedCultures and SupportedUICultures
ASP.NET Core allows you to specify two culture values, SupportedCultures and SupportedUICultures . The
CultureInfo object for SupportedCultures determines the results of culture-dependent functions, such as date,
time, number, and currency formatting. SupportedCultures also determines the sorting order of text, casing
conventions, and string comparisons. See CultureInfo.CurrentCulture for more info on how the server gets the
Culture. The SupportedUICultures determines which translates strings (from .resx files) are looked up by the
ResourceManager. The ResourceManager simply looks up culture-specific strings that's determined by
CurrentUICulture . Every thread in .NET has CurrentCulture and CurrentUICulture objects. ASP.NET Core
inspects these values when rendering culture-dependent functions. For example, if the current thread's culture
is set to "en-US" (English, United States), DateTime.Now.ToLongDateString() displays "Thursday, February 18,
2016", but if CurrentCulture is set to "es-ES" (Spanish, Spain) the output will be "jueves, 18 de febrero de
2016".
Resource files
A resource file is a useful mechanism for separating localizable strings from code. Translated strings for the
non-default language are isolated .resx resource files. For example, you might want to create Spanish resource
file named Welcome.es.resx containing translated strings. "es" is the language code for Spanish. To create this
resource file in Visual Studio:
1. In Solution Explorer, right click on the folder which will contain the resource file > Add > New Item.
2. In the Search installed templates box, enter "resource" and name the file.
3. Enter the key value (native string) in the Name column and the translated string in the Value column.
Visual Studio shows the Welcome.es.resx file.

Resource file naming
Resources are named for the full type name of their class minus the assembly name. For example, a French
resource in a project whose main assembly is LocalizationWebsite.Web.dll for the class
LocalizationWebsite.Web.Startup would be named Startup.fr.resx. A resource for the class
LocalizationWebsite.Web.Controllers.HomeController would be named Controllers.HomeController.fr.resx. If
your targeted class's namespace isn't the same as the assembly name you will need the full type name. For
example, in the sample project a resource for the type ExtraNamespace.Tools would be named
ExtraNamespace.Tools.fr.resx.
In the sample project, the ConfigureServices method sets the ResourcesPath to "Resources", so the project
relative path for the home controller's French resource file is Resources/Controllers.HomeController.fr.resx.
Alternatively, you can use folders to organize resource files. For the home controller, the path would be
Resources/Controllers/HomeController.fr.resx. If you don't use the ResourcesPath option, the .resx file would go
in the project base directory. The resource file for HomeController would be named
Controllers.HomeController.fr.resx. The choice of using the dot or path naming convention depends on how you
want to organize your resource files.
RESOURCE NAME DOT OR PATH NAMING
Resources/Controllers.HomeController.fr.resx Dot
Resources/Controllers/HomeController.fr.resx Path
Resource files using @inject IViewLocalizer in Razor views follow a similar pattern. The resource file for a
view can be named using either dot naming or path naming. Razor view resource files mimic the path of their
associated view file. Assuming we set the ResourcesPath to "Resources", the French resource file associated
with the Views/Home/About.cshtml view could be either of the following:
Resources/Views/Home/About.fr.resx
Resources/Views.Home.About.fr.resx
If you don't use the ResourcesPath option, the .resx file for a view would be located in the same folder as the
view.
RootNamespaceAttribute
The RootNamespace attribute provides the root namespace of an assembly when the root namespace of an
assembly is different than the assembly name.
If the root namespace of an assembly is different than the assembly name:
Localization does not work by default.
Localization fails due to the way resources are searched for within the assembly. RootNamespace is a build-
time value which is not available to the executing process.
If the RootNamespace is different from the AssemblyName , include the following in AssemblyInfo.cs (with
parameter values replaced with the actual values):
using Microsoft.Extensions.Localization;
[assembly: ResourceLocation("Resource Folder Name")]

[assembly: RootNamespace("App Root Namespace")]
The preceding code enables the successful resolution of resx files.
Culture fallback behavior

When searching for a resource, localization engages in "culture fallback". Starting from the requested culture, if
not found, it reverts to the parent culture of that culture. As an aside, the CultureInfo.Parent property
represents the parent culture. This usually (but not always) means removing the national signifier from the
ISO. For example, the dialect of Spanish spoken in Mexico is "es-MX". It has the parent "es"—Spanish non-
specific to any country.
Imagine your site receives a request for a "Welcome" resource using culture "fr-CA". The localization system
looks for the following resources, in order, and selects the first match:
Welcome.fr-CA.resx
Welcome.fr.resx
Welcome.resx (if the NeutralResourcesLanguage is "fr-CA")
As an example, if you remove the ".fr" culture designator and you have the culture set to French, the default
resource file is read and strings are localized. The Resource manager designates a default or fallback resource
for when nothing meets your requested culture. If you want to just return the key when missing a resource for
the requested culture you must not have a default resource file.
Generate resource files with Visual Studio
If you create a resource file in Visual Studio without a culture in the file name (for example, Welcome.resx),
Visual Studio will create a C# class with a property for each string. That's usually not what you want with
ASP.NET Core. You typically don't have a default .resx resource file (a .resx file without the culture name). We
suggest you create the .resx file with a culture name (for example Welcome.fr.resx). When you create a .resx file
with a culture name, Visual Studio won't generate the class file. We anticipate that many developers won't
create a default language resource file.
Add other cultures
Each language and culture combination (other than the default language) requires a unique resource file. You
create resource files for different cultures and locales by creating new resource files in which the ISO language
codes are part of the file name (for example, en-us, fr-ca, and en-gb). These ISO codes are placed between the
file name and the .resx file extension, as in Welcome.es-MX.resx (Spanish/Mexico).
Implement a strategy to select the language/culture for each request

Configure localization
Localization is configured in the ConfigureServices method:
services.AddLocalization(options => options.ResourcesPath = "Resources");
services.AddMvc()
.AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix)
.AddDataAnnotationsLocalization();
AddLocalization Adds the localization services to the services container. The code above also sets the
resources path to "Resources".
AddViewLocalization Adds support for localized view files. In this sample view localization is based on
the view file suffix. For example "fr" in the Index.fr.cshtml file.
AddDataAnnotationsLocalization Adds support for localized DataAnnotations validation messages
through IStringLocalizer abstractions.
Localization middleware
The current culture on a request is set in the localization Middleware. The localization middleware is enabled in
the Configure method. The localization middleware must be configured before any middleware which might
check the request culture (for example, app.UseMvcWithDefaultRoute() ).
var supportedCultures = new[]

{
new CultureInfo(enUSCulture),
new CultureInfo("en-AU"),
new CultureInfo("en-GB"),
new CultureInfo("en"),
new CultureInfo("es-ES"),
new CultureInfo("es-MX"),
new CultureInfo("es"),
new CultureInfo("fr-FR"),
new CultureInfo("fr"),
};
app.UseRequestLocalization(new RequestLocalizationOptions
{
DefaultRequestCulture = new RequestCulture(enUSCulture),
// Formatting numbers, dates, etc.
SupportedCultures = supportedCultures,
// UI strings that we have localized.
SupportedUICultures = supportedCultures
});
// To configure external authentication,
// see: http://go.microsoft.com/fwlink/?LinkID=532715
UseRequestLocalization initializes a RequestLocalizationOptions object. On every request the list of

RequestCultureProvider in the RequestLocalizationOptions is enumerated and the first provider that can
successfully determine the request culture is used. The default providers come from the
RequestLocalizationOptions class:
1. QueryStringRequestCultureProvider
2. CookieRequestCultureProvider
3. AcceptLanguageHeaderRequestCultureProvider
The default list goes from most specific to least specific. Later in the article we'll see how you can change the
order and even add a custom culture provider. If none of the providers can determine the request culture, the
DefaultRequestCulture is used.
QueryStringRequestCultureProvider
Some apps will use a query string to set the culture and UI culture. For apps that use the cookie or Accept-
Language header approach, adding a query string to the URL is useful for debugging and testing code. By
default, the QueryStringRequestCultureProvider is registered as the first localization provider in the
RequestCultureProvider list. You pass the query string parameters culture and ui-culture . The following
example sets the specific culture (language and region) to Spanish/Mexico:
http://localhost:5000/?culture=es-MX&ui-culture=es-MX
If you only pass in one of the two ( culture or ui-culture ), the query string provider will set both values using
the one you passed in. For example, setting just the culture will set both the Culture and the UICulture :
http://localhost:5000/?culture=es-MX
CookieRequestCultureProvider
Production apps will often provide a mechanism to set the culture with the ASP.NET Core culture cookie. Use
the MakeCookieValue method to create a cookie.
The CookieRequestCultureProvider DefaultCookieName returns the default cookie name used to track the user's
preferred culture information. The default cookie name is .AspNetCore.Culture .
The cookie format is c=%LANGCODE%|uic=%LANGCODE% , where c is Culture and uic is UICulture , for example:
c=en-UK|uic=en-US
If you only specify one of culture info and UI culture, the specified culture will be used for both culture info and
UI culture.
The Accept-Language HTTP header
The Accept-Language header is settable in most browsers and was originally intended to specify the user's
language. This setting indicates what the browser has been set to send or has inherited from the underlying
operating system. The Accept-Language HTTP header from a browser request isn't an infallible way to detect
the user's preferred language (see Setting language preferences in a browser). A production app should
include a way for a user to customize their choice of culture.
Set the Accept-Language HTTP header in IE
1. From the gear icon, tap Internet Options.
2. Tap Languages.
3. Tap Set Language Preferences.
4. Tap Add a language.
5. Add the language.
6. Tap the language, then tap Move Up.
Use a custom provider
Suppose you want to let your customers store their language and culture in your databases. You could write a
provider to look up these values for the user. The following code shows how to add a custom provider:
private const string enUSCulture = "en-US";
services.Configure<RequestLocalizationOptions>(options =>
{
{
new CultureInfo(enUSCulture),
new CultureInfo("fr")
};
options.DefaultRequestCulture = new RequestCulture(culture: enUSCulture, uiCulture: enUSCulture);

options.SupportedCultures = supportedCultures;
options.SupportedUICultures = supportedCultures;
options.RequestCultureProviders.Insert(0, new CustomRequestCultureProvider(async context =>

{
// My custom request culture logic
return new ProviderCultureResult("en");
}));
});
Use RequestLocalizationOptions to add or remove localization providers.

Set the culture programmatically
This sample Localization.StarterWeb project on GitHub contains UI to set the Culture . The
Views/Shared/_SelectLanguagePartial.cshtml file allows you to select the culture from the list of supported
cultures:
@using Microsoft.AspNetCore.Builder
@using Microsoft.AspNetCore.Http.Features
@using Microsoft.AspNetCore.Localization
@using Microsoft.Extensions.Options

@inject IOptions<RequestLocalizationOptions> LocOptions
@{
var requestCulture = Context.Features.Get<IRequestCultureFeature>();
var cultureItems = LocOptions.Value.SupportedUICultures
.Select(c => new SelectListItem { Value = c.Name, Text = c.DisplayName })
.ToList();
var returnUrl = string.IsNullOrEmpty(Context.Request.Path) ? "~/" : $"~{Context.Request.Path.Value}";
}
<div title="@Localizer["Request culture provider:"] @requestCulture?.Provider?.GetType().Name">

<form id="selectLanguage" asp-controller="Home"
asp-action="SetLanguage" asp-route-returnUrl="@returnUrl"
method="post" class="form-horizontal" role="form">
<label asp-for="@requestCulture.RequestCulture.UICulture.Name">@Localizer["Language:"]</label>
<select name="culture"
onchange="this.form.submit();"
asp-for="@requestCulture.RequestCulture.UICulture.Name" asp-items="cultureItems">
</select>
</form>
</div>
The Views/Shared/_SelectLanguagePartial.cshtml file is added to the footer section of the layout file so it will
be available to all views:
<div class="container body-content" style="margin-top:60px">

@RenderBody()
<hr>
<footer>
<div class="row">
<p>© @System.DateTime.Now.Year - Localization.StarterWeb</p>
</div>
<div class="col-md-6 text-right">
@await Html.PartialAsync("_SelectLanguagePartial")
</div>
</div>
</footer>
</div>
The SetLanguage method sets the culture cookie.

[HttpPost]
public IActionResult SetLanguage(string culture, string returnUrl)
{
Response.Cookies.Append(
CookieRequestCultureProvider.DefaultCookieName,
CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(culture)),
new CookieOptions { Expires = DateTimeOffset.UtcNow.AddYears(1) }
);
return LocalRedirect(returnUrl);
}
You can't plug in the _SelectLanguagePartial.cshtml to sample code for this project. The
Localization.StarterWeb project on GitHub has code to flow the RequestLocalizationOptions to a Razor
partial through the Dependency Injection container.
Globalization and localization terms

The process of localizing your app also requires a basic understanding of relevant character sets commonly
used in modern software development and an understanding of the issues associated with them. Although all
computers store text as numbers (codes), different systems store the same text using different numbers. The
localization process refers to translating the app user interface (UI) for a specific culture/locale.
Localizability is an intermediate process for verifying that a globalized app is ready for localization.
The RFC 4646 format for the culture name is <languagecode2>-<country/regioncode2> , where <languagecode2>
is the language code and <country/regioncode2> is the subculture code. For example, es-CL for Spanish
(Chile), en-US for English (United States), and en-AU for English (Australia). RFC 4646 is a combination of an
ISO 639 two-letter lowercase culture code associated with a language and an ISO 3166 two-letter uppercase
subculture code associated with a country or region. See Language Culture Name.
Internationalization is often abbreviated to "I18N". The abbreviation takes the first and last letters and the
number of letters between them, so 18 stands for the number of letters between the first "I" and the last "N".
The same applies to Globalization (G11N ), and Localization (L10N ).
Terms:
Globalization (G11N ): The process of making an app support different languages and regions.
Localization (L10N ): The process of customizing an app for a given language and region.
Internationalization (I18N ): Describes both globalization and localization.
Culture: It's a language and, optionally, a region.
Neutral culture: A culture that has a specified language, but not a region. (for example "en", "es")
Specific culture: A culture that has a specified language and region. (for example "en-US", "en-GB", "es-CL")
Parent culture: The neutral culture that contains a specific culture. (for example, "en" is the parent culture of
"en-US" and "en-GB")
Locale: A locale is the same as a culture.
Localization.StarterWeb project used in the article.
Resource Files in Visual Studio
Resources in .resx Files
Microsoft Multilingual App Toolkit
Configure portable object localization in ASP.NET
Core
By Sébastien Ros and Scott Addie

This article walks through the steps for using Portable Object (PO ) files in an ASP.NET Core application with the
Orchard Core framework.
Note: Orchard Core isn't a Microsoft product. Consequently, Microsoft provides no support for this feature.
What is a PO file?
PO files are distributed as text files containing the translated strings for a given language. Some advantages of
using PO files instead .resx files include:
PO files support pluralization; .resx files don't support pluralization.
PO files aren't compiled like .resx files. As such, specialized tooling and build steps aren't required.
PO files work well with collaborative online editing tools.
Example
Here is a sample PO file containing the translation for two strings in French, including one with its plural form:
fr.po
#: Services/EmailService.cs:29
msgid "Enter a comma separated list of email addresses."
msgstr "Entrez une liste d'emails séparés par une virgule."
#: Views/Email.cshtml:112
msgid "The email address is \"{0}\"."
msgid_plural "The email addresses are \"{0}\"."
msgstr[0] "L'adresse email est \"{0}\"."
msgstr[1] "Les adresses email sont \"{0}\""
This example uses the following syntax:

#: : A comment indicating the context of the string to be translated. The same string might be translated
differently depending on where it's being used.
msgid : The untranslated string.
msgstr : The translated string.
In the case of pluralization support, more entries can be defined.

msgid_plural : The untranslated plural string.
msgstr[0] : The translated string for the case 0.
msgstr[N] : The translated string for the case N.
The PO file specification can be found here.

Configuring PO file support in ASP.NET Core
This example is based on an ASP.NET Core MVC application generated from a Visual Studio 2017 project
template.
Referencing the package
Add a reference to the OrchardCore.Localization.Core NuGet package. It's available on MyGet at the following
package source: https://www.myget.org/F/orchardcore-preview/api/v3/index.json
The .csproj file now contains a line similar to the following (version number may vary):
<PackageReference Include="OrchardCore.Localization.Core" Version="1.0.0-beta1-3187" />
Registering the service

Add the required services to the ConfigureServices method of Startup.cs:

{
services.AddMvc()
.AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix);
services.AddPortableObjectLocalization();
services.Configure<RequestLocalizationOptions>(options =>
{
var supportedCultures = new List<CultureInfo>
{
new CultureInfo("en-US"),
};
options.DefaultRequestCulture = new RequestCulture("en-US");

options.SupportedCultures = supportedCultures;
options.SupportedUICultures = supportedCultures;
});
}
Add the required middleware to the Configure method of Startup.cs:

{
{
}
else
{
}
app.UseRequestLocalization();
}
Add the following code to your Razor view of choice. About.cshtml is used in this example.
<p>@Localizer["Hello world!"]</p>
An IViewLocalizer instance is injected and used to translate the text "Hello world!".
Creating a PO file
Create a file named .po in your application root folder. In this example, the file name is fr.po because the French
language is used:
msgid "Hello world!"

msgstr "Bonjour le monde!"
This file stores both the string to translate and the French-translated string. Translations revert to their parent
culture, if necessary. In this example, the fr.po file is used if the requested culture is fr-FR or fr-CA .
Testing the application
Run your application, and navigate to the URL /Home/About . The text Hello world! is displayed.
Navigate to the URL /Home/About?culture=fr-FR . The text Bonjour le monde! is displayed.
Pluralization
PO files support pluralization forms, which is useful when the same string needs to be translated differently based
on a cardinality. This task is made complicated by the fact that each language defines custom rules to select which
string to use based on the cardinality.
The Orchard Localization package provides an API to invoke these different plural forms automatically.
Creating pluralization PO files
Add the following content to the previously mentioned fr.po file:
msgid "There is one item."

msgid_plural "There are {0} items."
msgstr[0] "Il y a un élément."
msgstr[1] "Il y a {0} éléments."
See What is a PO file? for an explanation of what each entry in this example represents.
Adding a language using different pluralization forms
English and French strings were used in the previous example. English and French have only two pluralization
forms and share the same form rules, which is that a cardinality of one is mapped to the first plural form. Any other
cardinality is mapped to the second plural form.
Not all languages share the same rules. This is illustrated with the Czech language, which has three plural forms.
Create the cs.po file as follows, and note how the pluralization needs three different translations:
msgstr "Ahoj světe!!"
msgid "There is one item."

msgid_plural "There are {0} items."
msgstr[0] "Existuje jedna položka."
msgstr[1] "Existují {0} položky."
msgstr[2] "Existuje {0} položek."
To accept Czech localizations, add "cs" to the list of supported cultures in the ConfigureServices method:
var supportedCultures = new List<CultureInfo>

{
new CultureInfo("fr"),
new CultureInfo("cs")
};
Edit the Views/Home/About.cshtml file to render localized, plural strings for several cardinalities:
<p>@Localizer.Plural(1, "There is one item.", "There are {0} items.")</p>

Note: In a real world scenario, a variable would be used to represent the count. Here, we repeat the same code
with three different values to expose a very specific case.
Upon switching cultures, you see the following:
For /Home/About :
There is one item.

There are 2 items.
There are 5 items.
For /Home/About?culture=fr :
Il y a un élément.
Il y a 2 éléments.
Il y a 5 éléments.
For /Home/About?culture=cs :
Existuje jedna položka.

Existují 2 položky.
Existuje 5 položek.
Note that for the Czech culture, the three translations are different. The French and English cultures share the same
construction for the two last translated strings.
Advanced tasks
Contextualizing strings
Applications often contain the strings to be translated in several places. The same string may have a different
translation in certain locations within an app (Razor views or class files). A PO file supports the notion of a file
context, which can be used to categorize the string being represented. Using a file context, a string can be translated
differently, depending on the file context (or lack of a file context).
The PO localization services use the name of the full class or the view that's used when translating a string. This is
accomplished by setting the value on the msgctxt entry.
Consider a minor addition to the previous fr.po example. A Razor view located at Views/Home/About.cshtml can be
defined as the file context by setting the reserved msgctxt entry's value:
msgctxt "Views.Home.About"
With the msgctxt set as such, text translation occurs when navigating to /Home/About?culture=fr-FR . The
translation won't occur when navigating to /Home/Contact?culture=fr-FR .
When no specific entry is matched with a given file context, Orchard Core's fallback mechanism looks for an
appropriate PO file without a context. Assuming there's no specific file context defined for
Views/Home/Contact.cshtml, navigating to /Home/Contact?culture=fr-FR loads a PO file such as:

Changing the location of PO files

The default location of PO files can be changed in ConfigureServices :
services.AddPortableObjectLocalization(options => options.ResourcesPath = "Localization");
In this example, the PO files are loaded from the Localization folder.
Implementing a custom logic for finding localization files
When more complex logic is needed to locate PO files, the
OrchardCore.Localization.PortableObject.ILocalizationFileLocationProvider interface can be implemented and
registered as a service. This is useful when PO files can be stored in varying locations or when the files have to be
found within a hierarchy of folders.
Using a different default pluralized language
The package includes a Plural extension method that's specific to two plural forms. For languages requiring more
plural forms, create an extension method. With an extension method, you won't need to provide any localization file
for the default language — the original strings are already available directly in the code.
You can use the more generic Plural(int count, string[] pluralForms, params object[] arguments) overload which
accepts a string array of translations.
By Glenn Condron, Ryan Nowak, and Steve Gordon

An IHttpClientFactory can be registered and used to configure and create HttpClient instances in an app. It offers
the following benefits:
Provides a central location for naming and configuring logical HttpClient instances. For example, a github
client can be registered and configured to access GitHub. A default client can be registered for other purposes.
Codifies the concept of outgoing middleware via delegating handlers in HttpClient and provides extensions
for Polly-based middleware to take advantage of that.
Manages the pooling and lifetime of underlying HttpClientMessageHandler instances to avoid common DNS
problems that occur when manually managing HttpClient lifetimes.
Adds a configurable logging experience (via ILogger ) for all requests sent through clients created by the
factory.
Prerequisites
Projects targeting .NET Framework require installation of the Microsoft.Extensions.Http NuGet package. Projects
that target .NET Core and reference the Microsoft.AspNetCore.App metapackage already include the
Microsoft.Extensions.Http package.
Consumption patterns
There are several ways IHttpClientFactory can be used in an app:
Basic usage
Named clients
Typed clients
Generated clients
None of them are strictly superior to another. The best approach depends upon the app's constraints.
Basic usage
The IHttpClientFactory can be registered by calling the AddHttpClient extension method on the
IServiceCollection , inside the Startup.ConfigureServices method.
services.AddHttpClient();
Once registered, code can accept an IHttpClientFactory anywhere services can be injected with dependency
injection (DI). The IHttpClientFactory can be used to create a HttpClient instance:
public class BasicUsageModel : PageModel
{
private readonly IHttpClientFactory _clientFactory;
public IEnumerable<GitHubBranch> Branches { get; private set; }
public bool GetBranchesError { get; private set; }
public BasicUsageModel(IHttpClientFactory clientFactory)

{
_clientFactory = clientFactory;
}
public async Task OnGet()

{
var request = new HttpRequestMessage(HttpMethod.Get,
"https://api.github.com/repos/aspnet/docs/branches");
request.Headers.Add("Accept", "application/vnd.github.v3+json");
request.Headers.Add("User-Agent", "HttpClientFactory-Sample");
var client = _clientFactory.CreateClient();
var response = await client.SendAsync(request);
if (response.IsSuccessStatusCode)
{
Branches = await response.Content
.ReadAsAsync<IEnumerable<GitHubBranch>>();
}
else
{
GetBranchesError = true;
Branches = Array.Empty<GitHubBranch>();
}
}
}
Using IHttpClientFactory in this fashion is a great way to refactor an existing app. It has no impact on the way
HttpClient is used. In places where HttpClient instances are currently created, replace those occurrences with a
call to CreateClient.
Named clients
If an app requires many distinct uses of HttpClient , each with a different configuration, an option is to use
named clients. Configuration for a named HttpClient can be specified during registration in
Startup.ConfigureServices .
services.AddHttpClient("github", c =>
{
c.BaseAddress = new Uri("https://api.github.com/");
// Github API versioning
c.DefaultRequestHeaders.Add("Accept", "application/vnd.github.v3+json");
// Github requires a user-agent
c.DefaultRequestHeaders.Add("User-Agent", "HttpClientFactory-Sample");
});
In the preceding code, AddHttpClient is called, providing the name github. This client has some default
configuration applied—namely the base address and two headers required to work with the GitHub API.
Each time CreateClient is called, a new instance of HttpClient is created and the configuration action is called.
To consume a named client, a string parameter can be passed to CreateClient . Specify the name of the client to be
created:
public class NamedClientModel : PageModel
{
private readonly IHttpClientFactory _clientFactory;
public IEnumerable<GitHubPullRequest> PullRequests { get; private set; }
public bool GetPullRequestsError { get; private set; }
public bool HasPullRequests => PullRequests.Any();
public NamedClientModel(IHttpClientFactory clientFactory)

{
_clientFactory = clientFactory;
}

{
var request = new HttpRequestMessage(HttpMethod.Get,
"repos/aspnet/docs/pulls");
var client = _clientFactory.CreateClient("github");
var response = await client.SendAsync(request);
if (response.IsSuccessStatusCode)
{
PullRequests = await response.Content
.ReadAsAsync<IEnumerable<GitHubPullRequest>>();
}
else
{
GetPullRequestsError = true;
PullRequests = Array.Empty<GitHubPullRequest>();
}
}
}
In the preceding code, the request doesn't need to specify a hostname. It can pass just the path, since the base
address configured for the client is used.
Typed clients
Typed clients provide the same capabilities as named clients without the need to use strings as keys. The typed
client approach provides IntelliSense and compiler help when consuming clients. They provide a single location to
configure and interact with a particular HttpClient . For example, a single typed client might be used for a single
backend endpoint and encapsulate all logic dealing with that endpoint. Another advantage is that they work with
DI and can be injected where required in your app.
A typed client accepts a HttpClient parameter in its constructor:
public class GitHubService
{
public HttpClient Client { get; }
public GitHubService(HttpClient client)

{
client.BaseAddress = new Uri("https://api.github.com/");
// GitHub API versioning
client.DefaultRequestHeaders.Add("Accept",
"application/vnd.github.v3+json");
// GitHub requires a user-agent
client.DefaultRequestHeaders.Add("User-Agent",
"HttpClientFactory-Sample");
Client = client;
}
public async Task<IEnumerable<GitHubIssue>> GetAspNetDocsIssues()

{
var response = await Client.GetAsync(
"/repos/aspnet/docs/issues?state=open&sort=created&direction=desc");
response.EnsureSuccessStatusCode();
var result = await response.Content

.ReadAsAsync<IEnumerable<GitHubIssue>>();
return result;
}
}
In the preceding code, the configuration is moved into the typed client. The HttpClient object is exposed as a
public property. It's possible to define API-specific methods that expose HttpClient functionality. The
GetAspNetDocsIssues method encapsulates the code needed to query for and parse out the latest open issues from
a GitHub repository.
To register a typed client, the generic AddHttpClient extension method can be used within
Startup.ConfigureServices , specifying the typed client class:
services.AddHttpClient<GitHubService>();
The typed client is registered as transient with DI. The typed client can be injected and consumed directly:
public class TypedClientModel : PageModel
{
private readonly GitHubService _gitHubService;
public IEnumerable<GitHubIssue> LatestIssues { get; private set; }
public bool HasIssue => LatestIssues.Any();
public bool GetIssuesError { get; private set; }
public TypedClientModel(GitHubService gitHubService)

{
_gitHubService = gitHubService;
}

{
try
{
LatestIssues = await _gitHubService.GetAspNetDocsIssues();
}
catch(HttpRequestException)
{
GetIssuesError = true;
LatestIssues = Array.Empty<GitHubIssue>();
}
}
}
If preferred, the configuration for a typed client can be specified during registration in Startup.ConfigureServices ,
rather than in the typed client's constructor:
services.AddHttpClient<RepoService>(c =>
{
c.BaseAddress = new Uri("https://api.github.com/");
c.DefaultRequestHeaders.Add("Accept", "application/vnd.github.v3+json");
c.DefaultRequestHeaders.Add("User-Agent", "HttpClientFactory-Sample");
});
It's possible to entirely encapsulate the HttpClient within a typed client. Rather than exposing it as a property,
public methods can be provided which call the HttpClient instance internally.
public class RepoService
{
// _httpClient isn't exposed publicly
private readonly HttpClient _httpClient;
public RepoService(HttpClient client)

{
_httpClient = client;
}
public async Task<IEnumerable<string>> GetRepos()

{
var response = await _httpClient.GetAsync("aspnet/repos");
response.EnsureSuccessStatusCode();
var result = await response.Content

.ReadAsAsync<IEnumerable<string>>();
return result;
}
}
In the preceding code, the HttpClient is stored as a private field. All access to make external calls goes through
the GetRepos method.
Generated clients
IHttpClientFactory can be used in combination with other third-party libraries such as Refit. Refit is a REST
library for .NET. It converts REST APIs into live interfaces. An implementation of the interface is generated
dynamically by the RestService , using HttpClient to make the external HTTP calls.
An interface and a reply are defined to represent the external API and its response:
public interface IHelloClient

{
[Get("/helloworld")]
Task<Reply> GetMessageAsync();
}
public class Reply

{
}
A typed client can be added, using Refit to generate the implementation:

{
services.AddHttpClient("hello", c =>
{
c.BaseAddress = new Uri("http://localhost:5000");
})
.AddTypedClient(c => Refit.RestService.For<IHelloClient>(c));
services.AddMvc();
}
The defined interface can be consumed where necessary, with the implementation provided by DI and Refit:
[ApiController]
public class ValuesController : ControllerBase
{
private readonly IHelloClient _client;
public ValuesController(IHelloClient client)

{
_client = client;
}
[HttpGet("/")]
public async Task<ActionResult<Reply>> Index()
{
return await _client.GetMessageAsync();
}
}
Outgoing request middleware

HttpClient already has the concept of delegating handlers that can be linked together for outgoing HTTP
requests. The IHttpClientFactory makes it easy to define the handlers to apply for each named client. It supports
registration and chaining of multiple handlers to build an outgoing request middleware pipeline. Each of these
handlers is able to perform work before and after the outgoing request. This pattern is similar to the inbound
middleware pipeline in ASP.NET Core. The pattern provides a mechanism to manage cross-cutting concerns
around HTTP requests, including caching, error handling, serialization, and logging.
To create a handler, define a class deriving from DelegatingHandler . Override the SendAsync method to execute
code before passing the request to the next handler in the pipeline:
public class ValidateHeaderHandler : DelegatingHandler

{
protected override async Task<HttpResponseMessage> SendAsync(
HttpRequestMessage request,
{
if (!request.Headers.Contains("X-API-KEY"))
{
return new HttpResponseMessage(HttpStatusCode.BadRequest)
{
Content = new StringContent(
"You must supply an API key header called X-API-KEY")
};
}
return await base.SendAsync(request, cancellationToken);

}
}
The preceding code defines a basic handler. It checks to see if an X-API-KEY header has been included on the
request. If the header is missing, it can avoid the HTTP call and return a suitable response.
During registration, one or more handlers can be added to the configuration for a HttpClient . This task is
accomplished via extension methods on the IHttpClientBuilder.
services.AddTransient<ValidateHeaderHandler>();
services.AddHttpClient("externalservice", c =>
{
// Assume this is an "external" service which requires an API KEY
c.BaseAddress = new Uri("https://localhost:5000/");
})
.AddHttpMessageHandler<ValidateHeaderHandler>();
In the preceding code, the ValidateHeaderHandler is registered with DI. The handler must be registered in DI as
transient. Once registered, AddHttpMessageHandler can be called, passing in the type for the handler.
Multiple handlers can be registered in the order that they should execute. Each handler wraps the next handler
until the final HttpClientHandler executes the request:
services.AddTransient<SecureRequestHandler>();
services.AddTransient<RequestDataHandler>();
services.AddHttpClient("clientwithhandlers")
// This handler is on the outside and called first during the
// request, last during the response.
.AddHttpMessageHandler<SecureRequestHandler>()
// This handler is on the inside, closest to the request being
// sent.
.AddHttpMessageHandler<RequestDataHandler>();
Use Polly-based handlers

IHttpClientFactory integrates with a popular third-party library called Polly. Polly is a comprehensive resilience
and transient fault-handling library for .NET. It allows developers to express policies such as Retry, Circuit Breaker,
Timeout, Bulkhead Isolation, and Fallback in a fluent and thread-safe manner.
Extension methods are provided to enable the use of Polly policies with configured HttpClient instances. The
Polly extensions are available in the Microsoft.Extensions.Http.Polly NuGet package. This package isn't included in
the Microsoft.AspNetCore.App metapackage. To use the extensions, an explicit <PackageReference /> should be
included in the project.
<PropertyGroup>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Extensions.Http.Polly" Version="2.1.1" />
</ItemGroup>
</Project>
After restoring this package, extension methods are available to support adding Polly-based handlers to clients.
Handle transient faults
Most common faults occur when external HTTP calls are transient. A convenient extension method called
AddTransientHttpErrorPolicy is included which allows a policy to be defined to handle transient errors. Policies
configured with this extension method handle HttpRequestException , HTTP 5xx responses, and HTTP 408
responses.
The AddTransientHttpErrorPolicy extension can be used within Startup.ConfigureServices . The extension provides
access to a PolicyBuilder object configured to handle errors representing a possible transient fault:
services.AddHttpClient<UnreliableEndpointCallerService>()
.AddTransientHttpErrorPolicy(p =>
p.WaitAndRetryAsync(3, _ => TimeSpan.FromMilliseconds(600)));
In the preceding code, a WaitAndRetryAsync policy is defined. Failed requests are retried up to three times with a
delay of 600 ms between attempts.
Dynamically select policies
Additional extension methods exist which can be used to add Polly-based handlers. One such extension is
AddPolicyHandler , which has multiple overloads. One overload allows the request to be inspected when defining
which policy to apply:
var timeout = Policy.TimeoutAsync<HttpResponseMessage>(

var longTimeout = Policy.TimeoutAsync<HttpResponseMessage>(
services.AddHttpClient("conditionalpolicy")
// Run some code to select a policy based on the request
.AddPolicyHandler(request =>
request.Method == HttpMethod.Get ? timeout : longTimeout);
In the preceding code, if the outgoing request is a GET, a 10-second timeout is applied. For any other HTTP
method, a 30-second timeout is used.
Add multiple Polly handlers
It is common to nest Polly policies to provide enhanced functionality:
services.AddHttpClient("multiplepolicies")
.AddTransientHttpErrorPolicy(p => p.RetryAsync(3))
.AddTransientHttpErrorPolicy(
p => p.CircuitBreakerAsync(5, TimeSpan.FromSeconds(30)));
In the preceding example, two handlers are added. The first uses the AddTransientHttpErrorPolicy extension to add
a retry policy. Failed requests are retried up to three times. The second call to AddTransientHttpErrorPolicy adds a
circuit breaker policy. Further external requests are blocked for 30 seconds if five failed attempts occur
sequentially. Circuit breaker policies are stateful. All calls through this client share the same circuit state.
Add policies from the Polly registry
An approach to managing regularly used policies is to define them once and register them with a PolicyRegistry .
An extension method is provided which allows a handler to be added using a policy from the registry:
var registry = services.AddPolicyRegistry();
registry.Add("regular", timeout);
registry.Add("long", longTimeout);
services.AddHttpClient("regulartimeouthandler")
.AddPolicyHandlerFromRegistry("regular");
In the preceding code, two policies are registered when the PolicyRegistry is added to the ServiceCollection . To
use a policy from the registry, the AddPolicyHandlerFromRegistry method is used, passing the name of the policy to
apply.
Further information about IHttpClientFactory and Polly integrations can be found on the Polly wiki.
HttpClient and lifetime management

A new HttpClient instance is returned each time CreateClient is called on the IHttpClientFactory . There's an
HttpMessageHandler per named client. IHttpClientFactory pools the HttpMessageHandler instances created by
the factory to reduce resource consumption. An HttpMessageHandler instance may be reused from the pool when
creating a new HttpClient instance if its lifetime hasn't expired.
Pooling of handlers is desirable as each handler typically manages its own underlying HTTP connections. Creating
more handlers than necessary can result in connection delays. Some handlers also keep connections open
indefinitely, which can prevent the handler from reacting to DNS changes.
The default handler lifetime is two minutes. The default value can be overridden on a per named client basis. To
override it, call SetHandlerLifetime on the IHttpClientBuilder that is returned when creating the client:
services.AddHttpClient("extendedhandlerlifetime")
.SetHandlerLifetime(TimeSpan.FromMinutes(5));
Disposal of the client isn't required. Disposal cancels outgoing requests and guarantees the given HttpClient
instance can't be used after calling Dispose. IHttpClientFactory tracks and disposes resources used by
HttpClient instances. The HttpClient instances can generally be treated as .NET objects not requiring disposal.
Keeping a single HttpClient instance alive for a long duration is a common pattern used before the inception of
IHttpClientFactory . This pattern becomes unnecessary after migrating to IHttpClientFactory .
Logging
Clients created via IHttpClientFactory record log messages for all requests. Enable the appropriate information
level in your logging configuration to see the default log messages. Additional logging, such as the logging of
request headers, is only included at trace level.
The log category used for each client includes the name of the client. A client named MyNamedClient, for example,
logs messages with a category of System.Net.Http.HttpClient.MyNamedClient.LogicalHandler . Messages suffixed
with LogicalHandler occur outside the request handler pipeline. On the request, messages are logged before any
other handlers in the pipeline have processed it. On the response, messages are logged after any other pipeline
handlers have received the response.
Logging also occurs inside the request handler pipeline. In the MyNamedClient example, those messages are
logged against the log category System.Net.Http.HttpClient.MyNamedClient.ClientHandler . For the request, this
occurs after all other handlers have run and immediately before the request is sent out on the network. On the
response, this logging includes the state of the response before it passes back through the handler pipeline.
Enabling logging outside and inside the pipeline enables inspection of the changes made by the other pipeline
handlers. This may include changes to request headers, for example, or to the response status code.
Including the name of the client in the log category enables log filtering for specific named clients where
necessary.
Configure the HttpMessageHandler

It may be necessary to control the configuration of the inner HttpMessageHandler used by a client.
An IHttpClientBuilder is returned when adding named or typed clients. The
ConfigurePrimaryHttpMessageHandler extension method can be used to define a delegate. The delegate is used
to create and configure the primary HttpMessageHandler used by that client:
services.AddHttpClient("configured-inner-handler")
.ConfigurePrimaryHttpMessageHandler(() =>
{
return new HttpClientHandler()
{
AllowAutoRedirect = false,
UseDefaultCredentials = true
};
});
By Steve Smith
Web server implementation details related to HTTP requests and responses are defined in interfaces. These
interfaces are used by server implementations and middleware to create and modify the application's hosting
pipeline.
Feature interfaces
ASP.NET Core defines a number of HTTP feature interfaces in Microsoft.AspNetCore.Http.Features which are
used by servers to identify the features they support. The following feature interfaces handle requests and return
responses:
IHttpRequestFeature Defines the structure of an HTTP request, including the protocol, path, query string, headers,
and body.
IHttpResponseFeature Defines the structure of an HTTP response, including the status code, headers, and body of
the response.
IHttpAuthenticationFeature Defines support for identifying users based on a ClaimsPrincipal and specifying an
authentication handler.
IHttpUpgradeFeature Defines support for HTTP Upgrades, which allow the client to specify which additional
protocols it would like to use if the server wishes to switch protocols.
IHttpBufferingFeature Defines methods for disabling buffering of requests and/or responses.
IHttpConnectionFeature Defines properties for local and remote addresses and ports.
IHttpRequestLifetimeFeature Defines support for aborting connections, or detecting if a request has been
terminated prematurely, such as by a client disconnect.
IHttpSendFileFeature Defines a method for sending files asynchronously.
IHttpWebSocketFeature Defines an API for supporting web sockets.
IHttpRequestIdentifierFeature Adds a property that can be implemented to uniquely identify requests.
ISessionFeature Defines ISessionFactory and ISession abstractions for supporting user sessions.
ITlsConnectionFeature Defines an API for retrieving client certificates.
ITlsTokenBindingFeature Defines methods for working with TLS token binding parameters.
NOTE
ISessionFeature isn't a server feature, but is implemented by the SessionMiddleware (see Managing Application State).
Feature collections
The Features property of HttpContext provides an interface for getting and setting the available HTTP features
for the current request. Since the feature collection is mutable even within the context of a request, middleware
can be used to modify the collection and add support for additional features.
Middleware and request features

While servers are responsible for creating the feature collection, middleware can both add to this collection and
consume features from the collection. For example, the StaticFileMiddleware accesses the IHttpSendFileFeature
feature. If the feature exists, it's used to send the requested static file from its physical path. Otherwise, a slower
alternative method is used to send the file. When available, the IHttpSendFileFeature allows the operating system
to open the file and perform a direct kernel mode copy to the network card.
Additionally, middleware can add to the feature collection established by the server. Existing features can even be
replaced by middleware, allowing the middleware to augment the functionality of the server. Features added to
the collection are available immediately to other middleware or the underlying application itself later in the
request pipeline.
By combining custom server implementations and specific middleware enhancements, the precise set of features
an application requires can be constructed. This allows missing features to be added without requiring a change in
server, and ensures only the minimal amount of features are exposed, thus limiting attack surface area and
improving performance.
Summary
Feature interfaces define specific HTTP features that a given request may support. Servers define collections of
features, and the initial set of features supported by that server, but middleware can be used to enhance these
features.
Servers
Middleware
Open Web Interface for .NET (OWIN )
Access HttpContext in ASP.NET Core
ASP.NET Core apps access the HttpContext through the IHttpContextAccessor interface and its default
implementation HttpContextAccessor. It's only necessary to use IHttpContextAccessor when you need access to
the HttpContext inside a service.
Use HttpContext from Razor Pages

The Razor Pages PageModel exposes the HttpContext property:

{
public void OnGet()

{
Message = HttpContext.Request.PathBase;
}
}
Use HttpContext from a Razor view

Razor views expose the HttpContext directly via a RazorPage.Context property on the view. The following example
retrieves the current username in an Intranet app using Windows Authentication:
@{
var username = Context.User.Identity.Name;
}
Use HttpContext from a controller

Controllers expose the ControllerBase.HttpContext property:

{
{
var pathBase = HttpContext.Request.PathBase;
// Do something with the PathBase.
return View();
}
}
Use HttpContext from middleware

When working with custom middleware components, HttpContext is passed into the Invoke or InvokeAsync
method and can be accessed when the middleware is configured:
public class MyCustomMiddleware
{
public Task InvokeAsync(HttpContext context)
{
// Middleware initialization optionally using HttpContext
}
}
Use HttpContext from custom components

For other framework and custom components that require access to HttpContext , the recommended approach is
to register a dependency using the built-in dependency injection container. The dependency injection container
supplies the IHttpContextAccessor to any classes that declare it as a dependency in their constructors.

{
services.AddMvc()
services.AddHttpContextAccessor();
services.AddTransient<IUserRepository, UserRepository>();
}

{
services.AddMvc();
services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();
services.AddTransient<IUserRepository, UserRepository>();
}
In the preceding example:

UserRepository declares its dependency on IHttpContextAccessor .
The dependency is supplied when dependency injection resolves the dependency chain and creates an instance
of UserRepository .
public class UserRepository : IUserRepository

{
private readonly IHttpContextAccessor _httpContextAccessor;
public UserRepository(IHttpContextAccessor httpContextAccessor)

{
_httpContextAccessor = httpContextAccessor;
}
public void LogCurrentUser()

{
var username = _httpContextAccessor.HttpContext.User.Identity.Name;
service.LogAccessRequest(username);
}
}
Primitives in ASP.NET Core
ASP.NET Core primitives are low -level building blocks shared by framework extensions. You can use these
building blocks in your own code.
Detect changes with Change Tokens
Detect changes with change tokens in ASP.NET Core
By Luke Latham
A change token is a general-purpose, low -level building block used to track changes.
IChangeToken interface
IChangeToken propagates notifications that a change has occurred. IChangeToken resides in the
Microsoft.Extensions.Primitives namespace. For apps that don't use the Microsoft.AspNetCore.App metapackage
(ASP.NET Core 2.1 or later), reference the Microsoft.Extensions.Primitives NuGet package in the project file.
IChangeToken has two properties:
ActiveChangedCallbacks indicate if the token proactively raises callbacks. If ActiveChangedCallbacks is set to
false , a callback is never called, and the app must poll HasChanged for changes. It's also possible for a token
to never be cancelled if no changes occur or the underlying change listener is disposed or disabled.
HasChanged gets a value that indicates if a change has occurred.
The interface has one method, RegisterChangeCallback(Action<Object>, Object), which registers a callback that's
invoked when the token has changed. HasChanged must be set before the callback is invoked.
ChangeToken class
ChangeToken is a static class used to propagate notifications that a change has occurred. ChangeToken resides in
the Microsoft.Extensions.Primitives namespace. For apps that don't use the Microsoft.AspNetCore.App
metapackage, reference the Microsoft.Extensions.Primitives NuGet package in the project file.
The ChangeToken OnChange(Func<IChangeToken>, Action) method registers an Action to call whenever the
token changes:
Func<IChangeToken> produces the token.
Action is called when the token changes.
ChangeToken has an OnChange<TState>(Func<IChangeToken>, Action<TState>, TState) overload that takes an
additional TState parameter that's passed into the token consumer Action .
OnChange returns an IDisposable. Calling Dispose stops the token from listening for further changes and releases
the token's resources.
Example uses of change tokens in ASP.NET Core

Change tokens are used in prominent areas of ASP.NET Core monitoring changes to objects:
For monitoring changes to files, IFileProvider's Watch method creates an IChangeToken for the specified files
or folder to watch.
IChangeToken tokens can be added to cache entries to trigger cache evictions on change.
For TOptions changes, the default OptionsMonitor implementation of IOptionsMonitor has an overload that
accepts one or more IOptionsChangeTokenSource instances. Each instance returns an IChangeToken to register
a change notification callback for tracking options changes.
Monitoring for configuration changes

By default, ASP.NET Core templates use JSON configuration files (appsettings.json,
appsettings.Development.json, and appsettings.Production.json) to load app configuration settings.
These files are configured using the AddJsonFile(IConfigurationBuilder, String, Boolean, Boolean) extension
method on ConfigurationBuilder that accepts a reloadOnChange parameter (ASP.NET Core 1.1 and later).
reloadOnChange indicates if configuration should be reloaded on file changes. See this setting in the WebHost
convenience method CreateDefaultBuilder:

.AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, reloadOnChange: true);
File-based configuration is represented by FileConfigurationSource. FileConfigurationSource uses IFileProvider

to monitor files.
By default, the IFileMonitor is provided by a PhysicalFileProvider, which uses FileSystemWatcher to monitor for
configuration file changes.
The sample app demonstrates two implementations for monitoring configuration changes. If either the
appsettings.json file changes or the Environment version of the file changes, each implementation executes custom
code. The sample app writes a message to the console.
A configuration file's FileSystemWatcher can trigger multiple token callbacks for a single configuration file change.
The sample's implementation guards against this problem by checking file hashes on the configuration files.
Checking file hashes ensures that at least one of the configuration files has changed before running the custom
code. The sample uses SHA1 file hashing (Utilities/Utilities.cs):
public static byte[] ComputeHash(string filePath)
{
var runCount = 1;
while(runCount < 4)
{
try
{
if (File.Exists(filePath))
{
using (var fs = File.OpenRead(filePath))
{
return System.Security.Cryptography.SHA1.Create().ComputeHash(fs);
}
}
else
{
throw new FileNotFoundException();
}
}
catch (IOException ex)
{
if (runCount == 3 || ex.HResult != -2147024864)
{
throw;
}
else
{
Thread.Sleep(TimeSpan.FromSeconds(Math.Pow(2, runCount)));
runCount++;
}
}
}
return new byte[20];

}
A retry is implemented with an exponential back-off. The re-try is present because file locking may occur that
temporarily prevents computing a new hash on one of the files.
Simple startup change token
Register a token consumer Action callback for change notifications to the configuration reload token (Startup.cs):
ChangeToken.OnChange(
() => config.GetReloadToken(),
(state) => InvokeChanged(state),
env);
config.GetReloadToken() provides the token. The callback is the InvokeChanged method:

private void InvokeChanged(IHostingEnvironment env)
{
byte[] appsettingsHash = ComputeHash("appSettings.json");
byte[] appsettingsEnvHash =
ComputeHash($"appSettings.{env.EnvironmentName}.json");
if (!_appsettingsHash.SequenceEqual(appsettingsHash) ||
!_appsettingsEnvHash.SequenceEqual(appsettingsEnvHash))
{
_appsettingsHash = appsettingsHash;
_appsettingsEnvHash = appsettingsEnvHash;
WriteConsole("Configuration changed (Simple Startup Change Token)");

}
}
The state of the callback is used to pass in the IHostingEnvironment . This is useful to determine the correct
appsettings configuration JSON file to monitor, appsettings.<Environment>.json. File hashes are used to prevent
the WriteConsole statement from running multiple times due to multiple token callbacks when the configuration
file has only changed once.
This system runs as long as the app is running and can't be disabled by the user.
Monitoring configuration changes as a service
The sample implements:
Basic startup token monitoring.
Monitoring as a service.
A mechanism to enable and disable monitoring.
The sample establishes an IConfigurationMonitor interface (Extensions/ConfigurationMonitor.cs):
public interface IConfigurationMonitor

{
bool MonitoringEnabled { get; set; }
string CurrentState { get; set; }
}
The constructor of the implemented class, ConfigurationMonitor , registers a callback for change notifications:
public ConfigurationMonitor(IConfiguration config, IHostingEnvironment env)

{
_env = env;
ChangeToken.OnChange<IConfigurationMonitor>(
() => config.GetReloadToken(),
InvokeChanged,
this);
}
public bool MonitoringEnabled { get; set; } = false;

public string CurrentState { get; set; } = "Not monitoring";
config.GetReloadToken() supplies the token. InvokeChanged is the callback method. The state in this instance is a
reference to the IConfigurationMonitor instance that is used to access the monitoring state. Two properties are
used:
MonitoringEnabled indicates if the callback should run its custom code.
CurrentState describes the current monitoring state for use in the UI.
The InvokeChanged method is similar to the earlier approach, except that it:
Doesn't run its code unless MonitoringEnabled is true .
Notes the current state in its WriteConsole output.
private void InvokeChanged(IConfigurationMonitor state)

{
if (MonitoringEnabled)
{
byte[] appsettingsHash = ComputeHash("appSettings.json");
byte[] appsettingsEnvHash =
ComputeHash($"appSettings.{_env.EnvironmentName}.json");
if (!_appsettingsHash.SequenceEqual(appsettingsHash) ||
!_appsettingsEnvHash.SequenceEqual(appsettingsEnvHash))
{
string message = $"State updated at {DateTime.Now}";
_appsettingsHash = appsettingsHash;
_appsettingsEnvHash = appsettingsEnvHash;
WriteConsole($"Configuration changed (ConfigurationMonitor Class) {message}, state:

{state.CurrentState}");
}
}
}
An instance ConfigurationMonitor is registered as a service in ConfigureServices of Startup.cs:
services.AddSingleton<IConfigurationMonitor, ConfigurationMonitor>();
The Index page offers the user control over configuration monitoring. The instance of IConfigurationMonitor is
injected into the IndexModel :
public IndexModel(
IConfiguration config,
IConfigurationMonitor monitor,
FileService fileService)
{
_config = config;
_monitor = monitor;
_fileService = fileService;
}
A button enables and disables monitoring:
<button class="btn btn-danger" asp-page-handler="StopMonitoring">Stop Monitoring</button>

public IActionResult OnPostStartMonitoring()
{
_monitor.MonitoringEnabled = true;
_monitor.CurrentState = "Monitoring!";
}
public IActionResult OnPostStopMonitoring()

{
_monitor.MonitoringEnabled = false;
_monitor.CurrentState = "Not monitoring";
}
When OnPostStartMonitoring is triggered, monitoring is enabled, and the current state is cleared. When
OnPostStopMonitoring is triggered, monitoring is disabled, and the state is set to reflect that monitoring isn't
occurring.
Monitoring cached file changes

File content can be cached in-memory using IMemoryCache. In-memory caching is described in the Cache in-
memory topic. Without taking additional steps, such as the implementation described below, stale (outdated) data
is returned from a cache if the source data changes.
Not taking into account the status of a cached source file when renewing a sliding expiration period leads to stale
cache data. Each request for the data renews the sliding expiration period, but the file is never reloaded into the
cache. Any app features that use the file's cached content are subject to possibly receiving stale content.
Using change tokens in a file caching scenario prevents stale file content in the cache. The sample app
demonstrates an implementation of the approach.
The sample uses GetFileContent to:
Return file content.
Implement a retry algorithm with exponential back-off to cover cases where a file lock is temporarily
preventing a file from being read.
Utilities/Utilities.cs:
public async static Task<string> GetFileContent(string filePath)
{
var runCount = 1;
while(runCount < 4)
{
try
{
if (File.Exists(filePath))
{
using (var fileStreamReader = File.OpenText(filePath))
{
return await fileStreamReader.ReadToEndAsync();
}
}
else
{
throw new FileNotFoundException();
}
}
catch (IOException ex)
{
if (runCount == 3 || ex.HResult != -2147024864)
{
throw;
}
else
{
await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, runCount)));
runCount++;
}
}
}
return null;
}
A FileService is created to handle cached file lookups. The GetFileContent method call of the service attempts to
obtain file content from the in-memory cache and return it to the caller (Services/FileService.cs).
If cached content isn't found using the cache key, the following actions are taken:
1. The file content is obtained using GetFileContent .
2. A change token is obtained from the file provider with IFileProviders.Watch. The token's callback is triggered
when the file is modified.
3. The file content is cached with a sliding expiration period. The change token is attached with
MemoryCacheEntryExtensions.AddExpirationToken to evict the cache entry if the file changes while it's cached.
public class FileService
{
private readonly IMemoryCache _cache;
private List<string> _tokens = new List<string>();
public FileService(IMemoryCache cache, IHostingEnvironment env)

{
_cache = cache;
_fileProvider = env.ContentRootFileProvider;
}
public async Task<string> GetFileContents(string fileName)

{
// For the purposes of this example, files are stored
// in the content root of the app. To obtain the physical
// path to a file at the content root, use the
// ContentRootFileProvider on IHostingEnvironment.
var filePath = _fileProvider.GetFileInfo(fileName).PhysicalPath;
string fileContent;
// Try to obtain the file contents from the cache.

if (_cache.TryGetValue(filePath, out fileContent))
{
return fileContent;
}
// The cache doesn't have the entry, so obtain the file

// contents from the file itself.
fileContent = await GetFileContent(filePath);
if (fileContent != null)
{
// Obtain a change token from the file provider whose
// callback is triggered when the file is modified.
var changeToken = _fileProvider.Watch(fileName);
// Configure the cache entry options for a five minute

// sliding expiration and use the change token to
// expire the file in the cache if the file is
// modified.
var cacheEntryOptions = new MemoryCacheEntryOptions()
.SetSlidingExpiration(TimeSpan.FromMinutes(5))
.AddExpirationToken(changeToken);
// Put the file contents into the cache.

_cache.Set(filePath, fileContent, cacheEntryOptions);
return fileContent;
}
return string.Empty;
}
}
The FileService is registered in the service container along with the memory caching service ( Startup.cs):
services.AddMemoryCache();
services.AddSingleton<FileService>();
The page model loads the file's content using the service (Pages/Index.cshtml.cs):
var fileContent = await _fileService.GetFileContents("poem.txt");

CompositeChangeToken class
For representing one or more IChangeToken instances in a single object, use the CompositeChangeToken class.
var firstCancellationTokenSource = new CancellationTokenSource();

var secondCancellationTokenSource = new CancellationTokenSource();
var firstCancellationToken = firstCancellationTokenSource.Token;

var secondCancellationToken = secondCancellationTokenSource.Token;
var firstCancellationChangeToken = new CancellationChangeToken(firstCancellationToken);

var secondCancellationChangeToken = new CancellationChangeToken(secondCancellationToken);
var compositeChangeToken =
new CompositeChangeToken(
new List<IChangeToken>
{
firstCancellationChangeToken,
secondCancellationChangeToken
});
HasChanged on the composite token reports true if any represented token HasChanged is true .
ActiveChangeCallbacks on the composite token reports true if any represented token ActiveChangeCallbacks is
true . If multiple concurrent change events occur, the composite change callback is invoked exactly one time.
Cache in-memory
Response caching
Cache Tag Helper
Open Web Interface for .NET (OWIN) with ASP.NET
Core
By Steve Smith and Rick Anderson

ASP.NET Core supports the Open Web Interface for .NET (OWIN ). OWIN allows web apps to be decoupled from
web servers. It defines a standard way for middleware to be used in a pipeline to handle requests and associated
responses. ASP.NET Core applications and middleware can interoperate with OWIN -based applications, servers,
and middleware.
OWIN provides a decoupling layer that allows two frameworks with disparate object models to be used together.
The Microsoft.AspNetCore.Owin package provides two adapter implementations:
ASP.NET Core to OWIN
OWIN to ASP.NET Core
This allows ASP.NET Core to be hosted on top of an OWIN compatible server/host or for other OWIN
compatible components to be run on top of ASP.NET Core.
NOTE
Using these adapters comes with a performance cost. Apps using only ASP.NET Core components shouldn't use the
Microsoft.AspNetCore.Owin package or adapters.
Running OWIN middleware in the ASP.NET Core pipeline

ASP.NET Core's OWIN support is deployed as part of the Microsoft.AspNetCore.Owin package. You can import
OWIN support into your project by installing this package.
OWIN middleware conforms to the OWIN specification, which requires a
Func<IDictionary<string, object>, Task> interface, and specific keys be set (such as owin.ResponseBody ). The
following simple OWIN middleware displays "Hello World":
public Task OwinHello(IDictionary<string, object> environment)

{
string responseText = "Hello World via OWIN";
byte[] responseBytes = Encoding.UTF8.GetBytes(responseText);
// OWIN Environment Keys: http://owin.org/spec/spec/owin-1.0.0.html

var responseStream = (Stream)environment["owin.ResponseBody"];
var responseHeaders = (IDictionary<string, string[]>)environment["owin.ResponseHeaders"];
responseHeaders["Content-Length"] = new string[] {

responseBytes.Length.ToString(CultureInfo.InvariantCulture) };
responseHeaders["Content-Type"] = new string[] { "text/plain" };
return responseStream.WriteAsync(responseBytes, 0, responseBytes.Length);

}
The sample signature returns a Task and accepts an IDictionary<string, object> as required by OWIN.
The following code shows how to add the OwinHello middleware (shown above) to the ASP.NET Core pipeline
with the UseOwin extension method.

{
app.UseOwin(pipeline =>
{
pipeline(next => OwinHello);
});
}
You can configure other actions to take place within the OWIN pipeline.
NOTE
Response headers should only be modified prior to the first write to the response stream.
NOTE
Multiple calls to UseOwin is discouraged for performance reasons. OWIN components will operate best if grouped
together.
app.UseOwin(pipeline =>
{
pipeline(async (next) =>
{
// do something before
await OwinHello(new OwinEnvironment(HttpContext));
// do something after
});
});
Using ASP.NET Core Hosting on an OWIN-based server

OWIN -based servers can host ASP.NET Core apps. One such server is Nowin, a .NET OWIN web server. In the
sample for this article, I've included a project that references Nowin and uses it to create an IServer capable of
self-hosting ASP.NET Core.
using System;
using System.IO;
using System.Linq;
namespace NowinSample
{
{
{
.UseNowin()
.Build();
host.Run();
}
}
}
IServer is an interface that requires a Features property and a Start method.

Start is responsible for configuring and starting the server, which in this case is done through a series of fluent
API calls that set addresses parsed from the IServerAddressesFeature. Note that the fluent configuration of the
_builder variable specifies that requests will be handled by the appFunc defined earlier in the method. This
Func is called on each request to process incoming requests.
We'll also add an IWebHostBuilder extension to make it easy to add and configure the Nowin server.
using System;
using Microsoft.AspNetCore.Hosting.Server;
using Nowin;
using NowinSample;
namespace Microsoft.AspNetCore.Hosting
{
public static class NowinWebHostBuilderExtensions
{
public static IWebHostBuilder UseNowin(this IWebHostBuilder builder)
{
return builder.ConfigureServices(services =>
{
services.AddSingleton<IServer, NowinServer>();
});
}
public static IWebHostBuilder UseNowin(this IWebHostBuilder builder, Action<ServerBuilder> configure)

{
builder.ConfigureServices(services =>
{
services.Configure(configure);
});
return builder.UseNowin();
}
}
}
With this in place, invoke the extension in Program.cs to run an ASP.NET Core app using this custom server:
using System;
using System.IO;
using System.Linq;
namespace NowinSample
{
{
{
.UseNowin()
.Build();
host.Run();
}
}
}
Learn more about ASP.NET Servers.
Run ASP.NET Core on an OWIN-based server and use its WebSockets

support
Another example of how OWIN -based servers' features can be leveraged by ASP.NET Core is access to features
like WebSockets. The .NET OWIN web server used in the previous example has support for Web Sockets built in,
which can be leveraged by an ASP.NET Core application. The example below shows a simple web app that
supports Web Sockets and echoes back everything sent to the server through WebSockets.
{
{
{
if (context.WebSockets.IsWebSocketRequest)
{
WebSocket webSocket = await context.WebSockets.AcceptWebSocketAsync();
await EchoWebSocket(webSocket);
}
else
{
await next();
}
});
app.Run(context =>
{
return context.Response.WriteAsync("Hello World");
});
}
private async Task EchoWebSocket(WebSocket webSocket)

{
byte[] buffer = new byte[1024];
WebSocketReceiveResult received = await webSocket.ReceiveAsync(
new ArraySegment<byte>(buffer), CancellationToken.None);
while (!webSocket.CloseStatus.HasValue)
{
// Echo anything we receive
await webSocket.SendAsync(new ArraySegment<byte>(buffer, 0, received.Count),
received.MessageType, received.EndOfMessage, CancellationToken.None);
received = await webSocket.ReceiveAsync(new ArraySegment<byte>(buffer),

CancellationToken.None);
}
await webSocket.CloseAsync(webSocket.CloseStatus.Value,
webSocket.CloseStatusDescription, CancellationToken.None);
}
}
This sample is configured using the same NowinServer as the previous one - the only difference is in how the
application is configured in its Configure method. A test using a simple websocket client demonstrates the
application:
OWIN environment
You can construct an OWIN environment using the HttpContext .
var environment = new OwinEnvironment(HttpContext);

var features = new OwinFeatureCollection(environment);
OWIN keys
OWIN depends on an IDictionary<string,object> object to communicate information throughout an HTTP
Request/Response exchange. ASP.NET Core implements the keys listed below. See the primary specification,
extensions, and OWIN Key Guidelines and Common Keys.
Request data (OWIN v1.0.0)
KEY VALUE (TYPE) DESCRIPTION
owin.RequestScheme String
owin.RequestMethod String
owin.RequestPathBase String
owin.RequestPath String
owin.RequestQueryString String
owin.RequestProtocol String
owin.RequestHeaders IDictionary<string,string[]>
owin.RequestBody Stream
Request data (OWIN v1.1.0)

owin.RequestId String Optional
Response data (OWIN v1.0.0)

owin.ResponseStatusCode int Optional
owin.ResponseReasonPhrase String Optional
owin.ResponseHeaders IDictionary<string,string[]>
owin.ResponseBody Stream
Other data (OWIN v1.0.0)

owin.CallCancelled CancellationToken
owin.Version String
Common keys
ssl.ClientCertificate X509Certificate
ssl.LoadClientCertAsync Func<Task>
server.RemoteIpAddress String
server.RemotePort String
server.LocalIpAddress String
server.LocalPort String
server.IsLocal bool
server.OnSendingHeaders Action<Action<object>,object>
SendFiles v0.3.0
sendfile.SendAsync See delegate signature Per Request
Opaque v0.3.0
opaque.Version String
opaque.Upgrade OpaqueUpgrade See delegate signature
opaque.Stream Stream
opaque.CallCancelled CancellationToken
WebSocket v0.3.0
websocket.Version String
websocket.Accept WebSocketAccept See delegate signature
websocket.AcceptAlt Non-spec
websocket.SubProtocol String See RFC6455 Section 4.2.2 Step 5.5
websocket.SendAsync WebSocketSendAsync See delegate signature
websocket.ReceiveAsync WebSocketReceiveAsync See delegate signature
websocket.CloseAsync WebSocketCloseAsync See delegate signature
websocket.CallCancelled CancellationToken
websocket.ClientCloseStatus int Optional
websocket.ClientCloseDescription String Optional
Middleware
Servers
WebSockets support in ASP.NET Core
By Tom Dykstra and Andrew Stanton-Nurse

This article explains how to get started with WebSockets in ASP.NET Core. WebSocket (RFC 6455) is a protocol
that enables two-way persistent communication channels over TCP connections. It's used in apps that benefit
from fast, real-time communication, such as chat, dashboard, and game apps.
View or download sample code (how to download). See the Next steps section for more information.
Prerequisites
ASP.NET Core 1.1 or later
Any OS that supports ASP.NET Core:
Windows 7 / Windows Server 2008 or later
Linux
macOS
If the app runs on Windows with IIS:
IIS 8 / IIS 8 Express
WebSockets must be enabled in IIS (See the IIS/IIS Express support section.)
If the app runs on HTTP.sys:
For supported browsers, see https://caniuse.com/#feat=websockets.
When to use WebSockets

Use WebSockets to work directly with a socket connection. For example, use WebSockets for the best possible
performance with a real-time game.
ASP.NET Core SignalR is a library that simplifies adding real-time web functionality to apps. It uses WebSockets
whenever possible.
How to use WebSockets

Install the Microsoft.AspNetCore.WebSockets package.
Configure the middleware.
Accept WebSocket requests.
Send and receive messages.
Configure the middleware
Add the WebSockets middleware in the Configure method of the Startup class:
app.UseWebSockets();
The following settings can be configured:

KeepAliveInterval - How frequently to send "ping" frames to the client to ensure proxies keep the connection
open.
ReceiveBufferSize- The size of the buffer used to receive data. Advanced users may need to change this for
performance tuning based on the size of the data.
var webSocketOptions = new WebSocketOptions()

{
KeepAliveInterval = TimeSpan.FromSeconds(120),
ReceiveBufferSize = 4 * 1024
};
app.UseWebSockets(webSocketOptions);
Accept WebSocket requests

Somewhere later in the request life cycle (later in the Configure method or in an MVC action, for example) check
if it's a WebSocket request and accept the WebSocket request.
The following example is from later in the Configure method:

{
if (context.Request.Path == "/ws")
{
if (context.WebSockets.IsWebSocketRequest)
{
WebSocket webSocket = await context.WebSockets.AcceptWebSocketAsync();
await Echo(context, webSocket);
}
else
{
context.Response.StatusCode = 400;
}
}
else
{
await next();
}
});
A WebSocket request could come in on any URL, but this sample code only accepts requests for /ws .
Send and receive messages
The AcceptWebSocketAsync method upgrades the TCP connection to a WebSocket connection and provides a
WebSocket object. Use the WebSocket object to send and receive messages.
The code shown earlier that accepts the WebSocket request passes the WebSocket object to an Echo method. The
code receives a message and immediately sends back the same message. Messages are sent and received in a
loop until the client closes the connection:
private async Task Echo(HttpContext context, WebSocket webSocket)
{
var buffer = new byte[1024 * 4];
WebSocketReceiveResult result = await webSocket.ReceiveAsync(new ArraySegment<byte>(buffer),
while (!result.CloseStatus.HasValue)
{
await webSocket.SendAsync(new ArraySegment<byte>(buffer, 0, result.Count), result.MessageType,
result.EndOfMessage, CancellationToken.None);
result = await webSocket.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);

}
await webSocket.CloseAsync(result.CloseStatus.Value, result.CloseStatusDescription,
}
When accepting the WebSocket connection before beginning the loop, the middleware pipeline ends. Upon
closing the socket, the pipeline unwinds. That is, the request stops moving forward in the pipeline when the
WebSocket is accepted. When the loop is finished and the socket is closed, the request proceeds back up the
pipeline.
IIS/IIS Express support

Windows Server 2012 or later and Windows 8 or later with IIS/IIS Express 8 or later has support for the
WebSocket protocol.
To enable support for the WebSocket protocol on Windows Server 2012 or later:
1. Use the Add Roles and Features wizard from the Manage menu or the link in Server Manager.
2. Select Role-based or Feature-based Installation. Select Next.
3. Select the appropriate server (the local server is selected by default). Select Next.
4. Expand Web Server (IIS ) in the Roles tree, expand Web Server, and then expand Application
Development.
5. Select WebSocket Protocol. Select Next.
6. If additional features aren't needed, select Next.
7. Select Install.
8. When the installation completes, select Close to exit the wizard.
To enable support for the WebSocket protocol on Windows 8 or later:
1. Navigate to Control Panel > Programs > Programs and Features > Turn Windows features on or off
(left side of the screen).
2. Open the following nodes: Internet Information Services > World Wide Web Services > Application
Development Features.
3. Select the WebSocket Protocol feature. Select OK.
Disable WebSocket when using socket.io on node.js
If using the WebSocket support in socket.io on Node.js, disable the default IIS WebSocket module using the
webSocket element in web.config or applicationHost.config. If this step isn't performed, the IIS WebSocket
module attempts to handle the WebSocket communication rather than Node.js and the app.
<system.webServer>
<webSocket enabled="false" />
</system.webServer>
Next steps
The sample app that accompanies this article is an echo app. It has a web page that makes WebSocket
connections, and the server resends any messages it receives back to the client. Run the app from a command
prompt (it's not set up to run from Visual Studio with IIS Express) and navigate to http://localhost:5000. The web
page shows the connection status in the upper left:
Select Connect to send a WebSocket request to the URL shown. Enter a test message and select Send. When
done, select Close Socket. The Communication Log section reports each open, send, and close action as it
happens.
Microsoft.AspNetCore.App metapackage for
ASP.NET Core 2.1
This feature requires ASP.NET Core 2.1 and later targeting .NET Core 2.1 and later.
The Microsoft.AspNetCore.App metapackage for ASP.NET Core:
Does not include third-party dependencies except for Json.NET, Remotion.Linq, and IX-Async. These
3rd-party dependencies are deemed necessary to ensure the major frameworks features function.
Includes all supported packages by the ASP.NET Core team except those that contain third-party
dependencies (other than those previously mentioned).
Includes all supported packages by the Entity Framework Core team except those that contain third-
party dependencies (other than those previously mentioned).
All the features of ASP.NET Core 2.1 and later and Entity Framework Core 2.1 and later are included in the
Microsoft.AspNetCore.App package. The default project templates targeting ASP.NET Core 2.1 and later
use this package. We recommend applications targeting ASP.NET Core 2.1 and later and Entity Framework
Core 2.1 and later use the Microsoft.AspNetCore.App package.
The version number of the Microsoft.AspNetCore.App metapackage represents the ASP.NET Core version
and Entity Framework Core version.
Using the Microsoft.AspNetCore.App metapackage provides version restrictions that protect your app:
If a package is included that has a transitive (not direct) dependency on a package in
Microsoft.AspNetCore.App , and those version numbers differ, NuGet will generate an error.
Other packages added to your app cannot change the version of packages included in
Microsoft.AspNetCore.App .
Version consistency ensures a reliable experience. Microsoft.AspNetCore.App was designed to prevent
untested version combinations of related bits being used together in the same app.
Applications that use the Microsoft.AspNetCore.App metapackage automatically take advantage of the
ASP.NET Core shared framework. When you use the Microsoft.AspNetCore.App metapackage, no assets
from the referenced ASP.NET Core NuGet packages are deployed with the application—the ASP.NET
Core shared framework contains these assets. The assets in the shared framework are precompiled to
improve application startup time. For more information, see "shared framework" in .NET Core distribution
packaging.
The following project file references the Microsoft.AspNetCore.App metapackage for ASP.NET Core and
represents a typical ASP.NET Core 2.1 template:
<PropertyGroup>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
</Project>
The preceding markup represents a typical ASP.NET Core 2.1 and later template. It doesn't specify a
version number for the Microsoft.AspNetCore.App package reference. When the version is not specified, an
implicit version is specified by the SDK, that is, Microsoft.NET.Sdk.Web . We recommend relying on the
implicit version specified by the SDK and not explicitly setting the version number on the package
reference. If you have questions on this approach, leave a GitHub comment at the Discussion for the
Microsoft.AspNetCore.App implicit version.
The implicit version is set to major.minor.0 for portable apps. The shared framework roll-forward
mechanism will run the app on the latest compatible version among the installed shared frameworks. To
guarantee the same version is used in development, test, and production, ensure the same version of the
shared framework is installed in all environments. For self contained apps, the implicit version number is
set to the major.minor.patch of the shared framework bundled in the installed SDK.
Specifying a version number on the Microsoft.AspNetCore.App reference does not guarantee that version
of the shared framework will be chosen. For example, suppose version "2.1.1" is specified, but "2.1.3" is
installed. In that case, the app will use "2.1.3". Although not recommended, you can disable roll forward
(patch and/or minor). For more information regarding dotnet host roll-forward and how to configure its
behavior, see dotnet host roll forward.
<Project Sdk must be set to Microsoft.NET.Sdk.Web to use the implicit version Microsoft.AspNetCore.App .
When <Project Sdk="Microsoft.NET.Sdk"> (without the trailing .Web ) is used:
The following warning is generated:
Warning NU1604: Project dependency Microsoft.AspNetCore.App does not contain an inclusive
lower bound. Include a lower bound in the dependency version to ensure consistent restore results.
This is a known issue with the .NET Core 2.1 SDK and will be fixed in the .NET Core 2.2 SDK.
Update ASP.NET Core

The Microsoft.AspNetCore.App metapackage isn't a traditional package that's updated from NuGet. Similar
to Microsoft.NETCore.App , Microsoft.AspNetCore.App represents a shared runtime, which has special
versioning semantics handled outside of NuGet. For more information, see Packages, metapackages and
frameworks.
To update ASP.NET Core:
On development machines and build servers: Download and install the .NET Core SDK.
On deployment servers: Download and install the .NET Core runtime.
Applications will roll forward to the latest installed version on application restart. It's not necessary to
update the Microsoft.AspNetCore.App version number in the project file. For more information, see
Framework-dependent apps roll forward.
If your application previously used Microsoft.AspNetCore.All , see Migrating from
Microsoft.AspNetCore.All to Microsoft.AspNetCore.App.
Microsoft.AspNetCore.All metapackage for
ASP.NET Core 2.0
NOTE
We recommend applications targeting ASP.NET Core 2.1 and later use the Microsoft.AspNetCore.App rather than this
package. See Migrating from Microsoft.AspNetCore.All to Microsoft.AspNetCore.App in this article.
This feature requires ASP.NET Core 2.x targeting .NET Core 2.x.
The Microsoft.AspNetCore.All metapackage for ASP.NET Core includes:
All supported packages by the ASP.NET Core team.
All supported packages by the Entity Framework Core.
Internal and 3rd-party dependencies used by ASP.NET Core and Entity Framework Core.
All the features of ASP.NET Core 2.x and Entity Framework Core 2.x are included in the
Microsoft.AspNetCore.All package. The default project templates targeting ASP.NET Core 2.0 use this
package.
The version number of the Microsoft.AspNetCore.All metapackage represents the ASP.NET Core version and
Entity Framework Core version.
Applications that use the Microsoft.AspNetCore.All metapackage automatically take advantage of the .NET
Core Runtime Store. The Runtime Store contains all the runtime assets needed to run ASP.NET Core 2.x
applications. When you use the Microsoft.AspNetCore.All metapackage, no assets from the referenced
ASP.NET Core NuGet packages are deployed with the application — the .NET Core Runtime Store contains
these assets. The assets in the Runtime Store are precompiled to improve application startup time.
You can use the package trimming process to remove packages that you don't use. Trimmed packages are
excluded in published application output.
The following .csproj file references the Microsoft.AspNetCore.All metapackage for ASP.NET Core:
<PropertyGroup>
</PropertyGroup>
<ItemGroup>
</ItemGroup>
</Project>
Migrating from Microsoft.AspNetCore.All to

The following packages are included in Microsoft.AspNetCore.All but not the Microsoft.AspNetCore.App
package.
Microsoft.AspNetCore.ApplicationInsights.HostingStartup
Microsoft.AspNetCore.AzureAppServices.HostingStartup
Microsoft.AspNetCore.AzureAppServicesIntegration
Microsoft.AspNetCore.DataProtection.AzureKeyVault
Microsoft.AspNetCore.DataProtection.AzureStorage
Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv
Microsoft.AspNetCore.SignalR.Redis
Microsoft.Data.Sqlite
Microsoft.Data.Sqlite.Core
Microsoft.EntityFrameworkCore.Sqlite
Microsoft.EntityFrameworkCore.Sqlite.Core
Microsoft.Extensions.Caching.Redis
Microsoft.Extensions.Configuration.AzureKeyVault
Microsoft.Extensions.Logging.AzureAppServices
Microsoft.VisualStudio.Web.BrowserLink
To move from Microsoft.AspNetCore.All to Microsoft.AspNetCore.App , if your app uses any APIs from the
above packages, or packages brought in by those packages, add references to those packages in your project.
Any dependencies of the preceding packages that otherwise aren't dependencies of Microsoft.AspNetCore.App
are not included implicitly. For example:
StackExchange.Redis as a dependency of Microsoft.Extensions.Caching.Redis
Microsoft.ApplicationInsights as a dependency of
Microsoft.AspNetCore.ApplicationInsights.HostingStartup
Choose between ASP.NET and ASP.NET Core
No matter the web app you're creating, ASP.NET has a solution for you: from enterprise web apps targeting
Windows Server, to small microservices targeting Linux containers, and everything in between.
ASP.NET Core
ASP.NET Core is an open-source, cross-platform framework for building modern, cloud-based web apps on
Windows, macOS, or Linux.
ASP.NET
ASP.NET is a mature framework that provides all the services needed to build enterprise-grade, server-based web
apps on Windows.
Framework selection
Review the table below to determine which framework is most appropriate for your needs.
ASP.NET CORE ASP.NET
Build for Windows, macOS, or Linux Build for Windows
Razor Pages is the recommended approach to create a Web Use Web Forms, SignalR, MVC, Web API, WebHooks, or Web
UI as of ASP.NET Core 2.x. See also MVC, Web API, and Pages
SignalR.
Multiple versions per machine One version per machine
Develop with Visual Studio, Visual Studio for Mac, or Visual Develop with Visual Studio using C#, VB, or F#
Studio Code using C# or F#
Higher performance than ASP.NET Good performance
Choose .NET Framework or .NET Core runtime Use .NET Framework runtime
ASP.NET Core scenarios

Razor Pages is the recommended approach to create a Web UI as of ASP.NET Core 2.x.
Websites
APIs
Real-time
ASP.NET scenarios
Websites
APIs
Real-time
Resources
Introduction to ASP.NET
By Rick Anderson and Ryan Nowak

Razor Pages is a new aspect of ASP.NET Core MVC that makes coding page-focused scenarios easier and
more productive.
If you're looking for a tutorial that uses the Model-View -Controller approach, see Get started with ASP.NET
Core MVC.
This document provides an introduction to Razor Pages. It's not a step by step tutorial. If you find some of
the sections too advanced, see Get started with Razor Pages. For an overview of ASP.NET Core, see the
Introduction to ASP.NET Core.
Prerequisites
IDE/editor tooling
Creating a Razor Pages project

Visual Studio
Visual Studio Code
.NET Core CLI
See Get started with Razor Pages for detailed instructions on how to create a Razor Pages project using
Visual Studio.
Razor Pages
Razor Pages is enabled in Startup.cs:
{
{
// Includes support for Razor Pages and controllers.
services.AddMvc();
}

{
app.UseMvc();
}
}
Consider a basic page:
@page
<h1>Hello, world!</h1>
<h2>The time on the server is @DateTime.Now</h2>
The preceding code looks a lot like a Razor view file. What makes it different is the @page directive. @page
makes the file into an MVC action - which means that it handles requests directly, without going through a
controller. @page must be the first Razor directive on a page. @page affects the behavior of other Razor
constructs.
A similar page, using a PageModel class, is shown in the following two files. The Pages/Index2.cshtml file:
@page
@using RazorPagesIntro.Pages
@model IndexModel2
<h2>Separate page model</h2>

<p>
@Model.Message
</p>
The Pages/Index2.cshtml.cs page model:
using System;
namespace RazorPagesIntro.Pages
{
public class IndexModel2 : PageModel
{
public string Message { get; private set; } = "PageModel in C#";
public void OnGet()

{
Message += $" Server time is { DateTime.Now }";
}
}
}
By convention, the PageModel class file has the same name as the Razor Page file with .cs appended. For
example, the previous Razor Page is Pages/Index2.cshtml. The file containing the PageModel class is named
Pages/Index2.cshtml.cs.
The associations of URL paths to pages are determined by the page's location in the file system. The
following table shows a Razor Page path and the matching URL:
FILE NAME AND PATH MATCHING URL
/Pages/Index.cshtml / or /Index
/Pages/Contact.cshtml /Contact
/Pages/Store/Contact.cshtml /Store/Contact
/Pages/Store/Index.cshtml /Store or /Store/Index
Notes:
The runtime looks for Razor Pages files in the Pages folder by default.
Index is the default page when a URL doesn't include a page.
Writing a basic form

Razor Pages is designed to make common patterns used with web browsers easy to implement when
building an app. Model binding, Tag Helpers, and HTML helpers all just work with the properties defined in a
Razor Page class. Consider a page that implements a basic "contact us" form for the Contact model:
For the samples in this document, the DbContext is initialized in the Startup.cs file.
namespace RazorPagesContacts
{
{

{
options.UseInMemoryDatabase("name"));
services.AddMvc();
}

{
app.UseMvc();
}
}
}
The data model:

{
public class Customer
{
[Required, StringLength(100)]
}
}
The db context:
{
public class AppDbContext : DbContext
{
public AppDbContext(DbContextOptions options)
: base(options)
{
}
public DbSet<Customer> Customers { get; set; }

}
}
The Pages/Create.cshtml view file:
@page
<html>
<body>
<p>
Enter your name.
</p>
</form>
</body>
</html>
The Pages/Create.cshtml.cs page model:

{
{

{
_db = db;
}
[BindProperty]

{
{
return Page();
}
}
}
}
By convention, the PageModel class is called <PageName>Model and is in the same namespace as the page.
The PageModel class allows separation of the logic of a page from its presentation. It defines page handlers
for requests sent to the page and the data used to render the page. This separation allows you to manage
page dependencies through dependency injection and to unit test the pages.
The page has an OnPostAsync handler method, which runs on POST requests (when a user posts the form).
You can add handler methods for any HTTP verb. The most common handlers are:
OnGet to initialize state needed for the page. OnGet sample.
OnPost to handle form submissions.
The Asyncnaming suffix is optional but is often used by convention for asynchronous functions. The
OnPostAsync code in the preceding example looks similar to what you would normally write in a controller.
The preceding code is typical for Razor Pages. Most of the MVC primitives like model binding, validation, and
action results are shared.
The previous OnPostAsync method:
{
{
return Page();
}
}
The basic flow of OnPostAsync :

Check for validation errors.
If there are no errors, save the data and redirect.
If there are errors, show the page again with validation messages. Client-side validation is identical to
traditional ASP.NET Core MVC applications. In many cases, validation errors would be detected on the
client, and never submitted to the server.
When the data is entered successfully, the OnPostAsync handler method calls the RedirectToPage helper
method to return an instance of RedirectToPageResult . RedirectToPage is a new action result, similar to
RedirectToAction or RedirectToRoute , but customized for pages. In the preceding sample, it redirects to the
root Index page ( /Index ). RedirectToPage is detailed in the URL generation for Pages section.
When the submitted form has validation errors (that are passed to the server), the OnPostAsync handler
method calls the Page helper method. Page returns an instance of PageResult . Returning Page is similar to
how actions in controllers return View . PageResult is the default return type for a handler method. A
handler method that returns void renders the page.
The Customer property uses [BindProperty] attribute to opt in to model binding.

{

{
_db = db;
}
[BindProperty]

{
{
return Page();
}
}
}
Razor Pages, by default, bind properties only with non-GET verbs. Binding to properties can reduce the
amount of code you have to write. Binding reduces code by using the same property to render form fields (
<input asp-for="Customer.Name" /> ) and accept the input.
NOTE
For security reasons, you must opt in to binding GET request data to page model properties. Verify user input before
mapping it to properties. Opting in to this behavior is useful when addressing scenarios which rely on query string or
route values.
To bind a property on GET requests, set the [BindProperty] attribute's SupportsGet property to true :
[BindProperty(SupportsGet = true)]
The home page (Index.cshtml):
@page
@model RazorPagesContacts.Pages.IndexModel
<h1>Contacts</h1>
<thead>
<tr>
<th>ID</th>
<th>Name</th>
</tr>
</thead>
<tbody>
@foreach (var contact in Model.Customers)
{
<tr>
<td>@contact.Id</td>
<td>@contact.Name</td>
<td>
</td>
</tr>
}
</tbody>
</table>
<a asp-page="./Create">Create</a>
</form>
The associated PageModel class (Index.cshtml.cs):

{
{
public IndexModel(AppDbContext db)

{
_db = db;
}
public IList<Customer> Customers { get; private set; }

{
Customers = await _db.Customers.AsNoTracking().ToListAsync();
}

{
{
}
}
}
}
The Index.cshtml file contains the following markup to create an edit link for each contact:
The Anchor Tag Helper used the asp-route-{value} attribute to generate a link to the Edit page. The link
contains route data with the contact ID. For example, http://localhost:5000/Edit/1 .
The Pages/Edit.cshtml file:
@page "{id:int}"
@model RazorPagesContacts.Pages.EditModel
@{
ViewData["Title"] = "Edit Customer";
}
<h1>Edit Customer - @Model.Customer.Id</h1>

<input asp-for="Customer.Id" type="hidden" />
<div>
<label asp-for="Customer.Name"></label>
<div>
<input asp-for="Customer.Name" />
<span asp-validation-for="Customer.Name" ></span>
</div>
</div>
<div>
</div>
</form>
The first line contains the @page "{id:int}" directive. The routing constraint "{id:int}" tells the page to
accept requests to the page that contain int route data. If a request to the page doesn't contain route data
that can be converted to an int , the runtime returns an HTTP 404 (not found) error. To make the ID
@page "{id:int?}"
The Pages/Edit.cshtml.cs file:

using System;
{
{

{
_db = db;
}
[BindProperty]

{
Customer = await _db.Customers.FindAsync(id);
if (Customer == null)
{
}
return Page();
}

{
{
return Page();
}
_db.Attach(Customer).State = EntityState.Modified;
try
{
}
{
throw new Exception($"Customer {Customer.Id} not found!");
}
}
}
}
The Index.cshtml file also contains markup to create a delete button for each customer contact:

When the delete button is rendered in HTML, its formaction includes parameters for:
The customer contact ID specified by the asp-route-id attribute.
The handler specified by the asp-page-handler attribute.
Here is an example of a rendered delete button with a customer contact ID of 1 :
<button type="submit" formaction="/?id=1&handler=delete">delete</button>
When the button is selected, a form POST request is sent to the server. By convention, the name of the
handler method is selected based the value of the handler parameter according to the scheme
OnPost[handler]Async .
Because the handler is delete in this example, the OnPostDeleteAsync handler method is used to process
the POST request. If the asp-page-handler is set to a different value, such as remove , a page handler method
with the name OnPostRemoveAsync is selected.

{
{
}
}
The OnPostDeleteAsync method:

Accepts the id from the query string.
Queries the database for the customer contact with FindAsync .
If the customer contact is found, they're removed from the list of customer contacts. The database is
updated.
Calls RedirectToPage to redirect to the root Index page ( /Index ).
Mark page properties required

Properties on a PageModel can be decorated with the Required attribute:
{
{
{
return Page();
}
[BindProperty]
[Required(ErrorMessage = "Color is required")]
public string Color { get; set; }
public IActionResult OnPostAsync()

{
{
return Page();
}
// Process color.
}
}
}
See Model validation for more information.
Manage HEAD requests with the OnGet handler

Ordinarily, a HEAD handler is created and called for HEAD requests:
public void OnHead()

{
HttpContext.Response.Headers.Add("HandledBy", "Handled by OnHead!");
}
If no HEAD handler ( OnHead ) is defined, Razor Pages falls back to calling the GET page handler ( OnGet ) in
ASP.NET Core 2.1 or later. Opt in to this behavior with the SetCompatibilityVersion method in
Startup.Configure for ASP.NET Core 2.1 to 2.x:
services.AddMvc()
.SetCompatibilityVersion(Microsoft.AspNetCore.Mvc.CompatibilityVersion.Version_2_1);
SetCompatibilityVersion effectively sets the Razor Pages option AllowMappingHeadRequestsToGetHandler to

true .
Rather than opting into all 2.1 behaviors with SetCompatibilityVersion , you can explicitly opt-in to specific
behaviors. The following code opts into the mapping HEAD requests to the GET handler.
services.AddMvc()
{
options.AllowMappingHeadRequestsToGetHandler = true;
});
XSRF/CSRF and Razor Pages

You don't have to write any code for antiforgery validation. Antiforgery token generation and validation are
automatically included in Razor Pages.
Using Layouts, partials, templates, and Tag Helpers with Razor

Pages
Pages work with all the capabilities of the Razor view engine. Layouts, partials, templates, Tag Helpers,
_ViewStart.cshtml, _ViewImports.cshtml work in the same way they do for conventional Razor views.
Let's declutter this page by taking advantage of some of those capabilities.
Add a layout page to Pages/Shared/_Layout.cshtml:
Add a layout page to Pages/_Layout.cshtml:
<!DOCTYPE html>
<html>
<head>
<title>Razor Pages Sample</title>
</head>
<body>
<a asp-page="/Index">Home</a>
@RenderBody()
<a asp-page="/Customers/Create">Create</a> <br />
</body>
</html>
The Layout:
Controls the layout of each page (unless the page opts out of layout).
Imports HTML structures such as JavaScript and stylesheets.
See layout page for more information.
The Layout property is set in Pages/_ViewStart.cshtml:
@{
Layout = "_Layout";
}
The layout is in the Pages/Shared folder. Pages look for other views (layouts, templates, partials)
hierarchically, starting in the same folder as the current page. A layout in the Pages/Shared folder can be
used from any Razor page under the Pages folder.
The layout file should go in the Pages/Shared folder.
The layout is in the Pages folder. Pages look for other views (layouts, templates, partials) hierarchically,
starting in the same folder as the current page. A layout in the Pages folder can be used from any Razor page
under the Pages folder.
We recommend you not put the layout file in the Views/Shared folder. Views/Shared is an MVC views
pattern. Razor Pages are meant to rely on folder hierarchy, not path conventions.
View search from a Razor Page includes the Pages folder. The layouts, templates, and partials you're using
with MVC controllers and conventional Razor views just work.
Add a Pages/_ViewImports.cshtml file:
@namespace is explained later in the tutorial. The @addTagHelper directive brings in the built-in Tag Helpers to
all the pages in the Pages folder.
When the @namespace directive is used explicitly on a page:
@page
@namespace RazorPagesIntro.Pages.Customers
@model NameSpaceModel
<h2>Name space</h2>
<p>
@Model.Message
</p>
The directive sets the namespace for the page. The @model directive doesn't need to include the namespace.
When the @namespace directive is contained in _ViewImports.cshtml, the specified namespace supplies the
prefix for the generated namespace in the Page that imports the @namespace directive. The rest of the
generated namespace (the suffix portion) is the dot-separated relative path between the folder containing
_ViewImports.cshtml and the folder containing the page.
For example, the PageModel class Pages/Customers/Edit.cshtml.cs explicitly sets the namespace:
{
{

{
_db = db;
}
// Code removed for brevity.
The Pages/_ViewImports.cshtml file sets the following namespace:
The generated namespace for the Pages/Customers/Edit.cshtml Razor Page is the same as the PageModel
class.
@namespace also works with conventional Razor views.
The original Pages/Create.cshtml view file:
@page
<html>
<body>
<p>
Enter your name.
</p>
</form>
</body>
</html>
The updated Pages/Create.cshtml view file:
@page
@model CreateModel
<html>
<body>
<p>
Enter your name.
</p>
</form>
</body>
</html>
The Razor Pages starter project contains the Pages/_ValidationScriptsPartial.cshtml, which hooks up client-
side validation.
For more information on partial views, see Partial views in ASP.NET Core.
URL generation for Pages

The Create page, shown previously, uses RedirectToPage :

{
{
return Page();
}
}
The app has the following file/folder structure:

/Pages
Index.cshtml
/Customers
Create.cshtml
Edit.cshtml
Index.cshtml
The Pages/Customers/Create.cshtml and Pages/Customers/Edit.cshtml pages redirect to Pages/Index.cshtml
after success. The string /Index is part of the URI to access the preceding page. The string /Index can be
used to generate URIs to the Pages/Index.cshtml page. For example:
Url.Page("/Index", ...)
<a asp-page="/Index">My Index Page</a>
RedirectToPage("/Index")
The page name is the path to the page from the root /Pages folder including a leading / (for example,
/Index ). The preceding URL generation samples offer enhanced options and functional capabilities over
hardcoding a URL. URL generation uses routing and can generate and encode parameters according to how
the route is defined in the destination path.
URL generation for pages supports relative names. The following table shows which Index page is selected
with different RedirectToPage parameters from Pages/Customers/Create.cshtml:
REDIRECTTOPAGE(X) PAGE
RedirectToPage("/Index") Pages/Index
RedirectToPage("./Index"); Pages/Customers/Index
RedirectToPage("../Index") Pages/Index
RedirectToPage("Index") Pages/Customers/Index
RedirectToPage("Index") , RedirectToPage("./Index") , and RedirectToPage("../Index") are relative names.

The RedirectToPage parameter is combined with the path of the current page to compute the name of the
destination page.
Relative name linking is useful when building sites with a complex structure. If you use relative names to link
between pages in a folder, you can rename that folder. All the links still work (because they didn't include the
folder name).
ViewData attribute
Data can be passed to a page with ViewDataAttribute. Properties on controllers or Razor Page models
decorated with [ViewData] have their values stored and loaded from the ViewDataDictionary.
In the following example, the AboutModel contains a Title property decorated with [ViewData] . The Title
property is set to the title of the About page:
{
[ViewData]
public string Title { get; } = "About";
public void OnGet()

{
}
}
In the About page, access the Title property as a model property:
<!DOCTYPE html>
<html lang="en">
<head>
...
TempData
ASP.NET Core exposes the TempData property on a controller. This property stores data until it's read. The
Keep and Peek methods can be used to examine the data without deletion. TempData is useful for
redirection, when data is needed for more than a single request.
The [TempData] attribute is new in ASP.NET Core 2.0 and is supported on controllers and pages.
The following code sets the value of Message using TempData :
public class CreateDotModel : PageModel
{
public CreateDotModel(AppDbContext db)

{
_db = db;
}
[TempData]
[BindProperty]

{
{
return Page();
}
Message = $"Customer {Customer.Name} added";
}
}
The following markup in the Pages/Customers/Index.cshtml file displays the value of Message using
TempData .
<h3>Msg: @Model.Message</h3>
The Pages/Customers/Index.cshtml.cs page model applies the [TempData] attribute to the Message property.
[TempData]
See TempData for more information.
Multiple handlers per page

The following page generates markup for two page handlers using the asp-page-handler Tag Helper:
@page
@model CreateFATHModel
<html>
<body>
<p>
Enter your name.
</p>
</form>
</body>
</html>
The form in the preceding example has two submit buttons, each using the FormActionTagHelper to submit to
a different URL. The asp-page-handler attribute is a companion to asp-page . asp-page-handler generates
URLs that submit to each of the handler methods defined by a page. asp-page isn't specified because the
sample is linking to the current page.
The page model:
namespace RazorPagesContacts.Pages.Customers
{
public class CreateFATHModel : PageModel
{
public CreateFATHModel(AppDbContext db)

{
_db = db;
}
[BindProperty]
public async Task<IActionResult> OnPostJoinListAsync()

{
{
return Page();
}
}
public async Task<IActionResult> OnPostJoinListUCAsync()

{
{
return Page();
}
Customer.Name = Customer.Name?.ToUpper();
return await OnPostJoinListAsync();
}
}
}
The preceding code uses named handler methods. Named handler methods are created by taking the text in
the name after On<HTTP Verb> and before Async (if present). In the preceding example, the page methods
are OnPostJoinListAsync and OnPostJoinListUCAsync. With OnPost and Async removed, the handler
names are JoinList and JoinListUC .

Using the preceding code, the URL path that submits to is

OnPostJoinListAsync
http://localhost:5000/Customers/CreateFATH?handler=JoinList . The URL path that submits to
OnPostJoinListUCAsync is http://localhost:5000/Customers/CreateFATH?handler=JoinListUC .
Custom routes
Use the @page directive to:
Specify a custom route to a page. For example, the route to the About page can be set to
/Some/Other/Path with @page "/Some/Other/Path" .
Append segments to a page's default route. For example, an "item" segment can be added to a page's
default route with @page "item" .
Append parameters to a page's default route. For example, an ID parameter, id , can be required for a
page with @page "{id}" .
A root-relative path designated by a tilde ( ~ ) at the beginning of the path is supported. For example,
@page "~/Some/Other/Path" is the same as @page "/Some/Other/Path" .
You can change the query string ?handler=JoinList in the URL to a route segment /JoinList by specifying
the route template @page "{handler?}" .
If you don't like the query string ?handler=JoinList in the URL, you can change the route to put the handler
name in the path portion of the URL. You can customize the route by adding a route template enclosed in
double quotes after the @page directive.
@page "{handler?}"
@model CreateRouteModel
<html>
<body>
<p>
Enter your name.
</p>
</form>
</body>
</html>
Using the preceding code, the URL path that submits to OnPostJoinListAsync is
http://localhost:5000/Customers/CreateFATH/JoinList . The URL path that submits to OnPostJoinListUCAsync
is http://localhost:5000/Customers/CreateFATH/JoinListUC .
The ? following handler means the route parameter is optional.
Configuration and settings

To configure advanced options, use the extension method AddRazorPagesOptions on the MVC builder:

{
services.AddMvc()
{
options.RootDirectory = "/MyPages";
options.Conventions.AuthorizeFolder("/MyPages/Admin");
});
}
Currently you can use the RazorPagesOptions to set the root directory for pages, or add application model
conventions for pages. We'll enable more extensibility this way in the future.
To precompile views, see Razor view compilation .
Download or view sample code.
See Get started with Razor Pages, which builds on this introduction.
Specify that Razor Pages are at the content root
By default, Razor Pages are rooted in the /Pages directory. Add WithRazorPagesAtContentRoot to AddMvc
to specify that your Razor Pages are at the content root (ContentRootPath) of the app:
services.AddMvc()
{
...
})
.WithRazorPagesAtContentRoot();
Specify that Razor Pages are at a custom root directory

Add WithRazorPagesRoot to AddMvc to specify that your Razor Pages are at a custom root directory in the
app (provide a relative path):
services.AddMvc()
{
...
})
.WithRazorPagesRoot("/path/to/razor/pages");
Get started with Razor Pages in ASP.NET Core
Razor Pages authorization conventions in ASP.NET Core
Razor Pages route and app conventions in ASP.NET Core
Filter methods for Razor Pages in ASP.NET Core
By Rick Anderson
Razor Page filters IPageFilter and IAsyncPageFilter allow Razor Pages to run code before and after a Razor Page
handler is run. Razor Page filters are similar to ASP.NET Core MVC action filters, except they can't be applied to
individual page handler methods.
Razor Page filters:
Run code after a handler method has been selected, but before model binding occurs.
Run code before the handler method executes, after model binding is complete.
Run code after the handler method executes.
Can be implemented on a page or globally.
Cannot be applied to specific page handler methods.
Code can be run before a handler method executes using the page constructor or middleware, but only Razor Page
filters have access to HttpContext. Filters have a FilterContext derived parameter, which provides access to
HttpContext . For example, the Implement a filter attribute sample adds a header to the response, something that
can't be done with constructors or middleware.
Razor Page filters provide the following methods, which can be applied globally or at the page level:
Synchronous methods:
OnPageHandlerSelected : Called after a handler method has been selected, but before model binding
occurs.
OnPageHandlerExecuting : Called before the handler method executes, after model binding is complete.
OnPageHandlerExecuted : Called after the handler method executes, before the action result.
Asynchronous methods:
OnPageHandlerSelectionAsync : Called asynchronously after the handler method has been selected, but
before model binding occurs.
OnPageHandlerExecutionAsync : Called asynchronously before the handler method is invoked, after
model binding is complete.
NOTE
Implement either the synchronous or the async version of a filter interface, not both. The framework checks first to see if the
filter implements the async interface, and if so, it calls that. If not, it calls the synchronous interface's method(s). If both
interfaces are implemented, only the async methods are be called. The same rule applies to overrides in pages, implement the
synchronous or the async version of the override, not both.
Implement Razor Page filters globally

The following code implements IAsyncPageFilter :
using Microsoft.AspNetCore.Mvc.Filters;
namespace PageFilter.Filters
{
public class SampleAsyncPageFilter : IAsyncPageFilter
{
public SampleAsyncPageFilter(ILogger logger)

{
_logger = logger;
}
public async Task OnPageHandlerSelectionAsync(

PageHandlerSelectedContext context)
{
_logger.LogDebug("Global OnPageHandlerSelectionAsync called.");
await Task.CompletedTask;
}
public async Task OnPageHandlerExecutionAsync(

PageHandlerExecutingContext context,
PageHandlerExecutionDelegate next)
{
_logger.LogDebug("Global OnPageHandlerExecutionAsync called.");
}
}
}
In the preceding code, ILogger is not required. It's used in the sample to provide trace information for the
application.
The following code enables the SampleAsyncPageFilter in the Startup class:

{
services.AddMvc(options =>
{
options.Filters.Add(new SampleAsyncPageFilter(_logger));
});
}
The following code shows the complete Startup class:

using PageFilter.Filters;
namespace PageFilter
{
{
ILogger _logger;
public Startup(ILoggerFactory loggerFactory, IConfiguration configuration)
{
_logger = loggerFactory.CreateLogger<GlobalFiltersLogger>();
}

{
{
options.Filters.Add(new SampleAsyncPageFilter(_logger));
});
}

{
{
}
else
{
app.UseHsts();
}
app.UseMvc();
}
}
}
The following code calls AddFolderApplicationModelConvention to apply the SampleAsyncPageFilter to only pages in
/subFolder:

{
services.AddMvc()
{
options.Conventions.AddFolderApplicationModelConvention(
"/subFolder",
model => model.Filters.Add(new SampleAsyncPageFilter(_logger)));
});
}
The following code implements the synchronous IPageFilter :

{
public class SamplePageFilter : IPageFilter
{
public SamplePageFilter(ILogger logger)

{
_logger = logger;
}
public void OnPageHandlerSelected(PageHandlerSelectedContext context)

{
_logger.LogDebug("Global sync OnPageHandlerSelected called.");
}
public void OnPageHandlerExecuting(PageHandlerExecutingContext context)

{
_logger.LogDebug("Global sync PageHandlerExecutingContext called.");
}
public void OnPageHandlerExecuted(PageHandlerExecutedContext context)

{
_logger.LogDebug("Global sync OnPageHandlerExecuted called.");
}
}
}
The following code enables the SamplePageFilter :

{
{
options.Filters.Add(new SamplePageFilter(_logger));
});
}
Implement Razor Page filters by overriding filter methods

The following code overrides the synchronous Razor Page filters:
namespace PageFilter.Pages
{
{
public IndexModel(ILogger<IndexModel> logger)

{
_logger = logger;
}
public void OnGet()

{
_logger.LogDebug("IndexModel/OnGet");
}
public override void OnPageHandlerSelected(

PageHandlerSelectedContext context)
{
_logger.LogDebug("IndexModel/OnPageHandlerSelected");
}
public override void OnPageHandlerExecuting(

PageHandlerExecutingContext context)
{
Message = "Message set in handler executing";
_logger.LogDebug("IndexModel/OnPageHandlerExecuting");
}
public override void OnPageHandlerExecuted(

PageHandlerExecutedContext context)
{
_logger.LogDebug("IndexModel/OnPageHandlerExecuted");
}
}
}
Implement a filter attribute

The built-in attribute-based filter OnResultExecutionAsync filter can be subclassed. The following filter adds a
header to the response:
{
public class AddHeaderAttribute : ResultFilterAttribute
{
private readonly string _name;
private readonly string _value;
public AddHeaderAttribute (string name, string value)

{
_name = name;
_value = value;
}
public override void OnResultExecuting(ResultExecutingContext context)

{
context.HttpContext.Response.Headers.Add(_name, new string[] { _value });
}
}
}
The following code applies the AddHeader attribute:
[AddHeader("Author", "Rick")]
public class ContactModel : PageModel
{
public ContactModel(ILogger<ContactModel> logger)

{
_logger = logger;
}

{
Message = "Your contact page.";
_logger.LogDebug("Contact/OnGet");
await Task.CompletedTask;
}
}
See Overriding the default order for instructions on overriding the order.
See Cancellation and short circuiting for instructions to short-circuit the filter pipeline from a filter.
Authorize filter attribute

The Authorize attribute can be applied to a PageModel :
using Microsoft.AspNetCore.Authorization;
namespace PageFilter.Pages
{
[Authorize]
public class ModelWithAuthFilterModel : PageModel
{
public IActionResult OnGet() => Page();
}
}
Create reusable UI using the Razor Class Library
project in ASP.NET Core
By Rick Anderson
Razor views, pages, controllers, page models, View components, and data models can be built into a Razor Class
Library (RCL ). The RCL can be packaged and reused. Applications can include the RCL and override the views and
pages it contains. When a view, partial view, or Razor Page is found in both the web app and the RCL, the Razor
markup (.cshtml file) in the web app takes precedence.
This feature requires .NET Core 2.1 SDK or later
Create a class library containing Razor UI

Visual Studio
.NET Core CLI
Select ASP.NET Core Web Application.
Name the library (for example, "RazorClassLib") > OK. To avoid a file name collision with the generated view
library, ensure the library name doesn't end in .Views .
Verify ASP.NET Core 2.1 or later is selected.
Select Razor Class Library > OK.
A Razor Class Library has the following project file:
<Project Sdk="Microsoft.NET.Sdk.Razor">
<PropertyGroup>
<TargetFramework>netstandard2.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.1.2" />
</ItemGroup>
</Project>
Add Razor files to the RCL.

The ASP.NET Core templates assume the RCL content is in the Areas folder. See RCL Pages layout to create a
RCL that exposes content in ~/Pages rather than ~/Areas/Pages .
Referencing Razor Class Library content

The RCL can be referenced by:
NuGet package. See Creating NuGet packages and dotnet add package and Create and publish a NuGet
package.
{ProjectName}.csproj. See dotnet-add reference.
Walkthrough: Create a Razor Class Library project and use from a

Razor Pages project
You can download the complete project and test it rather than creating it. The sample download contains
additional code and links that make the project easy to test. You can leave feedback in this GitHub issue with your
comments on download samples versus step-by-step instructions.
Test the download app
If you haven't downloaded the completed app and would rather create the walkthrough project, skip to the next
section.
Visual Studio
.NET Core CLI
Open the .sln file in Visual Studio. Run the app.
Follow the instructions in Test WebApp1
Create a Razor Class Library

In this section, a Razor Class Library (RCL ) is created. Razor files are added to the RCL.
Visual Studio
.NET Core CLI
Create the RCL project:
Name the app RazorUIClassLib > OK.
Select Razor Class Library > OK.
Add a Razor partial view file named RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml.
Add Razor files and folders to the project
Replace the markup in RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml with the following
code:
<h3> _Message.cshtml partial view.</h3>
<p>RazorUIClassLib\Areas\MyFeature\Pages\Shared\_Message.cshtml</p>
Replace the markup in RazorUIClassLib/Areas/MyFeature/Pages/Page1.cshtml with the following code:
@page
<h2>Hello from a Razor UI class library!</h2>

<p> From RazorUIClassLib\Areas\MyFeature\Pages\Page1.cshtml</p>
<partial name="_Message" />
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers is required to use the partial view (

<partial name="_Message" /> ). Rather than including the @addTagHelper directive, you can add a
_ViewImports.cshtml file. For example:
dotnet new viewimports -o RazorUIClassLib/Areas/MyFeature/Pages
For more information on _ViewImports.cshtml, see Importing Shared Directives

Build the class library to verify there are no compiler errors:
dotnet build RazorUIClassLib
The build output contains RazorUIClassLib.dll and RazorUIClassLib.Views.dll. RazorUIClassLib.Views.dll contains

the compiled Razor content.
Use the Razor UI library from a Razor Pages project
Visual Studio
.NET Core CLI
Create the Razor Pages web app:
From Solution Explorer, right-click the solution > Add > New Project.
Name the app WebApp1.
Select Web Application > OK.
From Solution Explorer, right-click on WebApp1 and select Set as StartUp Project.
From Solution Explorer, right-click on WebApp1 and select Build Dependencies > Project
Dependencies.
Check RazorUIClassLib as a dependency of WebApp1.
From Solution Explorer, right-click on WebApp1 and select Add > Reference.
In the Reference Manager dialog, check RazorUIClassLib > OK.
Run the app.
Test WebApp1
Verify the Razor UI class library is being used.
Browse to /MyFeature/Page1 .
Override views, partial views, and pages

When a view, partial view, or Razor Page is found in both the web app and the Razor Class Library, the Razor
markup (.cshtml file) in the web app takes precedence. For example, add
WebApp1/Areas/MyFeature/Pages/Page1.cshtml to WebApp1, and Page1 in the WebApp1 will take precedence
over Page1 in the Razor Class Library.
In the sample download, rename WebApp1/Areas/MyFeature2 to WebApp1/Areas/MyFeature to test
precedence.
Copy the RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml partial view to
WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. Update the markup to indicate the new location.
Build and run the app to verify the app's version of the partial is being used.
RCL Pages layout
To reference RCL content as though it is part of the web app's Pages folder, create the RCL project with the
following file structure:
RazorUIClassLib/Pages
RazorUIClassLib/Pages/Shared
Suppose RazorUIClassLib/Pages/Shared contains two partial files: _Header.cshtml and _Footer.cshtml. The
<partial> tags could be added to _Layout.cshtml file:
<body>
<partial name="_Header">
@RenderBody()
<partial name="_Footer">
</body>
Razor Pages route and app conventions in ASP.NET
Core
By Luke Latham
Learn how to use page route and app model provider conventions to control page routing, discovery, and
processing in Razor Pages apps.
When you need to configure custom page routes for individual pages, configure routing to pages with the
AddPageRoute convention described later in this topic.
To specify a page route, add route segments, or add parameters to a route, use the page's @page directive. For
more information, see Custom routes.
There are reserved words that can't be used as route segments or parameter names. For more information, see
Routing: Reserved routing names.
SCENARIO THE SAMPLE DEMONSTRATES ...
Model conventions Add a route template and header to an app's pages.
Conventions.Add
IPageRouteModelConvention
IPageApplicationModelConvention
Page route action conventions Add a route template to pages in a folder and to a single
AddFolderRouteModelConvention page.
AddPageRouteModelConvention
AddPageRoute
Page model action conventions Add a header to pages in a folder, add a header to a single
AddFolderApplicationModelConvention page, and configure a filter factory to add a header to an
AddPageApplicationModelConvention app's pages.
ConfigureFilter (filter class, lambda expression, or filter
factory)
Default page app model provider Replace the default page model provider to change the
conventions for handler names.
Model conventions Add a route template and header to an app's pages.
Conventions.Add
IPageRouteModelConvention
IPageApplicationModelConvention
IPageHandlerModelConvention
Page route action conventions Add a route template to pages in a folder and to a single
AddFolderRouteModelConvention page.
AddPageRouteModelConvention
AddPageRoute
Page model action conventions Add a header to pages in a folder, add a header to a single
AddFolderApplicationModelConvention page, and configure a filter factory to add a header to an
AddPageApplicationModelConvention app's pages.
ConfigureFilter (filter class, lambda expression, or filter
factory)
Default page app model provider Replace the default page model provider to change the
conventions for handler names.
Razor Pages conventions are added and configured using the AddRazorPagesOptions extension method to
AddMvc on the service collection in the Startup class. The following convention examples are explained later in
this topic:

{
services.AddMvc()
{
options.Conventions.Add( ... );
options.Conventions.AddFolderRouteModelConvention("/OtherPages", model => { ... });
options.Conventions.AddPageRouteModelConvention("/About", model => { ... });
options.Conventions.AddPageRoute("/Contact", "TheContactPage/{text?}");
options.Conventions.AddFolderApplicationModelConvention("/OtherPages", model => { ... });
options.Conventions.AddPageApplicationModelConvention("/About", model => { ... });
options.Conventions.ConfigureFilter(model => { ... });
options.Conventions.ConfigureFilter( ... );
});
}
Route order
Routes specify an Order for processing (route matching).
ORDER BEHAVIOR
-1 The route is processed before other routes are processed.
0 Order isn't specified (default value). Not assigning Order (

Order = null ) defaults the route Order to 0 (zero) for
processing.
1, 2, … n Specifies the route processing order.
Route processing is established by convention:

Routes are processed in sequential order (-1, 0, 1, 2, … n).
When routes have the same Order , the most specific route is matched first followed by less specific routes.
When routes with the same Order and the same number of parameters match a request URL, routes are
processed in the order that they're added to the PageConventionCollection.
If possible, avoid depending on an established route processing order. Generally, routing selects the correct route
with URL matching. If you must set route Order properties to route requests correctly, the app's routing scheme
is probably confusing to clients and fragile to maintain. Seek to simplify the app's routing scheme. The sample app
requires an explicit route processing order to demonstrate several routing scenarios using a single app. However,
you should attempt to avoid the practice of setting route Order in production apps.
Razor Pages routing and MVC controller routing share an implementation. Information on route order in the MVC
topics is available at Routing to controller actions: Ordering attribute routes.
Model conventions
Add a delegate for IPageConvention to add model conventions that apply to Razor Pages.
Add a route model convention to all pages
Use Conventions to create and add an IPageRouteModelConvention to the collection of IPageConvention
instances that are applied during page route model construction.
The sample app adds a {globalTemplate?} route template to all of the pages in the app:
public class GlobalTemplatePageRouteModelConvention

: IPageRouteModelConvention
{
public void Apply(PageRouteModel model)
{
var selectorCount = model.Selectors.Count;
for (var i = 0; i < selectorCount; i++)
{
var selector = model.Selectors[i];
model.Selectors.Add(new SelectorModel
{
AttributeRouteModel = new AttributeRouteModel
{
Order = 1,
Template = AttributeRouteModel.CombineTemplates(
selector.AttributeRouteModel.Template,
"{globalTemplate?}"),
}
});
}
}
}
The Order property for the AttributeRouteModel is set to 1 . This ensures the following route matching behavior
in the sample app:
A route template for TheContactPage/{text?} is added later in the topic. The Contact Page route has a default
order of null ( Order = 0 ), so it matches before the {globalTemplate?} route template.
An {aboutTemplate?} route template is added later in the topic. The {aboutTemplate?} template is given an
Order of 2 . When the About page is requested at /About/RouteDataValue , "RouteDataValue" is loaded into
RouteData.Values["globalTemplate"] ( Order = 1 ) and not RouteData.Values["aboutTemplate"] ( Order = 2 ) due
to setting the Order property.
An {otherPagesTemplate?} route template is added later in the topic. The {otherPagesTemplate?} template is
given an Order of 2 . When any page in the Pages/OtherPages folder is requested with a route parameter (for
example, /OtherPages/Page1/RouteDataValue ), "RouteDataValue" is loaded into
RouteData.Values["globalTemplate"] ( Order = 1 ) and not RouteData.Values["otherPagesTemplate"] ( Order = 2 )
due to setting the Order property.
Wherever possible, don't set the Order , which results in Order = 0 . Rely on routing to select the correct route.
Razor Pages options, such as adding Conventions, are added when MVC is added to the service collection in
Startup.ConfigureServices . For an example, see the sample app.
options.Conventions.Add(new GlobalTemplatePageRouteModelConvention());
Request the sample's About page at localhost:5000/About/GlobalRouteValue and inspect the result:
Add an app model convention to all pages

Use Conventions to create and add an IPageApplicationModelConvention to the collection of IPageConvention
instances that are applied during page app model construction.
To demonstrate this and other conventions later in the topic, the sample app includes an AddHeaderAttribute class.
The class constructor accepts a name string and a values string array. These values are used in its
OnResultExecuting method to set a response header. The full class is shown in the Page model action conventions
section later in the topic.
The sample app uses the AddHeaderAttribute class to add a header, GlobalHeader , to all of the pages in the app:
public class GlobalHeaderPageApplicationModelConvention

: IPageApplicationModelConvention
{
public void Apply(PageApplicationModel model)
{
model.Filters.Add(new AddHeaderAttribute(
"GlobalHeader", new string[] { "Global Header Value" }));
}
}
Startup.cs:
options.Conventions.Add(new GlobalHeaderPageApplicationModelConvention());
Request the sample's About page at localhost:5000/About and inspect the headers to view the result:
Add a handler model convention to all pages
Use Conventions to create and add an IPageHandlerModelConvention to the collection of IPageConvention
instances that are applied during page handler model construction.
public class GlobalPageHandlerModelConvention

: IPageHandlerModelConvention
{
public void Apply(PageHandlerModel model)
{
...
}
}
Startup.ConfigureServices :
services.AddMvc()
{
options.Conventions.Add(new GlobalPageHandlerModelConvention());
});
Page route action conventions

The default route model provider that derives from IPageRouteModelProvider invokes conventions which are
designed to provide extensibility points for configuring page routes.
Folder route model convention
Use AddFolderRouteModelConvention to create and add an IPageRouteModelConvention that invokes an action
on the PageRouteModel for all of the pages under the specified folder.
The sample app uses AddFolderRouteModelConvention to add an {otherPagesTemplate?} route template to the pages
in the OtherPages folder:
options.Conventions.AddFolderRouteModelConvention("/OtherPages", model =>
{
{
{
{
Order = 2,
"{otherPagesTemplate?}"),
}
});
}
});
The Order property for the AttributeRouteModel is set to 2 . This ensures that the template for
{globalTemplate?} (set earlier in the topic to 1 ) is given priority for the first route data value position when a
single route value is provided. If a page in the Pages/OtherPages folder is requested with a route parameter value
(for example, /OtherPages/Page1/RouteDataValue ), "RouteDataValue" is loaded into
RouteData.Values["globalTemplate"] ( Order = 1 ) and not RouteData.Values["otherPagesTemplate"] ( Order = 2 )
due to setting the Order property.
Request the sample's Page1 page at localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue and
inspect the result:
Page route model convention

Use AddPageRouteModelConvention to create and add an IPageRouteModelConvention that invokes an action
on the PageRouteModel for the page with the specified name.
The sample app uses AddPageRouteModelConvention to add an {aboutTemplate?} route template to the About page:
options.Conventions.AddPageRouteModelConvention("/About", model =>
{
{
{
{
Order = 2,
"{aboutTemplate?}"),
}
});
}
});
The Order property for the AttributeRouteModel is set to 2 . This ensures that the template for
{globalTemplate?} (set earlier in the topic to 1 ) is given priority for the first route data value position when a
single route value is provided. If the About page is requested with a route parameter value at
/About/RouteDataValue , "RouteDataValue" is loaded into RouteData.Values["globalTemplate"] ( Order = 1 ) and not
RouteData.Values["aboutTemplate"] ( Order = 2 ) due to setting the Order property.
Request the sample's About page at localhost:5000/About/GlobalRouteValue/AboutRouteValue and inspect the result:
Configure a page route

Use AddPageRoute to configure a route to a page at the specified page path. Generated links to the page use your
specified route. AddPageRoute uses AddPageRouteModelConvention to establish the route.
The sample app creates a route to /TheContactPage for Contact.cshtml:
options.Conventions.AddPageRoute("/Contact", "TheContactPage/{text?}");
The Contact page can also be reached at /Contact via its default route.
The sample app's custom route to the Contact page allows for an optional text route segment ( {text?} ). The
page also includes this optional segment in its @page directive in case the visitor accesses the page at its /Contact
route:
@page "{text?}"
@model ContactModel
@{
ViewData["Title"] = "Contact";
}
<address>
One Microsoft Way<br>
Redmond, WA 98052-6399<br>
<abbr title="Phone">P:</abbr>
425.555.0100
</address>
<address>
<strong>Support:</strong> <a href="mailto:[email protected]">[email protected]</a><br>
<strong>Marketing:</strong> <a href="mailto:[email protected]">[email protected]</a>
</address>
<p>@Model.RouteDataTextTemplateValue</p>
Note that the URL generated for the Contact link in the rendered page reflects the updated route:
Visit the Contact page at either its ordinary route, /Contact , or the custom route, /TheContactPage . If you supply
an additional text route segment, the page shows the HTML -encoded segment that you provide:
Page model action conventions
The default page model provider that implements IPageApplicationModelProvider invokes conventions which are
designed to provide extensibility points for configuring page models. These conventions are useful when building
and modifying page discovery and processing scenarios.
For the examples in this section, the sample app uses an AddHeaderAttribute class, which is a ResultFilterAttribute,
that applies a response header:

{
private readonly string[] _values;
public AddHeaderAttribute(string name, string[] values)

{
_name = name;
_values = values;
}

{
context.HttpContext.Response.Headers.Add(_name, _values);
base.OnResultExecuting(context);
}
}
Using conventions, the sample demonstrates how to apply the attribute to all of the pages in a folder and to a
single page.
Folder app model convention
Use AddFolderApplicationModelConvention to create and add an IPageApplicationModelConvention that invokes
an action on PageApplicationModel instances for all pages under the specified folder.
The sample demonstrates the use of AddFolderApplicationModelConvention by adding a header, OtherPagesHeader ,
to the pages inside the OtherPages folder of the app:
options.Conventions.AddFolderApplicationModelConvention("/OtherPages", model =>

{
"OtherPagesHeader", new string[] { "OtherPages Header Value" }));
});
Request the sample's Page1 page at localhost:5000/OtherPages/Page1 and inspect the headers to view the result:
Page app model convention

Use AddPageApplicationModelConvention to create and add an IPageApplicationModelConvention that invokes
an action on the PageApplicationModel for the page with the specified name.
The sample demonstrates the use of AddPageApplicationModelConvention by adding a header, AboutHeader , to the
About page:
options.Conventions.AddPageApplicationModelConvention("/About", model =>

{
"AboutHeader", new string[] { "About Header Value" }));
});
Configure a filter
ConfigureFilter configures the specified filter to apply. You can implement a filter class, but the sample app shows
how to implement a filter in a lambda expression, which is implemented behind-the-scenes as a factory that
returns a filter:
options.Conventions.ConfigureFilter(model =>
{
if (model.RelativePath.Contains("OtherPages/Page2"))
{
return new AddHeaderAttribute(
"OtherPagesPage2Header",
new string[] { "OtherPages/Page2 Header Value" });
}
return new EmptyFilter();
});
The page app model is used to check the relative path for segments that lead to the Page2 page in the OtherPages
folder. If the condition passes, a header is added. If not, the EmptyFilter is applied.
EmptyFilter is an Action filter. Since Action filters are ignored by Razor Pages, the EmptyFilter no-ops as
intended if the path doesn't contain OtherPages/Page2 .
Request the sample's Page2 page at localhost:5000/OtherPages/Page2 and inspect the headers to view the result:
Configure a filter factory

ConfigureFilter configures the specified factory to apply filters to all Razor Pages.
The sample app provides an example of using a filter factory by adding a header, FilterFactoryHeader , with two
values to the app's pages:
options.Conventions.ConfigureFilter(new AddHeaderWithFactory());
AddHeaderWithFactory.cs:
public class AddHeaderWithFactory : IFilterFactory
{
// Implement IFilterFactory
public IFilterMetadata CreateInstance(IServiceProvider serviceProvider)
{
return new AddHeaderFilter();
}
private class AddHeaderFilter : IResultFilter

{
public void OnResultExecuting(ResultExecutingContext context)
{
context.HttpContext.Response.Headers.Add(
"FilterFactoryHeader",
new string[]
{
"Filter Factory Header Value 1",
"Filter Factory Header Value 2"
});
}
public void OnResultExecuted(ResultExecutedContext context)

{
}
}
public bool IsReusable

{
get
{
return false;
}
}
}
Replace the default page app model provider

Razor Pages uses the IPageApplicationModelProvider interface to create a DefaultPageApplicationModelProvider.
You can inherit from the default model provider to provide your own implementation logic for handler discovery
and processing. The default implementation (reference source) establishes conventions for unnamed and named
handler naming, which is described below.
Default unnamed handler methods
Handler methods for HTTP verbs ("unnamed" handler methods) follow a convention: On<HTTP verb>[Async]
(appending Async is optional but recommended for async methods).
UNNAMED HANDLER METHOD OPERATION
OnGet / OnGetAsync Initialize the page state.
OnPost / OnPostAsync Handle POST requests.
OnDelete / OnDeleteAsync Handle DELETE requests†.
OnPut / OnPutAsync Handle PUT requests†.
OnPatch / OnPatchAsync Handle PATCH requests†.
†Used for making API calls to the page.

Default named handler methods
Handler methods provided by the developer ("named" handler methods) follow a similar convention. The handler
name appears after the HTTP verb or between the HTTP verb and Async : On<HTTP verb><handler name>[Async]
(appending Async is optional but recommended for async methods). For example, methods that process
messages might take the naming shown in the table below.
EXAMPLE NAMED HANDLER METHOD EXAMPLE OPERATION
OnGetMessage / OnGetMessageAsync Obtain a message.
OnPostMessage / OnPostMessageAsync POST a message.
OnDeleteMessage / OnDeleteMessageAsync DELETE a message†.
OnPutMessage / OnPutMessageAsync PUT a message†.
OnPatchMessage / OnPatchMessageAsync PATCH a message†.

Customize handler method names
Assume that you prefer to change the way unnamed and named handler methods are named. An alternative
naming scheme is to avoid starting the method names with "On" and use the first word segment to determine the
HTTP verb. You can make other changes, such as converting the verbs for DELETE, PUT, and PATCH to POST.
Such a scheme provides the method names shown in the following table.
HANDLER METHOD OPERATION
Get Initialize the page state.
Post / PostAsync Handle POST requests.
Delete / DeleteAsync Handle DELETE requests†.
Put / PutAsync Handle PUT requests†.
Patch / PatchAsync Handle PATCH requests†.

HANDLER METHOD OPERATION
GetMessage Obtain a message.
PostMessage / PostMessageAsync POST a message.
DeleteMessage / DeleteMessageAsync POST a message to delete.
PutMessage / PutMessageAsync POST a message to put.
PatchMessage / PatchMessageAsync POST a message to patch.

To establish this scheme, inherit from the DefaultPageApplicationModelProvider class and override the
CreateHandlerModel method to supply custom logic for resolving PageModel handler names. The sample app
shows you how this is done in its CustomPageApplicationModelProvider class:
public class CustomPageApplicationModelProvider :

DefaultPageApplicationModelProvider
{
public CustomPageApplicationModelProvider(IModelMetadataProvider modelMetadataProvider,
IOptions<MvcOptions> options)
: base (modelMetadataProvider, options)
{
}
protected override PageHandlerModel CreateHandlerModel(MethodInfo method)

{
if (method == null)
{
throw new ArgumentNullException(nameof(method));
}
if (!IsHandler(method))
{
return null;
}
if (!TryParseHandlerMethod(
method.Name, out var httpMethod, out var handlerName))
{
return null;
}
var handlerModel = new PageHandlerModel(

method,
method.GetCustomAttributes(inherit: true))
{
Name = method.Name,
HandlerName = handlerName,
HttpMethod = httpMethod,
};
var methodParameters = handlerModel.MethodInfo.GetParameters();
for (var i = 0; i < methodParameters.Length; i++)

{
var parameter = methodParameters[i];
var parameterModel = CreateParameterModel(parameter);
parameterModel.Handler = handlerModel;
handlerModel.Parameters.Add(parameterModel);
handlerModel.Parameters.Add(parameterModel);
}
return handlerModel;
}
private static bool TryParseHandlerMethod(

string methodName, out string httpMethod, out string handler)
{
httpMethod = null;
handler = null;
// Parse the method name according to our conventions to

// determine the required HTTP verb and optional
// handler name.
//
// Valid names look like:
// - Get
// - Post
// - PostAsync
// - GetMessage
// - PostMessage
// - DeleteMessage
// - DeleteMessageAsync
var length = methodName.Length;

if (methodName.EndsWith("Async", StringComparison.Ordinal))
{
length -= "Async".Length;
}
if (length == 0)
{
// The method is named "Async". Exit processing.
return false;
}
// The HTTP verb is at the start of the method name. Use

// casing to determine where it ends.
var handlerNameStart = 1;
for (; handlerNameStart < length; handlerNameStart++)
{
if (char.IsUpper(methodName[handlerNameStart]))
{
break;
}
}
httpMethod = methodName.Substring(0, handlerNameStart);
// The handler name follows the HTTP verb and is optional.

// It includes everything up to the end excluding the
// "Async" suffix, if present.
handler = handlerNameStart == length ? null : methodName.Substring(0, length);
if (string.Equals(httpMethod, "GET", StringComparison.OrdinalIgnoreCase) ||

string.Equals(httpMethod, "POST", StringComparison.OrdinalIgnoreCase))
{
// Do nothing. The httpMethod is correct for GET and POST.
return true;
}
if (string.Equals(httpMethod, "DELETE", StringComparison.OrdinalIgnoreCase) ||
string.Equals(httpMethod, "PUT", StringComparison.OrdinalIgnoreCase) ||
string.Equals(httpMethod, "PATCH", StringComparison.OrdinalIgnoreCase))
{
// Convert HTTP verbs for DELETE, PUT, and PATCH to POST
// For example: DeleteMessage, PutMessage, PatchMessage -> POST
httpMethod = "POST";
return true;
}
}
else
{
return false;
}
}
}
Highlights of the class include:

The class inherits from DefaultPageApplicationModelProvider .
The TryParseHandlerMethod processes a handler to determine the HTTP verb ( httpMethod ) and named handler
name ( handlerName ) when creating the PageHandlerModel .
An Async postfix is ignored, if present.
Casing is used to parse the HTTP verb from the method name.
When the method name (without Async ) is equal to the HTTP verb name, there's no named handler.
The handlerName is set to null , and the method name is Get , Post , Delete , Put , or Patch .
When the method name (without Async ) is longer than the HTTP verb name, there's a named handler.
The handlerName is set to <method name (less 'Async', if present)> . For example, both "GetMessage"
and "GetMessageAsync" yield a handler name of "GetMessage".
DELETE, PUT, and PATCH HTTP verbs are converted to POST.
Register the CustomPageApplicationModelProvider in the Startup class:
services.AddSingleton<IPageApplicationModelProvider,
CustomPageApplicationModelProvider>();
The page model in Index.cshtml.cs shows how the ordinary handler method naming conventions are changed for
pages in the app. The ordinary "On" prefix naming used with Razor Pages is removed. The method that initializes
the page state is now named Get . You can see this convention used throughout the app if you open any page
model for any of the pages.
Each of the other methods start with the HTTP verb that describes its processing. The two methods that start with
Delete would normally be treated as DELETE HTTP verbs, but the logic in TryParseHandlerMethod explicitly sets
the verb to POST for both handlers.
Note that Async is optional between DeleteAllMessages and DeleteMessageAsync . They're both asynchronous
methods, but you can choose to use the Async postfix or not; we recommend that you do. DeleteAllMessages is
used here for demonstration purposes, but we recommend that you name such a method DeleteAllMessagesAsync .
It doesn't affect the processing of the sample's implementation, but using the Async postfix calls out the fact that
it's an asynchronous method.
public async Task Get()
{
Messages = await _db.Messages.AsNoTracking().ToListAsync();
}
public async Task<IActionResult> PostMessageAsync()

{
_db.Messages.Add(Message);
Result = $"{nameof(PostMessageAsync)} handler: Message '{Message.Text}' added.";
}
public async Task<IActionResult> DeleteAllMessages()

{
foreach (Message message in _db.Messages)
{
_db.Messages.Remove(message);
}
Result = $"{nameof(DeleteAllMessages)} handler: All messages deleted.";
}
public async Task<IActionResult> DeleteMessageAsync(int id)

{
var message = await _db.Messages.FindAsync(id);
if (message != null)
{
_db.Messages.Remove(message);
}
Result = $"{nameof(DeleteMessageAsync)} handler: Message with Id: {id} deleted.";
}
Note the handler names provided in Index.cshtml match the DeleteAllMessages and DeleteMessageAsync handler
methods:
<div class="row">
<h2>Clear all messages</h2>
<hr>
<button type="submit" asp-page-handler="DeleteAllMessages"
class="btn btn-danger">Clear All</button>
</div>
</form>
</div>
</div>
<div class="row">
<h2>Messages</h2>
<hr>
<ol>
@foreach (var message in Model.Messages)
{
<li>
@message.Text
<button type="submit" asp-page-handler="DeleteMessage"
class="btn btn-danger"
asp-route-id="@message.Id">Delete</button>
</li>
}
</ol>
</form>
</div>
Async in the handler method name DeleteMessageAsync is factored out by the TryParseHandlerMethod for handler
matching of POST request to method. The asp-page-handler name of DeleteMessage is matched to the handler
method DeleteMessageAsync .
MVC Filters and the Page filter (IPageFilter)

MVC Action filters are ignored by Razor Pages, since Razor Pages use handler methods. Other types of MVC
filters are available for you to use: Authorization, Exception, Resource, and Result. For more information, see the
Filters topic.
The Page filter (IPageFilter) is a filter that applies to Razor Pages. For more information, see Filter methods for
Razor Pages.
Razor Pages authorization conventions
Upload files to a Razor Page in ASP.NET Core
By Luke Latham
This topic builds upon the sample app in Get started with Razor Pages in ASP.NET Core.
This topic shows how to use simple model binding to upload files, which works well for uploading small files. For
information on streaming large files, see Uploading large files with streaming.
In the following steps, a movie schedule file upload feature is added to the sample app. A movie schedule is
represented by a Schedule class. The class includes two versions of the schedule. One version is provided to
customers, PublicSchedule . The other version is used for company employees, PrivateSchedule . Each version is
uploaded as a separate file. The tutorial demonstrates how to perform two file uploads from a page with a single
POST to the server.
Caution must be taken when providing users with the ability to upload files to a server. Attackers may execute
denial of service and other attacks on a system. Some security steps that reduce the likelihood of a successful
attack are:
Upload files to a dedicated file upload area on the system, which makes it easier to impose security measures
on uploaded content. When permitting file uploads, make sure that execute permissions are disabled on the
upload location.
Use a safe file name determined by the app, not from user input or the file name of the uploaded file.
Only allow a specific set of approved file extensions.
Verify client-side checks are performed on the server. Client-side checks are easy to circumvent.
Check the size of the upload and prevent larger uploads than expected.
Run a virus/malware scanner on uploaded content.
WARNING
Uploading malicious code to a system is frequently the first step to executing code that can:
Completely takeover a system.
Overload a system with the result that the system completely fails.
Compromise user or system data.
Apply graffiti to a public interface.
Add a FileUpload class

Create a Razor Page to handle a pair of file uploads. Add a FileUpload class, which is bound to the page to obtain
the schedule data. Right click the Models folder. Select Add > Class. Name the class FileUpload and add the
following properties:
{
public class FileUpload
{
[Required]
[Display(Name="Title")]
[Required]
[Display(Name="Public Schedule")]
public IFormFile UploadPublicSchedule { get; set; }
[Required]
[Display(Name="Private Schedule")]
public IFormFile UploadPrivateSchedule { get; set; }
}
}
{
public class FileUpload
{
[Required]
[Display(Name="Title")]
[Required]
[Display(Name="Public Schedule")]
public IFormFile UploadPublicSchedule { get; set; }
[Required]
[Display(Name="Private Schedule")]
public IFormFile UploadPrivateSchedule { get; set; }
}
}
The class has a property for the schedule's title and a property for each of the two versions of the schedule. All
three properties are required, and the title must be 3-60 characters long.
Add a helper method to upload files

To avoid code duplication for processing uploaded schedule files, add a static helper method first. Create a Utilities
folder in the app and add a FileHelpers.cs file with the following content. The helper method, ProcessFormFile ,
takes an IFormFile and ModelStateDictionary and returns a string containing the file's size and content. The
content type and length are checked. If the file doesn't pass a validation check, an error is added to the ModelState .
using System;
using System.IO;
using System.Net;
using System.Text;
using Microsoft.AspNetCore.Mvc.ModelBinding;
namespace RazorPagesMovie.Utilities
{
public class FileHelpers
{
public static async Task<string> ProcessFormFile(IFormFile formFile,
ModelStateDictionary modelState)
{
var fieldDisplayName = string.Empty;
// Use reflection to obtain the display name for the model

// property associated with this IFormFile. If a display
// name isn't found, error messages simply won't show
// a display name.
MemberInfo property =
typeof(FileUpload).GetProperty(
formFile.Name.Substring(formFile.Name.IndexOf(".") + 1));
if (property != null)
{
var displayAttribute =
property.GetCustomAttribute(typeof(DisplayAttribute))
as DisplayAttribute;
if (displayAttribute != null)
{
fieldDisplayName = $"{displayAttribute.Name} ";
}
}
// Use Path.GetFileName to obtain the file name, which will

// strip any path information passed as part of the
// FileName property. HtmlEncode the result in case it must
// be returned in an error message.
var fileName = WebUtility.HtmlEncode(
Path.GetFileName(formFile.FileName));
if (formFile.ContentType.ToLower() != "text/plain")
{
modelState.AddModelError(formFile.Name,
$"The {fieldDisplayName}file ({fileName}) must be a text file.");
}
// Check the file length and don't bother attempting to

// read it if the file contains no content. This check
// doesn't catch files that only have a BOM as their
// content, so a content length check is made later after
// reading the file's content to catch a file that only
// contains a BOM.
if (formFile.Length == 0)
{
$"The {fieldDisplayName}file ({fileName}) is empty.");
}
else if (formFile.Length > 1048576)
{
$"The {fieldDisplayName}file ({fileName}) exceeds 1 MB.");
}
else
{
try
{
string fileContents;
// The StreamReader is created to read files that are UTF-8 encoded.

// If uploads require some other encoding, provide the encoding in the
// using statement. To change to 32-bit encoding, change
// new UTF8Encoding(...) to new UTF32Encoding().
using (
var reader =
new StreamReader(
formFile.OpenReadStream(),
new UTF8Encoding(encoderShouldEmitUTF8Identifier: false,
throwOnInvalidBytes: true),
detectEncodingFromByteOrderMarks: true))
{
fileContents = await reader.ReadToEndAsync();
// Check the content length in case the file's only

// content was a BOM and the content is actually
// empty after removing the BOM.
if (fileContents.Length > 0)
{
return fileContents;
}
else
{
}
}
}
{
$"The {fieldDisplayName}file ({fileName}) upload failed. " +
$"Please contact the Help Desk for support. Error: {ex.Message}");
// Log the exception
}
}
}
}
}
using System;
using System.IO;
using System.Net;
using System.Text;
namespace RazorPagesMovie.Utilities
{
public class FileHelpers
{
public static async Task<string> ProcessFormFile(
IFormFile formFile, ModelStateDictionary modelState)
{
var fieldDisplayName = string.Empty;
// Use reflection to obtain the display name for the model

// property associated with this IFormFile. If a display
// name isn't found, error messages simply won't show
// a display name.
MemberInfo property =
typeof(FileUpload).GetProperty(formFile.Name.Substring(
formFile.Name.IndexOf(".") + 1));
formFile.Name.IndexOf(".") + 1));
if (property != null)
{
var displayAttribute =
property.GetCustomAttribute(typeof(DisplayAttribute))
as DisplayAttribute;
if (displayAttribute != null)
{
fieldDisplayName = $"{displayAttribute.Name} ";
}
}
// Use Path.GetFileName to obtain the file name, which will

// strip any path information passed as part of the
// FileName property. HtmlEncode the result in case it must
// be returned in an error message.
var fileName = WebUtility.HtmlEncode(
Path.GetFileName(formFile.FileName));
if (formFile.ContentType.ToLower() != "text/plain")
{
$"The {fieldDisplayName}file ({fileName}) must be a text file.");
}
// Check the file length and don't bother attempting to

// read it if the file contains no content. This check
// doesn't catch files that only have a BOM as their
// content, so a content length check is made later after
// reading the file's content to catch a file that only
// contains a BOM.
if (formFile.Length == 0)
{
}
else if (formFile.Length > 1048576)
{
$"The {fieldDisplayName}file ({fileName}) exceeds 1 MB.");
}
else
{
try
{
string fileContents;
// The StreamReader is created to read files that are UTF-8 encoded.

// using statement. To change to 32-bit encoding, change
// new UTF8Encoding(...) to new UTF32Encoding().
using (
var reader =
new StreamReader(
formFile.OpenReadStream(),
new UTF8Encoding(encoderShouldEmitUTF8Identifier: false,
throwOnInvalidBytes: true),
detectEncodingFromByteOrderMarks: true))
{
fileContents = await reader.ReadToEndAsync();
// Check the content length in case the file's only

// content was a BOM and the content is actually
// empty after removing the BOM.
if (fileContents.Length > 0)
{
return fileContents;
}
}
else
{
}
}
}
{
$"The {fieldDisplayName}file ({fileName}) upload failed. " +
$"Please contact the Help Desk for support. Error: {ex.Message}");
// Log the exception
}
}
}
}
}
Save the file to disk

The sample app saves uploaded files into database fields. To save a file to disk, use a FileStream. The following
example copies a file held by FileUpload.UploadPublicSchedule to a FileStream in an OnPostAsync method. The
FileStream writes the file to disk at the <PATH-AND-FILE-NAME> provided:

{
// Perform an initial check to catch FileUpload class attribute violations.
{
return Page();
}
var filePath = "<PATH-AND-FILE-NAME>";
using (var fileStream = new FileStream(filePath, FileMode.Create))

{
await FileUpload.UploadPublicSchedule.CopyToAsync(fileStream);
}
}
The worker process must have write permissions to the location specified by filePath .
NOTE
The filePath must include the file name. If the file name isn't provided, an UnauthorizedAccessException is thrown at
runtime.
WARNING
Never persist uploaded files in the same directory tree as the app.
The code sample provides no server-side protection against malicious file uploads. For information on reducing the attack
surface area when accepting files from users, see the following resources:
Unrestricted File Upload
Azure Security: Ensure appropriate controls are in place when accepting files from users
Save the file to Azure Blob Storage

To upload file content to Azure Blob Storage, see Get started with Azure Blob Storage using .NET. The topic
demonstrates how to use UploadFromStream to save a FileStream to blob storage.
Add the Schedule class

Right click the Models folder. Select Add > Class. Name the class Schedule and add the following properties:
using System;
{
public class Schedule
{
public string PublicSchedule { get; set; }
[Display(Name = "Public Schedule Size (bytes)")]

[DisplayFormat(DataFormatString = "{0:N1}")]
public long PublicScheduleSize { get; set; }
public string PrivateSchedule { get; set; }
[Display(Name = "Private Schedule Size (bytes)")]

public long PrivateScheduleSize { get; set; }
[Display(Name = "Uploaded (UTC)")]

[DisplayFormat(DataFormatString = "{0:F}")]
public DateTime UploadDT { get; set; }
}
}
using System;
{
public class Schedule
{
public string PublicSchedule { get; set; }
[Display(Name = "Public Schedule Size (bytes)")]

public long PublicScheduleSize { get; set; }
public string PrivateSchedule { get; set; }
[Display(Name = "Private Schedule Size (bytes)")]

public long PrivateScheduleSize { get; set; }
[Display(Name = "Uploaded (UTC)")]

[DisplayFormat(DataFormatString = "{0:F}")]
public DateTime UploadDT { get; set; }
}
}
The class uses Display and DisplayFormat attributes, which produce friendly titles and formatting when the
schedule data is rendered.
Update the RazorPagesMovieContext

Specify a DbSet in the RazorPagesMovieContext (Data/RazorPagesMovieContext.cs) for the schedules:
using System;
using System.Linq;
{
public class RazorPagesMovieContext : DbContext
{
public RazorPagesMovieContext (DbContextOptions<RazorPagesMovieContext> options)
: base(options)
{
}
public DbSet<RazorPagesMovie.Models.Movie> Movie { get; set; }

public DbSet<RazorPagesMovie.Models.Schedule> Schedule { get; set; }
}
}
Update the MovieContext

Specify a DbSet in the MovieContext (Models/MovieContext.cs) for the schedules:
{
{
: base(options)
{
}

public DbSet<Schedule> Schedule { get; set; }
}
}
Add the Schedule table to the database

Open the Package Manger Console (PMC ): Tools > NuGet Package Manager > Package Manager Console.
In the PMC, execute the following commands. These commands add a Schedule table to the database:
Add-Migration AddScheduleTable
Update-Database
Add a file upload Razor Page

In the Pages folder, create a Schedules folder. In the Schedules folder, create a page named Index.cshtml for
uploading a schedule with the following content:
@page
@model RazorPagesMovie.Pages.Schedules.IndexModel
@{
ViewData["Title"] = "Schedules";
}
<h2>Schedules</h2>
<hr />
<h3>Upload Schedules</h3>
<div class="row">
<form method="post" enctype="multipart/form-data">
<label asp-for="FileUpload.Title" class="control-label"></label>
<input asp-for="FileUpload.Title" type="text" class="form-control" />
<span asp-validation-for="FileUpload.Title" class="text-danger"></span>
</div>
<label asp-for="FileUpload.UploadPublicSchedule" class="control-label"></label>
<input asp-for="FileUpload.UploadPublicSchedule" type="file" class="form-control"
style="height:auto" />
<span asp-validation-for="FileUpload.UploadPublicSchedule" class="text-danger"></span>
</div>
<label asp-for="FileUpload.UploadPrivateSchedule" class="control-label"></label>
<input asp-for="FileUpload.UploadPrivateSchedule" type="file" class="form-control"
<span asp-validation-for="FileUpload.UploadPrivateSchedule" class="text-danger"></span>
</div>
<input type="submit" value="Upload" class="btn btn-default" />
</form>
</div>
</div>
<h3>Loaded Schedules</h3>
<thead>
<tr>
<th></th>
<th>
@Html.DisplayNameFor(model => model.Schedule[0].Title)
</th>
<th>
@Html.DisplayNameFor(model => model.Schedule[0].UploadDT)
</th>
<th class="text-center">
@Html.DisplayNameFor(model => model.Schedule[0].PublicScheduleSize)
</th>
@Html.DisplayNameFor(model => model.Schedule[0].PrivateScheduleSize)
</th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Schedule) {
<tr>
<td>
</td>
<td>
</td>
<td>
@Html.DisplayFor(modelItem => item.UploadDT)
</td>
<td class="text-center">
@Html.DisplayFor(modelItem => item.PublicScheduleSize)
</td>
@Html.DisplayFor(modelItem => item.PrivateScheduleSize)
</td>
</tr>
}
</tbody>
</table>
@section Scripts {
@section Scripts {
}
@page
@model RazorPagesMovie.Pages.Schedules.IndexModel
@{
ViewData["Title"] = "Schedules";
}
<h2>Schedules</h2>
<hr />
<h3>Upload Schedules</h3>
<div class="row">
<form method="post" enctype="multipart/form-data">
<label asp-for="FileUpload.Title" class="control-label"></label>
<input asp-for="FileUpload.Title" type="text" class="form-control" />
<span asp-validation-for="FileUpload.Title" class="text-danger"></span>
</div>
<label asp-for="FileUpload.UploadPublicSchedule" class="control-label"></label>
<input asp-for="FileUpload.UploadPublicSchedule" type="file" class="form-control"
<span asp-validation-for="FileUpload.UploadPublicSchedule" class="text-danger"></span>
</div>
<label asp-for="FileUpload.UploadPrivateSchedule" class="control-label"></label>
<input asp-for="FileUpload.UploadPrivateSchedule" type="file" class="form-control"
<span asp-validation-for="FileUpload.UploadPrivateSchedule" class="text-danger"></span>
</div>
<input type="submit" value="Upload" class="btn btn-default" />
</form>
</div>
</div>
<h3>Loaded Schedules</h3>
<thead>
<tr>
<th></th>
<th>
@Html.DisplayNameFor(model => model.Schedule[0].Title)
</th>
<th>
@Html.DisplayNameFor(model => model.Schedule[0].UploadDT)
</th>
@Html.DisplayNameFor(model => model.Schedule[0].PublicScheduleSize)
</th>
@Html.DisplayNameFor(model => model.Schedule[0].PrivateScheduleSize)
</th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Schedule) {
<tr>
<td>
</td>
<td>
</td>
<td>
@Html.DisplayFor(modelItem => item.UploadDT)
</td>
@Html.DisplayFor(modelItem => item.PublicScheduleSize)
</td>
@Html.DisplayFor(modelItem => item.PrivateScheduleSize)
</td>
</tr>
}
</tbody>
</table>
@section Scripts {
}
Each form group includes a <label> that displays the name of each class property. The Display attributes in the
FileUpload model provide the display values for the labels. For example, the UploadPublicSchedule property's
display name is set with [Display(Name="Public Schedule")] and thus displays "Public Schedule" in the label when
the form renders.
Each form group includes a validation <span>. If the user's input fails to meet the property attributes set in the
FileUpload class or if any of the ProcessFormFile method file validation checks fail, the model fails to validate.
When model validation fails, a helpful validation message is rendered to the user. For example, the Title property
is annotated with [Required] and [StringLength(60, MinimumLength = 3)] . If the user fails to supply a title, they
receive a message indicating that a value is required. If the user enters a value less than three characters or more
than sixty characters, they receive a message indicating that the value has an incorrect length. If a file is provided
that has no content, a message appears indicating that the file is empty.
Add the page model

Add the page model (Index.cshtml.cs) to the Schedules folder:
using System;
using RazorPagesMovie.Utilities;
namespace RazorPagesMovie.Pages.Schedules
{
{

{
_context = context;
}
[BindProperty]
public FileUpload FileUpload { get; set; }
public IList<Schedule> Schedule { get; private set; }

{
Schedule = await _context.Schedule.AsNoTracking().ToListAsync();
}

{
// Perform an initial check to catch FileUpload class
// attribute violations.
{
return Page();
}
var publicScheduleData =
await FileHelpers.ProcessFormFile(FileUpload.UploadPublicSchedule, ModelState);
var privateScheduleData =
await FileHelpers.ProcessFormFile(FileUpload.UploadPrivateSchedule, ModelState);
// Perform a second check to catch ProcessFormFile method

// violations.
{
return Page();
}
var schedule = new Schedule()

{
PublicSchedule = publicScheduleData,
PublicScheduleSize = FileUpload.UploadPublicSchedule.Length,
PrivateSchedule = privateScheduleData,
PrivateScheduleSize = FileUpload.UploadPrivateSchedule.Length,
Title = FileUpload.Title,
UploadDT = DateTime.UtcNow
};
_context.Schedule.Add(schedule);
}
}
}
using System;
using RazorPagesMovie.Utilities;
{
{

{
_context = context;
}
[BindProperty]

{
}

{
{
return Page();
}
await FileHelpers.ProcessFormFile(FileUpload.UploadPublicSchedule, ModelState);
await FileHelpers.ProcessFormFile(FileUpload.UploadPrivateSchedule, ModelState);
// Perform a second check to catch ProcessFormFile method

// violations.
{
return Page();
}

{
};
}
}
}
The page model ( IndexModel in Index.cshtml.cs) binds the FileUpload class:
[BindProperty]
[BindProperty]
The model also uses a list of the schedules ( IList<Schedule> ) to display the schedules stored in the database on
the page:

When the page loads with OnGetAsync , Schedules is populated from the database and used to generate an HTML
table of loaded schedules:

{
}

{
}
When the form is posted to the server, the ModelState is checked. If invalid, Schedule is rebuilt, and the page
renders with one or more validation messages stating why page validation failed. If valid, the FileUpload
properties are used in OnPostAsync to complete the file upload for the two versions of the schedule and to create a
new Schedule object to store the data. The schedule is then saved to the database:

{
{
return Page();
}
await FileHelpers.ProcessSchedule(FileUpload.UploadPublicSchedule, ModelState);
await FileHelpers.ProcessSchedule(FileUpload.UploadPrivateSchedule, ModelState);
// Perform a second check to catch ProcessSchedule method

// violations.
{
return Page();
}

{
};
}
{
{
return Page();
}
await FileHelpers.ProcessSchedule(FileUpload.UploadPublicSchedule, ModelState);
await FileHelpers.ProcessSchedule(FileUpload.UploadPrivateSchedule, ModelState);
// Perform a second check to catch ProcessSchedule method

// violations.
{
return Page();
}

{
};
}
Link the file upload Razor Page

Open Pages/Shared/_Layout.cshtml and add a link to the navigation bar to reach the Schedules page:

<li><a asp-page="/Schedules/Index">Schedules</a></li>
<li><a asp-page="/Contact">Contact</a></li>
</ul>
</div>
Add a page to confirm schedule deletion

When the user clicks to delete a schedule, a chance to cancel the operation is provided. Add a delete confirmation
page (Delete.cshtml) to the Schedules folder:
@page "{id:int}"
@model RazorPagesMovie.Pages.Schedules.DeleteModel
@{
ViewData["Title"] = "Delete Schedule";
}
<h2>Delete Schedule</h2>

<div>
<h4>Schedule</h4>
<hr />
<dt>
@Html.DisplayNameFor(model => model.Schedule.Title)
</dt>
<dd>
@Html.DisplayFor(model => model.Schedule.Title)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Schedule.PublicScheduleSize)
</dt>
<dd>
@Html.DisplayFor(model => model.Schedule.PublicScheduleSize)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Schedule.PrivateScheduleSize)
</dt>
<dd>
@Html.DisplayFor(model => model.Schedule.PrivateScheduleSize)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Schedule.UploadDT)
</dt>
<dd>
@Html.DisplayFor(model => model.Schedule.UploadDT)
</dd>
</dl>
<input type="hidden" asp-for="Schedule.ID" />
</form>
</div>
@page "{id:int}"
@model RazorPagesMovie.Pages.Schedules.DeleteModel
@{
ViewData["Title"] = "Delete Schedule";
}
<h2>Delete Schedule</h2>

<div>
<h4>Schedule</h4>
<hr />
<dt>
@Html.DisplayNameFor(model => model.Schedule.Title)
</dt>
<dd>
@Html.DisplayFor(model => model.Schedule.Title)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Schedule.PublicScheduleSize)
</dt>
<dd>
@Html.DisplayFor(model => model.Schedule.PublicScheduleSize)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Schedule.PrivateScheduleSize)
</dt>
<dd>
@Html.DisplayFor(model => model.Schedule.PrivateScheduleSize)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Schedule.UploadDT)
</dt>
<dd>
@Html.DisplayFor(model => model.Schedule.UploadDT)
</dd>
</dl>
<input type="hidden" asp-for="Schedule.ID" />
</form>
</div>
The page model (Delete.cshtml.cs) loads a single schedule identified by id in the request's route data. Add the
Delete.cshtml.cs file to the Schedules folder:
{
{
public DeleteModel(RazorPagesMovie.Models.RazorPagesMovieContext context)

{
_context = context;
}
[BindProperty]
public Schedule Schedule { get; set; }

{
if (id == null)
{
return NotFound();
}
Schedule = await _context.Schedule.SingleOrDefaultAsync(m => m.ID == id);
if (Schedule == null)
{
return NotFound();
}
return Page();
}

{
if (id == null)
{
return NotFound();
}
Schedule = await _context.Schedule.FindAsync(id);
if (Schedule != null)
{
_context.Schedule.Remove(Schedule);
}
}
}
}
using System;
using System.Linq;
{
{
public DeleteModel(RazorPagesMovie.Models.MovieContext context)

{
_context = context;
}
[BindProperty]
public Schedule Schedule { get; set; }

{
if (id == null)
{
return NotFound();
}
Schedule = await _context.Schedule.SingleOrDefaultAsync(m => m.ID == id);
if (Schedule == null)
{
return NotFound();
}
return Page();
}

{
if (id == null)
{
return NotFound();
}
{
}
}
}
}
The OnPostAsync method handles deleting the schedule by its id :

{
if (id == null)
{
return NotFound();
}
{
}
}

{
if (id == null)
{
return NotFound();
}
{
}
}
After successfully deleting the schedule, the RedirectToPage sends the user back to the schedules Index.cshtml
page.
The working Schedules Razor Page

When the page loads, labels and inputs for schedule title, public schedule, and private schedule are rendered with a
submit button:
Selecting the Upload button without populating any of the fields violates the [Required] attributes on the model.
The ModelState is invalid. The validation error messages are displayed to the user:
Type two letters into the Title field. The validation message changes to indicate that the title must be between 3-60
characters:
When one or more schedules are uploaded, the Loaded Schedules section renders the loaded schedules:
The user can click the Delete link from there to reach the delete confirmation view, where they have an
opportunity to confirm or cancel the delete operation.
Troubleshooting
For troubleshooting information with IFormFile uploading, see the File uploads in ASP.NET Core:
Troubleshooting.
ASP.NET Core Razor SDK
By Rick Anderson
The .NET Core 2.1 SDK or later includes the Microsoft.NET.Sdk.Razor MSBuild SDK (Razor SDK). The Razor SDK:
Standardizes the experience around building, packaging, and publishing projects containing Razor files for
ASP.NET Core MVC -based projects.
Includes a set of predefined targets, properties, and items that allow customizing the compilation of Razor files.
Prerequisites
Using the Razor SDK

Most web apps don't need to expressly reference the Razor SDK.
To use the Razor SDK to build class libraries containing Razor views or Razor Pages:
Use Microsoft.NET.Sdk.Razor instead of Microsoft.NET.Sdk :
<Project SDK="Microsoft.NET.Sdk.Razor">
...
</Project>
Typically a package reference to Microsoft.AspNetCore.Mvc is required to bring in additional dependencies

required to build and compile Razor Pages and Razor views. At minimum, your project needs to add
package references to:
Microsoft.AspNetCore.Razor.Design
Microsoft.AspNetCore.Mvc.Razor.Extensions
The preceding packages are included in Microsoft.AspNetCore.Mvc . The following markup shows a basic .csproj file
that uses the Razor SDK to build Razor files for an ASP.NET Core Razor Pages app:
<Project Sdk="Microsoft.NET.Sdk.Razor">
<PropertyGroup>
</PropertyGroup>
<ItemGroup>
</ItemGroup>
</Project>
Properties
The following properties control the Razor's SDK behavior as part of a project build:
RazorCompileOnBuild : When true , compiles and emits the Razor assembly as part of building the project.
Defaults to true .
RazorCompileOnPublish : When true , compiles and emits the Razor assembly as part of publishing the project.
Defaults to true .
The following properties and items are used to configure inputs and output to the Razor SDK:
ITEMS DESCRIPTION
RazorGenerate Item elements (.cshtml files) that are inputs to code

generation targets.
RazorCompile Item elements (.cs files) that are inputs to Razor compilation
targets. Use this ItemGroup to specify additional files to be
compiled into the Razor assembly.
RazorTargetAssemblyAttribute Item elements used to code generate attributes for the Razor
assembly. For example:
<RazorAssemblyAttribute
Include="System.Reflection.AssemblyMetadataAttribute"
_Parameter1="BuildSource"
_Parameter2="https://docs.asp.net/">
RazorEmbeddedResource Item elements added as embedded resources to the

generated Razor assembly
PROPERTY DESCRIPTION
RazorTargetName File name (without extension) of the assembly produced by

Razor.
RazorOutputPath The Razor output directory.
RazorCompileToolset Used to determine the toolset used to build the Razor

assembly. Valid values are Implicit , , and
PrecompilationTool .
EnableDefaultContentItems When true , includes certain file types, such as .cshtml files,
as content in the project. When referenced via
Microsoft.NET.Sdk.Web, also includes all files under wwwroot,
and config files.
EnableDefaultRazorGenerateItems When true , includes .cshtml files from Content items in

RazorGenerate items.
GenerateRazorTargetAssemblyInfo When true , generates a .cs file containing attributes

specified by RazorAssemblyAttribute and includes it in the
compile output.
EnableDefaultRazorTargetAssemblyInfoAttributes When true , adds a default set of assembly attributes to

RazorAssemblyAttribute .
CopyRazorGenerateFilesToPublishDirectory When true , copies RazorGenerate items (.cshtml) files to the

publish directory. Typically Razor files are not needed for a
published application if they participate in compilation at
build-time or publish-time. Defaults to false .
CopyRefAssembliesToPublishDirectory When true , copy reference assembly items to the publish

directory. Typically reference assemblies are not needed for a
published application if Razor compilation occurs at build-time
or publish-time. Set to true , if your published application
requires runtime compilation, for example, modifies cshtml
files at runtime, or uses embedded views. Defaults to false .
IncludeRazorContentInPack When true , all Razor content items (.cshtml files) will be
marked for inclusion in the generated NuGet package.
Defaults to false .
EmbedRazorGenerateSources When true , adds RazorGenerate (.cshtml) items as

embedded files to the generated Razor assembly. Defaults to
false .
UseRazorBuildServer When true , uses a persistent build server process to offload

code generation work. Defaults to the value of
UseSharedCompilation .
Targets
The Razor SDK defines two primary targets:
RazorGenerate - Code generates .cs files from RazorGenerate item elements. Use RazorGenerateDependsOn
property to specify additional targets that can run before or after this target.
RazorCompile - Compiles generated .cs files in to a Razor assembly. Use RazorCompileDependsOn to specify
additional targets that can run before or after this target.
Runtime compilation of Razor views
By default, the Razor SDK doesn't publish reference assemblies that are required to perform runtime
compilation. This results in compilation failures when the application model relies on runtime compilation—
for example, the app uses embedded views or changes views after the app is published. Set
CopyRefAssembliesToPublishDirectory to true to continue publishing reference assemblies.
For web applications, ensure your app is targeting Microsoft.NET.Sdk.Web SDK.

Overview of ASP.NET Core MVC
By Steve Smith
ASP.NET Core MVC is a rich framework for building web apps and APIs using the Model-View -Controller
design pattern.
What is the MVC pattern?

The Model-View -Controller (MVC ) architectural pattern separates an application into three main groups of
components: Models, Views, and Controllers. This pattern helps to achieve separation of concerns. Using this
pattern, user requests are routed to a Controller which is responsible for working with the Model to perform user
actions and/or retrieve results of queries. The Controller chooses the View to display to the user, and provides it
with any Model data it requires.
The following diagram shows the three main components and which ones reference the others:
This delineation of responsibilities helps you scale the application in terms of complexity because it's easier to
code, debug, and test something (model, view, or controller) that has a single job (and follows the Single
Responsibility Principle). It's more difficult to update, test, and debug code that has dependencies spread across
two or more of these three areas. For example, user interface logic tends to change more frequently than
business logic. If presentation code and business logic are combined in a single object, an object containing
business logic must be modified every time the user interface is changed. This often introduces errors and
requires the retesting of business logic after every minimal user interface change.
NOTE
Both the view and the controller depend on the model. However, the model depends on neither the view nor the
controller. This is one of the key benefits of the separation. This separation allows the model to be built and tested
independent of the visual presentation.
Model Responsibilities
The Model in an MVC application represents the state of the application and any business logic or operations
that should be performed by it. Business logic should be encapsulated in the model, along with any
implementation logic for persisting the state of the application. Strongly-typed views typically use ViewModel
types designed to contain the data to display on that view. The controller creates and populates these ViewModel
instances from the model.
NOTE
There are many ways to organize the model in an app that uses the MVC architectural pattern. Learn more about some
different kinds of model types.
View Responsibilities
Views are responsible for presenting content through the user interface. They use the Razor view engine to
embed .NET code in HTML markup. There should be minimal logic within views, and any logic in them should
relate to presenting content. If you find the need to perform a great deal of logic in view files in order to display
data from a complex model, consider using a View Component, ViewModel, or view template to simplify the
view.
Controller Responsibilities
Controllers are the components that handle user interaction, work with the model, and ultimately select a view to
render. In an MVC application, the view only displays information; the controller handles and responds to user
input and interaction. In the MVC pattern, the controller is the initial entry point, and is responsible for selecting
which model types to work with and which view to render (hence its name - it controls how the app responds to
a given request).
NOTE
Controllers shouldn't be overly complicated by too many responsibilities. To keep controller logic from becoming overly
complex, use the Single Responsibility Principle to push business logic out of the controller and into the domain model.
TIP
If you find that your controller actions frequently perform the same kinds of actions, you can follow the Don't Repeat
Yourself principle by moving these common actions into filters.
What is ASP.NET Core MVC

The ASP.NET Core MVC framework is a lightweight, open source, highly testable presentation framework
optimized for use with ASP.NET Core.
ASP.NET Core MVC provides a patterns-based way to build dynamic websites that enables a clean separation of
concerns. It gives you full control over markup, supports TDD -friendly development and uses the latest web
standards.
Features
ASP.NET Core MVC includes the following:
Routing
Model binding
Model validation
Filters
Areas
Web APIs
Testability
Razor view engine
Strongly typed views
Tag Helpers
View Components
Routing
ASP.NET Core MVC is built on top of ASP.NET Core's routing, a powerful URL -mapping component that lets
you build applications that have comprehensible and searchable URLs. This enables you to define your
application's URL naming patterns that work well for search engine optimization (SEO ) and for link generation,
without regard for how the files on your web server are organized. You can define your routes using a
convenient route template syntax that supports route value constraints, defaults and optional values.
Convention-based routing enables you to globally define the URL formats that your application accepts and how
each of those formats maps to a specific action method on given controller. When an incoming request is
received, the routing engine parses the URL and matches it to one of the defined URL formats, and then calls the
associated controller's action method.
routes.MapRoute(name: "Default", template: "{controller=Home}/{action=Index}/{id?}");
Attribute routing enables you to specify routing information by decorating your controllers and actions with
attributes that define your application's routes. This means that your route definitions are placed next to the
controller and action with which they're associated.
public class ProductsController : Controller
{
[HttpGet("{id}")]
public IActionResult GetProduct(int id)
{
...
}
}
Model binding
ASP.NET Core MVC model binding converts client request data (form values, route data, query string
parameters, HTTP headers) into objects that the controller can handle. As a result, your controller logic doesn't
have to do the work of figuring out the incoming request data; it simply has the data as parameters to its action
methods.
public async Task<IActionResult> Login(LoginViewModel model, string returnUrl = null) { ... }
Model validation
ASP.NET Core MVC supports validation by decorating your model object with data annotation validation
attributes. The validation attributes are checked on the client side before values are posted to the server, as well
as on the server before the controller action is called.
public class LoginViewModel
{
[Required]
[EmailAddress]
[Required]
[Display(Name = "Remember me?")]

public bool RememberMe { get; set; }
}
A controller action:
public async Task<IActionResult> Login(LoginViewModel model, string returnUrl = null)

{
{
// work with the model
}
// At this point, something failed, redisplay form
return View(model);
}
The framework handles validating request data both on the client and on the server. Validation logic specified on
model types is added to the rendered views as unobtrusive annotations and is enforced in the browser with
jQuery Validation.
ASP.NET Core has built-in support for dependency injection (DI). In ASP.NET Core MVC, controllers can
request needed services through their constructors, allowing them to follow the Explicit Dependencies Principle.
Your app can also use dependency injection in view files, using the @inject directive:
@inject SomeService ServiceName

<!DOCTYPE html>
<html lang="en">
<head>
<title>@ServiceName.GetTitle</title>
</head>
<body>
<h1>@ServiceName.GetTitle</h1>
</body>
</html>
Filters
Filters help developers encapsulate cross-cutting concerns, like exception handling or authorization. Filters
enable running custom pre- and post-processing logic for action methods, and can be configured to run at
certain points within the execution pipeline for a given request. Filters can be applied to controllers or actions as
attributes (or can be run globally). Several filters (such as Authorize ) are included in the framework.
[Authorize] is the attribute that is used to create MVC authorization filters.
[Authorize]
public class AccountController : Controller
{
Areas
Areas provide a way to partition a large ASP.NET Core MVC Web app into smaller functional groupings. An area
is an MVC structure inside an application. In an MVC project, logical components like Model, Controller, and
View are kept in different folders, and MVC uses naming conventions to create the relationship between these
components. For a large app, it may be advantageous to partition the app into separate high level areas of
functionality. For instance, an e-commerce app with multiple business units, such as checkout, billing, and search
etc. Each of these units have their own logical component views, controllers, and models.
Web APIs
In addition to being a great platform for building web sites, ASP.NET Core MVC has great support for building
Web APIs. You can build services that reach a broad range of clients including browsers and mobile devices.
The framework includes support for HTTP content-negotiation with built-in support to format data as JSON or
XML. Write custom formatters to add support for your own formats.
Use link generation to enable support for hypermedia. Easily enable support for cross-origin resource sharing
(CORS ) so that your Web APIs can be shared across multiple Web applications.
Testability
The framework's use of interfaces and dependency injection make it well-suited to unit testing, and the
framework includes features (like a TestHost and InMemory provider for Entity Framework) that make
integration tests quick and easy as well. Learn more about how to test controller logic.
Razor view engine
ASP.NET Core MVC views use the Razor view engine to render views. Razor is a compact, expressive and fluid
template markup language for defining views using embedded C# code. Razor is used to dynamically generate
web content on the server. You can cleanly mix server code with client side content and code.
<ul>
@for (int i = 0; i < 5; i++) {
<li>List item @i</li>
}
</ul>
Using the Razor view engine you can define layouts, partial views and replaceable sections.
Strongly typed views
Razor views in MVC can be strongly typed based on your model. Controllers can pass a strongly typed model to
views enabling your views to have type checking and IntelliSense support.
For example, the following view renders a model of type IEnumerable<Product> :
@model IEnumerable<Product>
<ul>
@foreach (Product p in Model)
{
<li>@p.Name</li>
}
</ul>
Tag Helpers
Tag Helpers enable server side code to participate in creating and rendering HTML elements in Razor files. You
can use tag helpers to define custom tags (for example, <environment> ) or to modify the behavior of existing tags
(for example, <label> ). Tag Helpers bind to specific elements based on the element name and its attributes. They
provide the benefits of server-side rendering while still preserving an HTML editing experience.
There are many built-in Tag Helpers for common tasks - such as creating forms, links, loading assets and more -
and even more available in public GitHub repositories and as NuGet packages. Tag Helpers are authored in C#,
and they target HTML elements based on element name, attribute name, or parent tag. For example, the built-in
LinkTagHelper can be used to create a link to the Login action of the AccountsController :
<p>
Thank you for confirming your email.
Please <a asp-controller="Account" asp-action="Login">Click here to Log in</a>.
</p>
The EnvironmentTagHelper can be used to include different scripts in your views (for example, raw or minified)
based on the runtime environment, such as Development, Staging, or Production:
</environment>
asp-fallback-test="window.jQuery">
</script>
</environment>
Tag Helpers provide an HTML -friendly development experience and a rich IntelliSense environment for creating
HTML and Razor markup. Most of the built-in Tag Helpers target existing HTML elements and provide server-
side attributes for the element.
View Components
View Components allow you to package rendering logic and reuse it throughout the application. They're similar
to partial views, but with associated logic.
Compatibility version
introduced in ASP.NET Core MVC 2.1 or later.
Model Binding in ASP.NET Core
By Rachel Appel
Introduction to model binding

Model binding in ASP.NET Core MVC maps data from HTTP requests to action method parameters. The
parameters may be simple types such as strings, integers, or floats, or they may be complex types. This is
a great feature of MVC because mapping incoming data to a counterpart is an often repeated scenario,
regardless of size or complexity of the data. MVC solves this problem by abstracting binding away so
developers don't have to keep rewriting a slightly different version of that same code in every app.
Writing your own text to type converter code is tedious, and error prone.
How model binding works

When MVC receives an HTTP request, it routes it to a specific action method of a controller. It determines
which action method to run based on what is in the route data, then it binds values from the HTTP
request to that action method's parameters. For example, consider the following URL:
http://contoso.com/movies/edit/2
Since the route template looks like this, {controller=Home}/{action=Index}/{id?} , movies/edit/2 routes to
the Movies controller, and its Edit action method. It also accepts an optional parameter called id . The
code for the action method should look something like this:
public IActionResult Edit(int? id)
Note: The strings in the URL route are not case sensitive.
MVC will try to bind request data to the action parameters by name. MVC will look for values for each
parameter using the parameter name and the names of its public settable properties. In the above
example, the only action parameter is named id , which MVC binds to the value with the same name in
the route values. In addition to route values MVC will bind data from various parts of the request and it
does so in a set order. Below is a list of the data sources in the order that model binding looks through
them:
1. Form values : These are form values that go in the HTTP request using the POST method.
(including jQuery POST requests).
2. Route values : The set of route values provided by Routing
3. Query strings : The query string part of the URI.
Note: Form values, route data, and query strings are all stored as name-value pairs.
Since model binding asked for a key named id and there's nothing named id in the form values, it
moved on to the route values looking for that key. In our example, it's a match. Binding happens, and the
value is converted to the integer 2. The same request using Edit(string id) would convert to the string "2".
So far the example uses simple types. In MVC simple types are any .NET primitive type or type with a
string type converter. If the action method's parameter were a class such as the Movie type, which
contains both simple and complex types as properties, MVC's model binding will still handle it nicely. It
uses reflection and recursion to traverse the properties of complex types looking for matches. Model
binding looks for the pattern parameter_name.property_name to bind values to properties. If it doesn't
find matching values of this form, it will attempt to bind using just the property name. For those types
such as Collection types, model binding looks for matches to parameter_name[index] or just [index].
Model binding treats Dictionary types similarly, asking for parameter_name[key ] or just [key ], as long as
the keys are simple types. Keys that are supported match the field names HTML and tag helpers
generated for the same model type. This enables round-tripping values so that the form fields remain
filled with the user's input for their convenience, for example, when bound data from a create or edit
didn't pass validation.
In order for binding to happen the class must have a public default constructor and member to be bound
must be public writable properties. When model binding happens the class will only be instantiated using
the public default constructor, then the properties can be set.
When a parameter is bound, model binding stops looking for values with that name and it moves on to
bind the next parameter. Otherwise, the default model binding behavior sets parameters to their default
values depending on their type:
T[] : With the exception of arrays of type byte[] , binding sets parameters of type T[] to
Array.Empty<T>() . Arrays of type byte[] are set to null .
Reference Types: Binding creates an instance of a class with the default constructor without setting
properties. However, model binding sets string parameters to null .
Nullable Types: Nullable types are set to null . In the above example, model binding sets id to
null since it's of type int? .
Value Types: Non-nullable value types of type T are set to default(T) . For example, model
binding will set a parameter int id to 0. Consider using model validation or nullable types rather
than relying on default values.
If binding fails, MVC doesn't throw an error. Every action which accepts user input should check the
ModelState.IsValid property.
Note: Each entry in the controller's ModelState property is a ModelStateEntry containing an Errors
property. It's rarely necessary to query this collection yourself. Use ModelState.IsValid instead.
Additionally, there are some special data types that MVC must consider when performing model binding:
IFormFile , IEnumerable<IFormFile> : One or more uploaded files that are part of the HTTP request.
CancellationToken : Used to cancel activity in asynchronous controllers.
These types can be bound to action parameters or to properties on a class type.
Once model binding is complete, Validation occurs. Default model binding works great for the vast
majority of development scenarios. It's also extensible so if you have unique needs you can customize the
built-in behavior.
Customize model binding behavior with attributes

MVC contains several attributes that you can use to direct its default model binding behavior to a
different source. For example, you can specify whether binding is required for a property, or if it should
never happen at all by using the [BindRequired] or [BindNever] attributes. Alternatively, you can
override the default data source, and specify the model binder's data source. Below is a list of model
binding attributes:
[BindRequired] : This attribute adds a model state error if binding cannot occur.
[BindNever] : Tells the model binder to never bind to this parameter.
[FromHeader], [FromQuery] , [FromRoute] , [FromForm] : Use these to specify the exact binding
source you want to apply.
[FromServices] : This attribute uses dependency injection to bind parameters from services.
[FromBody] : Use the configured formatters to bind data from the request body. The formatter is
selected based on content type of the request.
[ModelBinder] : Used to override the default model binder, binding source and name.
Attributes are very helpful tools when you need to override the default behavior of model binding.
Customize model binding and validation globally

The model binding and validation system's behavior is driven by ModelMetadata that describes:
How a model is to be bound.
How validation occurs on the type and its properties.
Aspects of the system's behavior can be configured globally by adding a details provider to
MvcOptions.ModelMetadataDetailsProviders. MVC has a few built-in details providers that allow
configuring behavior such as disabling model binding or validation for certain types.
To disable model binding on all models of a certain type, add an ExcludeBindingMetadataProvider in
Startup.ConfigureServices . For example, to disable model binding on all models of type System.Version :
services.AddMvc().AddMvcOptions(options =>
options.ModelMetadataDetailsProviders.Add(
new ExcludeBindingMetadataProvider(typeof(System.Version))));
To disable validation on properties of a certain type, add a SuppressChildValidationMetadataProvider in

Startup.ConfigureServices . For example, to disable validation on properties of type System.Guid :
services.AddMvc().AddMvcOptions(options =>
options.ModelMetadataDetailsProviders.Add(
new SuppressChildValidationMetadataProvider(typeof(System.Guid))));
Bind formatted data from the request body

Request data can come in a variety of formats including JSON, XML and many others. When you use the
[FromBody] attribute to indicate that you want to bind a parameter to data in the request body, MVC uses
a configured set of formatters to handle the request data based on its content type. By default MVC
includes a JsonInputFormatter class for handling JSON data, but you can add additional formatters for
handling XML and other custom formats.
NOTE
There can be at most one parameter per action decorated with [FromBody] . The ASP.NET Core MVC run-time
delegates the responsibility of reading the request stream to the formatter. Once the request stream is read for a
parameter, it's generally not possible to read the request stream again for binding other [FromBody] parameters.
NOTE
The JsonInputFormatter is the default formatter and is based on Json.NET.
ASP.NET Core selects input formatters based on the Content-Type header and the type of the parameter,
unless there's an attribute applied to it specifying otherwise. If you'd like to use XML or another format
you must configure it in the Startup.cs file, but you may first have to obtain a reference to
Microsoft.AspNetCore.Mvc.Formatters.Xml using NuGet. Your startup code should look something like this:

{
services.AddMvc()
.AddXmlSerializerFormatters();
}
Code in the Startup.cs file contains a ConfigureServices method with a services argument you can use
to build up services for your ASP.NET Core app. In the sample, we are adding an XML formatter as a
service that MVC will provide for this app. The options argument passed into the AddMvc method allows
you to add and manage filters, formatters, and other system options from MVC upon app startup. Then
apply the Consumes attribute to controller classes or action methods to work with the format you want.
Custom Model Binding
You can extend model binding by writing your own custom model binders. Learn more about custom
model binding.
Model validation in ASP.NET Core MVC
By Rachel Appel
Introduction to model validation

Before an app stores data in a database, the app must validate the data. Data must be checked for potential
security threats, verified that it's appropriately formatted by type and size, and it must conform to your
rules. Validation is necessary although it can be redundant and tedious to implement. In MVC, validation
happens on both the client and server.
Fortunately, .NET has abstracted validation into validation attributes. These attributes contain validation
code, thereby reducing the amount of code you must write.
View or download sample from GitHub.
Validation Attributes
Validation attributes are a way to configure model validation so it's similar conceptually to validation on
fields in database tables. This includes constraints such as assigning data types or required fields. Other
types of validation include applying patterns to data to enforce business rules, such as a credit card, phone
number, or email address. Validation attributes make enforcing these requirements much simpler and
easier to use.
Below is an annotated Movie model from an app that stores information about movies and TV shows.
Most of the properties are required and several string properties have length requirements. Additionally,
there's a numeric range restriction in place for the Price property from 0 to $999.99, along with a custom
validation attribute.
public class Movie

{
[Required]
[StringLength(100)]
[ClassicMovie(1960)]
[Required]
[StringLength(1000)]
public string Description { get; set; }
[Range(0, 999.99)]
[Required]
public Genre Genre { get; set; }
public bool Preorder { get; set; }

}
Simply reading through the model reveals the rules about data for this app, making it easier to maintain
the code. Below are several popular built-in validation attributes:
[CreditCard] : Validates the property has a credit card format.
[Compare] : Validates two properties in a model match.
[EmailAddress] : Validates the property has an email format.
[Phone] : Validates the property has a telephone format.
[Range] : Validates the property value falls within the given range.
[RegularExpression] : Validates that the data matches the specified regular expression.
[Required] : Makes a property required.
[StringLength] : Validates that a string property has at most the given maximum length.
[Url] : Validates the property has a URL format.
MVC supports any attribute that derives from ValidationAttribute for validation purposes. Many useful
validation attributes can be found in the System.ComponentModel.DataAnnotations namespace.
There may be instances where you need more features than built-in attributes provide. For those times,
you can create custom validation attributes by deriving from ValidationAttribute or changing your model
to implement IValidatableObject .
Notes on the use of the Required attribute

Non-nullable value types (such as decimal , int , float , and DateTime ) are inherently required and don't
need the Required attribute. The app performs no server-side validation checks for non-nullable types that
are marked Required .
MVC model binding, which isn't concerned with validation and validation attributes, rejects a form field
submission containing a missing value or whitespace for a non-nullable type. In the absence of a
BindRequired attribute on the target property, model binding ignores missing data for non-nullable types,
where the form field is absent from the incoming form data.
The BindRequired attribute (also see Customize model binding behavior with attributes) is useful to ensure
form data is complete. When applied to a property, the model binding system requires a value for that
property. When applied to a type, the model binding system requires values for all of the properties of that
type.
When you use a Nullable<T> type (for example, decimal? or System.Nullable<decimal> ) and mark it
Required , a server -side validation check is performed as if the property were a standard nullable type (for
example, a string ).
Client-side validation requires a value for a form field that corresponds to a model property that you've
marked Required and for a non-nullable type property that you haven't marked Required . Required can
be used to control the client-side validation error message.
Model State
Model state represents validation errors in submitted HTML form values.
MVC will continue validating fields until reaches the maximum number of errors (200 by default). You can
configure this number by inserting the following code into the ConfigureServices method in the Startup.cs
file:
services.AddMvc(options => options.MaxModelValidationErrors = 50);
Handling Model State Errors

Model validation occurs prior to each controller action being invoked, and it's the action method's
responsibility to inspect ModelState.IsValid and react appropriately. In many cases, the appropriate
reaction is to return an error response, ideally detailing the reason why model validation failed.
Some apps will choose to follow a standard convention for dealing with model validation errors, in which
case a filter may be an appropriate place to implement such a policy. You should test how your actions
behave with valid and invalid model states.
Manual validation
After model binding and validation are complete, you may want to repeat parts of it. For example, a user
may have entered text in a field expecting an integer, or you may need to compute a value for a model's
property.
You may need to run validation manually. To do so, call the TryValidateModel method, as shown here:
TryValidateModel(movie);
Custom validation
Validation attributes work for most validation needs. However, some validation rules are specific to your
business. Your rules might not be common data validation techniques such as ensuring a field is required
or that it conforms to a range of values. For these scenarios, custom validation attributes are a great
solution. Creating your own custom validation attributes in MVC is easy. Just inherit from the
ValidationAttribute , and override the IsValid method. The IsValid method accepts two parameters,
the first is an object named value and the second is a ValidationContext object named validationContext.
Value refers to the actual value from the field that your custom validator is validating.
In the following sample, a business rule states that users may not set the genre to Classic for a movie
released after 1960. The [ClassicMovie] attribute checks the genre first, and if it's a classic, then it checks
the release date to see that it's later than 1960. If it's released after 1960, validation fails. The attribute
accepts an integer parameter representing the year that you can use to validate data. You can capture the
value of the parameter in the attribute's constructor, as shown here:
public class ClassicMovieAttribute : ValidationAttribute, IClientModelValidator
{
private int _year;
public ClassicMovieAttribute(int year)

{
_year = year;
}
protected override ValidationResult IsValid(object value, ValidationContext validationContext)

{
Movie movie = (Movie)validationContext.ObjectInstance;
if (movie.Genre == Genre.Classic && movie.ReleaseDate.Year > _year)

{
return new ValidationResult(GetErrorMessage());
}
return ValidationResult.Success;
}
The movie variable above represents a Movie object that contains the data from the form submission to
validate. In this case, the validation code checks the date and genre in the IsValid method of the
ClassicMovieAttribute class as per the rules. Upon successful validation , IsValid returns a
ValidationResult.Success code. When validation fails, a ValidationResult with an error message is
returned:
private string GetErrorMessage()

{
return $"Classic movies must have a release year earlier than {_year}.";
}
When a user modifies the Genre field and submits the form, the IsValid method of the
ClassicMovieAttribute will verify whether the movie is a classic. Like any built-in attribute, apply the
ClassicMovieAttribute to a property such as ReleaseDate to ensure validation happens, as shown in the
previous code sample. Since the example works only with Movie types, a better option is to use
IValidatableObject as shown in the following paragraph.
Alternatively, this same code could be placed in the model by implementing the Validate method on the
IValidatableObject interface. While custom validation attributes work well for validating individual
properties, implementing IValidatableObject can be used to implement class-level validation as seen here.
public IEnumerable<ValidationResult> Validate(ValidationContext validationContext)

{
if (Genre == Genre.Classic && ReleaseDate.Year > _classicYear)
{
yield return new ValidationResult(
$"Classic movies must have a release year earlier than {_classicYear}.",
new[] { "ReleaseDate" });
}
}
Client side validation

Client side validation is a great convenience for users. It saves time they would otherwise spend waiting for
a round trip to the server. In business terms, even a few fractions of seconds multiplied hundreds of times
each day adds up to be a lot of time, expense, and frustration. Straightforward and immediate validation
enables users to work more efficiently and produce better quality input and output.
You must have a view with the proper JavaScript script references in place for client side validation to work
as you see here.
<script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-2.2.0.min.js"></script>
<script src="https://ajax.aspnetcdn.com/ajax/jquery.validate/1.16.0/jquery.validate.min.js"></script>
<script
src="https://ajax.aspnetcdn.com/ajax/jquery.validation.unobtrusive/3.2.6/jquery.validate.unobtrusive.mi
n.js"></script>
The jQuery Unobtrusive Validation script is a custom Microsoft front-end library that builds on the popular
jQuery Validate plugin. Without jQuery Unobtrusive Validation, you would have to code the same
validation logic in two places: once in the server side validation attributes on model properties, and then
again in client side scripts (the examples for jQuery Validate's validate() method shows how complex this
could become). Instead, MVC's Tag Helpers and HTML helpers are able to use the validation attributes and
type metadata from model properties to render HTML 5 data- attributes in the form elements that need
validation. MVC generates the data- attributes for both built-in and custom attributes. jQuery
Unobtrusive Validation then parses the data- attributes and passes the logic to jQuery Validate, effectively
"copying" the server side validation logic to the client. You can display validation errors on the client using
the relevant tag helpers as shown here:
</div>
</div>
The tag helpers above render the HTML below. Notice that the data- attributes in the HTML output
correspond to the validation attributes for the ReleaseDate property. The data-val-required attribute
below contains an error message to display if the user doesn't fill in the release date field. jQuery
Unobtrusive Validation passes this value to the jQuery Validate required() method, which then displays
that message in the accompanying <span> element.
<form action="/Movies/Create" method="post">

<h4>Movie</h4>
<div class="text-danger"></div>
<label class="col-md-2 control-label" for="ReleaseDate">ReleaseDate</label>
<input class="form-control" type="datetime"
data-val="true" data-val-required="The ReleaseDate field is required."
id="ReleaseDate" name="ReleaseDate" value="" />
<span class="text-danger field-validation-valid"
data-valmsg-for="ReleaseDate" data-valmsg-replace="true"></span>
</div>
</div>
</div>
</form>
Client-side validation prevents submission until the form is valid. The Submit button runs JavaScript that
either submits the form or displays error messages.
MVC determines type attribute values based on the .NET data type of a property, possibly overridden
using [DataType] attributes. The base [DataType] attribute does no real server-side validation. Browsers
choose their own error messages and display those errors as they wish, however the jQuery Validation
Unobtrusive package can override the messages and display them consistently with others. This happens
most obviously when users apply [DataType] subclasses such as [EmailAddress] .
Add Validation to Dynamic Forms
Because jQuery Unobtrusive Validation passes validation logic and parameters to jQuery Validate when the
page first loads, dynamically generated forms won't automatically exhibit validation. Instead, you must tell
jQuery Unobtrusive Validation to parse the dynamic form immediately after creating it. For example, the
code below shows how you might set up client side validation on a form added via AJAX.
$.get({
url: "https://url/that/returns/a/form",
dataType: "html",
error: function(jqXHR, textStatus, errorThrown) {
alert(textStatus + ": Couldn't add form. " + errorThrown);
},
success: function(newFormHTML) {
var container = document.getElementById("form-container");
container.insertAdjacentHTML("beforeend", newFormHTML);
var forms = container.getElementsByTagName("form");
var newForm = forms[forms.length - 1];
$.validator.unobtrusive.parse(newForm);
}
})
The $.validator.unobtrusive.parse() method accepts a jQuery selector for its one argument. This method
tells jQuery Unobtrusive Validation to parse the data- attributes of forms within that selector. The values
of those attributes are then passed to the jQuery Validate plugin so that the form exhibits the desired client
side validation rules.
Add Validation to Dynamic Controls
You can also update the validation rules on a form when individual controls, such as <input/> s and
<select/> s, are dynamically generated. You cannot pass selectors for these elements to the parse()
method directly because the surrounding form has already been parsed and won't update. Instead, you first
remove the existing validation data, then reparse the entire form, as shown below:
$.get({
url: "https://url/that/returns/a/control",
dataType: "html",
error: function(jqXHR, textStatus, errorThrown) {
alert(textStatus + ": Couldn't add control. " + errorThrown);
},
success: function(newInputHTML) {
var form = document.getElementById("my-form");
form.insertAdjacentHTML("beforeend", newInputHTML);
$(form).removeData("validator") // Added by jQuery Validate
.removeData("unobtrusiveValidation"); // Added by jQuery Unobtrusive Validation
$.validator.unobtrusive.parse(form);
}
})
IClientModelValidator
You may create client side logic for your custom attribute, and unobtrusive validation which creates an
adapter to jquery validation will execute it on the client for you automatically as part of validation. The first
step is to control what data- attributes are added by implementing the IClientModelValidator interface as
shown here:
public void AddValidation(ClientModelValidationContext context)

{
if (context == null)
{
throw new ArgumentNullException(nameof(context));
}
MergeAttribute(context.Attributes, "data-val", "true");

MergeAttribute(context.Attributes, "data-val-classicmovie", GetErrorMessage());
var year = _year.ToString(CultureInfo.InvariantCulture);

MergeAttribute(context.Attributes, "data-val-classicmovie-year", year);
}
Attributes that implement this interface can add HTML attributes to generated fields. Examining the output
for the ReleaseDate element reveals HTML that's similar to the previous example, except now there's a
data-val-classicmovie attribute that was defined in the AddValidation method of IClientModelValidator .
<input class="form-control" type="datetime"

data-val="true"
data-val-classicmovie="Classic movies must have a release year earlier than 1960."
data-val-classicmovie-year="1960"
data-val-required="The ReleaseDate field is required."
id="ReleaseDate" name="ReleaseDate" value="" />
Unobtrusive validation uses the data in the data- attributes to display error messages. However, jQuery
doesn't know about rules or messages until you add them to jQuery's validator object. This is shown in
the following example, which adds a custom classicmovie client validation method to the jQuery
validator object. For an explanation of the unobtrusive.adapters.add method, see Unobtrusive Client
Validation in ASP.NET MVC.
$.validator.addMethod('classicmovie',
function (value, element, params) {
// Get element value. Classic genre has value '0'.
var genre = $(params[0]).val(),
year = params[1],
date = new Date(value);
if (genre && genre.length > 0 && genre[0] === '0') {
// Since this is a classic movie, invalid if release date is after given year.
return date.getFullYear() <= year;
}
return true;
});
$.validator.unobtrusive.adapters.add('classicmovie',
['year'],
function (options) {
var element = $(options.form).find('select#Genre')[0];
options.rules['classicmovie'] = [element, parseInt(options.params['year'])];
options.messages['classicmovie'] = options.message;
});
With the preceding code, the classicmovie method performs client-side validation on the movie release
date. The error message displays if the method returns false .
Remote validation
Remote validation is a great feature to use when you need to validate data on the client against data on the
server. For example, your app may need to verify whether an email or user name is already in use, and it
must query a large amount of data to do so. Downloading large sets of data for validating one or a few
fields consumes too many resources. It may also expose sensitive information. An alternative is to make a
round-trip request to validate a field.
You can implement remote validation in a two step process. First, you must annotate your model with the
[Remote] attribute. The [Remote] attribute accepts multiple overloads you can use to direct client side
JavaScript to the appropriate code to call. The example below points to the VerifyEmail action method of
the Users controller.
[Remote(action: "VerifyEmail", controller: "Users")]

The second step is putting the validation code in the corresponding action method as defined in the
[Remote] attribute. According to the jQuery Validate remote method documentation, the server response
must be a JSON string that's either:
"true" for valid elements.
"false" , undefined , or null for invalid elements, using the default error message.
If the server response is a string (for example, "That name is already taken, try peter123 instead" ), the
string is displayed as a custom error message in place of the default string.
The definition of the VerifyEmail method follows these rules, as shown below. It returns a validation error
message if the email is taken, or true if the email is free, and wraps the result in a JsonResult object. The
client side can then use the returned value to proceed or display the error if needed.
[AcceptVerbs("Get", "Post")]
public IActionResult VerifyEmail(string email)
{
if (!_userRepository.VerifyEmail(email))
{
return Json($"Email {email} is already in use.");
}
return Json(true);
}
Now when users enter an email, JavaScript in the view makes a remote call to see if that email has been
taken and, if so, displays the error message. Otherwise, the user can submit the form as usual.
The AdditionalFields property of the [Remote] attribute is useful for validating combinations of fields
against data on the server. For example, if the User model from above had two additional properties
called FirstName and LastName , you might want to verify that no existing users already have that pair of
names. You define the new properties as shown in the following code:
[Remote(action: "VerifyName", controller: "Users", AdditionalFields = nameof(LastName))]

public string FirstName { get; set; }
[Remote(action: "VerifyName", controller: "Users", AdditionalFields = nameof(FirstName))]
AdditionalFields could've been set explicitly to the strings "FirstName" and "LastName" , but using the
nameof operator like this simplifies later refactoring. The action method to perform the validation must
then accept two arguments, one for the value of FirstName and one for the value of LastName .
[AcceptVerbs("Get", "Post")]
public IActionResult VerifyName(string firstName, string lastName)
{
if (!_userRepository.VerifyName(firstName, lastName))
{
return Json(data: $"A user named {firstName} {lastName} already exists.");
}
return Json(data: true);

}
Now when users enter a first and last name, JavaScript:

Makes a remote call to see if that pair of names has been taken.
If the pair has been taken, an error message is displayed.
If not taken, the user can submit the form.
If you need to validate two or more additional fields with the [Remote] attribute, you provide them as a
comma-delimited list. For example, to add a MiddleName property to the model, set the [Remote] attribute
as shown in the following code:
[Remote(action: "VerifyName", controller: "Users", AdditionalFields = nameof(FirstName) + "," +

nameof(LastName))]
public string MiddleName { get; set; }
AdditionalFields , like all attribute arguments, must be a constant expression. Therefore, you must not use
an interpolated string or call string.Join() to initialize AdditionalFields . For every additional field that
you add to the [Remote] attribute, you must add another argument to the corresponding controller action
method.
Views in ASP.NET Core MVC
By Steve Smith and Luke Latham

This document explains views used in ASP.NET Core MVC applications. For information on Razor Pages, see
Introduction to Razor Pages.
In the Model-View -Controller (MVC ) pattern, the view handles the app's data presentation and user interaction. A
view is an HTML template with embedded Razor markup. Razor markup is code that interacts with HTML
markup to produce a webpage that's sent to the client.
In ASP.NET Core MVC, views are .cshtml files that use the C# programming language in Razor markup. Usually,
view files are grouped into folders named for each of the app's controllers. The folders are stored in a Views
folder at the root of the app:
The Home controller is represented by a Home folder inside the Views folder. The Home folder contains the
views for the About, Contact, and Index (homepage) webpages. When a user requests one of these three
webpages, controller actions in the Home controller determine which of the three views is used to build and
return a webpage to the user.
Use layouts to provide consistent webpage sections and reduce code repetition. Layouts often contain the header,
navigation and menu elements, and the footer. The header and footer usually contain boilerplate markup for
many metadata elements and links to script and style assets. Layouts help you avoid this boilerplate markup in
your views.
Partial views reduce code duplication by managing reusable parts of views. For example, a partial view is useful
for an author biography on a blog website that appears in several views. An author biography is ordinary view
content and doesn't require code to execute in order to produce the content for the webpage. Author biography
content is available to the view by model binding alone, so using a partial view for this type of content is ideal.
View components are similar to partial views in that they allow you to reduce repetitive code, but they're
appropriate for view content that requires code to run on the server in order to render the webpage. View
components are useful when the rendered content requires database interaction, such as for a website shopping
cart. View components aren't limited to model binding in order to produce webpage output.
Benefits of using views

Views help to establish a Separation of Concerns (SoC ) design within an MVC app by separating the user
interface markup from other parts of the app. Following SoC design makes your app modular, which provides
several benefits:
The app is easier to maintain because it's better organized. Views are generally grouped by app feature. This
makes it easier to find related views when working on a feature.
The parts of the app are loosely coupled. You can build and update the app's views separately from the
business logic and data access components. You can modify the views of the app without necessarily having to
update other parts of the app.
It's easier to test the user interface parts of the app because the views are separate units.
Due to better organization, it's less likely that you'll accidentally repeat sections of the user interface.
Creating a view
Views that are specific to a controller are created in the Views/[ControllerName] folder. Views that are shared
among controllers are placed in the Views/Shared folder. To create a view, add a new file and give it the same
name as its associated controller action with the .cshtml file extension. To create a view that corresponds with the
About action in the Home controller, create an About.cshtml file in the Views/Home folder:
@{
}
<p>Use this area to provide additional information.</p>
Razor markup starts with the @ symbol. Run C# statements by placing C# code within Razor code blocks set off
by curly braces ( { ... } ). For example, see the assignment of "About" to ViewData["Title"] shown above. You
can display values within HTML by simply referencing the value with the @ symbol. See the contents of the
<h2> and <h3> elements above.
The view content shown above is only part of the entire webpage that's rendered to the user. The rest of the
page's layout and other common aspects of the view are specified in other view files. To learn more, see the
Layout topic.
How controllers specify views

Views are typically returned from actions as a ViewResult, which is a type of ActionResult. Your action method
can create and return a ViewResult directly, but that isn't commonly done. Since most controllers inherit from
Controller, you simply use the View helper method to return the ViewResult :
HomeController.cs

{
ViewData["Message"] = "Your application description page.";
return View();
}
When this action returns, the About.cshtml view shown in the last section is rendered as the following webpage:
The View helper method has several overloads. You can optionally specify:
An explicit view to return:
return View("Orders");
A model to pass to the view:
return View(Orders);
Both a view and a model:
return View("Orders", Orders);
View discovery
When an action returns a view, a process called view discovery takes place. This process determines which view
file is used based on the view name.
The default behavior of the View method ( return View(); ) is to return a view with the same name as the action
method from which it's called. For example, the About ActionResult method name of the controller is used to
search for a view file named About.cshtml. First, the runtime looks in the Views/[ControllerName] folder for the
view. If it doesn't find a matching view there, it searches the Shared folder for the view.
It doesn't matter if you implicitly return the ViewResult with return View(); or explicitly pass the view name to
the View method with return View("<ViewName>"); . In both cases, view discovery searches for a matching view
file in this order:
1. Views/[ControllerName]/[ViewName].cshtml
2. Views/Shared/[ViewName].cshtml
A view file path can be provided instead of a view name. If using an absolute path starting at the app root
(optionally starting with "/" or "~/"), the .cshtml extension must be specified:
return View("Views/Home/About.cshtml");
You can also use a relative path to specify views in different directories without the .cshtml extension. Inside the
HomeController , you can return the Index view of your Manage views with a relative path:
return View("../Manage/Index");
Similarly, you can indicate the current controller-specific directory with the "./" prefix:
return View("./About");
Partial views and view components use similar (but not identical) discovery mechanisms.
You can customize the default convention for how views are located within the app by using a custom
IViewLocationExpander.
View discovery relies on finding view files by file name. If the underlying file system is case sensitive, view names
are probably case sensitive. For compatibility across operating systems, match case between controller and action
names and associated view folders and file names. If you encounter an error that a view file can't be found while
working with a case-sensitive file system, confirm that the casing matches between the requested view file and
the actual view file name.
Follow the best practice of organizing the file structure for your views to reflect the relationships among
controllers, actions, and views for maintainability and clarity.
Passing data to views

Pass data to views using several approaches:
Strongly typed data: viewmodel
Weakly typed data
ViewData ( ViewDataAttribute )
ViewBag
Strongly typed data (viewmodel)

The most robust approach is to specify a model type in the view. This model is commonly referred to as a
viewmodel. You pass an instance of the viewmodel type to the view from the action.
Using a viewmodel to pass data to a view allows the view to take advantage of strong type checking. Strong
typing (or strongly typed) means that every variable and constant has an explicitly defined type (for example,
string , int , or DateTime ). The validity of types used in a view is checked at compile time.
Visual Studio and Visual Studio Code list strongly typed class members using a feature called IntelliSense. When
you want to see the properties of a viewmodel, type the variable name for the viewmodel followed by a period (
. ). This helps you write code faster with fewer errors.
Specify a model using the @model directive. Use the model with @Model :
@model WebApplication1.ViewModels.Address
<h2>Contact</h2>
<address>
@Model.Street<br>
@Model.City, @Model.State @Model.PostalCode<br>
<abbr title="Phone">P:</abbr> 425.555.0100
</address>
To provide the model to the view, the controller passes it as a parameter:

public IActionResult Contact()
{
ViewData["Message"] = "Your contact page.";
var viewModel = new Address()

{
Name = "Microsoft",
Street = "One Microsoft Way",
City = "Redmond",
State = "WA",
PostalCode = "98052-6399"
};
}
There are no restrictions on the model types that you can provide to a view. We recommend using Plain Old CLR
Object (POCO ) viewmodels with little or no behavior (methods) defined. Usually, viewmodel classes are either
stored in the Models folder or a separate ViewModels folder at the root of the app. The Address viewmodel used
in the example above is a POCO viewmodel stored in a file named Address.cs:
namespace WebApplication1.ViewModels
{
public class Address
{
public string Street { get; set; }
public string City { get; set; }
public string State { get; set; }
public string PostalCode { get; set; }
}
}
Nothing prevents you from using the same classes for both your viewmodel types and your business model
types. However, using separate models allows your views to vary independently from the business logic and data
access parts of your app. Separation of models and viewmodels also offers security benefits when models use
model binding and validation for data sent to the app by the user.
Weakly typed data (ViewData, ViewData attribute, and ViewBag)
ViewBag isn't available in Razor Pages.
In addition to strongly typed views, views have access to a weakly typed (also called loosely typed) collection of
data. Unlike strong types, weak types (or loose types) means that you don't explicitly declare the type of data
you're using. You can use the collection of weakly typed data for passing small amounts of data in and out of
controllers and views.
PASSING DATA BETWEEN A ... EXAMPLE
Controller and a view Populating a dropdown list with data.
View and a layout view Setting the <title> element content in the layout view from a
view file.
Partial view and a view A widget that displays data based on the webpage that the
user requested.
This collection can be referenced through either the ViewData or ViewBag properties on controllers and views.
The ViewData property is a dictionary of weakly typed objects. The ViewBag property is a wrapper around
ViewData that provides dynamic properties for the underlying ViewData collection.
ViewData and ViewBag are dynamically resolved at runtime. Since they don't offer compile-time type checking,
both are generally more error-prone than using a viewmodel. For that reason, some developers prefer to
minimally or never use ViewData and ViewBag .
ViewData
ViewData is a ViewDataDictionary object accessed through string keys. String data can be stored and used
directly without the need for a cast, but you must cast other ViewData object values to specific types when you
extract them. You can use ViewData to pass data from controllers to views and within views, including partial
views and layouts.
The following is an example that sets values for a greeting and an address using ViewData in an action:
public IActionResult SomeAction()

{
ViewData["Greeting"] = "Hello";
ViewData["Address"] = new Address()
{
Name = "Steve",
Street = "123 Main St",
City = "Hudson",
State = "OH",
PostalCode = "44236"
};
return View();
}
Work with the data in a view:
@{
// Since Address isn't a string, it requires a cast.
var address = ViewData["Address"] as Address;
}
@ViewData["Greeting"] World!
<address>
@address.Name<br>
@address.Street<br>
@address.City, @address.State @address.PostalCode
</address>
ViewData attribute
Another approach that uses the ViewDataDictionary is ViewDataAttribute. Properties on controllers or Razor
Page models decorated with [ViewData] have their values stored and loaded from the dictionary.
In the following example, the Home controller contains a Title property decorated with [ViewData] . The About
method sets the title for the About view:
{
[ViewData]

{
Title = "About Us";
ViewData["Message"] = "Your application description page.";
return View();
}
}
In the About view, access the Title property as a model property:
<!DOCTYPE html>
<html lang="en">
<head>
...
ViewBag
ViewBag is a DynamicViewData object that provides dynamic access to the objects stored in ViewData . ViewBag
can be more convenient to work with, since it doesn't require casting. The following example shows how to use
ViewBag with the same result as using ViewData above:
public IActionResult SomeAction()

{
ViewBag.Greeting = "Hello";
ViewBag.Address = new Address()
{
Name = "Steve",
Street = "123 Main St",
City = "Hudson",
State = "OH",
PostalCode = "44236"
};
return View();
}
@ViewBag.Greeting World!
<address>
@ViewBag.Address.Name<br>
@ViewBag.Address.Street<br>
@ViewBag.Address.City, @ViewBag.Address.State @ViewBag.Address.PostalCode
</address>
Using ViewData and ViewBag simultaneously

Since ViewData and ViewBag refer to the same underlying ViewData collection, you can use both ViewData and
ViewBag and mix and match between them when reading and writing values.
Set the title using ViewBag and the description using ViewData at the top of an About.cshtml view:
@{
Layout = "/Views/Shared/_Layout.cshtml";
ViewBag.Title = "About Contoso";
ViewData["Description"] = "Let us tell you about Contoso's philosophy and mission.";
}
Read the properties but reverse the use of ViewData and ViewBag . In the _Layout.cshtml file, obtain the title
using ViewData and obtain the description using ViewBag :
<!DOCTYPE html>
<html lang="en">
<head>
<title>@ViewData["Title"]</title>
<meta name="description" content="@ViewBag.Description">
...
Remember that strings don't require a cast for ViewData . You can use @ViewData["Title"] without casting.
Using both ViewData and ViewBag at the same time works, as does mixing and matching reading and writing the
properties. The following markup is rendered:
<!DOCTYPE html>
<html lang="en">
<head>
<title>About Contoso</title>
<meta name="description" content="Let us tell you about Contoso's philosophy and mission.">
...
Summary of the differences between ViewData and ViewBag

ViewBag isn't available in the Razor Pages.
ViewData
Derives from ViewDataDictionary, so it has dictionary properties that can be useful, such as
ContainsKey , Add , Remove , and Clear .
Keys in the dictionary are strings, so whitespace is allowed. Example:
ViewData["Some Key With Whitespace"]
Any type other than a string must be cast in the view to use ViewData .
ViewBag
Derives from DynamicViewData, so it allows the creation of dynamic properties using dot notation (
@ViewBag.SomeKey = <value or object> ), and no casting is required. The syntax of ViewBag makes it
quicker to add to controllers and views.
Simpler to check for null values. Example: @ViewBag.Person?.Name
When to use ViewData or ViewBag
Both ViewData and ViewBag are equally valid approaches for passing small amounts of data among controllers
and views. The choice of which one to use is based on preference. You can mix and match ViewData and ViewBag
objects, however, the code is easier to read and maintain with one approach used consistently. Both approaches
are dynamically resolved at runtime and thus prone to causing runtime errors. Some development teams avoid
them.
Dynamic views
Views that don't declare a model type using @model but that have a model instance passed to them (for example,
return View(Address); ) can reference the instance's properties dynamically:
<address>
@Model.Street<br>
@Model.City, @Model.State @Model.PostalCode<br>
<abbr title="Phone">P:</abbr> 425.555.0100
</address>
This feature offers flexibility but doesn't offer compilation protection or IntelliSense. If the property doesn't exist,
webpage generation fails at runtime.
More view features

Tag Helpers make it easy to add server-side behavior to existing HTML tags. Using Tag Helpers avoids the need
to write custom code or helpers within your views. Tag helpers are applied as attributes to HTML elements and
are ignored by editors that can't process them. This allows you to edit and render view markup in a variety of
tools.
Generating custom HTML markup can be achieved with many built-in HTML Helpers. More complex user
interface logic can be handled by View Components. View components provide the same SoC that controllers
and views offer. They can eliminate the need for actions and views that deal with data used by common user
interface elements.
Like many other aspects of ASP.NET Core, views support dependency injection, allowing services to be injected
into views.
By Rick Anderson, Luke Latham, Taylor Mullen, and Dan Vicarel

Razor is a markup syntax for embedding server-based code into webpages. The Razor syntax consists of Razor
markup, C#, and HTML. Files containing Razor generally have a .cshtml file extension.
Rendering HTML
The default Razor language is HTML. Rendering HTML from Razor markup is no different than rendering HTML
from an HTML file. HTML markup in .cshtml Razor files is rendered by the server unchanged.
Razor syntax
Razor supports C# and uses the @ symbol to transition from HTML to C#. Razor evaluates C# expressions and
renders them in the HTML output.
When an @ symbol is followed by a Razor reserved keyword, it transitions into Razor-specific markup.
Otherwise, it transitions into plain C#.
To escape an @ symbol in Razor markup, use a second @ symbol:
<p>@@Username</p>
The code is rendered in HTML with a single @ symbol:
<p>@Username</p>
HTML attributes and content containing email addresses don't treat the @ symbol as a transition character. The
email addresses in the following example are untouched by Razor parsing:
<a href="mailto:[email protected]">[email protected]</a>
Implicit Razor expressions

Implicit Razor expressions start with @ followed by C# code:
<p>@DateTime.Now</p>
<p>@DateTime.IsLeapYear(2016)</p>
With the exception of the C# await keyword, implicit expressions must not contain spaces. If the C# statement
has a clear ending, spaces can be intermingled:
<p>@await DoSomething("hello", "world")</p>
Implicit expressions cannot contain C# generics, as the characters inside the brackets ( <> ) are interpreted as an
HTML tag. The following code is not valid:
<p>@GenericMethod<int>()</p>
The preceding code generates a compiler error similar to one of the following:
The "int" element wasn't closed. All elements must be either self-closing or have a matching end tag.
Cannot convert method group 'GenericMethod' to non-delegate type 'object'. Did you intend to invoke the
method?`
Generic method calls must be wrapped in an explicit Razor expression or a Razor code block.
Explicit Razor expressions

Explicit Razor expressions consist of an @ symbol with balanced parenthesis. To render last week's time, the
following Razor markup is used:
<p>Last week this time: @(DateTime.Now - TimeSpan.FromDays(7))</p>
Any content within the @() parenthesis is evaluated and rendered to the output.
Implicit expressions, described in the previous section, generally can't contain spaces. In the following code, one
week isn't subtracted from the current time:
<p>Last week: @DateTime.Now - TimeSpan.FromDays(7)</p>
The code renders the following HTML:
<p>Last week: 7/7/2016 4:39:52 PM - TimeSpan.FromDays(7)</p>
Explicit expressions can be used to concatenate text with an expression result:
@{
var joe = new Person("Joe", 33);
}
<p>Age@(joe.Age)</p>
Without the explicit expression, <p>[email protected]</p> is treated as an email address, and <p>[email protected]</p> is
rendered. When written as an explicit expression, <p>Age33</p> is rendered.
Explicit expressions can be used to render output from generic methods in .cshtml files. The following markup
shows how to correct the error shown earlier caused by the brackets of a C# generic. The code is written as an
explicit expression:
<p>@(GenericMethod<int>())</p>
Expression encoding
C# expressions that evaluate to a string are HTML encoded. C# expressions that evaluate to IHtmlContent are
rendered directly through IHtmlContent.WriteTo . C# expressions that don't evaluate to IHtmlContent are
converted to a string by ToString and encoded before they're rendered.
@("<span>Hello World</span>")
<span>Hello World</span>
The HTML is shown in the browser as:
HtmlHelper.Raw output isn't encoded but rendered as HTML markup.
WARNING
Using HtmlHelper.Raw on unsanitized user input is a security risk. User input might contain malicious JavaScript or other
exploits. Sanitizing user input is difficult. Avoid using HtmlHelper.Raw with user input.
@Html.Raw("<span>Hello World</span>")
Razor code blocks

Razor code blocks start with @ and are enclosed by {} . Unlike expressions, C# code inside code blocks isn't
rendered. Code blocks and expressions in a view share the same scope and are defined in order:
@{
var quote = "The future depends on what you do today. - Mahatma Gandhi";
}
<p>@quote</p>
@{
quote = "Hate cannot drive out hate, only love can do that. - Martin Luther King, Jr.";
}
<p>@quote</p>
<p>The future depends on what you do today. - Mahatma Gandhi</p>

<p>Hate cannot drive out hate, only love can do that. - Martin Luther King, Jr.</p>
Implicit transitions
The default language in a code block is C#, but the Razor Page can transition back to HTML:
@{
var inCSharp = true;
<p>Now in HTML, was in C# @inCSharp</p>
}
Explicit delimited transition

To define a subsection of a code block that should render HTML, surround the characters for rendering with the
Razor <text> tag:
@for (var i = 0; i < people.Length; i++)

{
var person = people[i];
<text>Name: @person.Name</text>
}
Use this approach to render HTML that isn't surrounded by an HTML tag. Without an HTML or Razor tag, a
Razor runtime error occurs.
The <text> tag is useful to control whitespace when rendering content:
Only the content between the <text> tag is rendered.
No whitespace before or after the <text> tag appears in the HTML output.
Explicit Line Transition with @:
To render the rest of an entire line as HTML inside a code block, use the @: syntax:

{
@:Name: @person.Name
}
Without the @: in the code, a Razor runtime error is generated.

Warning: Extra @ characters in a Razor file can cause compiler errors at statements later in the block. These
compiler errors can be difficult to understand because the actual error occurs before the reported error. This
error is common after combining multiple implicit/explicit expressions into a single code block.
Control structures
Control structures are an extension of code blocks. All aspects of code blocks (transitioning to markup, inline C#)
also apply to the following structures:
Conditionals @if, else if, else, and @switch
@if controls when code runs:
@if (value % 2 == 0)
{
<p>The value was even.</p>
}
else and else if don't require the @ symbol:

@if (value % 2 == 0)
{
<p>The value was even.</p>
}
else if (value >= 1337)
{
<p>The value is large.</p>
}
else
{
<p>The value is odd and small.</p>
}
The following markup shows how to use a switch statement:
@switch (value)
{
case 1:
<p>The value is 1!</p>
break;
case 1337:
<p>Your number is 1337!</p>
break;
default:
<p>Your number wasn't 1 or 1337.</p>
break;
}
Looping @for, @foreach, @while, and @do while

Templated HTML can be rendered with looping control statements. To render a list of people:
@{
var people = new Person[]
{
new Person("Weston", 33),
new Person("Johnathon", 41),
...
};
}
The following looping statements are supported:

@for

{
<p>Name: @person.Name</p>
<p>Age: @person.Age</p>
}
@foreach
@foreach (var person in people)

{
}
@while
@{ var i = 0; }
@while (i < people.Length)
{
i++;
}
@do while
@{ var i = 0; }
@do
{
i++;
} while (i < people.Length);
Compound @using
In C#, a using statement is used to ensure an object is disposed. In Razor, the same mechanism is used to
create HTML Helpers that contain additional content. In the following code, HTML Helpers render a form tag
with the @using statement:
@using (Html.BeginForm())
{
<div>
email:
<input type="email" id="Email" value="">
<button>Register</button>
</div>
}
Scope-level actions can be performed with Tag Helpers.

@try, catch, finally
Exception handling is similar to C#:
@try
{
throw new InvalidOperationException("You did something invalid.");
}
{
<p>The exception message: @ex.Message</p>
}
finally
{
<p>The finally statement.</p>
}
@lock
Razor has the capability to protect critical sections with lock statements:
@lock (SomeLock)
{
// Do critical section work
}
Comments
Razor supports C# and HTML comments:
@{
/* C# comment */
// Another C# comment
}

Razor comments are removed by the server before the webpage is rendered. Razor uses @* *@ to delimit
comments. The following code is commented out, so the server doesn't render any markup:
@*
@{
/* C# comment */
// Another C# comment
}
*@
Directives
Razor directives are represented by implicit expressions with reserved keywords following the @ symbol. A
directive typically changes the way a view is parsed or enables different functionality.
Understanding how Razor generates code for a view makes it easier to understand how directives work.
@{
var quote = "Getting old ain't for wimps! - Anonymous";
}
<div>Quote of the Day: @quote</div>
The code generates a class similar to the following:
public class _Views_Something_cshtml : RazorPage<dynamic>

{
public override async Task ExecuteAsync()
{
var output = "Getting old ain't for wimps! - Anonymous";
WriteLiteral("/r/n<div>Quote of the Day: ");

Write(output);
WriteLiteral("</div>");
}
}
Later in this article, the section Viewing the Razor C# class generated for a view explains how to view this
generated class.
@using
The @using directive adds the C# using directive to the generated view:
@using System.IO
@{
var dir = Directory.GetCurrentDirectory();
}
<p>@dir</p>
@model
The @model directive specifies the type of the model passed to a view:
@model TypeNameOfModel
In an ASP.NET Core MVC app created with individual user accounts, the Views/Account/Login.cshtml view
contains the following model declaration:
@model LoginViewModel
The class generated inherits from RazorPage<dynamic> :
public class _Views_Account_Login_cshtml : RazorPage<LoginViewModel>
Razor exposes a Model property for accessing the model passed to the view:
<div>The Login Email: @Model.Email</div>
The @model directive specifies the type of this property. The directive specifies the T in RazorPage<T> that the
generated class that the view derives from. If the @model directive isn't specified, the Model property is of type
dynamic . The value of the model is passed from the controller to the view. For more information, see Strongly
typed models and the @model keyword.
@inherits
The @inherits directive provides full control of the class the view inherits:
@inherits TypeNameOfClassToInheritFrom
The following code is a custom Razor page type:
using Microsoft.AspNetCore.Mvc.Razor;
public abstract class CustomRazorPage<TModel> : RazorPage<TModel>

{
public string CustomText { get; } = "Gardyloo! - A Scottish warning yelled from a window before dumping
a slop bucket on the street below.";
}
The CustomText is displayed in a view:

@inherits CustomRazorPage<TModel>
<div>Custom text: @CustomText</div>
<div>Custom text: Gardyloo! - A Scottish warning yelled from a window before dumping a slop bucket on the
street below.</div>
@model and @inherits can be used in the same view. @inherits can be in a _ViewImports.cshtml file that the
view imports:
The following code is an example of a strongly-typed view:
<div>The Login Email: @Model.Email</div>

<div>Custom text: @CustomText</div>
If "[email protected]" is passed in the model, the view generates the following HTML markup:
<div>The Login Email: [email protected]</div>

<div>Custom text: Gardyloo! - A Scottish warning yelled from a window before dumping a slop bucket on the
street below.</div>
@inject
The @inject directive enables the Razor Page to inject a service from the service container into a view. For more
information, see Dependency injection into views.
@functions
The @functions directive enables a Razor Page to add a C# code block to a view:
@functions { // C# Code }
For example:
@functions {
public string GetHello()
{
return "Hello";
}
}
<div>From method: @GetHello()</div>
The code generates the following HTML markup:
<div>From method: Hello</div>
The following code is the generated Razor C# class:

using Microsoft.AspNetCore.Mvc.Razor;
public class _Views_Home_Test_cshtml : RazorPage<dynamic>

{
// Functions placed between here
public string GetHello()
{
return "Hello";
}
// And here.
#pragma warning disable 1998
public override async Task ExecuteAsync()
{
WriteLiteral("\r\n<div>From method: ");
Write(GetHello());
WriteLiteral("</div>\r\n");
}
#pragma warning restore 1998
@section
The @section directive is used in conjunction with the layout to enable views to render content in different parts
of the HTML page. For more information, see Sections.
Tag Helpers
There are three directives that pertain to Tag Helpers.
DIRECTIVE FUNCTION
@addTagHelper Makes Tag Helpers available to a view.
@removeTagHelper Removes Tag Helpers previously added from a view.
@tagHelperPrefix Specifies a tag prefix to enable Tag Helper support and to

make Tag Helper usage explicit.
Razor reserved keywords

Razor keywords
page (Requires ASP.NET Core 2.0 and later)
namespace
functions
inherits
model
section
helper (Not currently supported by ASP.NET Core)
Razor keywords are escaped with @(Razor Keyword) (for example, @(functions) ).
C# Razor keywords
case
do
default
for
foreach
if
else
lock
switch
try
catch
finally
using
while
C# Razor keywords must be double-escaped with @(@C# Razor Keyword) (for example, @(@case) ). The first @
escapes the Razor parser. The second @ escapes the C# parser.
Reserved keywords not used by Razor
class
Viewing the Razor C# class generated for a view

Add the following class to the ASP.NET Core MVC project:
using Microsoft.AspNetCore.Mvc.Razor.Extensions;
using Microsoft.AspNetCore.Razor.Language;
public class CustomTemplateEngine : MvcRazorTemplateEngine

{
public CustomTemplateEngine(RazorEngine engine, RazorProject project)
: base(engine, project)
{
}
public override RazorCSharpDocument GenerateCode(RazorCodeDocument codeDocument)

{
var csharpDocument = base.GenerateCode(codeDocument);
var generatedCode = csharpDocument.GeneratedCode;
// Look at generatedCode
return csharpDocument;
}
}
Override the RazorTemplateEngine added by MVC with the CustomTemplateEngine class:

{
services.AddMvc();
services.AddSingleton<RazorTemplateEngine, CustomTemplateEngine>();
}
Set a break point on the return csharpDocument statement of CustomTemplateEngine . When program execution
stops at the break point, view the value of generatedCode .
View lookups and case sensitivity
The Razor view engine performs case-sensitive lookups for views. However, the actual lookup is determined by
the underlying file system:
File based source:
On operating systems with case insensitive file systems (for example, Windows), physical file provider
lookups are case insensitive. For example, return View("Test") results in matches for
/Views/Home/Test.cshtml, /Views/home/test.cshtml, and any other casing variant.
On case-sensitive file systems (for example, Linux, OSX, and with EmbeddedFileProvider ), lookups are
case-sensitive. For example, return View("Test") specifically matches /Views/Home/Test.cshtml.
Precompiled views: With ASP.NET Core 2.0 and later, looking up precompiled views is case insensitive on all
operating systems. The behavior is identical to physical file provider's behavior on Windows. If two
precompiled views differ only in case, the result of lookup is non-deterministic.
Developers are encouraged to match the casing of file and directory names to the casing of:
* Area, controller, and action names.

* Razor Pages.
Matching case ensures the deployments find their views regardless of the underlying file system.
Razor file compilation in ASP.NET Core
By Rick Anderson
A Razor file is compiled at runtime, when the associated MVC view is invoked. Build-time Razor file publishing is
unsupported. Razor files can optionally be compiled at publish time and deployed with the app—using the
precompilation tool.
A Razor file is compiled at runtime, when the associated Razor Page or MVC view is invoked. Build-time Razor file
publishing is unsupported. Razor files can optionally be compiled at publish time and deployed with the app—
using the precompilation tool.
A Razor file is compiled at runtime, when the associated Razor Page or MVC view is invoked. Razor files are
compiled at both build and publish time using the Razor SDK.
Precompilation considerations
The following are side effects of precompiling Razor files:
A smaller published bundle
A faster startup time
You can't edit Razor files—the associated content is absent from the published bundle.
Deploy precompiled files

Build- and publish-time compilation of Razor files is enabled by default by the Razor SDK. Editing Razor files after
they're updated is supported at build time. By default, only the compiled Views.dll and no .cshtml files are
deployed with your app.
IMPORTANT
The precompilation tool will be removed in ASP.NET Core 3.0. We recommend migrating to Razor Sdk.
The Razor SDK is effective only when no precompilation-specific properties are set in the project file. For instance, setting the
.csproj file's MvcRazorCompileOnPublish property to true disables the Razor SDK.
If your project targets .NET Framework, install the Microsoft.AspNetCore.Mvc.Razor.ViewCompilation NuGet

package:
<PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.ViewCompilation"
Version="2.0.4"
PrivateAssets="All" />
If your project targets .NET Core, no changes are necessary.

The ASP.NET Core 2.x project templates implicitly set the MvcRazorCompileOnPublish property to true by default.
Consequently, this element can be safely removed from the .csproj file.
IMPORTANT
The precompilation tool will be removed in ASP.NET Core 3.0. We recommend migrating to Razor Sdk.
Razor file precompilation is unavailable when performing a self-contained deployment (SCD) in ASP.NET Core 2.0.
Set the MvcRazorCompileOnPublish property to true , and install the

Microsoft.AspNetCore.Mvc.Razor.ViewCompilation NuGet package. The following .csproj sample highlights these
settings:
<PropertyGroup>
<MvcRazorCompileOnPublish>true</MvcRazorCompileOnPublish>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore" Version="1.1.0" />
<PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.ViewCompilation" Version="1.1.0-*" />
</ItemGroup>
</Project>
Prepare the app for a framework-dependent deployment with the .NET Core CLI publish command. For example,
execute the following command at the project root:
dotnet publish -c Release
A <project_name>.PrecompiledViews.dll file, containing the compiled Razor files, is produced when

precompilation succeeds. For example, the screenshot below depicts the contents of Index.cshtml within
WebApplication1.PrecompiledViews.dll:
ASP.NET Core Razor SDK
Layout in ASP.NET Core
By Steve Smith
Views frequently share visual and programmatic elements. In this article, you'll learn how to use common
layouts, share directives, and run common code before rendering views in your ASP.NET Core app.
What is a Layout
Most web apps have a common layout that provides the user with a consistent experience as they navigate
from page to page. The layout typically includes common user interface elements such as the app header,
navigation or menu elements, and footer.
Common HTML structures such as scripts and stylesheets are also frequently used by many pages within
an app. All of these shared elements may be defined in a layout file, which can then be referenced by any
view used within the app. Layouts reduce duplicate code in views, helping them follow the Don't Repeat
Yourself (DRY ) principle.
By convention, the default layout for an ASP.NET Core app is named _Layout.cshtml . The Visual Studio
ASP.NET Core MVC project template includes this layout file in the Views/Shared folder:
This layout defines a top level template for views in the app. Apps don't require a layout, and apps can
define more than one layout, with different views specifying different layouts.
An example _Layout.cshtml :
<!DOCTYPE html>
<html>
<head>
<title>@ViewData["Title"] - WebApplication1</title>
</environment>
<link rel="stylesheet"
href="https://ajax.aspnetcdn.com/ajax/bootstrap/3.3.6/css/bootstrap.min.css"
asp-fallback-test-class="sr-only" asp-fallback-test-property="position" asp-fallback-
test-value="absolute" />
</environment>
</head>
<body>
<div class="navbar navbar-inverse navbar-fixed-top">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-
target=".navbar-collapse">
</button>
<a asp-area="" asp-controller="Home" asp-action="Index" class="navbar-
brand">WebApplication1</a>
</div>
</ul>
@await Html.PartialAsync("_LoginPartial")
</div>
</div>
</div>
@RenderBody()
<hr />
<footer>
<p>© 2016 - WebApplication1</p>
</footer>
</div>
</environment>
</script>
asp-fallback-test="window.jQuery && window.jQuery.fn && window.jQuery.fn.modal">
</script>
</environment>
@RenderSection("scripts", required: false)

</body>
</html>
Specifying a Layout
Razor views have a Layout property. Individual views specify a layout by setting this property:
@{
Layout = "_Layout";
}
The layout specified can use a full path (example: /Views/Shared/_Layout.cshtml ) or a partial name
(example: _Layout ). When a partial name is provided, the Razor view engine will search for the layout file
using its standard discovery process. The controller-associated folder is searched first, followed by the
Shared folder. This discovery process is identical to the one used to discover partial views.
By default, every layout must call RenderBody . Wherever the call to RenderBody is placed, the contents of
the view will be rendered.
Sections
A layout can optionally reference one or more sections, by calling RenderSection . Sections provide a way to
organize where certain page elements should be placed. Each call to RenderSection can specify whether
that section is required or optional. If a required section isn't found, an exception will be thrown. Individual
views specify the content to be rendered within a section using the @section Razor syntax. If a view defines
a section, it must be rendered (or an error will occur).
An example @section definition in a view:
@section Scripts {
<script type="text/javascript" src="/scripts/main.js"></script>
}
In the code above, validation scripts are added to the scripts section on a view that includes a form. Other
views in the same application might not require any additional scripts, and so wouldn't need to define a
scripts section.
Sections defined in a view are available only in its immediate layout page. They cannot be referenced from
partials, view components, or other parts of the view system.
Ignoring sections
By default, the body and all sections in a content page must all be rendered by the layout page. The Razor
view engine enforces this by tracking whether the body and each section have been rendered.
To instruct the view engine to ignore the body or sections, call the IgnoreBody and IgnoreSection methods.
The body and every section in a Razor page must be either rendered or ignored.
Importing Shared Directives

Views can use Razor directives to do many things, such as importing namespaces or performing
dependency injection. Directives shared by many views may be specified in a common
_ViewImports.cshtml file. The _ViewImports file supports the following directives:
@addTagHelper
@removeTagHelper
@tagHelperPrefix
@using
@model
@inherits
@inject
The file doesn't support other Razor features, such as functions and section definitions.
A sample _ViewImports.cshtml file:
@using WebApplication1
@using WebApplication1.Models
@using WebApplication1.Models.AccountViewModels
@using WebApplication1.Models.ManageViewModels
@using Microsoft.AspNetCore.Identity
The _ViewImports.cshtml file for an ASP.NET Core MVC app is typically placed in the Views folder. A
_ViewImports.cshtml file can be placed within any folder, in which case it will only be applied to views
within that folder and its subfolders. _ViewImports files are processed starting at the root level, and then for
each folder leading up to the location of the view itself, so settings specified at the root level may be
overridden at the folder level.
For example, if a root level _ViewImports.cshtml file specifies @model and @addTagHelper , and another
_ViewImports.cshtml file in the controller -associated folder of the view specifies a different @model and
adds another @addTagHelper , the view will have access to both tag helpers and will use the latter @model .
If multiple _ViewImports.cshtml files are run for a view, combined behavior of the directives included in the
ViewImports.cshtml files will be as follows:
@addTagHelper , @removeTagHelper : all run, in order
@tagHelperPrefix : the closest one to the view overrides any others
@model : the closest one to the view overrides any others
@inherits : the closest one to the view overrides any others
@using : all are included; duplicates are ignored
@inject : for each property, the closest one to the view overrides any others with the same property
name
Running Code Before Each View

If you have code you need to run before every view, this should be placed in the _ViewStart.cshtml file. By
convention, the _ViewStart.cshtml file is located in the Views folder. The statements listed in
_ViewStart.cshtml are run before every full view (not layouts, and not partial views). Like
ViewImports.cshtml, _ViewStart.cshtml is hierarchical. If a _ViewStart.cshtml file is defined in the
controller-associated view folder, it will be run after the one defined in the root of the Views folder (if any).
A sample _ViewStart.cshtml file:
@{
Layout = "_Layout";
}
The file above specifies that all views will use the _Layout.cshtml layout.
NOTE
Neither _ViewStart.cshtml nor _ViewImports.cshtml are typically placed in the /Views/Shared folder. The
app-level versions of these files should be placed directly in the /Views folder.
Tag Helpers in ASP.NET Core
By Rick Anderson
What are Tag Helpers?

Tag Helpers enable server-side code to participate in creating and rendering HTML elements in
Razor files. For example, the built-in ImageTagHelper can append a version number to the image
name. Whenever the image changes, the server generates a new unique version for the image, so
clients are guaranteed to get the current image (instead of a stale cached image). There are many
built-in Tag Helpers for common tasks - such as creating forms, links, loading assets and more - and
even more available in public GitHub repositories and as NuGet packages. Tag Helpers are authored
in C#, and they target HTML elements based on element name, attribute name, or parent tag. For
example, the built-in LabelTagHelper can target the HTML <label> element when the
LabelTagHelper attributes are applied. If you're familiar with HTML Helpers, Tag Helpers reduce the
explicit transitions between HTML and C# in Razor views. In many cases, HTML Helpers provide an
alternative approach to a specific Tag Helper, but it's important to recognize that Tag Helpers don't
replace HTML Helpers and there's not a Tag Helper for each HTML Helper. Tag Helpers compared to
HTML Helpers explains the differences in more detail.
What Tag Helpers provide

An HTML -friendly development experience For the most part, Razor markup using Tag Helpers
looks like standard HTML. Front-end designers conversant with HTML/CSS/JavaScript can edit
Razor without learning C# Razor syntax.
A rich IntelliSense environment for creating HTML and Razor markup This is in sharp
contrast to HTML Helpers, the previous approach to server-side creation of markup in Razor views.
Tag Helpers compared to HTML Helpers explains the differences in more detail. IntelliSense support
for Tag Helpers explains the IntelliSense environment. Even developers experienced with Razor C#
syntax are more productive using Tag Helpers than writing C# Razor markup.
A way to make you more productive and able to produce more robust, reliable, and
maintainable code using information only available on the server For example, historically
the mantra on updating images was to change the name of the image when you change the image.
Images should be aggressively cached for performance reasons, and unless you change the name of
an image, you risk clients getting a stale copy. Historically, after an image was edited, the name had
to be changed and each reference to the image in the web app needed to be updated. Not only is this
very labor intensive, it's also error prone (you could miss a reference, accidentally enter the wrong
string, etc.) The built-in ImageTagHelper can do this for you automatically. The ImageTagHelper can
append a version number to the image name, so whenever the image changes, the server
automatically generates a new unique version for the image. Clients are guaranteed to get the
current image. This robustness and labor savings comes essentially free by using the
ImageTagHelper .
Most built-in Tag Helpers target standard HTML elements and provide server-side attributes for the
element. For example, the <input> element used in many views in the Views/Account folder
contains the asp-for attribute. This attribute extracts the name of the specified model property into
the rendered HTML. Consider a Razor view with the following model:
public class Movie
{
}
The following Razor markup:
<label asp-for="Movie.Title"></label>
Generates the following HTML:
<label for="Movie_Title">Title</label>
The asp-for attribute is made available by the For property in the LabelTagHelper. See Author Tag
Helpers for more information.
Managing Tag Helper scope

Tag Helpers scope is controlled by a combination of @addTagHelper , @removeTagHelper , and the "!"
opt-out character.
@addTagHelper makes Tag Helpers available
If you create a new ASP.NET Core web app named AuthoringTagHelpers, the following
Views/_ViewImports.cshtml file will be added to your project:
@addTagHelper *, AuthoringTagHelpers
The @addTagHelper directive makes Tag Helpers available to the view. In this case, the view file is
Pages/_ViewImports.cshtml, which by default is inherited by all files in the Pages folder and sub-
folders; making Tag Helpers available. The code above uses the wildcard syntax ("*") to specify that
all Tag Helpers in the specified assembly (Microsoft.AspNetCore.Mvc.TagHelpers) will be available to
every view file in the Views directory or sub-directory. The first parameter after @addTagHelper
specifies the Tag Helpers to load (we are using "*" for all Tag Helpers), and the second parameter
"Microsoft.AspNetCore.Mvc.TagHelpers" specifies the assembly containing the Tag Helpers.
Microsoft.AspNetCore.Mvc.TagHelpers is the assembly for the built-in ASP.NET Core Tag Helpers.
To expose all of the Tag Helpers in this project (which creates an assembly named
AuthoringTagHelpers), you would use the following:
@using AuthoringTagHelpers
If your project contains an with the default namespace (

EmailTagHelper
AuthoringTagHelpers.TagHelpers.EmailTagHelper ), you can provide the fully qualified name ( FQN ) of
the Tag Helper:
@addTagHelper AuthoringTagHelpers.TagHelpers.EmailTagHelper, AuthoringTagHelpers
To add a Tag Helper to a view using an FQN, you first add the FQN (
AuthoringTagHelpers.TagHelpers.EmailTagHelper ), and then the assembly name
(AuthoringTagHelpers). Most developers prefer to use the "*" wildcard syntax. The wildcard syntax
allows you to insert the wildcard character "*" as the suffix in an FQN. For example, any of the
following directives will bring in the EmailTagHelper :
@addTagHelper AuthoringTagHelpers.TagHelpers.E*, AuthoringTagHelpers

@addTagHelper AuthoringTagHelpers.TagHelpers.Email*, AuthoringTagHelpers
As mentioned previously, adding the @addTagHelper directive to the Views/_ViewImports.cshtml file

makes the Tag Helper available to all view files in the Views directory and sub-directories. You can
use the @addTagHelper directive in specific view files if you want to opt-in to exposing the Tag Helper
to only those views.
@removeTagHelper removes Tag Helpers
The @removeTagHelper has the same two parameters as @addTagHelper , and it removes a Tag Helper
that was previously added. For example, @removeTagHelper applied to a specific view removes the
specified Tag Helper from the view. Using @removeTagHelper in a Views/Folder/_ViewImports.cshtml
file removes the specified Tag Helper from all of the views in Folder.
Controlling Tag Helper scope with the _ViewImports.cshtml file
You can add a _ViewImports.cshtml to any view folder, and the view engine applies the directives
from both that file and the Views/_ViewImports.cshtml file. If you added an empty
Views/Home/_ViewImports.cshtml file for the Home views, there would be no change because the
_ViewImports.cshtml file is additive. Any @addTagHelper directives you add to the
Views/Home/_ViewImports.cshtml file (that are not in the default Views/_ViewImports.cshtml file)
would expose those Tag Helpers to views only in the Home folder.
Opting out of individual elements
You can disable a Tag Helper at the element level with the Tag Helper opt-out character ("!"). For
example, Email validation is disabled in the <span> with the Tag Helper opt-out character:
<!span asp-validation-for="Email" class="text-danger"></!span>
You must apply the Tag Helper opt-out character to the opening and closing tag. (The Visual Studio
editor automatically adds the opt-out character to the closing tag when you add one to the opening
tag). After you add the opt-out character, the element and Tag Helper attributes are no longer
displayed in a distinctive font.
Using @tagHelperPrefix to make Tag Helper usage explicit
The @tagHelperPrefix directive allows you to specify a tag prefix string to enable Tag Helper support
and to make Tag Helper usage explicit. For example, you could add the following markup to the
Views/_ViewImports.cshtml file:
@tagHelperPrefix th:
In the code image below, the Tag Helper prefix is set to th: , so only those elements using the prefix
th: support Tag Helpers (Tag Helper-enabled elements have a distinctive font). The <label> and
<input> elements have the Tag Helper prefix and are Tag Helper -enabled, while the <span> element
doesn't.
The same hierarchy rules that apply to @addTagHelper also apply to @tagHelperPrefix .
IntelliSense support for Tag Helpers

When you create a new ASP.NET Core web app in Visual Studio, it adds the NuGet package
"Microsoft.AspNetCore.Razor.Tools". This is the package that adds Tag Helper tooling.
Consider writing an HTML <label> element. As soon as you enter <l in the Visual Studio editor,
IntelliSense displays matching elements:
Not only do you get HTML help, but the icon (the "@" symbol with "<>" under it).
identifies the element as targeted by Tag Helpers. Pure HTML elements (such as the fieldset )
display the "<>" icon.
A pure HTML <label> tag displays the HTML tag (with the default Visual Studio color theme) in a
brown font, the attributes in red, and the attribute values in blue.
After you enter <label , IntelliSense lists the available HTML/CSS attributes and the Tag Helper-
targeted attributes:
IntelliSense statement completion allows you to enter the tab key to complete the statement with the
selected value:
As soon as a Tag Helper attribute is entered, the tag and attribute fonts change. Using the default
Visual Studio "Blue" or "Light" color theme, the font is bold purple. If you're using the "Dark" theme
the font is bold teal. The images in this document were taken using the default theme.
You can enter the Visual Studio CompleteWord shortcut (Ctrl +spacebar is the default inside the
double quotes (""), and you are now in C#, just like you would be in a C# class. IntelliSense displays
all the methods and properties on the page model. The methods and properties are available
because the property type is ModelExpression . In the image below, I'm editing the Register view, so
the RegisterViewModel is available.
IntelliSense lists the properties and methods available to the model on the page. The rich
IntelliSense environment helps you select the CSS class:
Tag Helpers compared to HTML Helpers

Tag Helpers attach to HTML elements in Razor views, while HTML Helpers are invoked as methods
interspersed with HTML in Razor views. Consider the following Razor markup, which creates an
HTML label with the CSS class "caption":
@Html.Label("FirstName", "First Name:", new {@class="caption"})
The at ( @ ) symbol tells Razor this is the start of code. The next two parameters ("FirstName" and
"First Name:") are strings, so IntelliSense can't help. The last argument:
new {@class="caption"}
Is an anonymous object used to represent attributes. Because class is a reserved keyword in C#, you
use the @ symbol to force C# to interpret "@class=" as a symbol (property name). To a front-end
designer (someone familiar with HTML/CSS/JavaScript and other client technologies but not
familiar with C# and Razor), most of the line is foreign. The entire line must be authored with no
help from IntelliSense.
Using the LabelTagHelper , the same markup can be written as:
With the Tag Helper version, as soon as you enter <l in the Visual Studio editor, IntelliSense
displays matching elements:
IntelliSense helps you write the entire line. The LabelTagHelper also defaults to setting the content of
the asp-for attribute value ("FirstName") to "First Name"; It converts camel-cased properties to a
sentence composed of the property name with a space where each new upper-case letter occurs. In
the following markup:
generates:
<label class="caption" for="FirstName">First Name</label>
The camel-cased to sentence-cased content isn't used if you add content to the <label> . For
example:
generates:
<label class="caption" for="FirstName">Name First</label>
The following code image shows the Form portion of the Views/Account/Register.cshtml Razor view
generated from the legacy ASP.NET 4.5.x MVC template included with Visual Studio 2015.
The Visual Studio editor displays C# code with a grey background. For example, the
AntiForgeryToken HTML Helper:
@Html.AntiForgeryToken()
is displayed with a grey background. Most of the markup in the Register view is C#. Compare that to
the equivalent approach using Tag Helpers:
The markup is much cleaner and easier to read, edit, and maintain than the HTML Helpers approach.
The C# code is reduced to the minimum that the server needs to know about. The Visual Studio
editor displays markup targeted by a Tag Helper in a distinctive font.
Consider the Email group:
<label asp-for="Email" class="col-md-2 control-label"></label>
<input asp-for="Email" class="form-control" />
<span asp-validation-for="Email" class="text-danger"></span>
</div>
</div>
Each of the "asp-" attributes has a value of "Email", but "Email" isn't a string. In this context, "Email" is
the C# model expression property for the RegisterViewModel .
The Visual Studio editor helps you write all of the markup in the Tag Helper approach of the register
form, while Visual Studio provides no help for most of the code in the HTML Helpers approach.
IntelliSense support for Tag Helpers goes into detail on working with Tag Helpers in the Visual
Studio editor.
Tag Helpers compared to Web Server Controls

Tag Helpers don't own the element they're associated with; they simply participate in the
rendering of the element and content. ASP.NET Web Server controls are declared and
invoked on a page.
Web Server controls have a non-trivial lifecycle that can make developing and debugging
difficult.
Web Server controls allow you to add functionality to the client Document Object Model
(DOM ) elements by using a client control. Tag Helpers have no DOM.
Web Server controls include automatic browser detection. Tag Helpers have no knowledge of
the browser.
Multiple Tag Helpers can act on the same element (see Avoiding Tag Helper conflicts ) while
you typically can't compose Web Server controls.
Tag Helpers can modify the tag and content of HTML elements that they're scoped to, but
don't directly modify anything else on a page. Web Server controls have a less specific scope
and can perform actions that affect other parts of your page; enabling unintended side effects.
Web Server controls use type converters to convert strings into objects. With Tag Helpers,
you work natively in C#, so you don't need to do type conversion.
Web Server controls use System.ComponentModel to implement the run-time and design-
time behavior of components and controls. System.ComponentModel includes the base classes
and interfaces for implementing attributes and type converters, binding to data sources, and
licensing components. Contrast that to Tag Helpers, which typically derive from TagHelper ,
and the TagHelper base class exposes only two methods, Process and ProcessAsync .
Customizing the Tag Helper element font

You can customize the font and colorization from Tools > Options > Environment > Fonts and
Colors:
Author Tag Helpers
Working with Forms
TagHelperSamples on GitHub contains Tag Helper samples for working with Bootstrap.
Author Tag Helpers in ASP.NET Core
By Rick Anderson
Get started with Tag Helpers

This tutorial provides an introduction to programming Tag Helpers. Introduction to Tag Helpers describes the
benefits that Tag Helpers provide.
A tag helper is any class that implements the ITagHelper interface. However, when you author a tag helper, you
generally derive from TagHelper , doing so gives you access to the Process method.
1. Create a new ASP.NET Core project called AuthoringTagHelpers. You won't need authentication for this
project.
2. Create a folder to hold the Tag Helpers called TagHelpers. The TagHelpers folder is not required, but it's a
reasonable convention. Now let's get started writing some simple tag helpers.
A minimal Tag Helper

In this section, you write a tag helper that updates an email tag. For example:
<email>Support</email>
The server will use our email tag helper to convert that markup into the following:
<a href="mailto:[email protected]">[email protected]</a>
That is, an anchor tag that makes this an email link. You might want to do this if you are writing a blog engine
and need it to send email for marketing, support, and other contacts, all to the same domain.
1. Add the following EmailTagHelper class to the TagHelpers folder.
using Microsoft.AspNetCore.Razor.TagHelpers;
namespace AuthoringTagHelpers.TagHelpers
{
public class EmailTagHelper : TagHelper
{
public override void Process(TagHelperContext context, TagHelperOutput output)
{
output.TagName = "a"; // Replaces <email> with <a> tag
}
}
}
Notes:
Tag helpers use a naming convention that targets elements of the root class name (minus the
TagHelper portion of the class name). In this example, the root name of EmailTagHelper is email,
so the <email> tag will be targeted. This naming convention should work for most tag helpers,
later on I'll show how to override it.
The EmailTagHelper class derives from TagHelper . The TagHelper class provides methods and
properties for writing Tag Helpers.
The overridden Process method controls what the tag helper does when executed. The TagHelper
class also provides an asynchronous version ( ProcessAsync ) with the same parameters.
The context parameter to Process (and ProcessAsync ) contains information associated with the
execution of the current HTML tag.
The output parameter to Process (and ProcessAsync ) contains a stateful HTML element
representative of the original source used to generate an HTML tag and content.
Our class name has a suffix of TagHelper, which is not required, but it's considered a best practice
convention. You could declare the class as:
public class Email : TagHelper
2. To make the EmailTagHelper class available to all our Razor views, add the addTagHelper directive to the
Views/_ViewImports.cshtml file:
The code above uses the wildcard syntax to specify all the tag helpers in our assembly will be available.
The first string after @addTagHelper specifies the tag helper to load (Use "*" for all tag helpers), and the
second string "AuthoringTagHelpers" specifies the assembly the tag helper is in. Also, note that the
second line brings in the ASP.NET Core MVC tag helpers using the wildcard syntax (those helpers are
discussed in Introduction to Tag Helpers.) It's the @addTagHelper directive that makes the tag helper
available to the Razor view. Alternatively, you can provide the fully qualified name (FQN ) of a tag helper
as shown below:
@addTagHelper AuthoringTagHelpers.TagHelpers.EmailTagHelper, AuthoringTagHelpers
To add a tag helper to a view using a FQN, you first add the FQN (
AuthoringTagHelpers.TagHelpers.EmailTagHelper ), and then the assembly name ( AuthoringTagHelpers). Most
developers will prefer to use the wildcard syntax. Introduction to Tag Helpers goes into detail on tag helper
adding, removing, hierarchy, and wildcard syntax.
3. Update the markup in the Views/Home/Contact.cshtml file with these changes:
@{
}
<address>
One Microsoft Way<br />
Redmond, WA 98052<br />
425.555.0100
</address>
<address>
<strong>Support:</strong><email>Support</email><br />
<strong>Marketing:</strong><email>Marketing</email>
</address>
4. Run the app and use your favorite browser to view the HTML source so you can verify that the email tags
are replaced with anchor markup (For example, <a>Support</a> ). Support and Marketing are rendered as
a links, but they don't have an href attribute to make them functional. We'll fix that in the next section.
SetAttribute and SetContent

In this section, we'll update the EmailTagHelper so that it will create a valid anchor tag for email. We'll update it
to take information from a Razor view (in the form of a mail-to attribute) and use that in generating the anchor.
Update the EmailTagHelper class with the following:

{
private const string EmailDomain = "contoso.com";
// Can be passed via <email mail-to="..." />.

// Pascal case gets translated into lower-kebab-case.
public string MailTo { get; set; }

{
var address = MailTo + "@" + EmailDomain;

output.Attributes.SetAttribute("href", "mailto:" + address);
output.Content.SetContent(address);
}
}
Notes:
Pascal-cased class and property names for tag helpers are translated into their lower kebab case.
Therefore, to use the MailTo attribute, you'll use <email mail-to="value"/> equivalent.
The last line sets the completed content for our minimally functional tag helper.
The highlighted line shows the syntax for adding attributes:
{
var address = MailTo + "@" + EmailDomain;

output.Attributes.SetAttribute("href", "mailto:" + address);
output.Content.SetContent(address);
}
That approach works for the attribute "href" as long as it doesn't currently exist in the attributes collection. You
can also use the output.Attributes.Add method to add a tag helper attribute to the end of the collection of tag
attributes.
1. Update the markup in the Views/Home/Contact.cshtml file with these changes:
@{
ViewData["Title"] = "Contact Copy";
}
<address>
One Microsoft Way Copy Version <br />
Redmond, WA 98052-6399<br />
425.555.0100
</address>
<address>
<strong>Support:</strong><email mail-to="Support"></email><br />
<strong>Marketing:</strong><email mail-to="Marketing"></email>
</address>
2. Run the app and verify that it generates the correct links.
NOTE
If you were to write the email tag self-closing ( <email mail-to="Rick" /> ), the final output would also be self-
closing. To enable the ability to write the tag with only a start tag ( <email mail-to="Rick"> ) you must decorate
the class with the following:
[HtmlTargetElement("email", TagStructure = TagStructure.WithoutEndTag)]

public class EmailVoidTagHelper : TagHelper
{
// Code removed for brevity
With a self-closing email tag helper, the output would be <a href="mailto:[email protected]" /> . Self-
closing anchor tags are not valid HTML, so you wouldn't want to create one, but you might want to create
a tag helper that's self-closing. Tag helpers set the type of the TagMode property after reading a tag.
ProcessAsync
In this section, we'll write an asynchronous email helper.
1. Replace the EmailTagHelper class with the following code:
{
public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
{
var content = await output.GetChildContentAsync();
var target = content.GetContent() + "@" + EmailDomain;
output.Attributes.SetAttribute("href", "mailto:" + target);
output.Content.SetContent(target);
}
}
Notes:
This version uses the asynchronous ProcessAsync method. The asynchronous
GetChildContentAsync returns a Task containing the TagHelperContent .
Use the output parameter to get contents of the HTML element.

2. Make the following change to the Views/Home/Contact.cshtml file so the tag helper can get the target
email.
@{
}
<address>
425.555.0100
</address>
<address>
</address>
3. Run the app and verify that it generates valid email links.
RemoveAll, PreContent.SetHtmlContent and PostContent.SetHtmlContent
1. Add the following BoldTagHelper class to the TagHelpers folder.
{
[HtmlTargetElement(Attributes = "bold")]
public class BoldTagHelper : TagHelper
{
{
output.Attributes.RemoveAll("bold");
output.PreContent.SetHtmlContent("<strong>");
output.PostContent.SetHtmlContent("</strong>");
}
}
}
Notes:
The [HtmlTargetElement] attribute passes an attribute parameter that specifies that any HTML
element that contains an HTML attribute named "bold" will match, and the Process override
method in the class will run. In our sample, the Process method removes the "bold" attribute and
surrounds the containing markup with <strong></strong> .
Because you don't want to replace the existing tag content, you must write the opening <strong>
tag with the PreContent.SetHtmlContent method and the closing </strong> tag with the
PostContent.SetHtmlContent method.
2. Modify the About.cshtml view to contain a bold attribute value. The completed code is shown below.
@{
}
<p bold>Use this area to provide additional information.</p>
<bold> Is this bold?</bold>
3. Run the app. You can use your favorite browser to inspect the source and verify the markup.
The [HtmlTargetElement] attribute above only targets HTML markup that provides an attribute name of
"bold". The <bold> element wasn't modified by the tag helper.
4. Comment out the [HtmlTargetElement] attribute line and it will default to targeting <bold> tags, that is,
HTML markup of the form <bold> . Remember, the default naming convention will match the class name
BoldTagHelper to <bold> tags.
5. Run the app and verify that the <bold> tag is processed by the tag helper.
Decorating a class with multiple [HtmlTargetElement] attributes results in a logical-OR of the targets. For
example, using the code below, a bold tag or a bold attribute will match.
[HtmlTargetElement("bold")]
[HtmlTargetElement(Attributes = "bold")]
public class BoldTagHelper : TagHelper
{
{
output.Attributes.RemoveAll("bold");
output.PreContent.SetHtmlContent("<strong>");
output.PostContent.SetHtmlContent("</strong>");
}
}
When multiple attributes are added to the same statement, the runtime treats them as a logical-AND. For
example, in the code below, an HTML element must be named "bold" with an attribute named "bold" (
<bold bold /> ) to match.
[HtmlTargetElement("bold", Attributes = "bold")]
You can also use the [HtmlTargetElement] to change the name of the targeted element. For example if you
wanted the BoldTagHelper to target <MyBold> tags, you would use the following attribute:
[HtmlTargetElement("MyBold")]
Pass a model to a Tag Helper

1. Add a Models folder.
2. Add the following WebsiteContext class to the Models folder:
using System;
namespace AuthoringTagHelpers.Models
{
public class WebsiteContext
{
public Version Version { get; set; }
public int CopyrightYear { get; set; }
public bool Approved { get; set; }
public int TagsToShow { get; set; }
}
}
3. Add the following WebsiteInformationTagHelper class to the TagHelpers folder.
using System;
using AuthoringTagHelpers.Models;
{
public class WebsiteInformationTagHelper : TagHelper
{
public WebsiteContext Info { get; set; }

{
output.TagName = "section";
output.Content.SetHtmlContent(
$@"<ul><li><strong>Version:</strong> {Info.Version}</li>
<li><strong>Copyright Year:</strong> {Info.CopyrightYear}</li>
<li><strong>Approved:</strong> {Info.Approved}</li>
<li><strong>Number of tags to show:</strong> {Info.TagsToShow}</li></ul>");
output.TagMode = TagMode.StartTagAndEndTag;
}
}
}
Notes:
As mentioned previously, tag helpers translates Pascal-cased C# class names and properties for
tag helpers into lower kebab case. Therefore, to use the WebsiteInformationTagHelper in Razor,
you'll write <website-information /> .
You are not explicitly identifying the target element with the [HtmlTargetElement] attribute, so the
default of website-information will be targeted. If you applied the following attribute (note it's not
kebab case but matches the class name):
[HtmlTargetElement("WebsiteInformation")]
The lower kebab case tag <website-information /> wouldn't match. If you want use the
[HtmlTargetElement] attribute, you would use kebab case as shown below:
[HtmlTargetElement("Website-Information")]
Elements that are self-closing have no content. For this example, the Razor markup will use a self-
closing tag, but the tag helper will be creating a section element (which isn't self-closing and you
are writing content inside the section element). Therefore, you need to set TagMode to
StartTagAndEndTag to write output. Alternatively, you can comment out the line setting TagMode
and write markup with a closing tag. (Example markup is provided later in this tutorial.)
The $ (dollar sign) in the following line uses an interpolated string:
$@"<ul><li><strong>Version:</strong> {Info.Version}</li>
4. Add the following markup to the About.cshtml view. The highlighted markup displays the web site
information.
@using AuthoringTagHelpers.Models
@{
}
<p bold>Use this area to provide additional information.</p>
<bold> Is this bold?</bold>
<h3> web site info </h3>

<website-information info="new WebsiteContext {
Version = new Version(1, 3),
CopyrightYear = 1638,
Approved = true,
TagsToShow = 131 }" />
NOTE
In the Razor markup shown below:

Approved = true,
TagsToShow = 131 }" />
Razor knows the info attribute is a class, not a string, and you want to write C# code. Any non-string tag helper
attribute should be written without the @ character.
5. Run the app, and navigate to the About view to see the web site information.
NOTE
You can use the following markup with a closing tag and remove the line with TagMode.StartTagAndEndTag in
the tag helper:

Approved = true,
TagsToShow = 131 }" >
</website-information>
Condition Tag Helper

The condition tag helper renders output when passed a true value.
1. Add the following ConditionTagHelper class to the TagHelpers folder.
{
[HtmlTargetElement(Attributes = nameof(Condition))]
public class ConditionTagHelper : TagHelper
{
public bool Condition { get; set; }

{
if (!Condition)
{
output.SuppressOutput();
}
}
}
}
2. Replace the contents of the Views/Home/Index.cshtml file with the following markup:
@using AuthoringTagHelpers.Models
@model WebsiteContext
@{
ViewData["Title"] = "Home Page";
}
<div>
<h3>Information about our website (outdated):</h3>
<Website-InforMation info="Model" />
<div condition="Model.Approved">
<p>
This website has <strong surround="em">@Model.Approved</strong> been approved yet.
Visit www.contoso.com for more information.
</p>
</div>
</div>
3. Replace the Index method in the Home controller with the following code:
public IActionResult Index(bool approved = false)
{
return View(new WebsiteContext
{
Approved = approved,
Version = new Version(1, 3, 3, 7),
TagsToShow = 20
});
}
4. Run the app and browse to the home page. The markup in the conditional div won't be rendered.
Append the query string ?approved=true to the URL (for example,
http://localhost:1235/Home/Index?approved=true ). approved is set to true and the conditional markup will
be displayed.
NOTE
Use the nameof operator to specify the attribute to target rather than specifying a string as you did with the bold tag
helper:
[HtmlTargetElement(Attributes = nameof(Condition))]
// [HtmlTargetElement(Attributes = "condition")]
public class ConditionTagHelper : TagHelper
{
public bool Condition { get; set; }

{
if (!Condition)
{
output.SuppressOutput();
}
}
}
The nameof operator will protect the code should it ever be refactored (we might want to change the name to
RedCondition ).
Avoid Tag Helper conflicts

In this section, you write a pair of auto-linking tag helpers. The first will replace markup containing a URL
starting with HTTP to an HTML anchor tag containing the same URL (and thus yielding a link to the URL ). The
second will do the same for a URL starting with WWW.
Because these two helpers are closely related and you may refactor them in the future, we'll keep them in the
same file.
1. Add the following AutoLinkerHttpTagHelper class to the TagHelpers folder.
[HtmlTargetElement("p")]
public class AutoLinkerHttpTagHelper : TagHelper
{
{
var childContent = await output.GetChildContentAsync();
// Find Urls in the content and replace them with their anchor tag equivalent.
output.Content.SetHtmlContent(Regex.Replace(
childContent.GetContent(),
@"\b(?:https?://)(\S+)\b",
"<a target=\"_blank\" href=\"$0\">$0</a>")); // http link version}
}
}
NOTE
The AutoLinkerHttpTagHelper class targets p elements and uses Regex to create the anchor.
2. Add the following markup to the end of the Views/Home/Contact.cshtml file:
@{
}
<address>
425.555.0100
</address>
<address>
</address>
<p>Visit us at http://docs.asp.net or at www.microsoft.com</p>
3. Run the app and verify that the tag helper renders the anchor correctly.
4. Update the AutoLinker class to include the AutoLinkerWwwTagHelper which will convert www text to an
anchor tag that also contains the original www text. The updated code is highlighted below:
{
{
@"\b(?:https?://)(\S+)\b",
}
}
public class AutoLinkerWwwTagHelper : TagHelper
{
{
@"\b(www\.)(\S+)\b",
"<a target=\"_blank\" href=\"http://$0\">$0</a>")); // www version
}
}
}
5. Run the app. Notice the www text is rendered as a link but the HTTP text isn't. If you put a break point in
both classes, you can see that the HTTP tag helper class runs first. The problem is that the tag helper
output is cached, and when the WWW tag helper is run, it overwrites the cached output from the HTTP
tag helper. Later in the tutorial we'll see how to control the order that tag helpers run in. We'll fix the code
with the following:
{
{
var childContent = output.Content.IsModified ? output.Content.GetContent() :
(await output.GetChildContentAsync()).GetContent();
childContent,
@"\b(?:https?://)(\S+)\b",
}
}
public class AutoLinkerWwwTagHelper : TagHelper
{
{
childContent,
@"\b(www\.)(\S+)\b",
"<a target=\"_blank\" href=\"http://$0\">$0</a>")); // www version
}
}
NOTE
In the first edition of the auto-linking tag helpers, you got the content of the target with the following code:
That is, you call GetChildContentAsync using the TagHelperOutput passed into the ProcessAsync method.
As mentioned previously, because the output is cached, the last tag helper to run wins. You fixed that problem with
the following code:

The code above checks to see if the content has been modified, and if it has, it gets the content from the output
buffer.
6. Run the app and verify that the two links work as expected. While it might appear our auto linker tag
helper is correct and complete, it has a subtle problem. If the WWW tag helper runs first, the www links
won't be correct. Update the code by adding the Order overload to control the order that the tag runs in.
The Order property determines the execution order relative to other tag helpers targeting the same
element. The default order value is zero and instances with lower values are executed first.
{
// This filter must run before the AutoLinkerWwwTagHelper as it searches and replaces http and
// the AutoLinkerWwwTagHelper adds http to the markup.
public override int Order
{
get { return int.MinValue; }
}
The above code will guarantee that the HTTP tag helper runs before the WWW tag helper. Change Order
to MaxValue and verify that the markup generated for the WWW tag is incorrect.
Inspect and retrieve child content

The tag helpers provide several properties to retrieve content.
The result of GetChildContentAsync can be appended to output.Content .
You can inspect the result of GetChildContentAsync with GetContent .
If you modify output.Content , the TagHelper body won't be executed or rendered unless you call
GetChildContentAsync as in our auto-linker sample:

{
{
childContent,
@"\b(?:https?://)(\S+)\b",
}
}
Multiple calls to GetChildContentAsync returns the same value and doesn't re-execute the TagHelper body
unless you pass in a false parameter indicating not to use the cached result.
Tag Helpers in forms in ASP.NET Core
By Rick Anderson, Dave Paquette, and Jerrie Pelser

This document demonstrates working with Forms and the HTML elements commonly used on a Form. The HTML
Form element provides the primary mechanism web apps use to post back data to the server. Most of this
document describes Tag Helpers and how they can help you productively create robust HTML forms. We
recommend you read Introduction to Tag Helpers before you read this document.
In many cases, HTML Helpers provide an alternative approach to a specific Tag Helper, but it's important to
recognize that Tag Helpers don't replace HTML Helpers and there's not a Tag Helper for each HTML Helper. When
an HTML Helper alternative exists, it's mentioned.
The Form Tag Helper

The Form Tag Helper:
Generates the HTML <FORM> action attribute value for a MVC controller action or named route
Generates a hidden Request Verification Token to prevent cross-site request forgery (when used with the
[ValidateAntiForgeryToken] attribute in the HTTP Post action method)
Provides the asp-route-<Parameter Name> attribute, where <Parameter Name> is added to the route values.
The routeValues parameters to Html.BeginForm and Html.BeginRouteForm provide similar functionality.
Has an HTML Helper alternative Html.BeginForm and Html.BeginRouteForm
Sample:
<form asp-controller="Demo" asp-action="Register" method="post">


</form>
The Form Tag Helper above generates the following HTML:
<form method="post" action="/Demo/Register">

<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>" />
</form>
The MVC runtime generates the action attribute value from the Form Tag Helper attributes asp-controller and
asp-action . The Form Tag Helper also generates a hidden Request Verification Token to prevent cross-site request
forgery (when used with the [ValidateAntiForgeryToken] attribute in the HTTP Post action method). Protecting a
pure HTML Form from cross-site request forgery is difficult, the Form Tag Helper provides this service for you.
Using a named route
The asp-route Tag Helper attribute can also generate markup for the HTML action attribute. An app with a route
named register could use the following markup for the registration page:
<form asp-route="register" method="post">
</form>
Many of the views in the Views/Account folder (generated when you create a new web app with Individual User
Accounts) contain the asp-route-returnurl attribute:
<form asp-controller="Account" asp-action="Login"

asp-route-returnurl="@ViewData["ReturnUrl"]"
NOTE
With the built in templates, returnUrl is only populated automatically when you try to access an authorized resource but
are not authenticated or authorized. When you attempt an unauthorized access, the security middleware redirects you to the
login page with the returnUrl set.
The Input Tag Helper

The Input Tag Helper binds an HTML <input> element to a model expression in your razor view.
Syntax:
<input asp-for="<Expression Name>" />
The Input Tag Helper:

Generates the id and HTML attributes for the expression name specified in the asp-for attribute.
name
asp-for="Property1.Property2" is equivalent to m => m.Property1.Property2 . The name of the expression is
what is used for the asp-for attribute value. See the Expression names section for additional information.
Sets the HTML type attribute value based on the model type and data annotation attributes applied to the
model property
Won't overwrite the HTML type attribute value when one is specified
Generates HTML5 validation attributes from data annotation attributes applied to model properties
Has an HTML Helper feature overlap with Html.TextBoxFor and Html.EditorFor . See the HTML Helper
alternatives to Input Tag Helper section for details.
Provides strong typing. If the name of the property changes and you don't update the Tag Helper you'll get
an error similar to the following:
An error occurred during the compilation of a resource required to process

this request. Please review the following specific error details and modify
your source code appropriately.
Type expected
'RegisterViewModel' does not contain a definition for 'Email' and no
extension method 'Email' accepting a first argument of type 'RegisterViewModel'
could be found (are you missing a using directive or an assembly reference?)
The Input Tag Helper sets the HTML type attribute based on the .NET type. The following table lists some
common .NET types and generated HTML type (not every .NET type is listed).
.NET TYPE INPUT TYPE
Bool type=”checkbox”
String type=”text”
DateTime type=”datetime”
Byte type=”number”
Int type=”number”
Single, Double type=”number”
The following table shows some common data annotations attributes that the input tag helper will map to specific
input types (not every validation attribute is listed):
ATTRIBUTE INPUT TYPE
[EmailAddress] type=”email”
[Url] type=”url”
[HiddenInput] type=”hidden”
[Phone] type=”tel”
[DataType(DataType.Password)] type=”password”
[DataType(DataType.Date)] type=”date”
[DataType(DataType.Time)] type=”time”
Sample:
namespace FormsTagHelper.ViewModels
{
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
[Required]
}
}
@model RegisterViewModel
<form asp-controller="Demo" asp-action="RegisterInput" method="post">

Email: <input asp-for="Email" /> <br />
Password: <input asp-for="Password" /><br />
<button type="submit">Register</button>
</form>
The code above generates the following HTML:
<form method="post" action="/Demo/RegisterInput">

Email:
<input type="email" data-val="true"
data-val-email="The Email Address field is not a valid email address."
data-val-required="The Email Address field is required."
id="Email" name="Email" value="" /> <br>
Password:
<input type="password" data-val="true"
data-val-required="The Password field is required."
id="Password" name="Password" /><br>
</form>
The data annotations applied to the Email and Password properties generate metadata on the model. The Input
Tag Helper consumes the model metadata and produces HTML5 data-val-* attributes (see Model Validation).
These attributes describe the validators to attach to the input fields. This provides unobtrusive HTML5 and jQuery
validation. The unobtrusive attributes have the format data-val-rule="Error Message" , where rule is the name of
the validation rule (such as data-val-required , data-val-email , data-val-maxlength , etc.) If an error message is
provided in the attribute, it's displayed as the value for the data-val-rule attribute. There are also attributes of the
form data-val-ruleName-argumentName="argumentValue" that provide additional details about the rule, for example,
data-val-maxlength-max="1024" .
HTML Helper alternatives to Input Tag Helper

Html.TextBox , Html.TextBoxFor , Html.Editor and Html.EditorFor have overlapping features with the Input Tag
Helper. The Input Tag Helper will automatically set the type attribute; Html.TextBox and Html.TextBoxFor won't.
Html.Editor and Html.EditorFor handle collections, complex objects and templates; the Input Tag Helper doesn't.
The Input Tag Helper, Html.EditorFor and Html.TextBoxFor are strongly typed (they use lambda expressions);
Html.TextBox and Html.Editor are not (they use expression names).
HtmlAttributes
@Html.Editor() and @Html.EditorFor() use a special ViewDataDictionary entry named htmlAttributes when
executing their default templates. This behavior is optionally augmented using additionalViewData parameters. The
key "htmlAttributes" is case-insensitive. The key "htmlAttributes" is handled similarly to the htmlAttributes object
passed to input helpers like @Html.TextBox() .
@Html.EditorFor(model => model.YourProperty,

new { htmlAttributes = new { @class="myCssClass", style="Width:100px" } })
Expression names
The asp-for attribute value is a ModelExpression and the right hand side of a lambda expression. Therefore,
asp-for="Property1" becomes m => m.Property1 in the generated code which is why you don't need to prefix with
Model . You can use the "@" character to start an inline expression and move before the m. :
@{
var joe = "Joe";
}
<input asp-for="@joe" />
Generates the following:
<input type="text" id="joe" name="joe" value="Joe" />
With collection properties, asp-for="CollectionProperty[23].Member" generates the same name as

asp-for="CollectionProperty[i].Member" when i has the value 23 .
When ASP.NET Core MVC calculates the value of ModelExpression , it inspects several sources, including
ModelState . Consider <input type="text" asp-for="@Name" /> . The calculated value attribute is the first non-null
value from:
ModelState entry with key "Name".
Result of the expression Model.Name .
Navigating child properties
You can also navigate to child properties using the property path of the view model. Consider a more complex
model class that contains a child Address property.
public class AddressViewModel

{
public string AddressLine1 { get; set; }
}
public class RegisterAddressViewModel

{
public AddressViewModel Address { get; set; }

}
In the view, we bind to Address.AddressLine1 :
@model RegisterAddressViewModel
<form asp-controller="Demo" asp-action="RegisterAddress" method="post">

Address: <input asp-for="Address.AddressLine1" /><br />
</form>
The following HTML is generated for Address.AddressLine1 :
<input type="text" id="Address_AddressLine1" name="Address.AddressLine1" value="" />
Expression names and Collections

Sample, a model containing an array of Colors :
public class Person

{
public List<string> Colors { get; set; }
public int Age { get; set; }

}
The action method:
public IActionResult Edit(int id, int colorIndex)

{
ViewData["Index"] = colorIndex;
return View(GetPerson(id));
}
The following Razor shows how you access a specific Color element:
@model Person
@{
var index = (int)ViewData["index"];
}
<form asp-controller="ToDo" asp-action="Edit" method="post">

@Html.EditorFor(m => m.Colors[index])
<label asp-for="Age"></label>
<input asp-for="Age" /><br />
<button type="submit">Post</button>
</form>
The Views/Shared/EditorTemplates/String.cshtml template:
@model string
<label asp-for="@Model"></label>
<input asp-for="@Model" /> <br />
Sample using List<T> :

{
public bool IsDone { get; set; }

}
The following Razor shows how to iterate over a collection:

@model List<ToDoItem>

<table>
<tr> <th>Name</th> <th>Is Done</th> </tr>
@for (int i = 0; i < Model.Count; i++)

{
<tr>
@Html.EditorFor(model => model[i])
</tr>
}
</table>
</form>
The Views/Shared/EditorTemplates/ToDoItem.cshtml template:
@model ToDoItem
<td>
<label asp-for="@Model.Name"></label>
</td>
<td>
<input asp-for="@Model.IsDone" />
</td>
@*
This template replaces the following Razor which evaluates the indexer three times.
<td>
<label asp-for="@Model[i].Name"></label>
@Html.DisplayFor(model => model[i].Name)
</td>
<td>
<input asp-for="@Model[i].IsDone" />
</td>
*@
NOTE
Always use for (and not foreach ) to iterate over a list. Evaluating an indexer in a LINQ expression can be expensive and
should be minimized.
NOTE
The commented sample code above shows how you would replace the lambda expression with the @ operator to access
each ToDoItem in the list.
The Textarea Tag Helper

The Textarea Tag Helper tag helper is similar to the Input Tag Helper.
Generates the id and name attributes, and the data validation attributes from the model for a <textarea>
element.
Provides strong typing.
HTML Helper alternative: Html.TextAreaFor
Sample:
{
public class DescriptionViewModel
{
[MinLength(5)]
[MaxLength(1024)]
}
}
@model DescriptionViewModel
<form asp-controller="Demo" asp-action="RegisterTextArea" method="post">

<textarea asp-for="Description"></textarea>
<button type="submit">Test</button>
</form>
The following HTML is generated:
<form method="post" action="/Demo/RegisterTextArea">

<textarea data-val="true"
data-val-maxlength="The field Description must be a string or array type with a maximum length of
'1024'."
data-val-maxlength-max="1024"
data-val-minlength="The field Description must be a string or array type with a minimum length of
'5'."
data-val-minlength-min="5"
id="Description" name="Description">
</textarea>
</form>
The Label Tag Helper

Generates the label caption and for attribute on a element for an expression name
HTML Helper alternative: Html.LabelFor .
The Label Tag Helper provides the following benefits over a pure HTML label element:
You automatically get the descriptive label value from the Display attribute. The intended display name
might change over time, and the combination of Display attribute and Label Tag Helper will apply the
Display everywhere it's used.
Less markup in source code

Strong typing with the model property.
Sample:
{
public class SimpleViewModel
{
[Required]
[EmailAddress]
}
}
@model SimpleViewModel
<form asp-controller="Demo" asp-action="RegisterLabel" method="post">

<label asp-for="Email"></label>
<input asp-for="Email" /> <br />
</form>
The following HTML is generated for the <label> element:
<label for="Email">Email Address</label>
The Label Tag Helper generated the for attribute value of "Email", which is the ID associated with the <input>
element. The Tag Helpers generate consistent id and for elements so they can be correctly associated. The
caption in this sample comes from the Display attribute. If the model didn't contain a Display attribute, the
caption would be the property name of the expression.
The Validation Tag Helpers

There are two Validation Tag Helpers. The Validation Message Tag Helper (which displays a validation message for
a single property on your model), and the Validation Summary Tag Helper (which displays a summary of validation
errors). The Input Tag Helper adds HTML5 client side validation attributes to input elements based on data
annotation attributes on your model classes. Validation is also performed on the server. The Validation Tag Helper
displays these error messages when a validation error occurs.
The Validation Message Tag Helper
Adds the HTML5 data-valmsg-for="property" attribute to the span element, which attaches the validation
error messages on the input field of the specified model property. When a client side validation error occurs,
jQuery displays the error message in the <span> element.
Validation also takes place on the server. Clients may have JavaScript disabled and some validation can only
be done on the server side.
HTML Helper alternative: Html.ValidationMessageFor
The Validation Message Tag Helper is used with the asp-validation-for attribute on a HTML span element.
<span asp-validation-for="Email"></span>
The Validation Message Tag Helper will generate the following HTML:
<span class="field-validation-valid"
data-valmsg-for="Email"
data-valmsg-replace="true"></span>
You generally use the Validation Message Tag Helper after an Input Tag Helper for the same property. Doing so
displays any validation error messages near the input that caused the error.
NOTE
You must have a view with the correct JavaScript and jQuery script references in place for client side validation. See Model
Validation for more information.
When a server side validation error occurs (for example when you have custom server side validation or client-side
validation is disabled), MVC places that error message as the body of the <span> element.
<span class="field-validation-error" data-valmsg-for="Email"

data-valmsg-replace="true">
The Email Address field is required.
</span>
The Validation Summary Tag Helper

Targets <div> elements with the asp-validation-summary attribute
HTML Helper alternative: @Html.ValidationSummary
The Validation Summary Tag Helper is used to display a summary of validation messages. The
asp-validation-summary attribute value can be any of the following:
ASP-VALIDATION-SUMMARY VALIDATION MESSAGES DISPLAYED
ValidationSummary.All Property and model level
ValidationSummary.ModelOnly Model
ValidationSummary.None None
Sample
In the following example, the data model is decorated with DataAnnotation attributes, which generates validation
error messages on the <input> element. When a validation error occurs, the Validation Tag Helper displays the
error message:
{
{
[Required]
[EmailAddress]
[Required]
}
}
<form asp-controller="Demo" asp-action="RegisterValidation" method="post">

<div asp-validation-summary="ModelOnly"></div>
<span asp-validation-for="Email"></span><br />
<span asp-validation-for="Password"></span><br />
</form>
The generated HTML (when the model is valid):
<form action="/DemoReg/Register" method="post">

<div class="validation-summary-valid" data-valmsg-summary="true">
<ul><li style="display:none"></li></ul></div>
Email: <input name="Email" id="Email" type="email" value=""
data-val-required="The Email field is required."
data-val-email="The Email field is not a valid email address."
data-val="true"> <br>
<span class="field-validation-valid" data-valmsg-replace="true"
data-valmsg-for="Email"></span><br>
Password: <input name="Password" id="Password" type="password"
data-val-required="The Password field is required." data-val="true"><br>
data-valmsg-for="Password"></span><br>
</form>
The Select Tag Helper

Generates select and associated option elements for properties of your model.
Has an HTML Helper alternative Html.DropDownListFor and Html.ListBoxFor
The Select Tag Helper asp-for specifies the model property name for the select element and asp-items specifies
the option elements. For example:
<select asp-for="Country" asp-items="Model.Countries"></select>
Sample:
{
public class CountryViewModel
{
public string Country { get; set; }
public List<SelectListItem> Countries { get; } = new List<SelectListItem>

{
new SelectListItem { Value = "MX", Text = "Mexico" },
new SelectListItem { Value = "CA", Text = "Canada" },
new SelectListItem { Value = "US", Text = "USA" },
};
}
}
The Index method initializes the CountryViewModel , sets the selected country and passes it to the Index view.
public IActionResult IndexOption(int id)

{
var model = new CountryViewModel();
model.Country = "CA";
return View(model);
}
The HTTP POST Index method displays the selection:
[HttpPost]
public IActionResult Index(CountryViewModel model)
{
{
var msg = model.Country + " selected";
return RedirectToAction("IndexSuccess", new { message = msg});
}
// If we got this far, something failed; redisplay form.

return View(model);
}
The Index view:
@model CountryViewModel
<form asp-controller="Home" asp-action="Index" method="post">

<br /><button type="submit">Register</button>
</form>
Which generates the following HTML (with "CA" selected):

<form method="post" action="/">
<select id="Country" name="Country">
<option value="MX">Mexico</option>
<option selected="selected" value="CA">Canada</option>
<option value="US">USA</option>
</select>
</form>
NOTE
We don't recommend using ViewBag or ViewData with the Select Tag Helper. A view model is more robust at providing
MVC metadata and generally less problematic.
The asp-for attribute value is a special case and doesn't require a Model prefix, the other Tag Helper attributes do
(such as asp-items )
Enum binding
It's often convenient to use <select> with an enum property and generate the SelectListItem elements from the
enum values.
Sample:
public class CountryEnumViewModel

{
public CountryEnum EnumCountry { get; set; }
}
}
{
public enum CountryEnum
{
[Display(Name = "United Mexican States")]
Mexico,
[Display(Name = "United States of America")]
USA,
Canada,
France,
Germany,
Spain
}
}
The GetEnumSelectList method generates a SelectList object for an enum.

@model CountryEnumViewModel
<form asp-controller="Home" asp-action="IndexEnum" method="post">

<select asp-for="EnumCountry"
asp-items="Html.GetEnumSelectList<CountryEnum>()"> >
</select>
</form>
You can decorate your enumerator list with the Display attribute to get a richer UI:
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}
<form method="post" action="/Home/IndexEnum">

<select data-val="true" data-val-required="The EnumCountry field is required."
id="EnumCountry" name="EnumCountry">
<option value="0">United Mexican States</option>
<option value="1">United States of America</option>
<option value="2">Canada</option>
<option value="3">France</option>
<option value="4">Germany</option>
<option selected="selected" value="5">Spain</option>
</select>
</form>
Option Group
The HTML <optgroup> element is generated when the view model contains one or more SelectListGroup objects.
The CountryViewModelGroup groups the SelectListItem elements into the "North America" and "Europe" groups:
public class CountryViewModelGroup
{
public CountryViewModelGroup()
{
var NorthAmericaGroup = new SelectListGroup { Name = "North America" };
var EuropeGroup = new SelectListGroup { Name = "Europe" };
Countries = new List<SelectListItem>

{
new SelectListItem
{
Value = "MEX",
Text = "Mexico",
Group = NorthAmericaGroup
},
new SelectListItem
{
Value = "CAN",
Text = "Canada",
},
new SelectListItem
{
Value = "US",
Text = "USA",
},
new SelectListItem
{
Value = "FR",
Text = "France",
Group = EuropeGroup
},
new SelectListItem
{
Value = "ES",
Text = "Spain",
Group = EuropeGroup
},
new SelectListItem
{
Value = "DE",
Text = "Germany",
Group = EuropeGroup
}
};
}
public List<SelectListItem> Countries { get; }
The two groups are shown below:

The generated HTML:
<form method="post" action="/Home/IndexGroup">

<optgroup label="North America">
<option value="MEX">Mexico</option>
<option value="CAN">Canada</option>
</optgroup>
<optgroup label="Europe">
<option value="FR">France</option>
<option value="ES">Spain</option>
<option value="DE">Germany</option>
</optgroup>
</select>
</form>
Multiple select
The Select Tag Helper will automatically generate the multiple = "multiple" attribute if the property specified in the
asp-for attribute is an IEnumerable . For example, given the following model:
{
public class CountryViewModelIEnumerable
{
public IEnumerable<string> CountryCodes { get; set; }

{
new SelectListItem { Value = "FR", Text = "France" },
new SelectListItem { Value = "ES", Text = "Spain" },
new SelectListItem { Value = "DE", Text = "Germany"}
};
}
}
With the following view:

@model CountryViewModelIEnumerable
<form asp-controller="Home" asp-action="IndexMultiSelect" method="post">

<select asp-for="CountryCodes" asp-items="Model.Countries"></select>
</form>
<form method="post" action="/Home/IndexMultiSelect">

<select id="CountryCodes"
multiple="multiple"
name="CountryCodes"><option value="MX">Mexico</option>
<option value="CA">Canada</option>
</select>
</form>
No selection
If you find yourself using the "not specified" option in multiple pages, you can create a template to eliminate
repeating the HTML:
<form asp-controller="Home" asp-action="IndexEmpty" method="post">

@Html.EditorForModel()
</form>
The Views/Shared/EditorTemplates/CountryViewModel.cshtml template:
<select asp-for="Country" asp-items="Model.Countries">

<option value="">--none--</option>
</select>
Adding HTML <option> elements isn't limited to the No selection case. For example, the following view and action
method will generate HTML similar to the code above:

{
return View(model);
}

<select asp-for="Country">
<option value=""><none></option>
</select>
</form>
The correct <option> element will be selected ( contain the selected="selected" attribute) depending on the
current Country value.
<form method="post" action="/Home/IndexEmpty">

<option value="CA" selected="selected">Canada</option>
</select>
</form>
Tag Helpers
HTML Form element
Request Verification Token
Model Binding
Model Validation
IAttributeAdapter Interface
Code snippets for this document
Tag Helper Components in ASP.NET Core
By Scott Addie and Fiyaz Bin Hasan

A Tag Helper Component is a Tag Helper that allows you to conditionally modify or add HTML elements from
server-side code. This feature is available in ASP.NET Core 2.0 or later.
ASP.NET Core includes two built-in Tag Helper Components: head and body . They're located in the
Microsoft.AspNetCore.Mvc.Razor.TagHelpers namespace and can be used in both MVC and Razor Pages. Tag
Helper Components don't require registration with the app in _ViewImports.cshtml.
Use cases
Two common use cases of Tag Helper Components include:
1. Injecting a <link> into the <head> .
2. Injecting a <script> into the <body> .
The following sections describe these use cases.

Inject into HTML head element
Inside the HTML <head> element, CSS files are commonly imported with the HTML <link> element. The
following code injects a <link> element into the <head> element using the head Tag Helper Component:
using System;
namespace RazorPagesSample.TagHelpers
{
public class AddressStyleTagHelperComponent : TagHelperComponent
{
private readonly string _style =
@"<link rel=""stylesheet"" href=""/css/address.css"" />";
public override int Order => 1;
public override Task ProcessAsync(TagHelperContext context,

TagHelperOutput output)
{
if (string.Equals(context.TagName, "head",
StringComparison.OrdinalIgnoreCase))
{
output.PostContent.AppendHtml(_style);
}
}
}
}
In the preceding code:

AddressStyleTagHelperComponent implements TagHelperComponent. The abstraction:
Allows initialization of the class with a TagHelperContext.
Enables the use of Tag Helper Components to add or modify HTML elements.
The Order property defines the order in which the Components are rendered. Order is necessary when there
are multiple usages of Tag Helper Components in an app.
ProcessAsync compares the execution context's TagName property value to head . If the comparison evaluates
to true, the content of the _style field is injected into the HTML <head> element.
Inject into HTML body element
The body Tag Helper Component can inject a <script> element into the <body> element. The following code
demonstrates this technique:
using System;
using System.IO;
{
public class AddressScriptTagHelperComponent : TagHelperComponent
{
public override async Task ProcessAsync(TagHelperContext context,

{
if (string.Equals(context.TagName, "body",
StringComparison.OrdinalIgnoreCase))
{
var script = await File.ReadAllTextAsync(
"TagHelpers/Templates/AddressToolTipScript.html");
output.PostContent.AppendHtml(script);
}
}
}
}
A separate HTML file is used to store the <script> element. The HTML file makes the code cleaner and more
maintainable. The preceding code reads the contents of TagHelpers/Templates/AddressToolTipScript.html and
appends it with the Tag Helper output. The AddressToolTipScript.html file includes the following markup:
<script>
$("address[printable]").hover(function() {
$(this).attr({
"data-toggle": "tooltip",
"data-placement": "right",
"title": "Home of Microsoft!"
});
});
</script>
The preceding code binds a Bootstrap tooltip widget to any <address> element that includes a printable
attribute. The effect is visible when a mouse pointer hovers over the element.
Register a Component
A Tag Helper Component must be added to the app's Tag Helper Components collection. There are three ways to
add to the collection:
1. Registration via services container
2. Registration via Razor file
3. Registration via Page Model or controller
Registration via services container
If the Tag Helper Component class isn't managed with ITagHelperComponentManager, it must be registered with
the dependency injection (DI) system. The following Startup.ConfigureServices code registers the
AddressStyleTagHelperComponent and AddressScriptTagHelperComponent classes with a transient lifetime:

{
{
});
services.AddMvc()
services.AddTransient<ITagHelperComponent,
AddressScriptTagHelperComponent>();
services.AddTransient<ITagHelperComponent,
AddressStyleTagHelperComponent>();
}
Registration via Razor file

If the Tag Helper Component isn't registered with DI, it can be registered from a Razor Pages page or an MVC
view. This technique is used for controlling the injected markup and the component execution order from a Razor
file.
ITagHelperComponentManager is used to add Tag Helper Components or remove them from the app. The following
code demonstrates this technique with AddressTagHelperComponent :
@using RazorPagesSample.TagHelpers;
@using Microsoft.AspNetCore.Mvc.Razor.TagHelpers;
@inject ITagHelperComponentManager manager;
@{
string markup;
if (Model.IsWeekend)
{
markup = "<em class='text-warning'>Office closed today!</em>";
}
else
{
markup = "<em class='text-info'>Office open today!</em>";
}
manager.Components.Add(new AddressTagHelperComponent(markup, 1));

}

The @inject directive provides an instance of ITagHelperComponentManager . The instance is assigned to a
variable named manager for access downstream in the Razor file.
An instance of AddressTagHelperComponent is added to the app's Tag Helper Components collection.
AddressTagHelperComponent is modified to accommodate a constructor that accepts the markup and order
parameters:
private readonly string _markup;
public override int Order { get; }
public AddressTagHelperComponent(string markup = "", int order = 1)

{
_markup = markup;
Order = order;
}
The provided markup parameter is used in ProcessAsync as follows:

{
if (string.Equals(context.TagName, "address",
StringComparison.OrdinalIgnoreCase) &&
output.Attributes.ContainsName("printable"))
{
TagHelperContent childContent = await output.GetChildContentAsync();
string content = childContent.GetContent();
$"<div>{content}<br>{_markup}</div>{_printableButton}");
}
}
Registration via Page Model or controller

If the Tag Helper Component isn't registered with DI, it can be registered from a Razor Pages page model or an
MVC controller. This technique is useful for separating C# logic from Razor files.
Constructor injection is used to access an instance of ITagHelperComponentManager . The Tag Helper Component is
added to the instance's Tag Helper Components collection. The following Razor Pages page model demonstrates
this technique with AddressTagHelperComponent :
using System;
using Microsoft.AspNetCore.Mvc.Razor.TagHelpers;
using RazorPagesSample.TagHelpers;

{
private readonly ITagHelperComponentManager _tagHelperComponentManager;
public bool IsWeekend

{
get
{
var dayOfWeek = DateTime.Now.DayOfWeek;
return dayOfWeek == DayOfWeek.Saturday ||

dayOfWeek == DayOfWeek.Sunday;
}
}
public IndexModel(ITagHelperComponentManager tagHelperComponentManager)

{
_tagHelperComponentManager = tagHelperComponentManager;
}
public void OnGet()

{
string markup;
if (IsWeekend)
{
markup = "<em class='text-warning'>Office closed today!</em>";
}
else
{
markup = "<em class='text-info'>Office open today!</em>";
}
_tagHelperComponentManager.Components.Add(
new AddressTagHelperComponent(markup, 1));
}
}

Constructor injection is used to access an instance of ITagHelperComponentManager .
An instance of AddressTagHelperComponent is added to the app's Tag Helper Components collection.
Create a Component
To create a custom Tag Helper Component:
Create a public class deriving from TagHelperComponentTagHelper.
Apply an [HtmlTargetElement] attribute to the class. Specify the name of the target HTML element.
Optional: Apply an [EditorBrowsable(EditorBrowsableState.Never)] attribute to the class to suppress the type's
display in IntelliSense.
The following code creates a custom Tag Helper Component that targets the <address> HTML element:
using System.ComponentModel;
{
[HtmlTargetElement("address")]
[EditorBrowsable(EditorBrowsableState.Never)]
public class AddressTagHelperComponentTagHelper : TagHelperComponentTagHelper
{
public AddressTagHelperComponentTagHelper(
ITagHelperComponentManager componentManager,
ILoggerFactory loggerFactory) : base(componentManager, loggerFactory)
{
}
}
}
Use the custom address Tag Helper Component to inject HTML markup as follows:
public class AddressTagHelperComponent : TagHelperComponent

{
private readonly string _printableButton =
"<button type='button' class='btn btn-info' onclick=\"window.open("
"'https://binged.it/2AXRRYw')\">" +
"<span class='glyphicon glyphicon-road' aria-hidden='true'></span>" +
"</button>";

{
if (string.Equals(context.TagName, "address",
StringComparison.OrdinalIgnoreCase) &&
output.Attributes.ContainsName("printable"))
{
var content = await output.GetChildContentAsync();
$"<div>{content.GetContent()}</div>{_printableButton}");
}
}
}
The preceding ProcessAsync method injects the HTML provided to SetHtmlContent into the matching <address>
element. The injection occurs when:
The execution context's TagName property value equals address .
The corresponding <address> element has a printable attribute.
For example, the if statement evaluates to true when processing the following <address> element:
<address printable>
Redmond, WA 98052-6399<br />
425.555.0100
</address>
ASP.NET Core built-in Tag Helpers
ASP.NET Core built-in Tag Helpers
By Peter Kellner
ASP.NET Core includes many built-in Tag Helpers to boost your productivity. This section provides an overview of
the built-in Tag Helpers.
NOTE
There are built-in Tag Helpers which aren't discussed, since they're used internally by the Razor view engine. This includes a
Tag Helper for the ~ character, which expands to the root path of the website.
Built-in ASP.NET Core Tag Helpers

Anchor Tag Helper
Cache Tag Helper
Environment Tag Helper
Form Tag Helper
Image Tag Helper
Input Tag Helper
Label Tag Helper
Partial Tag Helper
Select Tag Helper
Textarea Tag Helper
Validation Message Tag Helper
Validation Summary Tag Helper
Tag Helper Components in ASP.NET Core
Anchor Tag Helper in ASP.NET Core
By Peter Kellner and Scott Addie

The Anchor Tag Helper enhances the standard HTML anchor ( <a ... ></a> ) tag by adding new attributes. By
convention, the attribute names are prefixed with asp- . The rendered anchor element's href attribute value is
determined by the values of the asp- attributes.
SpeakerController is used in samples throughout this document:
using System.Linq;
public class SpeakerController : Controller

{
private List<Speaker> Speakers =
new List<Speaker>
{
new Speaker {SpeakerId = 10},
new Speaker {SpeakerId = 11},
new Speaker {SpeakerId = 12}
};
[Route("Speaker/{id:int}")]
public IActionResult Detail(int id) =>
View(Speakers.FirstOrDefault(a => a.SpeakerId == id));
[Route("/Speaker/Evaluations",
Name = "speakerevals")]
public IActionResult Evaluations() => View();
[Route("/Speaker/EvaluationsCurrent",
Name = "speakerevalscurrent")]
public IActionResult Evaluations(
int speakerId,
bool currentYear) => View();
public IActionResult Index() => View(Speakers);

}
public class Speaker

{
public int SpeakerId { get; set; }
}
An inventory of the asp- attributes follows.
asp-controller
The asp-controller attribute assigns the controller used for generating the URL. The following markup lists all
speakers:
<a asp-controller="Speaker"
asp-action="Index">All Speakers</a>
The generated HTML:
<a href="/Speaker">All Speakers</a>
If the asp-controller attribute is specified and asp-action isn't, the default asp-action value is the controller
action associated with the currently executing view. If asp-action is omitted from the preceding markup, and
the Anchor Tag Helper is used in HomeController's Index view (/Home), the generated HTML is:
<a href="/Home">All Speakers</a>
asp-action
The asp-action attribute value represents the controller action name included in the generated href attribute.
The following markup sets the generated href attribute value to the speaker evaluations page:
asp-action="Evaluations">Speaker Evaluations</a>
The generated HTML:
<a href="/Speaker/Evaluations">Speaker Evaluations</a>
If no asp-controller attribute is specified, the default controller calling the view executing the current view is
used.
If the asp-action attribute value is Index , then no action is appended to the URL, leading to the invocation of
the default Index action. The action specified (or defaulted), must exist in the controller referenced in
asp-controller .
asp-route-{value}
The asp-route-{value} attribute enables a wildcard route prefix. Any value occupying the {value} placeholder is
interpreted as a potential route parameter. If a default route isn't found, this route prefix is appended to the
generated href attribute as a request parameter and value. Otherwise, it's substituted in the route template.
Consider the following controller action:
public IActionResult AnchorTagHelper(int id)

{
var speaker = new Speaker
{
SpeakerId = id
};
return View(speaker);
}
With a default route template defined in Startup.Configure:

{
// need route and attribute on controller: [Area("Blogs")]
routes.MapRoute(name: "areaRoute",
template: "{area:exists}/{controller=Home}/{action=Index}");
// default route for non-areas

routes.MapRoute(
name: "default",
});
The MVC view uses the model, provided by the action, as follows:
@model Speaker
<!DOCTYPE html>
<html>
<body>
asp-action="Detail"
asp-route-id="@Model.SpeakerId">SpeakerId: @Model.SpeakerId</a>
</body>
</html>
The default route's {id?} placeholder was matched. The generated HTML:
<a href="/Speaker/Detail/12">SpeakerId: 12</a>
Assume the route prefix isn't part of the matching routing template, as with the following MVC view:
@model Speaker
<!DOCTYPE html>
<html>
<body>
asp-action="Detail"
asp-route-speakerid="@Model.SpeakerId">SpeakerId: @Model.SpeakerId</a>
<body>
</html>
The following HTML is generated because speakerid wasn't found in the matching route:
<a href="/Speaker/Detail?speakerid=12">SpeakerId: 12</a>
If either asp-controller or asp-action aren't specified, then the same default processing is followed as is in the
asp-route attribute.
asp-route
The asp-route attribute is used for creating a URL linking directly to a named route. Using routing attributes, a
route can be named as shown in the SpeakerController and used in its Evaluations action:
[Route("/Speaker/Evaluations",
Name = "speakerevals")]
public IActionResult Evaluations() => View();
In the following markup, the asp-route attribute references the named route:
<a asp-route="speakerevals">Speaker Evaluations</a>
The Anchor Tag Helper generates a route directly to that controller action using the URL /Speaker/Evaluations.
The generated HTML:
<a href="/Speaker/Evaluations">Speaker Evaluations</a>
If asp-controller or asp-action is specified in addition to asp-route , the route generated may not be what
you expect. To avoid a route conflict, asp-route shouldn't be used with the asp-controller and asp-action
attributes.
asp-all-route-data
The asp-all-route-data attribute supports the creation of a dictionary of key-value pairs. The key is the
parameter name, and the value is the parameter value.
In the following example, a dictionary is initialized and passed to a Razor view. Alternatively, the data could be
passed in with your model.
@{
var parms = new Dictionary<string, string>
{
{ "speakerId", "11" },
{ "currentYear", "true" }
};
}
<a asp-route="speakerevalscurrent"
asp-all-route-data="parms">Speaker Evaluations</a>
The preceding code generates the following HTML:
<a href="/Speaker/EvaluationsCurrent?speakerId=11&currentYear=true">Speaker Evaluations</a>
The asp-all-route-data dictionary is flattened to produce a querystring meeting the requirements of the
overloaded Evaluations action:
[Route("/Speaker/EvaluationsCurrent",
Name = "speakerevalscurrent")]
public IActionResult Evaluations(
int speakerId,
bool currentYear) => View();
If any keys in the dictionary match route parameters, those values are substituted in the route as appropriate.
The other non-matching values are generated as request parameters.
asp-fragment
The asp-fragment attribute defines a URL fragment to append to the URL. The Anchor Tag Helper adds the
hash character (#). Consider the following markup:
asp-action="Evaluations"
asp-fragment="SpeakerEvaluations">Speaker Evaluations</a>
The generated HTML:
<a href="/Speaker/Evaluations#SpeakerEvaluations">Speaker Evaluations</a>
Hash tags are useful when building client-side apps. They can be used for easy marking and searching in
JavaScript, for example.
asp-area
The asp-area attribute sets the area name used to set the appropriate route. The following example depicts how
the area attribute causes a remapping of routes. Setting asp-area to "Blogs" prefixes the directory Areas/Blogs
to the routes of the associated controllers and views for this anchor tag.
<Project name>
wwwroot
Areas
Blogs
Controllers
HomeController.cs
Views
Home
AboutBlog.cshtml
Index.cshtml
_ViewStart.cshtml
Controllers
Given the preceding directory hierarchy, the markup to reference the AboutBlog.cshtml file is:
<a asp-area="Blogs"
asp-controller="Home"
asp-action="AboutBlog">About Blog</a>
The generated HTML:
<a href="/Blogs/Home/AboutBlog">About Blog</a>

TIP
For areas to work in an MVC app, the route template must include a reference to the area, if it exists. That template is
represented by the second parameter of the routes.MapRoute method call in Startup.Configure:
{
// need route and attribute on controller: [Area("Blogs")]
routes.MapRoute(name: "areaRoute",
template: "{area:exists}/{controller=Home}/{action=Index}");
// default route for non-areas

routes.MapRoute(
name: "default",
});
asp-protocol
The asp-protocol attribute is for specifying a protocol (such as https ) in your URL. For example:
<a asp-protocol="https"
asp-action="About">About</a>
The generated HTML:
<a href="https://localhost/Home/About">About</a>
The host name in the example is localhost, but the Anchor Tag Helper uses the website's public domain when
generating the URL.
asp-host
The asp-host attribute is for specifying a host name in your URL. For example:
<a asp-protocol="https"
asp-host="microsoft.com"
asp-action="About">About</a>
The generated HTML:
<a href="https://microsoft.com/Home/About">About</a>
asp-page
The asp-page attribute is used with Razor Pages. Use it to set an anchor tag's href attribute value to a specific
page. Prefixing the page name with a forward slash ("/") creates the URL.
The following sample points to the attendee Razor Page:
<a asp-page="/Attendee">All Attendees</a>

The generated HTML:
<a href="/Attendee">All Attendees</a>
The asp-page attribute is mutually exclusive with the asp-route , asp-controller , and asp-action attributes.
However, asp-page can be used with asp-route-{value} to control routing, as the following markup
demonstrates:
<a asp-page="/Attendee"
asp-route-attendeeid="10">View Attendee</a>
The generated HTML:
<a href="/Attendee?attendeeid=10">View Attendee</a>
asp-page-handler
The asp-page-handler attribute is used with Razor Pages. It's intended for linking to specific page handlers.
Consider the following page handler:
public void OnGetProfile(int attendeeId)

{
ViewData["AttendeeId"] = attendeeId;
// code omitted for brevity

}
The page model's associated markup links to the OnGetProfile page handler. Note that the On<Verb> prefix of
the page handler method name is omitted in the asp-page-handler attribute value. If this were an asynchronous
method, the Async suffix would be omitted too.
<a asp-page="/Attendee"
asp-page-handler="Profile"
asp-route-attendeeid="12">Attendee Profile</a>
The generated HTML:
<a href="/Attendee?attendeeid=12&handler=Profile">Attendee Profile</a>
Areas
Intro to Razor Pages
Cache Tag Helper in ASP.NET Core MVC
By Peter Kellner
The Cache Tag Helper provides the ability to dramatically improve the performance of your ASP.NET Core app
by caching its content to the internal ASP.NET Core cache provider.
The Razor View Engine sets the default expires-after to twenty minutes.
The following Razor markup caches the date/time:
<cache>@DateTime.Now</cache>
The first request to the page that contains CacheTagHelper will display the current date/time. Additional requests
will show the cached value until the cache expires (default 20 minutes) or is evicted by memory pressure.
You can set the cache duration with the following attributes:
Cache Tag Helper Attributes

enabled
ATTRIBUTE TYPE VALID VALUES
boolean "true" (default)
"false"
Determines whether the content enclosed by the Cache Tag Helper is cached. The default is true . If set to false
this Cache Tag Helper will have no caching effect on the rendered output.
Example:
<cache enabled="true">
Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>
expires-on
ATTRIBUTE TYPE EXAMPLE VALUE
DateTimeOffset "@new DateTime(2025,1,29,17,02,0)"
Sets an absolute expiration date. The following example will cache the contents of the Cache Tag Helper until 5:02
PM on January 29, 2025.
Example:
<cache expires-on="@new DateTime(2025,1,29,17,02,0)">
</cache>
expires-after
TimeSpan "@TimeSpan.FromSeconds(120)"
Sets the length of time from the first request time to cache the contents.
Example:
<cache expires-after="@TimeSpan.FromSeconds(120)">
</cache>
expires-sliding
TimeSpan "@TimeSpan.FromSeconds(60)"
Sets the time that a cache entry should be evicted if it has not been accessed.
Example:
<cache expires-sliding="@TimeSpan.FromSeconds(60)">
</cache>
vary-by-header
ATTRIBUTE TYPE EXAMPLE VALUES
String "User-Agent"
"User-Agent,content-encoding"
Accepts a single header value or a comma-separated list of header values that trigger a cache refresh when they
change. The following example monitors the header value User-Agent . The example will cache the content for
every different User-Agent presented to the web server.
Example:
<cache vary-by-header="User-Agent">
</cache>
vary-by-query
String "Make"
"Make,Model"
Accepts a single header value or a comma-separated list of header values that trigger a cache refresh when the
header value changes. The following example looks at the values of Make and Model .
Example:
<cache vary-by-query="Make,Model">
</cache>
vary-by-route
String "Make"
"Make,Model"
route data parameter value(s) change. Example:
Startup.cs
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{Make?}/{Model?}");
Index.cshtml
<cache vary-by-route="Make,Model">
</cache>
vary-by-cookie
String ".AspNetCore.Identity.Application"
".AspNetCore.Identity.Application,HairColor"
header values(s) change. The following example looks at the cookie associated with ASP.NET Core Identity.
When a user is authenticated the request cookie to be set which triggers a cache refresh.
Example:
<cache vary-by-cookie=".AspNetCore.Identity.Application">
</cache>
vary-by-user
Boolean "true"
"false" (default)
Specifies whether or not the cache should reset when the logged-in user (or Context Principal) changes. The
current user is also known as the Request Context Principal and can be viewed in a Razor view by referencing
@User.Identity.Name .
The following example looks at the current logged in user.

Example:
<cache vary-by-user="true">
</cache>
Using this attribute maintains the contents in cache through a log-in and log-out cycle. When using
vary-by-user="true" , a log-in and log-out action invalidates the cache for the authenticated user. The cache is
invalidated because a new unique cookie value is generated on login. Cache is maintained for the anonymous
state when no cookie is present or has expired. This means if no user is logged in, the cache will be maintained.
vary-by
String "@Model"
Allows for customization of what data gets cached. When the object referenced by the attribute's string value
changes, the content of the Cache Tag Helper is updated. Often a string-concatenation of model values are
assigned to this attribute. Effectively, that means an update to any of the concatenated values invalidates the
cache.
The following example assumes the controller method rendering the view sums the integer value of the two route
parameters, myParam1 and myParam2 , and returns that as the single model property. When this sum changes, the
content of the Cache Tag Helper is rendered and cached again.
Example:
Action:
public IActionResult Index(string myParam1,string myParam2,string myParam3)
{
int num1;
int num2;
int.TryParse(myParam1, out num1);
int.TryParse(myParam2, out num2);
return View(viewName, num1 + num2);
}
Index.cshtml
<cache vary-by="@Model"">
</cache>
priority
CacheItemPriority "High"
"Low"
"NeverRemove"
"Normal"
Provides cache eviction guidance to the built-in cache provider. The web server will evict Low cache entries first
when it's under memory pressure.
Example:
<cache priority="High">
</cache>
The priority attribute doesn't guarantee a specific level of cache retention. CacheItemPriority is only a
suggestion. Setting this attribute to NeverRemove doesn't guarantee that the cache will always be retained. See
Additional Resources for more information.
The Cache Tag Helper is dependent on the memory cache service. The Cache Tag Helper adds the service if it has
not been added.
Cache in-memory
Distributed Cache Tag Helper in ASP.NET Core
By Peter Kellner
The Distributed Cache Tag Helper provides the ability to dramatically improve the performance of your ASP.NET
Core app by caching its content to a distributed cache source.
The Distributed Cache Tag Helper inherits from the same base class as the Cache Tag Helper. All attributes
associated with the Cache Tag Helper will also work on the Distributed Tag Helper.
The Distributed Cache Tag Helper follows the Explicit Dependencies Principle known as Constructor
Injection. Specifically, the IDistributedCache interface container is passed into the Distributed Cache Tag
Helper's constructor. If no specific concrete implementation of IDistributedCache has been created in
ConfigureServices , usually found in startup.cs, then the Distributed Cache Tag Helper will use the same in-
memory provider for storing cached data as the basic Cache Tag Helper.
Distributed Cache Tag Helper Attributes

enabled expires-on expires-after expires-sliding vary-by-header vary-by-query vary-by-route vary-by-cookie
vary-by-user vary-by priority
See Cache Tag Helper for definitions. Distributed Cache Tag Helper inherits from the same class as Cache Tag
Helper so all these attributes are common from Cache Tag Helper.
name (required)
string "my-distributed-cache-unique-key-101"
The required name attribute is used as a key to that cache stored for each instance of a Distributed Cache Tag
Helper. Unlike the basic Cache Tag Helper that assigns a key to each Cache Tag Helper instance based on the
Razor page name and location of the Tag Helper in the razor page, the Distributed Cache Tag Helper only bases
its key on the attribute name
Usage Example:
<distributed-cache name="my-distributed-cache-unique-key-101">
Time Inside Cache Tag Helper: @DateTime.Now
</distributed-cache>
Distributed Cache Tag Helper IDistributedCache implementations

There are two implementations of IDistributedCache built in to ASP.NET Core. One is based on SQL Server and
the other is based on Redis. Details of these implementations can be found at Work with a distributed cache in
ASP.NET Core. Both implementations involve setting an instance of IDistributedCache in ASP.NET Core's
Startup.cs.
There are no tag attributes specifically associated with using any specific implementation of IDistributedCache .
Work with a distributed cache in ASP.NET Core
Cache in-memory in ASP.NET Core
Introduction to Identity on ASP.NET Core
Environment Tag Helper in ASP.NET Core
By Peter Kellner and Hisham Bin Ateya

The Environment Tag Helper conditionally renders its enclosed content based on the current hosting environment.
Its single attribute names is a comma separated list of environment names, that if any match to the current
environment, will trigger the enclosed content to be rendered.
Environment Tag Helper Attributes

names
Accepts a single hosting environment name or a comma-separated list of hosting environment names that trigger
the rendering of the enclosed content.
These value(s) are compared to the current value returned from the ASP.NET Core static property
HostingEnvironment.EnvironmentName . This value is one of the following: Staging; Development or Production.
The comparison ignores case.
An example of a valid environment tag helper is:
<strong>HostingEnvironment.EnvironmentName is Staging or Production</strong>
</environment>
include and exclude attributes

ASP.NET Core 2.x adds the include & exclude attributes. These attributes control rendering the enclosed
content based on the included or excluded hosting environment names.
include ASP.NET Core 2.0 and later
The include property has a similar behavior of the names attribute in ASP.NET Core 1.0.
<environment include="Staging,Production">
</environment>
exclude ASP.NET Core 2.0 and later

In contrast, the exclude property lets the EnvironmentTagHelper render the enclosed content for all hosting
environment names except the one(s) that you specified.
</environment>

The Form Tag Helper

Sample:

</form>

</form>
Using a named route
</form>

NOTE

Syntax:

name
model property

Type expected
Sample:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

Email:
Password:
</form>

HtmlAttributes

Expression names
@{
var joe = "Joe";
}

value from:

{
}

{

}

</form>

public class Person

{

}
The action method:

{
}
@model Person
@{
}

</form>
@model string

{

}


<table>

{
<tr>
</tr>
}
</table>
</form>
@model ToDoItem
<td>
</td>
<td>
</td>
@*
<td>
</td>
<td>
</td>
*@
NOTE
NOTE

element.
Sample:
{
{
[MinLength(5)]
[MaxLength(1024)]
}
}

</form>

'1024'."
'5'."
</textarea>
</form>


Sample:
{
{
[Required]
[EmailAddress]
}
}

</form>

NOTE

</span>

Sample
error message:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

</form>

Sample:
{
{

{
};
}
}

{
return View(model);
}
[HttpPost]
{
{
}

return View(model);
}
The Index view:

</form>

</select>
</form>
NOTE
Enum binding
enum values.
Sample:

{
}
}
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}


</select>
</form>
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}

</select>
</form>
Option Group
{
{

{
new SelectListItem
{
Value = "MEX",
Text = "Mexico",
},
new SelectListItem
{
Value = "CAN",
Text = "Canada",
},
new SelectListItem
{
Value = "US",
Text = "USA",
},
new SelectListItem
{
Value = "FR",
Text = "France",
Group = EuropeGroup
},
new SelectListItem
{
Value = "ES",
Text = "Spain",
Group = EuropeGroup
},
new SelectListItem
{
Value = "DE",
Text = "Germany",
Group = EuropeGroup
}
};
}

The generated HTML:

</optgroup>
</optgroup>
</select>
</form>
Multiple select
{
{

{
};
}
}


</form>

multiple="multiple"
</select>
</form>
No selection
repeating the HTML:

</form>

</select>

{
return View(model);
}

</select>
</form>

</select>
</form>
Tag Helpers
HTML Form element
Model Binding
Model Validation
Image Tag Helper in ASP.NET Core
By Peter Kellner
The Image Tag Helper enhances the img ( <img> ) tag. It requires a src tag as well as the boolean attribute
asp-append-version .
If the image source ( src ) is a static file on the host web server, a unique cache busting string is appended as a
query parameter to the image source. This ensures that if the file on the host web server changes, a unique request
URL is generated that includes the updated request parameter. The cache busting string is a unique value
representing the hash of the static image file.
If the image source ( src ) isn't a static file (for example a remote URL or the file doesn't exist on the server), the
<img> tag's src attribute is generated with no cache busting query string parameter.
Image Tag Helper Attributes

asp-append-version
When specified along with a src attribute, the Image Tag Helper is invoked.
An example of a valid img tag helper is:
<img src="~/images/asplogo.png"
asp-append-version="true" />
If the static file exists in the directory ..wwwroot/images/asplogo.png the generated html is similar to the following
(the hash will be different):
<img
src="/images/asplogo.png?v=Kl_dqr9NVtnMdsM2MUg4qthUnWZm5T1fCEimBPWDNgM"/>
The value assigned to the parameter v is the hash value of the file on disk. If the web server is unable to obtain
read access to the static file referenced, no v parameters is added to the src attribute.
src
To activate the Image Tag Helper, the src attribute is required on the <img> element.
NOTE
The Image Tag Helper uses the Cache provider on the local web server to store the calculated Sha512 of a given file. If the
file is requested again the Sha512 doesn't need to be recalculated. The Cache is invalidated by a file watcher that's attached
to the file when the file's Sha512 is calculated.

The Form Tag Helper

Sample:

</form>

</form>
Using a named route
</form>

NOTE

Syntax:

name
model property

Type expected
Sample:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

Email:
Password:
</form>

HtmlAttributes

Expression names
@{
var joe = "Joe";
}

value from:

{
}

{

}

</form>

public class Person

{

}
The action method:

{
}
@model Person
@{
}

</form>
@model string

{

}


<table>

{
<tr>
</tr>
}
</table>
</form>
@model ToDoItem
<td>
</td>
<td>
</td>
@*
<td>
</td>
<td>
</td>
*@
NOTE
NOTE

element.
Sample:
{
{
[MinLength(5)]
[MaxLength(1024)]
}
}

</form>

'1024'."
'5'."
</textarea>
</form>


Sample:
{
{
[Required]
[EmailAddress]
}
}

</form>

NOTE

</span>

Sample
error message:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

</form>

Sample:
{
{

{
};
}
}

{
return View(model);
}
[HttpPost]
{
{
}

return View(model);
}
The Index view:

</form>

</select>
</form>
NOTE
Enum binding
enum values.
Sample:

{
}
}
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}


</select>
</form>
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}

</select>
</form>
Option Group
{
{

{
new SelectListItem
{
Value = "MEX",
Text = "Mexico",
},
new SelectListItem
{
Value = "CAN",
Text = "Canada",
},
new SelectListItem
{
Value = "US",
Text = "USA",
},
new SelectListItem
{
Value = "FR",
Text = "France",
Group = EuropeGroup
},
new SelectListItem
{
Value = "ES",
Text = "Spain",
Group = EuropeGroup
},
new SelectListItem
{
Value = "DE",
Text = "Germany",
Group = EuropeGroup
}
};
}

The generated HTML:

</optgroup>
</optgroup>
</select>
</form>
Multiple select
{
{

{
};
}
}


</form>

multiple="multiple"
</select>
</form>
No selection
repeating the HTML:

</form>

</select>

{
return View(model);
}

</select>
</form>

</select>
</form>
Tag Helpers
HTML Form element
Model Binding
Model Validation

The Form Tag Helper

Sample:

</form>

</form>
Using a named route
</form>

NOTE

Syntax:

name
model property

Type expected
Sample:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

Email:
Password:
</form>

HtmlAttributes

Expression names
@{
var joe = "Joe";
}

value from:

{
}

{

}

</form>

public class Person

{

}
The action method:

{
}
@model Person
@{
}

</form>
@model string

{

}


<table>

{
<tr>
</tr>
}
</table>
</form>
@model ToDoItem
<td>
</td>
<td>
</td>
@*
<td>
</td>
<td>
</td>
*@
NOTE
NOTE

element.
Sample:
{
{
[MinLength(5)]
[MaxLength(1024)]
}
}

</form>

'1024'."
'5'."
</textarea>
</form>


Sample:
{
{
[Required]
[EmailAddress]
}
}

</form>

NOTE

</span>

Sample
error message:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

</form>

Sample:
{
{

{
};
}
}

{
return View(model);
}
[HttpPost]
{
{
}

return View(model);
}
The Index view:

</form>

</select>
</form>
NOTE
Enum binding
enum values.
Sample:

{
}
}
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}


</select>
</form>
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}

</select>
</form>
Option Group
{
{

{
new SelectListItem
{
Value = "MEX",
Text = "Mexico",
},
new SelectListItem
{
Value = "CAN",
Text = "Canada",
},
new SelectListItem
{
Value = "US",
Text = "USA",
},
new SelectListItem
{
Value = "FR",
Text = "France",
Group = EuropeGroup
},
new SelectListItem
{
Value = "ES",
Text = "Spain",
Group = EuropeGroup
},
new SelectListItem
{
Value = "DE",
Text = "Germany",
Group = EuropeGroup
}
};
}

The generated HTML:

</optgroup>
</optgroup>
</select>
</form>
Multiple select
{
{

{
};
}
}


</form>

multiple="multiple"
</select>
</form>
No selection
repeating the HTML:

</form>

</select>

{
return View(model);
}

</select>
</form>

</select>
</form>
Tag Helpers
HTML Form element
Model Binding
Model Validation
Partial Tag Helper in ASP.NET Core
By Scott Addie
Overview
The Partial Tag Helper is used for rendering a partial view in Razor Pages and MVC apps. Consider that it:
Requires ASP.NET Core 2.1 or later.
Is an alternative to HTML Helper syntax.
Renders the partial view asynchronously.
The HTML Helper options for rendering a partial view include:
@await Html.PartialAsync
@await Html.RenderPartialAsync
@Html.Partial
@Html.RenderPartial
The Product model is used in samples throughout this document:
namespace TagHelpersBuiltIn.Models
{
public class Product
{
public int Number { get; set; }

}
}
An inventory of the Partial Tag Helper attributes follows.
name
The name attribute is required. It indicates the name or the path of the partial view to be rendered. When a partial
view name is provided, the view discovery process is initiated. That process is bypassed when an explicit path is
provided. For all acceptable name values, see Partial view discovery.
The following markup uses an explicit path, indicating that _ProductPartial.cshtml is to be loaded from the Shared
folder. Using the for attribute, a model is passed to the partial view for binding.
<partial name="Shared/_ProductPartial.cshtml"
for="Product" />
for
The for attribute assigns a ModelExpression to be evaluated against the current model. A ModelExpression infers
the @Model. syntax. For example, for="Product" can be used instead of for="@Model.Product" . This default
inference behavior is overridden by using the @ symbol to define an inline expression. The for attribute can't be
used with the model attribute.
The following markup loads _ProductPartial.cshtml:
<partial name="_ProductPartial"
for="Product" />
The partial view is bound to the associated page model's Product property:
using TagHelpersBuiltIn.Models;
namespace TagHelpersBuiltIn.Pages
{
public class ProductModel : PageModel
{
public Product Product { get; set; }
public void OnGet()

{
Product = new Product
{
Number = 1,
Name = "Test product",
Description = "This is a test product"
};
}
}
}
model
The model attribute assigns a model instance to pass to the partial view. The model attribute can't be used with
the for attribute.
In the following markup, a new Product object is instantiated and passed to the model attribute for binding:
<partial name="_ProductPartial"
model='new Product { Number = 1, Name = "Test product", Description = "This is a test" }' />
view-data
The view-data attribute assigns a ViewDataDictionary to pass to the partial view. The following markup makes
the entire ViewData collection accessible to the partial view:
@{
ViewData["IsNumberReadOnly"] = true;
}
<partial name="_ProductViewDataPartial"
for="Product"
view-data="ViewData" />
In the preceding code, the IsNumberReadOnly key value is set to true and added to the ViewData collection.
Consequently, ViewData["IsNumberReadOnly"] is made accessible within the following partial view:
@model TagHelpersBuiltIn.Models.Product
<label asp-for="Number"></label>
@if ((bool)ViewData["IsNumberReadOnly"])
{
<input asp-for="Number" type="number" class="form-control" readonly />
}
else
{
<input asp-for="Number" type="number" class="form-control" />
}
</div>
<label asp-for="Name"></label>
<input asp-for="Name" type="text" class="form-control" />
</div>
<label asp-for="Description"></label>
<textarea asp-for="Description" rows="4" cols="50" class="form-control"></textarea>
</div>
In this example, the value of ViewData["IsNumberReadOnly"] determines whether the Number field is displayed as
read only.
Migrate from an HTML Helper

Consider the following asynchronous HTML Helper example. A collection of products is iterated and displayed.
Per the PartialAsync method's first parameter, the _ProductPartial.cshtml partial view is loaded. An instance of
the Product model is passed to the partial view for binding.
@foreach (var product in Model.Products)

{
@await Html.PartialAsync("_ProductPartial", product)
}
The following Partial Tag Helper achieves the same asynchronous rendering behavior as the PartialAsync HTML
Helper. The model attribute is assigned a Product model instance for binding to the partial view.
@foreach (var product in Model.Products)

{
<partial name="_ProductPartial" model="product" />
}

The Form Tag Helper

Sample:

</form>

</form>
Using a named route
</form>

NOTE

Syntax:

name
model property

Type expected
Sample:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

Email:
Password:
</form>

HtmlAttributes

Expression names
@{
var joe = "Joe";
}

value from:

{
}

{

}

</form>

public class Person

{

}
The action method:

{
}
@model Person
@{
}

</form>
@model string

{

}


<table>

{
<tr>
</tr>
}
</table>
</form>
@model ToDoItem
<td>
</td>
<td>
</td>
@*
<td>
</td>
<td>
</td>
*@
NOTE
NOTE

element.
Sample:
{
{
[MinLength(5)]
[MaxLength(1024)]
}
}

</form>

'1024'."
'5'."
</textarea>
</form>


Sample:
{
{
[Required]
[EmailAddress]
}
}

</form>

NOTE

</span>

Sample
error message:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

</form>

Sample:
{
{

{
};
}
}

{
return View(model);
}
[HttpPost]
{
{
}

return View(model);
}
The Index view:

</form>

</select>
</form>
NOTE
Enum binding
enum values.
Sample:

{
}
}
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}


</select>
</form>
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}

</select>
</form>
Option Group
{
{

{
new SelectListItem
{
Value = "MEX",
Text = "Mexico",
},
new SelectListItem
{
Value = "CAN",
Text = "Canada",
},
new SelectListItem
{
Value = "US",
Text = "USA",
},
new SelectListItem
{
Value = "FR",
Text = "France",
Group = EuropeGroup
},
new SelectListItem
{
Value = "ES",
Text = "Spain",
Group = EuropeGroup
},
new SelectListItem
{
Value = "DE",
Text = "Germany",
Group = EuropeGroup
}
};
}

The generated HTML:

</optgroup>
</optgroup>
</select>
</form>
Multiple select
{
{

{
};
}
}


</form>

multiple="multiple"
</select>
</form>
No selection
repeating the HTML:

</form>

</select>

{
return View(model);
}

</select>
</form>

</select>
</form>
Tag Helpers
HTML Form element
Model Binding
Model Validation

The Form Tag Helper

Sample:

</form>

</form>
Using a named route
</form>

NOTE

Syntax:

name
model property

Type expected
Sample:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

Email:
Password:
</form>

HtmlAttributes

Expression names
@{
var joe = "Joe";
}

value from:

{
}

{

}

</form>

public class Person

{

}
The action method:

{
}
@model Person
@{
}

</form>
@model string

{

}


<table>

{
<tr>
</tr>
}
</table>
</form>
@model ToDoItem
<td>
</td>
<td>
</td>
@*
<td>
</td>
<td>
</td>
*@
NOTE
NOTE

element.
Sample:
{
{
[MinLength(5)]
[MaxLength(1024)]
}
}

</form>

'1024'."
'5'."
</textarea>
</form>


Sample:
{
{
[Required]
[EmailAddress]
}
}

</form>

NOTE

</span>

Sample
error message:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

</form>

Sample:
{
{

{
};
}
}

{
return View(model);
}
[HttpPost]
{
{
}

return View(model);
}
The Index view:

</form>

</select>
</form>
NOTE
Enum binding
enum values.
Sample:

{
}
}
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}


</select>
</form>
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}

</select>
</form>
Option Group
{
{

{
new SelectListItem
{
Value = "MEX",
Text = "Mexico",
},
new SelectListItem
{
Value = "CAN",
Text = "Canada",
},
new SelectListItem
{
Value = "US",
Text = "USA",
},
new SelectListItem
{
Value = "FR",
Text = "France",
Group = EuropeGroup
},
new SelectListItem
{
Value = "ES",
Text = "Spain",
Group = EuropeGroup
},
new SelectListItem
{
Value = "DE",
Text = "Germany",
Group = EuropeGroup
}
};
}

The generated HTML:

</optgroup>
</optgroup>
</select>
</form>
Multiple select
{
{

{
};
}
}


</form>

multiple="multiple"
</select>
</form>
No selection
repeating the HTML:

</form>

</select>

{
return View(model);
}

</select>
</form>

</select>
</form>
Tag Helpers
HTML Form element
Model Binding
Model Validation

The Form Tag Helper

Sample:

</form>

</form>
Using a named route
</form>

NOTE

Syntax:

name
model property

Type expected
Sample:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

Email:
Password:
</form>

HtmlAttributes

Expression names
@{
var joe = "Joe";
}

value from:

{
}

{

}

</form>

public class Person

{

}
The action method:

{
}
@model Person
@{
}

</form>
@model string

{

}


<table>

{
<tr>
</tr>
}
</table>
</form>
@model ToDoItem
<td>
</td>
<td>
</td>
@*
<td>
</td>
<td>
</td>
*@
NOTE
NOTE

element.
Sample:
{
{
[MinLength(5)]
[MaxLength(1024)]
}
}

</form>

'1024'."
'5'."
</textarea>
</form>


Sample:
{
{
[Required]
[EmailAddress]
}
}

</form>

NOTE

</span>

Sample
error message:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

</form>

Sample:
{
{

{
};
}
}

{
return View(model);
}
[HttpPost]
{
{
}

return View(model);
}
The Index view:

</form>

</select>
</form>
NOTE
Enum binding
enum values.
Sample:

{
}
}
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}


</select>
</form>
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}

</select>
</form>
Option Group
{
{

{
new SelectListItem
{
Value = "MEX",
Text = "Mexico",
},
new SelectListItem
{
Value = "CAN",
Text = "Canada",
},
new SelectListItem
{
Value = "US",
Text = "USA",
},
new SelectListItem
{
Value = "FR",
Text = "France",
Group = EuropeGroup
},
new SelectListItem
{
Value = "ES",
Text = "Spain",
Group = EuropeGroup
},
new SelectListItem
{
Value = "DE",
Text = "Germany",
Group = EuropeGroup
}
};
}

The generated HTML:

</optgroup>
</optgroup>
</select>
</form>
Multiple select
{
{

{
};
}
}


</form>

multiple="multiple"
</select>
</form>
No selection
repeating the HTML:

</form>

</select>

{
return View(model);
}

</select>
</form>

</select>
</form>
Tag Helpers
HTML Form element
Model Binding
Model Validation

This document demonstrates working with Forms and the HTML elements commonly used on a
Form. The HTML Form element provides the primary mechanism web apps use to post back data
to the server. Most of this document describes Tag Helpers and how they can help you
productively create robust HTML forms. We recommend you read Introduction to Tag Helpers
before you read this document.
In many cases, HTML Helpers provide an alternative approach to a specific Tag Helper, but it's
important to recognize that Tag Helpers don't replace HTML Helpers and there's not a Tag Helper
for each HTML Helper. When an HTML Helper alternative exists, it's mentioned.
The Form Tag Helper

Generates the HTML <FORM> action attribute value for a MVC controller action or
named route
Generates a hidden Request Verification Token to prevent cross-site request forgery (when
used with the [ValidateAntiForgeryToken] attribute in the HTTP Post action method)
Provides the asp-route-<Parameter Name> attribute, where <Parameter Name> is added to
the route values. The routeValues parameters to Html.BeginForm and
Html.BeginRouteForm provide similar functionality.
Sample:

</form>

</form>
The MVC runtime generates the action attribute value from the Form Tag Helper attributes
asp-controller and asp-action . The Form Tag Helper also generates a hidden Request
Verification Token to prevent cross-site request forgery (when used with the
[ValidateAntiForgeryToken] attribute in the HTTP Post action method). Protecting a pure HTML
Form from cross-site request forgery is difficult, the Form Tag Helper provides this service for
you.
Using a named route
The asp-route Tag Helper attribute can also generate markup for the HTML action attribute. An
app with a route named register could use the following markup for the registration page:

</form>
Many of the views in the Views/Account folder (generated when you create a new web app with
Individual User Accounts) contain the asp-route-returnurl attribute:

NOTE
With the built in templates, returnUrl is only populated automatically when you try to access an
authorized resource but are not authenticated or authorized. When you attempt an unauthorized access,
the security middleware redirects you to the login page with the returnUrl set.

Syntax:

Generates the id and name HTML attributes for the expression name specified in the
asp-for attribute. asp-for="Property1.Property2" is equivalent to
m => m.Property1.Property2 . The name of the expression is what is used for the asp-for
attribute value. See the Expression names section for additional information.
Sets the HTML type attribute value based on the model type and data annotation
attributes applied to the model property
Generates HTML5 validation attributes from data annotation attributes applied to model
properties
Has an HTML Helper feature overlap with Html.TextBoxFor and Html.EditorFor . See the
HTML Helper alternatives to Input Tag Helper section for details.
Provides strong typing. If the name of the property changes and you don't update the Tag
Helper you'll get an error similar to the following:
Type expected
The Input Tag Helper sets the HTML type attribute based on the .NET type. The following table
lists some common .NET types and generated HTML type (not every .NET type is listed).
The following table shows some common data annotations attributes that the input tag helper
will map to specific input types (not every validation attribute is listed):
Sample:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

Email:
Password:
</form>
The data annotations applied to the Email and Password properties generate metadata on the
model. The Input Tag Helper consumes the model metadata and produces HTML5 data-val-*
attributes (see Model Validation). These attributes describe the validators to attach to the input
fields. This provides unobtrusive HTML5 and jQuery validation. The unobtrusive attributes have
the format data-val-rule="Error Message" , where rule is the name of the validation rule (such as
data-val-required , data-val-email , data-val-maxlength , etc.) If an error message is provided in
the attribute, it's displayed as the value for the data-val-rule attribute. There are also attributes
of the form data-val-ruleName-argumentName="argumentValue" that provide additional details about
the rule, for example, data-val-maxlength-max="1024" .
Html.TextBox , Html.TextBoxFor , Html.Editor and Html.EditorFor have overlapping features
with the Input Tag Helper. The Input Tag Helper will automatically set the type attribute;
Html.TextBox and Html.TextBoxFor won't. Html.Editor and Html.EditorFor handle collections,
complex objects and templates; the Input Tag Helper doesn't. The Input Tag Helper,
Html.EditorFor and Html.TextBoxFor are strongly typed (they use lambda expressions);
HtmlAttributes
@Html.Editor() and @Html.EditorFor() use a special ViewDataDictionary entry named
htmlAttributes when executing their default templates. This behavior is optionally augmented
using additionalViewData parameters. The key "htmlAttributes" is case-insensitive. The key
"htmlAttributes" is handled similarly to the htmlAttributes object passed to input helpers like
@Html.TextBox() .

Expression names
The asp-for attribute value is a ModelExpression and the right hand side of a lambda expression.
Therefore, asp-for="Property1" becomes m => m.Property1 in the generated code which is why
you don't need to prefix with Model . You can use the "@" character to start an inline expression
and move before the m. :
@{
var joe = "Joe";
}

When ASP.NET Core MVC calculates the value of ModelExpression , it inspects several sources,
including ModelState . Consider <input type="text" asp-for="@Name" /> . The calculated value
attribute is the first non-null value from:
You can also navigate to child properties using the property path of the view model. Consider a
more complex model class that contains a child Address property.

{
}
{

}

</form>

public class Person

{

}
The action method:

{
}
@model Person
@{
}

</form>
@model string

{

}

<table>

{
<tr>
</tr>
}
</table>
</form>
@model ToDoItem
<td>
</td>
<td>
</td>
@*
<td>
</td>
<td>
</td>
*@
NOTE
Always use for (and not foreach ) to iterate over a list. Evaluating an indexer in a LINQ expression can
be expensive and should be minimized.
NOTE
The commented sample code above shows how you would replace the lambda expression with the @
operator to access each ToDoItem in the list.

Generates the id and name attributes, and the data validation attributes from the model
for a <textarea> element.
Sample:
{
{
[MinLength(5)]
[MaxLength(1024)]
}
}

</form>

data-val-maxlength="The field Description must be a string or array type with a maximum
length of '1024'."
data-val-minlength="The field Description must be a string or array type with a minimum
length of '5'."
</textarea>
</form>

You automatically get the descriptive label value from the Display attribute. The intended
display name might change over time, and the combination of Display attribute and Label
Tag Helper will apply the Display everywhere it's used.
Sample:
{
{
[Required]
[EmailAddress]
}
}

</form>
The Label Tag Helper generated the for attribute value of "Email", which is the ID associated
with the <input> element. The Tag Helpers generate consistent id and for elements so they
can be correctly associated. The caption in this sample comes from the Display attribute. If the
model didn't contain a Display attribute, the caption would be the property name of the
expression.

There are two Validation Tag Helpers. The Validation Message Tag Helper (which displays a
validation message for a single property on your model), and the Validation Summary Tag Helper
(which displays a summary of validation errors). The Input Tag Helper adds HTML5 client side
validation attributes to input elements based on data annotation attributes on your model classes.
Validation is also performed on the server. The Validation Tag Helper displays these error
messages when a validation error occurs.
Adds the HTML5 data-valmsg-for="property" attribute to the span element, which attaches
the validation error messages on the input field of the specified model property. When a
client side validation error occurs, jQuery displays the error message in the <span>
element.
Validation also takes place on the server. Clients may have JavaScript disabled and some
validation can only be done on the server side.
The Validation Message Tag Helper is used with the asp-validation-for attribute on a HTML
span element.
You generally use the Validation Message Tag Helper after an Input Tag Helper for the same
property. Doing so displays any validation error messages near the input that caused the error.
NOTE
You must have a view with the correct JavaScript and jQuery script references in place for client side
validation. See Model Validation for more information.
When a server side validation error occurs (for example when you have custom server side
validation or client-side validation is disabled), MVC places that error message as the body of the
<span> element.

</span>
Sample
In the following example, the data model is decorated with DataAnnotation attributes, which
generates validation error messages on the <input> element. When a validation error occurs, the
Validation Tag Helper displays the error message:
{
{
[Required]
[EmailAddress]
[Required]
}
}

</form>

</form>

The Select Tag Helper asp-for specifies the model property name for the select element and
asp-items specifies the option elements. For example:
Sample:
{
{

{
};
}
}
The Index method initializes the CountryViewModel , sets the selected country and passes it to the
Index view.

{
return View(model);
}

[HttpPost]
{
{
}

return View(model);
}
The Index view:

</form>

</select>
</form>
NOTE
We don't recommend using ViewBag or ViewData with the Select Tag Helper. A view model is more
robust at providing MVC metadata and generally less problematic.
The asp-for attribute value is a special case and doesn't require a Model prefix, the other Tag
Helper attributes do (such as asp-items )
Enum binding
It's often convenient to use <select> with an enum property and generate the SelectListItem
elements from the enum values.
Sample:
{
}
}
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}

</select>
</form>
{
{
Mexico,
USA,
Canada,
France,
Germany,
Spain
}
}

</select>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>"
/>
</form>
Option Group
The HTML <optgroup> element is generated when the view model contains one or more
SelectListGroup objects.
The CountryViewModelGroup groups the SelectListItem elements into the "North America" and
"Europe" groups:
{
{

{
new SelectListItem
{
Value = "MEX",
Text = "Mexico",
},
new SelectListItem
{
Value = "CAN",
Text = "Canada",
},
new SelectListItem
{
Value = "US",
Text = "USA",
},
new SelectListItem
{
Value = "FR",
Text = "France",
Group = EuropeGroup
},
new SelectListItem
{
Value = "ES",
Text = "Spain",
Group = EuropeGroup
},
new SelectListItem
{
Value = "DE",
Text = "Germany",
Group = EuropeGroup
}
};
}

The generated HTML:

</optgroup>
</optgroup>
</select>
</form>
Multiple select
The Select Tag Helper will automatically generate the multiple = "multiple" attribute if the
property specified in the asp-for attribute is an IEnumerable . For example, given the following
model:
{
{

{
};
}
}

</form>

multiple="multiple"
</select>
</form>
No selection
If you find yourself using the "not specified" option in multiple pages, you can create a template to
eliminate repeating the HTML:

</form>

</select>
Adding HTML <option> elements isn't limited to the No selection case. For example, the
following view and action method will generate HTML similar to the code above:

{
return View(model);
}

</select>
</form>
The correct <option> element will be selected ( contain the selected="selected" attribute)
depending on the current Country value.

</select>
</form>
Tag Helpers
HTML Form element
Model Binding
Model Validation
By Steve Smith, Luke Latham, Maher JENDOUBI, Rick Anderson, and Scott Sauber
A partial view is a Razor markup file (.cshtml) that renders HTML output within another markup file's rendered
output.
The term partial view is used when developing either an MVC app, where markup files are called views, or a
Razor Pages app, where markup files are called pages. This topic generically refers to MVC views and Razor
Pages pages as markup files.
When to use partial views

Partial views are an effective way to:
Break up large markup files into smaller components.
In a large, complex markup file composed of several logical pieces, there's an advantage to working with
each piece isolated into a partial view. The code in the markup file is manageable because the markup
only contains the overall page structure and references to partial views.
Reduce the duplication of common markup content across markup files.
When the same markup elements are used across markup files, a partial view removes the duplication of
markup content into one partial view file. When the markup is changed in the partial view, it updates the
rendered output of the markup files that use the partial view.
Partial views shouldn't be used to maintain common layout elements. Common layout elements should be
specified in _Layout.cshtml files.
Don't use a partial view where complex rendering logic or code execution is required to render the markup.
Instead of a partial view, use a view component.
Declare partial views

A partial view is a .cshtml markup file maintained within the Views folder (MVC ) or Pages folder (Razor Pages).
In ASP.NET Core MVC, a controller's ViewResult is capable of returning either a view or a partial view. An
analogous capability is planned for Razor Pages in ASP.NET Core 2.2. In Razor Pages, a PageModel can return
a PartialViewResult. Referencing and rendering partial views is described in the Reference a partial view section.
Unlike MVC view or page rendering, a partial view doesn't run _ViewStart.cshtml. For more information on
_ViewStart.cshtml, see Layout in ASP.NET Core.
Partial view file names often begin with an underscore ( _ ). This naming convention isn't required, but it helps
to visually differentiate partial views from views and pages. When the file name starts with an underscore,
Razor Pages doesn't process the markup file as a Razor Pages page, even when the file's markup includes the
@page directive.
A partial view is a .cshtml markup file maintained within the Views folder.
A controller's ViewResult is capable of returning either a view or a partial view.
Unlike MVC view rendering, a partial view doesn't run _ViewStart.cshtml. For more information on
_ViewStart.cshtml, see Layout in ASP.NET Core.
Partial view file names often begin with an underscore ( _ ). This naming convention isn't required, but it helps
to visually differentiate partial views from views.
Reference a partial view

Within a markup file, there are several ways to reference a partial view. We recommend that apps use one of
the following asynchronous rendering approaches:
Partial Tag Helper
Asynchronous HTML Helper
Within a markup file, there are two ways to reference a partial view:
Synchronous HTML Helper
We recommend that apps use the Asynchronous HTML Helper.
Partial Tag Helper
The Partial Tag Helper requires ASP.NET Core 2.1 or later.
The Partial Tag Helper renders content asynchronously and uses an HTML -like syntax:
<partial name="_PartialName" />
When a file extension is present, the Tag Helper references a partial view that must be in the same folder as the
markup file calling the partial view:
<partial name="_PartialName.cshtml" />
The following example references a partial view from the app root. Paths that start with a tilde-slash ( ~/ ) or a
slash ( / ) refer to the app root:
Razor Pages
<partial name="~/Pages/Folder/_PartialName.cshtml" />

<partial name="/Pages/Folder/_PartialName.cshtml" />
MVC
<partial name="~/Views/Folder/_PartialName.cshtml" />

<partial name="/Views/Folder/_PartialName.cshtml" />
The following example references a partial view with a relative path:
<partial name="../Account/_PartialName.cshtml" />
For more information, see Partial Tag Helper in ASP.NET Core.

When using an HTML Helper, the best practice is to use PartialAsync. PartialAsync returns an IHtmlContent
type wrapped in a Task<TResult>. The method is referenced by prefixing the awaited call with an @ character:
@await Html.PartialAsync("_PartialName")
When the file extension is present, the HTML Helper references a partial view that must be in the same folder
as the markup file calling the partial view:
@await Html.PartialAsync("_PartialName.cshtml")
The following example references a partial view from the app root. Paths that start with a tilde-slash ( ~/ ) or a
slash ( / ) refer to the app root:
Razor Pages
@await Html.PartialAsync("~/Pages/Folder/_PartialName.cshtml")
@await Html.PartialAsync("/Pages/Folder/_PartialName.cshtml")
MVC
@await Html.PartialAsync("~/Views/Folder/_PartialName.cshtml")
@await Html.PartialAsync("/Views/Folder/_PartialName.cshtml")
The following example references a partial view with a relative path:
@await Html.PartialAsync("../Account/_LoginPartial.cshtml")
Alternatively, you can render a partial view with RenderPartialAsync. This method doesn't return an
IHtmlContent. It streams the rendered output directly to the response. Because the method doesn't return a
result, it must be called within a Razor code block:
@{
await Html.RenderPartialAsync("_AuthorPartial");
}
Since RenderPartialAsync streams rendered content, it provides better performance in some scenarios. In
performance-critical situations, benchmark the page using both approaches and use the approach that
generates a faster response.
Synchronous HTML Helper
Partial and RenderPartial are the synchronous equivalents of PartialAsync and RenderPartialAsync ,
respectively. The synchronous equivalents aren't recommended because there are scenarios in which they
deadlock. The synchronous methods are targeted for removal in a future release.
IMPORTANT
If you need to execute code, use a view component instead of a partial view.
Calling Partial or RenderPartial results in a Visual Studio analyzer warning. For example, the presence of
Partial yields the following warning message:
Use of IHtmlHelper.Partial may result in application deadlocks. Consider using <partial> Tag Helper or
IHtmlHelper.PartialAsync.
Replace calls to @Html.Partial with @await Html.PartialAsync or the Partial Tag Helper. For more information
on Partial Tag Helper migration, see Migrate from an HTML Helper.
Partial view discovery

When a partial view is referenced by name without a file extension, the following locations are searched in the
stated order:
Razor Pages
1. Currently executing page's folder
2. Directory graph above the page's folder
3. /Shared
4. /Pages/Shared
5. /Views/Shared
MVC
1. /Areas/<Area-Name>/Views/<Controller-Name>
2. /Areas/<Area-Name>/Views/Shared
3. /Views/Shared
4. /Pages/Shared
1. /Areas/<Area-Name>/Views/<Controller-Name>
2. /Areas/<Area-Name>/Views/Shared
3. /Views/Shared
The following conventions apply to partial view discovery:

Different partial views with the same file name are allowed when the partial views are in different folders.
When referencing a partial view by name without a file extension and the partial view is present in both the
caller's folder and the Shared folder, the partial view in the caller's folder supplies the partial view. If the
partial view isn't present in the caller's folder, the partial view is provided from the Shared folder. Partial
views in the Shared folder are called shared partial views or default partial views.
Partial views can be chained—a partial view can call another partial view if a circular reference isn't formed
by the calls. Relative paths are always relative to the current file, not to the root or parent of the file.
NOTE
A Razor section defined in a partial view is invisible to parent markup files. The section is only visible to the partial
view in which it's defined.
Access data from partial views

When a partial view is instantiated, it receives a copy of the parent's ViewData dictionary. Updates made to the
data within the partial view aren't persisted to the parent view. ViewData changes in a partial view are lost when
the partial view returns.
The following example demonstrates how to pass an instance of ViewDataDictionary to a partial view:
@await Html.PartialAsync("_PartialName", customViewData)
You can pass a model into a partial view. The model can be a custom object. You can pass a model with
PartialAsync (renders a block of content to the caller ) or RenderPartialAsync (streams the content to the
output):
@await Html.PartialAsync("_PartialName", model)
Razor Pages
The following markup in the sample app is from the Pages/ArticlesRP/ReadRP.cshtml page. The page contains
two partial views. The second partial view passes in a model and ViewData to the partial view. The
ViewDataDictionary constructor overload is used to pass a new ViewData dictionary while retaining the existing
ViewData dictionary.
@model ReadRPModel
<h2>@Model.Article.Title</h2>
@* Pass the author's name to Pages\Shared\_AuthorPartialRP.cshtml *@
@await Html.PartialAsync("../Shared/_AuthorPartialRP", Model.Article.AuthorName)
@Model.Article.PublicationDate
@* Loop over the Sections and pass in a section and additional ViewData to
the strongly typed Pages\ArticlesRP\_ArticleSectionRP.cshtml partial view. *@
@{
var index = 0;
@foreach (var section in Model.Article.Sections)

{
@await Html.PartialAsync("_ArticleSectionRP", section,
new ViewDataDictionary(ViewData)
{
{ "index", index }
})
index++;
}
}
Pages/Shared/_AuthorPartialRP.cshtml is the first partial view referenced by the ReadRP.cshtml markup file:
@model string
<div>
<h3>@Model</h3>
This partial view from /Pages/Shared/_AuthorPartialRP.cshtml.
</div>
Pages/ArticlesRP/_ArticleSectionRP.cshtml is the second partial view referenced by the ReadRP.cshtml markup

file:
@using PartialViewsSample.ViewModels
@model ArticleSection
<h3>@Model.Title Index: @ViewData["index"]</h3>

<div>
@Model.Content
</div>
MVC
The following markup in the sample app shows the Views/Articles/Read.cshtml view. The view contains two
partial views. The second partial view passes in a model and ViewData to the partial view. The
ViewDataDictionary constructor overload is used to pass a new ViewData dictionary while retaining the existing
ViewData dictionary.
@model PartialViewsSample.ViewModels.Article
@* Pass the author's name to Views\Shared\_AuthorPartial.cshtml *@
@await Html.PartialAsync("_AuthorPartial", Model.AuthorName)
@Model.PublicationDate
@* Loop over the Sections and pass in a section and additional ViewData to
the strongly typed Views\Articles\_ArticleSection.cshtml partial view. *@
@{
var index = 0;
@foreach (var section in Model.Sections)

{
@await Html.PartialAsync("_ArticleSection", section,
new ViewDataDictionary(ViewData)
{
{ "index", index }
})
index++;
}
}
Views/Shared/_AuthorPartial.cshtml is the first partial view referenced by the ReadRP.cshtml markup file:
@model string
<div>
<h3>@Model</h3>
This partial view from /Views/Shared/_AuthorPartial.cshtml.
</div>
Views/Articles/_ArticleSection.cshtml is the second partial view referenced by the Read.cshtml markup file:
@using PartialViewsSample.ViewModels
@model ArticleSection
<h3>@Model.Title Index: @ViewData["index"]</h3>

<div>
@Model.Content
</div>
At runtime, the partials are rendered into the parent markup file's rendered output, which itself is rendered
within the shared _Layout.cshtml. The first partial view renders the article author's name and publication date:
Abraham Lincoln
This partial view from <shared partial view file path>. 11/19/1863 12:00:00 AM
The second partial view renders the article's sections:
Section One Index: 0

Four score and seven years ago ...
Section Two Index: 1
Now we are engaged in a great civil war, testing ...
Section Three Index: 2
But, in a larger sense, we can not dedicate ...
Partial Tag Helper in ASP.NET Core
View components in ASP.NET Core
Areas in ASP.NET Core
By Steve Smith
ASP.NET Core supports dependency injection into views. This can be useful for view -specific services, such as
localization or data required only for populating view elements. You should try to maintain separation of
concerns between your controllers and views. Most of the data your views display should be passed in from the
controller.
A Simple Example
You can inject a service into a view using the @inject directive. You can think of @inject as adding a property
to your view, and populating the property using DI.
The syntax for @inject : @inject <type> <name>
An example of @inject in action:
@using System.Threading.Tasks
@using ViewInjectSample.Model
@using ViewInjectSample.Model.Services
@model IEnumerable<ToDoItem>
@inject StatisticsService StatsService
<!DOCTYPE html>
<html>
<head>
<title>To Do Items</title>
</head>
<body>
<div>
<h1>To Do Items</h1>
<ul>
<li>Total Items: @StatsService.GetCount()</li>
<li>Completed: @StatsService.GetCompletedCount()</li>
<li>Avg. Priority: @StatsService.GetAveragePriority()</li>
</ul>
<table>
<tr>
<th>Name</th>
<th>Priority</th>
<th>Is Done?</th>
</tr>
{
<tr>
<td>@item.Name</td>
<td>@item.Priority</td>
<td>@item.IsDone</td>
</tr>
}
</table>
</div>
</body>
</html>
This view displays a list of ToDoItem instances, along with a summary showing overall statistics. The summary is
populated from the injected StatisticsService . This service is registered for dependency injection in
ConfigureServices in Startup.cs:
// For more information on how to configure your application, visit http://go.microsoft.com/fwlink/?

LinkID=398940
{
services.AddMvc();
services.AddTransient<IToDoItemRepository, ToDoItemRepository>();
services.AddTransient<StatisticsService>();
services.AddTransient<ProfileOptionsService>();
The StatisticsService performs some calculations on the set of ToDoItem instances, which it accesses via a
repository:
using System.Linq;
using ViewInjectSample.Interfaces;
namespace ViewInjectSample.Model.Services
{
public class StatisticsService
{
private readonly IToDoItemRepository _toDoItemRepository;
public StatisticsService(IToDoItemRepository toDoItemRepository)

{
_toDoItemRepository = toDoItemRepository;
}
public int GetCount()

{
return _toDoItemRepository.List().Count();
}
public int GetCompletedCount()

{
return _toDoItemRepository.List().Count(x => x.IsDone);
}
public double GetAveragePriority()

{
if (_toDoItemRepository.List().Count() == 0)
{
return 0.0;
}
return _toDoItemRepository.List().Average(x => x.Priority);

}
}
}
The sample repository uses an in-memory collection. The implementation shown above (which operates on all of
the data in memory) isn't recommended for large, remotely accessed data sets.
The sample displays data from the model bound to the view and the service injected into the view:
Populating Lookup Data
View injection can be useful to populate options in UI elements, such as dropdown lists. Consider a user profile
form that includes options for specifying gender, state, and other preferences. Rendering such a form using a
standard MVC approach would require the controller to request data access services for each of these sets of
options, and then populate a model or ViewBag with each set of options to be bound.
An alternative approach injects services directly into the view to obtain the options. This minimizes the amount
of code required by the controller, moving this view element construction logic into the view itself. The controller
action to display a profile editing form only needs to pass the form the profile instance:
using ViewInjectSample.Model;
namespace ViewInjectSample.Controllers
{
public class ProfileController : Controller
{
[Route("Profile")]
{
// TODO: look up profile based on logged-in user
var profile = new Profile()
{
Name = "Steve",
FavColor = "Blue",
Gender = "Male",
State = new State("Ohio","OH")
};
return View(profile);
}
}
}
The HTML form used to update these preferences includes dropdown lists for three of the properties:
These lists are populated by a service that has been injected into the view:
@using ViewInjectSample.Model.Services
@model ViewInjectSample.Model.Profile
@inject ProfileOptionsService Options
<!DOCTYPE html>
<html>
<head>
<title>Update Profile</title>
</head>
<body>
<div>
<h1>Update Profile</h1>
Name: @Html.TextBoxFor(m => m.Name)
<br/>
Gender: @Html.DropDownList("Gender",
Options.ListGenders().Select(g =>
new SelectListItem() { Text = g, Value = g }))
<br/>
State: @Html.DropDownListFor(m => m.State.Code,

Options.ListStates().Select(s =>
new SelectListItem() { Text = s.Name, Value = s.Code}))
<br />
Fav. Color: @Html.DropDownList("FavColor",

Options.ListColors().Select(c =>
new SelectListItem() { Text = c, Value = c }))
</div>
</body>
</html>
The ProfileOptionsService is a UI-level service designed to provide just the data needed for this form:
namespace ViewInjectSample.Model.Services
{
public class ProfileOptionsService
{
public List<string> ListGenders()
{
// keeping this simple
return new List<string>() {"Female", "Male"};
}
public List<State> ListStates()

{
// a few states from USA
return new List<State>()
{
new State("Alabama", "AL"),
new State("Alaska", "AK"),
new State("Ohio", "OH")
};
}
public List<string> ListColors()

{
return new List<string>() { "Blue","Green","Red","Yellow" };
}
}
}
IMPORTANT
Don't forget to register types you request through dependency injection in Startup.ConfigureServices . An
unregistered type throws an exception at runtime because the service provider is internally queried via GetRequiredService.
Overriding Services
In addition to injecting new services, this technique can also be used to override previously injected services on a
page. The figure below shows all of the fields available on the page used in the first example:
As you can see, the default fields include Html , Component , and Url (as well as the StatsService that we
injected). If for instance you wanted to replace the default HTML Helpers with your own, you could easily do so
using @inject :
@using ViewInjectSample.Helpers
@inject MyHtmlHelper Html
<!DOCTYPE html>
<html>
<head>
<title>My Helper</title>
</head>
<body>
<div>
Test: @Html.Value
</div>
</body>
</html>
If you want to extend existing services, you can simply use this technique while inheriting from or wrapping the
existing implementation with your own.
See Also
Simon Timms Blog: Getting Lookup Data Into Your View
By Rick Anderson
View components
View components are similar to partial views, but they're much more powerful. View components don't use
model binding, and only depend on the data provided when calling into it. This article was written using
ASP.NET Core MVC, but view components also work with Razor Pages.
A view component:
Renders a chunk rather than a whole response.
Includes the same separation-of-concerns and testability benefits found between a controller and view.
Can have parameters and business logic.
Is typically invoked from a layout page.
View components are intended anywhere you have reusable rendering logic that's too complex for a partial
view, such as:
Dynamic navigation menus
Tag cloud (where it queries the database)
Login panel
Shopping cart
Recently published articles
Sidebar content on a typical blog
A login panel that would be rendered on every page and show either the links to log out or log in, depending
on the log in state of the user
A view component consists of two parts: the class (typically derived from ViewComponent) and the result it
returns (typically a view ). Like controllers, a view component can be a POCO, but most developers will want to
take advantage of the methods and properties available by deriving from ViewComponent .
Creating a view component

This section contains the high-level requirements to create a view component. Later in the article, we'll examine
each step in detail and create a view component.
The view component class
A view component class can be created by any of the following:
Deriving from ViewComponent
Decorating a class with the [ViewComponent] attribute, or deriving from a class with the [ViewComponent]
attribute
Creating a class where the name ends with the suffix ViewComponent
Like controllers, view components must be public, non-nested, and non-abstract classes. The view component
name is the class name with the "ViewComponent" suffix removed. It can also be explicitly specified using the
ViewComponentAttribute.Name property.
A view component class:
Fully supports constructor dependency injection
Doesn't take part in the controller lifecycle, which means you can't use filters in a view component
View component methods
A view component defines its logic in an InvokeAsync method that returns an IViewComponentResult . Parameters
come directly from invocation of the view component, not from model binding. A view component never directly
handles a request. Typically, a view component initializes a model and passes it to a view by calling the View
method. In summary, view component methods:
Define an InvokeAsync method that returns an IViewComponentResult
Typically initializes a model and passes it to a view by calling the ViewComponent View method
Parameters come from the calling method, not HTTP, there's no model binding
Are not reachable directly as an HTTP endpoint, they're invoked from your code (usually in a view ). A view
component never handles a request
Are overloaded on the signature rather than any details from the current HTTP request
View search path
The runtime searches for the view in the following paths:
/Pages/Components/<view_component_name>/<view_name>
/Views/<controller_name>/Components/<view_component_name>/<view_name>
/Views/Shared/Components/<view_component_name>/<view_name>
The default view name for a view component is Default, which means your view file will typically be named
Default.cshtml. You can specify a different view name when creating the view component result or when calling
the View method.
We recommend you name the view file Default.cshtml and use the
Views/Shared/Components/<view_component_name>/<view_name> path. The PriorityList view component
used in this sample uses Views/Shared/Components/PriorityList/Default.cshtml for the view component view.
Invoking a view component

To use the view component, call the following inside a view:
@Component.InvokeAsync("Name of view component", <anonymous type containing parameters>)
The parameters will be passed to the InvokeAsync method. The PriorityList view component developed in the
article is invoked from the Views/Todo/Index.cshtml view file. In the following, the InvokeAsync method is called
with two parameters:
@await Component.InvokeAsync("PriorityList", new { maxPriority = 4, isDone = true })
Invoking a view component as a Tag Helper

For ASP.NET Core 1.1 and higher, you can invoke a view component as a Tag Helper:
<vc:priority-list max-priority="2" is-done="false">
</vc:priority-list>
Pascal-cased class and method parameters for Tag Helpers are translated into their lower kebab case. The Tag
Helper to invoke a view component uses the <vc></vc> element. The view component is specified as follows:
<vc:[view-component-name]
parameter1="parameter1 value"
parameter2="parameter2 value">
</vc:[view-component-name]>
To use a view component as a Tag Helper, register the assembly containing the view component using the
@addTagHelper directive. If your view component is in an assembly called MyWebApp , add the following directive
to the _ViewImports.cshtml file:
@addTagHelper *, MyWebApp
You can register a view component as a Tag Helper to any file that references the view component. See
Managing Tag Helper Scope for more information on how to register Tag Helpers.
The InvokeAsync method used in this tutorial:
In Tag Helper markup:

</vc:priority-list>
In the sample above, the PriorityList view component becomes priority-list . The parameters to the view
component are passed as attributes in lower kebab case.
Invoking a view component directly from a controller
View components are typically invoked from a view, but you can invoke them directly from a controller method.
While view components don't define endpoints like controllers, you can easily implement a controller action that
returns the content of a ViewComponentResult .
In this example, the view component is called directly from the controller:
public IActionResult IndexVC()

{
return ViewComponent("PriorityList", new { maxPriority = 3, isDone = false });
}
Walkthrough: Creating a simple view component

Download, build and test the starter code. It's a simple project with a Todo controller that displays a list of Todo
items.
Add a ViewComponent class
Create a ViewComponents folder and add the following PriorityListViewComponent class:
using System.Linq;
using ViewComponentSample.Models;
namespace ViewComponentSample.ViewComponents
{
public class PriorityListViewComponent : ViewComponent
{
private readonly ToDoContext db;
public PriorityListViewComponent(ToDoContext context)

{
db = context;
}
public async Task<IViewComponentResult> InvokeAsync(

int maxPriority, bool isDone)
{
var items = await GetItemsAsync(maxPriority, isDone);
return View(items);
}
private Task<List<TodoItem>> GetItemsAsync(int maxPriority, bool isDone)
{
return db.ToDo.Where(x => x.IsDone == isDone &&
x.Priority <= maxPriority).ToListAsync();
}
}
}
Notes on the code:

View component classes can be contained in any folder in the project.
Because the class name PriorityListViewComponent ends with the suffix ViewComponent, the
runtime will use the string "PriorityList" when referencing the class component from a view. I'll explain
that in more detail later.
The [ViewComponent] attribute can change the name used to reference a view component. For example,
we could've named the class XYZ and applied the ViewComponent attribute:
[ViewComponent(Name = "PriorityList")]
public class XYZ : ViewComponent
The [ViewComponent] attribute above tells the view component selector to use the name PriorityList
when looking for the views associated with the component, and to use the string "PriorityList" when
referencing the class component from a view. I'll explain that in more detail later.
The component uses dependency injection to make the data context available.
InvokeAsync exposes a method which can be called from a view, and it can take an arbitrary number of
arguments.
The InvokeAsync method returns the set of ToDo items that satisfy the isDone and maxPriority
parameters.
Create the view component Razor view
Create the Views/Shared/Components folder. This folder must be named Components.
Create the Views/Shared/Components/PriorityList folder. This folder name must match the name of the
view component class, or the name of the class minus the suffix (if we followed convention and used the
ViewComponent suffix in the class name). If you used the ViewComponent attribute, the class name would
need to match the attribute designation.
Create a Views/Shared/Components/PriorityList/Default.cshtml Razor view:
@model IEnumerable<ViewComponentSample.Models.TodoItem>
<h3>Priority Items</h3>
<ul>
@foreach (var todo in Model)
{
<li>@todo.Name</li>
}
</ul>
The Razor view takes a list of TodoItem and displays them. If the view component InvokeAsync method
doesn't pass the name of the view (as in our sample), Default is used for the view name by convention.
Later in the tutorial, I'll show you how to pass the name of the view. To override the default styling for a
specific controller, add a view to the controller-specific view folder (for example
Views/Todo/Components/PriorityList/Default.cshtml).
If the view component is controller-specific, you can add it to the controller-specific folder
(Views/Todo/Components/PriorityList/Default.cshtml).
Add a div containing a call to the priority list component to the bottom of the Views/Todo/index.cshtml
file:
</table>
<div>
@await Component.InvokeAsync("PriorityList", new { maxPriority = 2, isDone = false })
</div>
The markup @await Component.InvokeAsync shows the syntax for calling view components. The first argument is
the name of the component we want to invoke or call. Subsequent parameters are passed to the component.
InvokeAsync can take an arbitrary number of arguments.
Test the app. The following image shows the ToDo list and the priority items:
You can also call the view component directly from the controller:
public IActionResult IndexVC()

{
return ViewComponent("PriorityList", new { maxPriority = 3, isDone = false });
}
Specifying a view name

A complex view component might need to specify a non-default view under some conditions. The following
code shows how to specify the "PVC" view from the InvokeAsync method. Update the InvokeAsync method in
the PriorityListViewComponent class.
{
string MyView = "Default";
// If asking for all completed tasks, render with the "PVC" view.
if (maxPriority > 3 && isDone == true)
{
MyView = "PVC";
}
return View(MyView, items);
}
Copy the Views/Shared/Components/PriorityList/Default.cshtml file to a view named

Views/Shared/Components/PriorityList/PVC.cshtml. Add a heading to indicate the PVC view is being used.
@model IEnumerable<ViewComponentSample.Models.TodoItem>
<h2> PVC Named Priority Component View</h2>

<h4>@ViewBag.PriorityMessage</h4>
<ul>
@foreach (var todo in Model)
{
<li>@todo.Name</li>
}
</ul>
Update Views/TodoList/Index.cshtml:
Run the app and verify PVC view.

If the PVC view isn't rendered, verify you are calling the view component with a priority of 4 or higher.
Examine the view path
Change the priority parameter to three or less so the priority view isn't returned.
Temporarily rename the Views/Todo/Components/PriorityList/Default.cshtml to 1Default.cshtml.
Test the app, you'll get the following error:

InvalidOperationException: The view 'Components/PriorityList/Default' wasn't found. The following
locations were searched:
/Views/ToDo/Components/PriorityList/Default.cshtml
/Views/Shared/Components/PriorityList/Default.cshtml
EnsureSuccessful
Copy Views/Todo/Components/PriorityList/1Default.cshtml to
Views/Shared/Components/PriorityList/Default.cshtml.
Add some markup to the Shared Todo view component view to indicate the view is from the Shared
folder.
Test the Shared component view.
Avoiding magic strings
If you want compile time safety, you can replace the hard-coded view component name with the class name.
Create the view component without the "ViewComponent" suffix:
using System.Linq;
using ViewComponentSample.Models;
namespace ViewComponentSample.ViewComponents
{
public class PriorityList : ViewComponent
{
private readonly ToDoContext db;
public PriorityList(ToDoContext context)

{
db = context;
}

{
return View(items);
}
private Task<List<TodoItem>> GetItemsAsync(int maxPriority, bool isDone)
{
return db.ToDo.Where(x => x.IsDone == isDone &&
x.Priority <= maxPriority).ToListAsync();
}
}
}
Add a using statement to your Razor view file, and use the nameof operator:
@using ViewComponentSample.Models
@using ViewComponentSample.ViewComponents
@model IEnumerable<TodoItem>
<h2>ToDo nameof</h2>

<div>
@await Component.InvokeAsync(nameof(PriorityList), new { maxPriority = 4, isDone = true })

</div>
Perform synchronous work

The framework handles invoking a synchronous Invoke method if you don't need to perform asynchronous
work. The following method creates a synchronous Invoke view component:
public class PriorityList : ViewComponent

{
public IViewComponentResult Invoke(int maxPriority, bool isDone)
{
var items = new List<string> { $"maxPriority: {maxPriority}", $"isDone: {isDone}" };
return View(items);
}
}
The view component's Razor file lists the strings passed to the Invoke method
(Views/Home/Components/PriorityList/Default.cshtml):
@model List<string>
<h3>Priority Items</h3>
<ul>
{
<li>@item</li>
}
</ul>
The view component is invoked in a Razor file (for example, Views/Home/Index.cshtml) using one of the
following approaches:
IViewComponentHelper
Tag Helper
To use the IViewComponentHelper approach, call Component.InvokeAsync :
The view component is invoked in a Razor file (for example, Views/Home/Index.cshtml) with
IViewComponentHelper.
Call Component.InvokeAsync :
@await Component.InvokeAsync(nameof(PriorityList), new { maxPriority = 4, isDone = true })
To use the Tag Helper, register the assembly containing the View Component using the @addTagHelper directive
(the view component is in an assembly called MyWebApp ):
@addTagHelper *, MyWebApp
Use the view component Tag Helper in the Razor markup file:

</vc:priority-list>
The method signature of PriorityList.Invoke is synchronous, but Razor finds and calls the method with
Component.InvokeAsync in the markup file.
Handle requests with controllers in ASP.NET Core
MVC
By Steve Smith and Scott Addie

Controllers, actions, and action results are a fundamental part of how developers build apps using ASP.NET Core
MVC.
What is a Controller?
A controller is used to define and group a set of actions. An action (or action method) is a method on a controller
which handles requests. Controllers logically group similar actions together. This aggregation of actions allows
common sets of rules, such as routing, caching, and authorization, to be applied collectively. Requests are mapped
to actions through routing.
By convention, controller classes:
Reside in the project's root-level Controllers folder
Inherit from Microsoft.AspNetCore.Mvc.Controller
A controller is an instantiable class in which at least one of the following conditions is true:
The class name is suffixed with "Controller"
The class inherits from a class whose name is suffixed with "Controller"
The class is decorated with the [Controller] attribute
A controller class must not have an associated [NonController] attribute.
Controllers should follow the Explicit Dependencies Principle. There are a couple of approaches to implementing
this principle. If multiple controller actions require the same service, consider using constructor injection to
request those dependencies. If the service is needed by only a single action method, consider using Action
Injection to request the dependency.
Within the Model-View -Controller pattern, a controller is responsible for the initial processing of the request and
instantiation of the model. Generally, business decisions should be performed within the model.
The controller takes the result of the model's processing (if any) and returns either the proper view and its
associated view data or the result of the API call. Learn more at Overview of ASP.NET Core MVC and Get started
with ASP.NET Core MVC and Visual Studio.
The controller is a UI -level abstraction. Its responsibilities are to ensure request data is valid and to choose which
view (or result for an API) should be returned. In well-factored apps, it doesn't directly include data access or
business logic. Instead, the controller delegates to services handling these responsibilities.
Defining Actions
Public methods on a controller, except those decorated with the [NonAction] attribute, are actions. Parameters on
actions are bound to request data and are validated using model binding. Model validation occurs for everything
that's model-bound. The ModelState.IsValid property value indicates whether model binding and validation
succeeded.
Action methods should contain logic for mapping a request to a business concern. Business concerns should
typically be represented as services that the controller accesses through dependency injection. Actions then map
the result of the business action to an application state.
Actions can return anything, but frequently return an instance of IActionResult (or Task<IActionResult> for async
methods) that produces a response. The action method is responsible for choosing what kind of response. The
action result does the responding.
Controller Helper Methods
Controllers usually inherit from Controller, although this isn't required. Deriving from Controller provides access
to three categories of helper methods:
1. Methods resulting in an empty response body
No Content-Type HTTP response header is included, since the response body lacks content to describe.
There are two result types within this category: Redirect and HTTP Status Code.
HTTP Status Code
This type returns an HTTP status code. A couple of helper methods of this type are BadRequest , NotFound ,
and Ok . For example, return BadRequest(); produces a 400 status code when executed. When methods
such as BadRequest , NotFound , and Ok are overloaded, they no longer qualify as HTTP Status Code
responders, since content negotiation is taking place.
Redirect
This type returns a redirect to an action or destination (using Redirect , LocalRedirect , RedirectToAction ,
or RedirectToRoute ). For example, return RedirectToAction("Complete", new {id = 123}); redirects to
Complete , passing an anonymous object.
The Redirect result type differs from the HTTP Status Code type primarily in the addition of a Location
HTTP response header.
2. Methods resulting in a non-empty response body with a predefined content type
Most helper methods in this category include a ContentType property, allowing you to set the Content-Type
response header to describe the response body.
There are two result types within this category: View and Formatted Response.
View
This type returns a view which uses a model to render HTML. For example, return View(customer); passes
a model to the view for data-binding.
Formatted Response
This type returns JSON or a similar data exchange format to represent an object in a specific manner. For
example, return Json(customer); serializes the provided object into JSON format.
Other common methods of this type include File , PhysicalFile, and VirtualFile . For example,
return PhysicalFile(customerFilePath, "text/xml"); returns an XML file described by a Content-Type
response header value of "text/xml".
3. Methods resulting in a non-empty response body formatted in a content type negotiated with the client
This category is better known as Content Negotiation. Content negotiation applies whenever an action returns
an ObjectResult type or something other than an IActionResult implementation. An action that returns a non-
IActionResult implementation (for example, object ) also returns a Formatted Response.
Some helper methods of this type include BadRequest , CreatedAtRoute , and Ok . Examples of these methods
include return BadRequest(modelState); , return CreatedAtRoute("routename", values, newobject); , and
return Ok(value); , respectively. Note that BadRequest and Ok perform content negotiation only when passed a
value; without being passed a value, they instead serve as HTTP Status Code result types. The CreatedAtRoute
method, on the other hand, always performs content negotiation since its overloads all require that a value be
passed.
Cross-Cutting Concerns
Applications typically share parts of their workflow. Examples include an app that requires authentication to access
the shopping cart, or an app that caches data on some pages. To perform logic before or after an action method,
use a filter. Using Filters on cross-cutting concerns can reduce duplication, allowing them to follow the Don't
Repeat Yourself (DRY ) principle.
Most filter attributes, such as [Authorize] , can be applied at the controller or action level depending upon the
desired level of granularity.
Error handling and response caching are often cross-cutting concerns:
Handle errors
Response Caching
Many cross-cutting concerns can be handled using filters or custom middleware.
By Ryan Nowak and Rick Anderson

ASP.NET Core MVC uses the Routing middleware to match the URLs of incoming requests and map them
to actions. Routes are defined in startup code or attributes. Routes describe how URL paths should be
matched to actions. Routes are also used to generate URLs (for links) sent out in responses.
Actions are either conventionally routed or attribute routed. Placing a route on the controller or the action
makes it attribute routed. See Mixed routing for more information.
This document will explain the interactions between MVC and routing, and how typical MVC apps make use
of routing features. See Routing for details on advanced routing.
Setting up Routing Middleware

In your Configure method you may see code similar to:
{
routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");
});
Inside the call to UseMvc , MapRoute is used to create a single route, which we'll refer to as the default
route. Most MVC apps will use a route with a template similar to the default route.
The route template "{controller=Home}/{action=Index}/{id?}" can match a URL path like
/Products/Details/5 and will extract the route values { controller = Products, action = Details, id = 5 }
by tokenizing the path. MVC will attempt to locate a controller named ProductsController and run the
action Details :

{
public IActionResult Details(int id) { ... }
}
Note that in this example, model binding would use the value of id = 5 to set the id parameter to 5
when invoking this action. See the Model Binding for more details.
Using the default route:
The route template:

{controller=Home} defines Home as the default controller
{action=Index} defines Index as the default action
{id?} defines id as optional

Default and optional route parameters don't need to be present in the URL path for a match. See Route
Template Reference for a detailed description of route template syntax.
"{controller=Home}/{action=Index}/{id?}" can match the URL path / and will produce the route values
{ controller = Home, action = Index } . The values for controller and action make use of the default
values, id doesn't produce a value since there's no corresponding segment in the URL path. MVC would
use these route values to select the HomeController and Index action:

{
public IActionResult Index() { ... }
}
Using this controller definition and route template, the HomeController.Index action would be executed for
any of the following URL paths:
/Home/Index/17
/Home/Index
/Home
The convenience method UseMvcWithDefaultRoute :
Can be used to replace:
{
});
UseMvc and UseMvcWithDefaultRoute add an instance of RouterMiddleware to the middleware pipeline. MVC
doesn't interact directly with middleware, and uses routing to handle requests. MVC is connected to the
routes through an instance of MvcRouteHandler . The code inside of UseMvc is similar to the following:
var routes = new RouteBuilder(app);
// Add connection to MVC, will be hooked up by calls to MapRoute.

routes.DefaultHandler = new MvcRouteHandler(...);
// Execute callback to register routes.

// routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");
// Create route collection and add the middleware.

app.UseRouter(routes.Build());
UseMvc doesn't directly define any routes, it adds a placeholder to the route collection for the attribute
route. The overload UseMvc(Action<IRouteBuilder>) lets you add your own routes and also supports attribute
routing. UseMvc and all of its variations adds a placeholder for the attribute route - attribute routing is
always available regardless of how you configure UseMvc . UseMvcWithDefaultRoute defines a default route
and supports attribute routing. The Attribute Routing section includes more details on attribute routing.
Conventional routing
The default route:
is an example of a conventional routing. We call this style conventional routing because it establishes a
convention for URL paths:
the first path segment maps to the controller name
the second maps to the action name.
the third segment is used for an optional id used to map to a model entity
Using this route, the URL path /Products/List maps to the ProductsController.List action, and
default
/Blog/Article/17 maps to BlogController.Article . This mapping is based on the controller and action
names only and isn't based on namespaces, source file locations, or method parameters.
TIP
Using conventional routing with the default route allows you to build the application quickly without having to come
up with a new URL pattern for each action you define. For an application with CRUD style actions, having consistency
for the URLs across your controllers can help simplify your code and make your UI more predictable.
WARNING
The id is defined as optional by the route template, meaning that your actions can execute without the ID provided
as part of the URL. Usually what will happen if id is omitted from the URL is that it will be set to 0 by model
binding, and as a result no entity will be found in the database matching id == 0 . Attribute routing can give you
fine-grained control to make the ID required for some actions and not for others. By convention the documentation
will include optional parameters like id when they're likely to appear in correct usage.
Multiple routes
You can add multiple routes inside UseMvc by adding more calls to MapRoute . Doing so allows you to define
multiple conventions, or to add conventional routes that are dedicated to a specific action, such as:
{
routes.MapRoute("blog", "blog/{*article}",
defaults: new { controller = "Blog", action = "Article" });
});
The blog route here is a dedicated conventional route, meaning that it uses the conventional routing
system, but is dedicated to a specific action. Since controller and action don't appear in the route
template as parameters, they can only have the default values, and thus this route will always map to the
action BlogController.Article .
Routes in the route collection are ordered, and will be processed in the order they're added. So in this
example, the blog route will be tried before the default route.
NOTE
Dedicated conventional routes often use catch-all route parameters like {*article} to capture the remaining
portion of the URL path. This can make a route 'too greedy' meaning that it matches URLs that you intended to be
matched by other routes. Put the 'greedy' routes later in the route table to solve this.
Fallback
As part of request processing, MVC will verify that the route values can be used to find a controller and
action in your application. If the route values don't match an action then the route isn't considered a match,
and the next route will be tried. This is called fallback, and it's intended to simplify cases where conventional
routes overlap.
Disambiguating actions
When two actions match through routing, MVC must disambiguate to choose the 'best' candidate or else
throw an exception. For example:

{
public IActionResult Edit(int id) { ... }
[HttpPost]
public IActionResult Edit(int id, Product product) { ... }
}
This controller defines two actions that would match the URL path /Products/Edit/17 and route data
{ controller = Products, action = Edit, id = 17 } . This is a typical pattern for MVC controllers where
Edit(int) shows a form to edit a product, and Edit(int, Product) processes the posted form. To make this
possible MVC would need to choose Edit(int, Product) when the request is an HTTP POST and
Edit(int) when the HTTP verb is anything else.
The HttpPostAttribute ( [HttpPost] ) is an implementation of IActionConstraint that will only allow the
action to be selected when the HTTP verb is POST . The presence of an IActionConstraint makes the
Edit(int, Product) a 'better' match than Edit(int) , so Edit(int, Product) will be tried first.
You will only need to write custom IActionConstraint implementations in specialized scenarios, but it's
important to understand the role of attributes like HttpPostAttribute - similar attributes are defined for
other HTTP verbs. In conventional routing it's common for actions to use the same action name when
they're part of a show form -> submit form workflow. The convenience of this pattern will become more
apparent after reviewing the Understanding IActionConstraint section.
If multiple routes match, and MVC can't find a 'best' route, it will throw an AmbiguousActionException .
Route names
The strings "blog" and "default" in the following examples are route names:
{
});
The route names give the route a logical name so that the named route can be used for URL generation.
This greatly simplifies URL creation when the ordering of routes could make URL generation complicated.
Route names must be unique application-wide.
Route names have no impact on URL matching or handling of requests; they're used only for URL
generation. Routing has more detailed information on URL generation including URL generation in MVC -
specific helpers.
Attribute routing
Attribute routing uses a set of attributes to map actions directly to route templates. In the following example,
app.UseMvc(); is used in the Configure method and no route is passed. The HomeController will match a
set of URLs similar to what the default route {controller=Home}/{action=Index}/{id?} would match:

{
[Route("")]
[Route("Home")]
[Route("Home/Index")]
{
return View();
}
[Route("Home/About")]
{
return View();
}
[Route("Home/Contact")]
{
return View();
}
}
The HomeController.Index() action will be executed for any of the URL paths / , /Home , or /Home/Index .
NOTE
This example highlights a key programming difference between attribute routing and conventional routing. Attribute
routing requires more input to specify a route; the conventional default route handles routes more succinctly.
However, attribute routing allows (and requires) precise control of which route templates apply to each action.
With attribute routing the controller name and action names play no role in which action is selected. This
example will match the same URLs as the previous example.
public class MyDemoController : Controller
{
[Route("")]
[Route("Home")]
[Route("Home/Index")]
public IActionResult MyIndex()
{
return View("Index");
}
[Route("Home/About")]
public IActionResult MyAbout()
{
return View("About");
}
[Route("Home/Contact")]
public IActionResult MyContact()
{
return View("Contact");
}
}
NOTE
The route templates above don't define route parameters for action , area , and controller . In fact, these route
parameters are not allowed in attribute routes. Since the route template is already associated with an action, it
wouldn't make sense to parse the action name from the URL.
Attribute routing with Http[Verb] attributes

Attribute routing can also make use of the Http[Verb] attributes such as HttpPostAttribute . All of these
attributes can accept a route template. This example shows two actions that match the same route template:
[HttpGet("/products")]
public IActionResult ListProducts()
{
// ...
}
[HttpPost("/products")]
public IActionResult CreateProduct(...)
{
// ...
}
For a URL path like /products the ProductsApi.ListProducts action will be executed when the HTTP verb is
GET and ProductsApi.CreateProduct will be executed when the HTTP verb is POST . Attribute routing first
matches the URL against the set of route templates defined by route attributes. Once a route template
matches, IActionConstraint constraints are applied to determine which actions can be executed.
TIP
When building a REST API, it's rare that you will want to use [Route(...)] on an action method. It's better to use
the more specific Http*Verb*Attributes to be precise about what your API supports. Clients of REST APIs are
expected to know what paths and HTTP verbs map to specific logical operations.
Since an attribute route applies to a specific action, it's easy to make parameters required as part of the route
template definition. In this example, id is required as part of the URL path.
public class ProductsApiController : Controller
{
[HttpGet("/products/{id}", Name = "Products_List")]
public IActionResult GetProduct(int id) { ... }
}
The ProductsApi.GetProduct(int) action will be executed for a URL path like /products/3 but not for a URL
path like /products . See Routing for a full description of route templates and related options.
Route Name
The following code defines a route name of Products_List :

{
[HttpGet("/products/{id}", Name = "Products_List")]
public IActionResult GetProduct(int id) { ... }
}
Route names can be used to generate a URL based on a specific route. Route names have no impact on the
URL matching behavior of routing and are only used for URL generation. Route names must be unique
application-wide.
NOTE
Contrast this with the conventional default route, which defines the id parameter as optional ( {id?} ). This ability
to precisely specify APIs has advantages, such as allowing /products and /products/5 to be dispatched to
different actions.
Combining routes
To make attribute routing less repetitive, route attributes on the controller are combined with route
attributes on the individual actions. Any route templates defined on the controller are prepended to route
templates on the actions. Placing a route attribute on the controller makes all actions in the controller use
attribute routing.
[Route("products")]
{
[HttpGet]
public IActionResult ListProducts() { ... }
[HttpGet("{id}")]
public ActionResult GetProduct(int id) { ... }
}
In this example the URL path /products can match ProductsApi.ListProducts , and the URL path
/products/5 can match ProductsApi.GetProduct(int) . Both of these actions only match HTTP GET because
they're decorated with the HttpGetAttribute .
Route templates applied to an action that begin with a / don't get combined with route templates applied
to the controller. This example matches a set of URL paths similar to the default route.
[Route("Home")]
{
[Route("")] // Combines to define the route template "Home"
[Route("Index")] // Combines to define the route template "Home/Index"
[Route("/")] // Doesn't combine, defines the route template ""
{
ViewData["Message"] = "Home index";
var url = Url.Action("Index", "Home");
ViewData["Message"] = "Home index" + "var url = Url.Action; = " + url;
return View();
}
[Route("About")] // Combines to define the route template "Home/About"

{
return View();
}
}
Ordering attribute routes

In contrast to conventional routes which execute in a defined order, attribute routing builds a tree and
matches all routes simultaneously. This behaves as-if the route entries were placed in an ideal ordering; the
most specific routes have a chance to execute before the more general routes.
For example, a route like blog/search/{topic} is more specific than a route like blog/{*article} . Logically
speaking the blog/search/{topic} route 'runs' first, by default, because that's the only sensible ordering.
Using conventional routing, the developer is responsible for placing routes in the desired order.
Attribute routes can configure an order, using the Order property of all of the framework provided route
attributes. Routes are processed according to an ascending sort of the Order property. The default order is
0 . Setting a route using Order = -1 will run before routes that don't set an order. Setting a route using
Order = 1 will run after default route ordering.
TIP
Avoid depending on Order . If your URL-space requires explicit order values to route correctly, then it's likely
confusing to clients as well. In general attribute routing will select the correct route with URL matching. If the default
order used for URL generation isn't working, using route name as an override is usually simpler than applying the
Order property.
Razor Pages routing and MVC controller routing share an implementation. Information on route order in
the Razor Pages topics is available at Razor Pages route and app conventions: Route order.
Token replacement in route templates ([controller], [action], [area])

For convenience, attribute routes support token replacement by enclosing a token in square-braces ( [ , ] ).
The tokens [action] , [area] , and [controller] will be replaced with the values of the action name, area
name, and controller name from the action where the route is defined. In this example the actions can match
URL paths as described in the comments:
[Route("[controller]/[action]")]
{
[HttpGet] // Matches '/Products/List'
public IActionResult List() {
// ...
}
[HttpGet("{id}")] // Matches '/Products/Edit/{id}'

public IActionResult Edit(int id) {
// ...
}
}
Token replacement occurs as the last step of building the attribute routes. The above example will behave the
same as the following code:

{
[HttpGet("[controller]/[action]")] // Matches '/Products/List'
public IActionResult List() {
// ...
}
[HttpGet("[controller]/[action]/{id}")] // Matches '/Products/Edit/{id}'

public IActionResult Edit(int id) {
// ...
}
}
Attribute routes can also be combined with inheritance. This is particularly powerful combined with token
replacement.
public abstract class MyBaseController : Controller { ... }
public class ProductsController : MyBaseController

{
[HttpGet] // Matches '/api/Products'
public IActionResult List() { ... }
[HttpPut("{id}")] // Matches '/api/Products/{id}'

public IActionResult Edit(int id) { ... }
}
Token replacement also applies to route names defined by attribute routes.

[Route("[controller]/[action]", Name="[controller]_[action]")] will generate a unique route name for each
action.
To match the literal token replacement delimiter [ or ] , escape it by repeating the character ( [[ or ]] ).
Multiple Routes
Attribute routing supports defining multiple routes that reach the same action. The most common usage of
this is to mimic the behavior of the default conventional route as shown in the following example:
[Route("[controller]")]
{
[Route("")] // Matches 'Products'
[Route("Index")] // Matches 'Products/Index'
}
Putting multiple route attributes on the controller means that each one will combine with each of the route
attributes on the action methods.
[Route("Store")]
[Route("[controller]")]
{
[HttpPost("Buy")] // Matches 'Products/Buy' and 'Store/Buy'
[HttpPost("Checkout")] // Matches 'Products/Checkout' and 'Store/Checkout'
public IActionResult Buy()
}
When multiple route attributes (that implement IActionConstraint ) are placed on an action, then each
action constraint combines with the route template from the attribute that defined it.
{
[HttpPut("Buy")] // Matches PUT 'api/Products/Buy'
[HttpPost("Checkout")] // Matches POST 'api/Products/Checkout'
public IActionResult Buy()
}
TIP
While using multiple routes on actions can seem powerful, it's better to keep your application's URL space simple and
well-defined. Use multiple routes on actions only where needed, for example to support existing clients.
Specifying attribute route optional parameters, default values, and constraints

Attribute routes support the same inline syntax as conventional routes to specify optional parameters,
default values, and constraints.
[HttpPost("product/{id:int}")]
public IActionResult ShowProduct(int id)
{
// ...
}
See Route Template Reference for a detailed description of route template syntax.
Custom route attributes using IRouteTemplateProvider
All of the route attributes provided in the framework ( [Route(...)] , [HttpGet(...)] , etc.) implement the
IRouteTemplateProvider interface. MVC looks for attributes on controller classes and action methods when
the app starts and uses the ones that implement IRouteTemplateProvider to build the initial set of routes.
You can implement IRouteTemplateProvider to define your own route attributes. Each
IRouteTemplateProvider allows you to define a single route with a custom route template, order, and name:
public class MyApiControllerAttribute : Attribute, IRouteTemplateProvider
{
public string Template => "api/[controller]";
public int? Order { get; set; }

}
The attribute from the above example automatically sets the Template to "api/[controller]" when
[MyApiController] is applied.
Using Application Model to customize attribute routes

The application model is an object model created at startup with all of the metadata used by MVC to route
and execute your actions. The application model includes all of the data gathered from route attributes
(through IRouteTemplateProvider ). You can write conventions to modify the application model at startup
time to customize how routing behaves. This section shows a simple example of customizing routing using
application model.
using Microsoft.AspNetCore.Mvc.ApplicationModels;
using System.Linq;
using System.Text;
public class NamespaceRoutingConvention : IControllerModelConvention
{
private readonly string _baseNamespace;
public NamespaceRoutingConvention(string baseNamespace)

{
_baseNamespace = baseNamespace;
}
public void Apply(ControllerModel controller)

{
var hasRouteAttributes = controller.Selectors.Any(selector =>
selector.AttributeRouteModel != null);
if (hasRouteAttributes)
{
// This controller manually defined some routes, so treat this
// as an override and not apply the convention here.
return;
}
// Use the namespace and controller name to infer a route for the controller.
//
// Example:
//
// controller.ControllerTypeInfo -> "My.Application.Admin.UsersController"
// baseNamespace -> "My.Application"
//
// template => "Admin/[controller]"
//
// This makes your routes roughly line up with the folder structure of your project.
//
var namespc = controller.ControllerType.Namespace;
if (namespc == null)
return;
var template = new StringBuilder();
template.Append(namespc, _baseNamespace.Length + 1,
namespc.Length - _baseNamespace.Length - 1);
template.Replace('.', '/');
template.Append("/[controller]");
foreach (var selector in controller.Selectors)

{
selector.AttributeRouteModel = new AttributeRouteModel()
{
Template = template.ToString()
};
}
}
}
Mixed routing: Attribute routing vs conventional routing

MVC applications can mix the use of conventional routing and attribute routing. It's typical to use
conventional routes for controllers serving HTML pages for browsers, and attribute routing for controllers
serving REST APIs.
Actions are either conventionally routed or attribute routed. Placing a route on the controller or the action
makes it attribute routed. Actions that define attribute routes cannot be reached through the conventional
routes and vice-versa. Any route attribute on the controller makes all actions in the controller attribute
routed.
NOTE
What distinguishes the two types of routing systems is the process applied after a URL matches a route template. In
conventional routing, the route values from the match are used to choose the action and controller from a lookup
table of all conventional routed actions. In attribute routing, each template is already associated with an action, and
no further lookup is needed.
URL Generation
MVC applications can use routing's URL generation features to generate URL links to actions. Generating
URLs eliminates hardcoding URLs, making your code more robust and maintainable. This section focuses
on the URL generation features provided by MVC and will only cover basics of how URL generation works.
See Routing for a detailed description of URL generation.
The IUrlHelper interface is the underlying piece of infrastructure between MVC and routing for URL
generation. You'll find an instance of IUrlHelper available through the Url property in controllers, views,
and view components.
In this example, the IUrlHelper interface is used through the Controller.Url property to generate a URL to
another action.
public class UrlGenerationController : Controller

{
public IActionResult Source()
{
// Generates /UrlGeneration/Destination
var url = Url.Action("Destination");
return Content($"Go check out {url}, it's really great.");
}
public IActionResult Destination()

{
return View();
}
}
If the application is using the default conventional route, the value of the url variable will be the URL path
string /UrlGeneration/Destination . This URL path is created by routing by combining the route values from
the current request (ambient values), with the values passed to Url.Action and substituting those values
into the route template:
ambient values: { controller = "UrlGeneration", action = "Source" }

values passed to Url.Action: { controller = "UrlGeneration", action = "Destination" }
route template: {controller}/{action}/{id?}
result: /UrlGeneration/Destination
Each route parameter in the route template has its value substituted by matching names with the values and
ambient values. A route parameter that doesn't have a value can use a default value if it has one, or be
skipped if it's optional (as in the case of id in this example). URL generation will fail if any required route
parameter doesn't have a corresponding value. If URL generation fails for a route, the next route is tried until
all routes have been tried or a match is found.
The example of Url.Action above assumes conventional routing, but URL generation works similarly with
attribute routing, though the concepts are different. With conventional routing, the route values are used to
expand a template, and the route values for controller and action usually appear in that template - this
works because the URLs matched by routing adhere to a convention. In attribute routing, the route values
for controller and action are not allowed to appear in the template - they're instead used to look up
which template to use.
This example uses attribute routing:
// In Startup class
{
app.UseMvc();
}

{
[HttpGet("")]
{
var url = Url.Action("Destination"); // Generates /custom/url/to/destination
return Content($"Go check out {url}, it's really great.");
}
[HttpGet("custom/url/to/destination")]
public IActionResult Destination() {
return View();
}
}
MVC builds a lookup table of all attribute routed actions and will match the controller and action values
to select the route template to use for URL generation. In the sample above, custom/url/to/destination is
generated.
Generating URLs by action name
Url.Action ( IUrlHelper . Action ) and all related overloads all are based on that idea that you want to
specify what you're linking to by specifying a controller name and action name.
NOTE
When using Url.Action , the current route values for controller and action are specified for you - the value of
controller and action are part of both ambient values and values. The method Url.Action , always uses the
current values of action and controller and will generate a URL path that routes to the current action.
Routing attempts to use the values in ambient values to fill in information that you didn't provide when
generating a URL. Using a route like {a}/{b}/{c}/{d} and ambient values
{ a = Alice, b = Bob, c = Carol, d = David } , routing has enough information to generate a URL without
any additional values - since all route parameters have a value. If you added the value { d = Donovan } , the
value { d = David } would be ignored, and the generated URL path would be Alice/Bob/Carol/Donovan .
WARNING
URL paths are hierarchical. In the example above, if you added the value { c = Cheryl } , both of the values
{ c = Carol, d = David } would be ignored. In this case we no longer have a value for d and URL generation
will fail. You would need to specify the desired value of c and d . You might expect to hit this problem with the
default route ( {controller}/{action}/{id?} ) - but you will rarely encounter this behavior in practice as
Url.Action will always explicitly specify a controller and action value.
Longer overloads of Url.Action also take an additional route values object to provide values for route
parameters other than controller and action . You will most commonly see this used with id like
Url.Action("Buy", "Products", new { id = 17 }) . By convention the route values object is usually an object
of anonymous type, but it can also be an IDictionary<> or a plain old .NET object. Any additional route
values that don't match route parameters are put in the query string.
public class TestController : Controller

{
{
// Generates /Products/Buy/17?color=red
var url = Url.Action("Buy", "Products", new { id = 17, color = "red" });
return Content(url);
}
}
TIP
To create an absolute URL, use an overload that accepts a protocol :
Url.Action("Buy", "Products", new { id = 17 }, protocol: Request.Scheme)
Generating URLs by route

The code above demonstrated generating a URL by passing in the controller and action name. IUrlHelper
also provides the Url.RouteUrl family of methods. These methods are similar to Url.Action , but they don't
copy the current values of action and controller to the route values. The most common usage is to
specify a route name to use a specific route to generate the URL, generally without specifying a controller or
action name.

{
[HttpGet("")]
{
var url = Url.RouteUrl("Destination_Route"); // Generates /custom/url/to/destination
return Content($"See {url}, it's really great.");
}
[HttpGet("custom/url/to/destination", Name = "Destination_Route")]

public IActionResult Destination() {
return View();
}
}
Generating URLs in HTML

IHtmlHelper provides the HtmlHelper methods Html.BeginForm and Html.ActionLink to generate <form>
and <a> elements respectively. These methods use the Url.Action method to generate a URL and they
accept similar arguments. The Url.RouteUrl companions for HtmlHelper are Html.BeginRouteForm and
Html.RouteLink which have similar functionality.
TagHelpers generate URLs through the form TagHelper and the <a> TagHelper. Both of these use
IUrlHelper for their implementation. See Working with Forms for more information.
Inside views, the IUrlHelper is available through the Url property for any ad-hoc URL generation not
covered by the above.
Generating URLS in Action Results
The examples above have shown using IUrlHelper in a controller, while the most common usage in a
controller is to generate a URL as part of an action result.
The ControllerBase and Controller base classes provide convenience methods for action results that
reference another action. One typical usage is to redirect after accepting user input.
public IActionResult Edit(int id, Customer customer)

{
{
// Update DB with new details.
}
return View(customer);
}
The action results factory methods follow a similar pattern to the methods on IUrlHelper .
Special case for dedicated conventional routes
Conventional routing can use a special kind of route definition called a dedicated conventional route. In the
example below, the route named blog is a dedicated conventional route.
{
});
Using these route definitions, Url.Action("Index", "Home") will generate the URL path / with the default
route, but why? You might guess the route values { controller = Home, action = Index } would be enough
to generate a URL using blog , and the result would be /blog?action=Index&controller=Home .
Dedicated conventional routes rely on a special behavior of default values that don't have a corresponding
route parameter that prevents the route from being "too greedy" with URL generation. In this case the
default values are { controller = Blog, action = Article } , and neither controller nor action appears as
a route parameter. When routing performs URL generation, the values provided must match the default
values. URL generation using blog will fail because the values { controller = Home, action = Index } don't
match { controller = Blog, action = Article } . Routing then falls back to try default , which succeeds.
Areas
Areas are an MVC feature used to organize related functionality into a group as a separate routing-
namespace (for controller actions) and folder structure (for views). Using areas allows an application to have
multiple controllers with the same name - as long as they have different areas. Using areas creates a
hierarchy for the purpose of routing by adding another route parameter, area to controller and action .
This section will discuss how routing interacts with areas - see Areas for details about how areas are used
with views.
The following example configures MVC to use the default conventional route and an area route for an area
named Blog :
{
routes.MapAreaRoute("blog_route", "Blog",
"Manage/{controller}/{action}/{id?}");
routes.MapRoute("default_route", "{controller}/{action}/{id?}");
});
When matching a URL path like , the first route will produce the route values
/Manage/Users/AddUser
{ area = Blog, controller = Users, action = AddUser } . The area route value is produced by a default
value for area , in fact the route created by MapAreaRoute is equivalent to the following:
{
routes.MapRoute("blog_route", "Manage/{controller}/{action}/{id?}",
defaults: new { area = "Blog" }, constraints: new { area = "Blog" });
routes.MapRoute("default_route", "{controller}/{action}/{id?}");
});
MapAreaRoute creates a route using both a default value and constraint for area using the provided area
name, in this case Blog . The default value ensures that the route always produces { area = Blog, ... } ,
the constraint requires the value { area = Blog, ... } for URL generation.
TIP
Conventional routing is order-dependent. In general, routes with areas should be placed earlier in the route table as
they're more specific than routes without an area.
Using the above example, the route values would match the following action:
namespace MyApp.Namespace1
{
[Area("Blog")]
public class UsersController : Controller
{
public IActionResult AddUser()
{
return View();
}
}
}
The AreaAttribute is what denotes a controller as part of an area, we say that this controller is in the Blog
area. Controllers without an [Area] attribute are not members of any area, and will not match when the
area route value is provided by routing. In the following example, only the first controller listed can match
the route values { area = Blog, controller = Users, action = AddUser } .
{
[Area("Blog")]
{
{
return View();
}
}
}
{
// Matches { area = Zebra, controller = Users, action = AddUser }
[Area("Zebra")]
{
{
return View();
}
}
}
{
// Matches { area = string.Empty, controller = Users, action = AddUser }
// Matches { area = null, controller = Users, action = AddUser }
// Matches { controller = Users, action = AddUser }
{
{
return View();
}
}
}
NOTE
The namespace of each controller is shown here for completeness - otherwise the controllers would have a naming
conflict and generate a compiler error. Class namespaces have no effect on MVC's routing.
The first two controllers are members of areas, and only match when their respective area name is provided
by the area route value. The third controller isn't a member of any area, and can only match when no value
for area is provided by routing.
NOTE
In terms of matching no value, the absence of the area value is the same as if the value for area were null or the
empty string.
When executing an action inside an area, the route value for area will be available as an ambient value for
routing to use for URL generation. This means that by default areas act sticky for URL generation as
demonstrated by the following sample.
{
routes.MapAreaRoute("duck_route", "Duck",
"Manage/{controller}/{action}/{id?}");
routes.MapRoute("default", "Manage/{controller=Home}/{action=Index}/{id?}");
});
{
[Area("Duck")]
{
public IActionResult GenerateURLInArea()
{
// Uses the 'ambient' value of area
var url = Url.Action("Index", "Home");
// returns /Manage
}
public IActionResult GenerateURLOutsideOfArea()

{
// Uses the empty value for area
var url = Url.Action("Index", "Home", new { area = "" });
// returns /Manage/Home/Index
}
}
}
Understanding IActionConstraint
NOTE
This section is a deep-dive on framework internals and how MVC chooses an action to execute. A typical application
won't need a custom IActionConstraint
You have likely already used IActionConstraint even if you're not familiar with the interface. The [HttpGet]
Attribute and similar [Http-VERB] attributes implement IActionConstraint in order to limit the execution of
an action method.
{
[HttpGet]
public IActionResult Edit() { }
public IActionResult Edit(...) { }

}
Assuming the default conventional route, the URL path /Products/Edit would produce the values
{ controller = Products, action = Edit } , which would match both of the actions shown here. In
IActionConstraint terminology we would say that both of these actions are considered candidates - as they
both match the route data.
When the HttpGetAttribute executes, it will say that Edit() is a match for GET and isn't a match for any other
HTTP verb. The Edit(...) action doesn't have any constraints defined, and so will match any HTTP verb. So
assuming a POST - only Edit(...) matches. But, for a GET both actions can still match - however, an action
with an IActionConstraint is always considered better than an action without. So because Edit() has
[HttpGet] it's considered more specific, and will be selected if both actions can match.
Conceptually, IActionConstraint is a form of overloading, but instead of overloading methods with the
same name, it's overloading between actions that match the same URL. Attribute routing also uses
IActionConstraint and can result in actions from different controllers both being considered candidates.
Implementing IActionConstraint
The simplest way to implement an IActionConstraint is to create a class derived from System.Attribute
and place it on your actions and controllers. MVC will automatically discover any IActionConstraint that are
applied as attributes. You can use the application model to apply constraints, and this is probably the most
flexible approach as it allows you to metaprogram how they're applied.
In the following example a constraint chooses an action based on a country code from the route data. The
full sample on GitHub.
public class CountrySpecificAttribute : Attribute, IActionConstraint

{
private readonly string _countryCode;
public CountrySpecificAttribute(string countryCode)

{
_countryCode = countryCode;
}
public int Order

{
get
{
return 0;
}
}
public bool Accept(ActionConstraintContext context)

{
return string.Equals(
context.RouteContext.RouteData.Values["country"].ToString(),
_countryCode,
StringComparison.OrdinalIgnoreCase);
}
}
You are responsible for implementing the Accept method and choosing an 'Order' for the constraint to
execute. In this case, the Accept method returns true to denote the action is a match when the country
route value matches. This is different from a RouteValueAttribute in that it allows fallback to a non-
attributed action. The sample shows that if you define an en-US action then a country code like fr-FR will
fall back to a more generic controller that doesn't have [CountrySpecific(...)] applied.
The Order property decides which stage the constraint is part of. Action constraints run in groups based on
the Order . For example, all of the framework provided HTTP method attributes use the same Order value
so that they run in the same stage. You can have as many stages as you need to implement your desired
policies.
TIP
To decide on a value for Order think about whether or not your constraint should be applied before HTTP methods.
Lower numbers run first.
File uploads in ASP.NET Core
By Steve Smith
ASP.NET MVC actions support uploading of one or more files using simple model binding for smaller files or
streaming for larger files.
View or download sample from GitHub
Uploading small files with model binding

To upload small files, you can use a multi-part HTML form or construct a POST request using JavaScript. An
example form using Razor, which supports multiple uploaded files, is shown below:
<form method="post" enctype="multipart/form-data" asp-controller="UploadFiles" asp-action="Index">

<p>Upload one or more files using this form:</p>
<input type="file" name="files" multiple />
</div>
</div>
<input type="submit" value="Upload" />
</div>
</div>
</form>
In order to support file uploads, HTML forms must specify an enctype of multipart/form-data . The files input
element shown above supports uploading multiple files. Omit the multiple attribute on this input element to
allow just a single file to be uploaded. The above markup renders in a browser as:
The individual files uploaded to the server can be accessed through Model Binding using the IFormFile interface.
IFormFile has the following structure:
public interface IFormFile
{
string ContentType { get; }
string ContentDisposition { get; }
IHeaderDictionary Headers { get; }
long Length { get; }
string Name { get; }
string FileName { get; }
Stream OpenReadStream();
void CopyTo(Stream target);
Task CopyToAsync(Stream target, CancellationToken cancellationToken = null);
}
WARNING
Don't rely on or trust the FileName property without validation. The FileName property should only be used for display
purposes.
When uploading files using model binding and the IFormFile interface, the action method can accept either a
single IFormFile or an IEnumerable<IFormFile> (or List<IFormFile> ) representing several files. The following
example loops through one or more uploaded files, saves them to the local file system, and returns the total
number and size of files uploaded.
Warning: The following code uses GetTempFileName , which throws an IOException if more than 65535 files are
created without deleting previous temporary files. A real app should either delete temporary files or use
GetTempPath and GetRandomFileName to create temporary file names. The 65535 files limit is per server, so another
app on the server can use up all 65535 files.
[HttpPost("UploadFiles")]
public async Task<IActionResult> Post(List<IFormFile> files)
{
long size = files.Sum(f => f.Length);
// full path to file in temp location

var filePath = Path.GetTempFileName();
foreach (var formFile in files)

{
if (formFile.Length > 0)
{
using (var stream = new FileStream(filePath, FileMode.Create))
{
await formFile.CopyToAsync(stream);
}
}
}
// process uploaded files

// Don't rely on or trust the FileName property without validation.
return Ok(new { count = files.Count, size, filePath});

}
Files uploaded using the IFormFile technique are buffered in memory or on disk on the web server before being
processed. Inside the action method, the IFormFile contents are accessible as a stream. In addition to the local file
system, files can be streamed to Azure Blob storage or Entity Framework.
To store binary file data in a database using Entity Framework, define a property of type byte[] on the entity:
public class ApplicationUser : IdentityUser
{
public byte[] AvatarImage { get; set; }
}
Specify a viewmodel property of type IFormFile :

{
// other properties omitted
public IFormFile AvatarImage { get; set; }

}
NOTE
IFormFile can be used directly as an action method parameter or as a viewmodel property, as shown above.
Copy the IFormFile to a stream and save it to the byte array:
// POST: /Account/Register
[HttpPost]
[AllowAnonymous]
public async Task<IActionResult> Register(RegisterViewModel model)
{
ViewData["ReturnUrl"] = returnUrl;
{
var user = new ApplicationUser {
UserName = model.Email,
Email = model.Email
};
using (var memoryStream = new MemoryStream())
{
await model.AvatarImage.CopyToAsync(memoryStream);
user.AvatarImage = memoryStream.ToArray();
}
// additional logic omitted
// Don't rely on or trust the model.AvatarImage.FileName property

// without validation.
}
NOTE
Use caution when storing binary data in relational databases, as it can adversely impact performance.
Uploading large files with streaming

If the size or frequency of file uploads is causing resource problems for the app, consider streaming the file upload
rather than buffering it in its entirety, as the model binding approach shown above does. While using IFormFile
and model binding is a much simpler solution, streaming requires a number of steps to implement properly.
NOTE
Any single buffered file exceeding 64KB will be moved from RAM to a temp file on disk on the server. The resources (disk,
RAM) used by file uploads depend on the number and size of concurrent file uploads. Streaming isn't so much about perf, it's
about scale. If you try to buffer too many uploads, your site will crash when it runs out of memory or disk space.
The following example demonstrates using JavaScript/Angular to stream to a controller action. The file's
antiforgery token is generated using a custom filter attribute and passed in HTTP headers instead of in the request
body. Because the action method processes the uploaded data directly, model binding is disabled by another filter.
Within the action, the form's contents are read using a MultipartReader , which reads each individual
MultipartSection , processing the file or storing the contents as appropriate. Once all sections have been read, the
action performs its own model binding.
The initial action loads the form and saves an antiforgery token in a cookie (via the
GenerateAntiforgeryTokenCookieForAjax attribute):
[HttpGet]
[GenerateAntiforgeryTokenCookieForAjax]
{
return View();
}
The attribute uses ASP.NET Core's built-in Antiforgery support to set a cookie with a request token:
public class GenerateAntiforgeryTokenCookieForAjaxAttribute : ActionFilterAttribute

{
public override void OnActionExecuted(ActionExecutedContext context)
{
var antiforgery = context.HttpContext.RequestServices.GetService<IAntiforgery>();
// We can send the request token as a JavaScript-readable cookie,

// and Angular will use it by default.
var tokens = antiforgery.GetAndStoreTokens(context.HttpContext);
context.HttpContext.Response.Cookies.Append(
"XSRF-TOKEN",
tokens.RequestToken,
new CookieOptions() { HttpOnly = false });
}
}
Angular automatically passes an antiforgery token in a request header named X-XSRF-TOKEN . The ASP.NET Core
MVC app is configured to refer to this header in its configuration in Startup.cs:

{
// Angular's default header name for sending the XSRF token.
services.AddAntiforgery(options => options.HeaderName = "X-XSRF-TOKEN");
services.AddMvc();
}
The DisableFormValueModelBinding attribute, shown below, is used to disable model binding for the Upload action
method.
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method)]
public class DisableFormValueModelBindingAttribute : Attribute, IResourceFilter
{
public void OnResourceExecuting(ResourceExecutingContext context)
{
var factories = context.ValueProviderFactories;
factories.RemoveType<FormValueProviderFactory>();
factories.RemoveType<JQueryFormValueProviderFactory>();
}
public void OnResourceExecuted(ResourceExecutedContext context)

{
}
}
Since model binding is disabled, the Upload action method doesn't accept parameters. It works directly with the
Request property of ControllerBase . A MultipartReader is used to read each section. The file is saved with a
GUID filename and the key/value data is stored in a KeyValueAccumulator . Once all sections have been read, the
contents of the KeyValueAccumulator are used to bind the form data to a model type.
The complete Upload method is shown below:
Warning: The following code uses GetTempFileName , which throws an IOException if more than 65535 files are
created without deleting previous temporary files. A real app should either delete temporary files or use
GetTempPath and GetRandomFileName to create temporary file names. The 65535 files limit is per server, so another
app on the server can use up all 65535 files.
// 1. Disable the form value model binding here to take control of handling
// potentially large files.
// 2. Typically antiforgery tokens are sent in request body, but since we
// do not want to read the request body early, the tokens are made to be
// sent via headers. The antiforgery token filter first looks for tokens
// in the request header and then falls back to reading the body.
[HttpPost]
[DisableFormValueModelBinding]
public async Task<IActionResult> Upload()
{
if (!MultipartRequestHelper.IsMultipartContentType(Request.ContentType))
{
return BadRequest($"Expected a multipart request, but got {Request.ContentType}");
}
// Used to accumulate all the form url encoded key value pairs in the
// request.
var formAccumulator = new KeyValueAccumulator();
string targetFilePath = null;
var boundary = MultipartRequestHelper.GetBoundary(

MediaTypeHeaderValue.Parse(Request.ContentType),
_defaultFormOptions.MultipartBoundaryLengthLimit);
var reader = new MultipartReader(boundary, HttpContext.Request.Body);
var section = await reader.ReadNextSectionAsync();

while (section != null)
{
ContentDispositionHeaderValue contentDisposition;
var hasContentDispositionHeader = ContentDispositionHeaderValue.TryParse(section.ContentDisposition,
out contentDisposition);
if (hasContentDispositionHeader)
{
if (MultipartRequestHelper.HasFileContentDisposition(contentDisposition))
{
{
targetFilePath = Path.GetTempFileName();
using (var targetStream = System.IO.File.Create(targetFilePath))
{
await section.Body.CopyToAsync(targetStream);
_logger.LogInformation($"Copied the uploaded file '{targetFilePath}'");

}
}
else if (MultipartRequestHelper.HasFormDataContentDisposition(contentDisposition))
{
// Content-Disposition: form-data; name="key"
//
// value
// Do not limit the key name length here because the

// multipart headers length limit is already in effect.
var key = HeaderUtilities.RemoveQuotes(contentDisposition.Name);
var encoding = GetEncoding(section);
using (var streamReader = new StreamReader(
section.Body,
encoding,
detectEncodingFromByteOrderMarks: true,
bufferSize: 1024,
leaveOpen: true))
{
// The value length limit is enforced by MultipartBodyLengthLimit
var value = await streamReader.ReadToEndAsync();
if (String.Equals(value, "undefined", StringComparison.OrdinalIgnoreCase))
{
value = String.Empty;
}
formAccumulator.Append(key, value);
if (formAccumulator.ValueCount > _defaultFormOptions.ValueCountLimit)

{
throw new InvalidDataException($"Form key count limit
{_defaultFormOptions.ValueCountLimit} exceeded.");
}
}
}
}
// Drains any remaining section body that has not been consumed and
// reads the headers for the next section.
section = await reader.ReadNextSectionAsync();
}
// Bind form data to a model

var user = new User();
var formValueProvider = new FormValueProvider(
BindingSource.Form,
new FormCollection(formAccumulator.GetResults()),
CultureInfo.CurrentCulture);
var bindingSuccessful = await TryUpdateModelAsync(user, prefix: "",

valueProvider: formValueProvider);
if (!bindingSuccessful)
{
{
}
}
var uploadedData = new UploadedData()

{
Name = user.Name,
Age = user.Age,
Zipcode = user.Zipcode,
Zipcode = user.Zipcode,
FilePath = targetFilePath
};
return Json(uploadedData);
}
Troubleshooting
Below are some common problems encountered when working with uploading files and their possible solutions.
Unexpected Not Found error with IIS
The following error indicates your file upload exceeds the server's configured maxAllowedContentLength :
HTTP 404.13 - Not Found

The request filtering module is configured to deny a request that exceeds the request content length.
The default setting is 30000000 , which is approximately 28.6MB. The value can be customized by editing
web.config:
<system.webServer>
<security>
<requestFiltering>

<requestLimits maxAllowedContentLength="52428800" />
</requestFiltering>
</security>
</system.webServer>
This setting only applies to IIS. The behavior doesn't occur by default when hosting on Kestrel. For more
information, see Request Limits <requestLimits>.
Null Reference Exception with IFormFile
If your controller is accepting uploaded files using IFormFile but you find that the value is always null, confirm
that your HTML form is specifying an enctype value of multipart/form-data . If this attribute isn't set on the
<form> element, the file upload won't occur and any bound IFormFile arguments will be null.
Dependency injection into controllers in ASP.NET
Core
By Steve Smith
ASP.NET Core MVC controllers should request their dependencies explicitly via their constructors. In some
instances, individual controller actions may require a service, and it may not make sense to request at the
controller level. In this case, you can also choose to inject a service as a parameter on the action method.
Dependency Injection
Dependency injection is a technique that follows the Dependency Inversion Principle, allowing for applications to
be composed of loosely coupled modules. ASP.NET Core has built-in support for dependency injection, which
makes applications easier to test and maintain.
Constructor Injection
ASP.NET Core's built-in support for constructor-based dependency injection extends to MVC controllers. By
simply adding a service type to your controller as a constructor parameter, ASP.NET Core will attempt to resolve
that type using its built in service container. Services are typically, but not always, defined using interfaces. For
example, if your application has business logic that depends on the current time, you can inject a service that
retrieves the time (rather than hard-coding it), which would allow your tests to pass in implementations that use a
set time.
using System;
namespace ControllerDI.Interfaces
{
public interface IDateTime
{
DateTime Now { get; }
}
}
Implementing an interface like this one so that it uses the system clock at runtime is trivial:
using System;
using ControllerDI.Interfaces;
namespace ControllerDI.Services
{
public class SystemDateTime : IDateTime
{
public DateTime Now
{
get { return DateTime.Now; }
}
}
}
With this in place, we can use the service in our controller. In this case, we have added some logic to the
HomeController Index method to display a greeting to the user based on the time of day.
using ControllerDI.Interfaces;
namespace ControllerDI.Controllers
{
{
private readonly IDateTime _dateTime;
public HomeController(IDateTime dateTime)

{
_dateTime = dateTime;
}

{
var serverTime = _dateTime.Now;
if (serverTime.Hour < 12)
{
ViewData["Message"] = "It's morning here - Good Morning!";
}
else if (serverTime.Hour < 17)
{
ViewData["Message"] = "It's afternoon here - Good Afternoon!";
}
else
{
ViewData["Message"] = "It's evening here - Good Evening!";
}
return View();
}
}
}
If we run the application now, we will most likely encounter an error:
InvalidOperationException: Unable to resolve service for type 'ControllerDI.Interfaces.IDateTime' while

attempting to activate 'ControllerDI.Controllers.HomeController'.
Microsoft.Extensions.DependencyInjection.ActivatorUtilities.GetService(IServiceProvider sp, Type type, Type
requiredBy, Boolean isDefaultParameterRequired)
This error occurs when we have not configured a service in the ConfigureServices method in our Startup class.
To specify that requests for IDateTime should be resolved using an instance of SystemDateTime , add the
highlighted line in the listing below to your ConfigureServices method:

{
services.AddTransient<IDateTime, SystemDateTime>();
}
NOTE
This particular service could be implemented using any of several different lifetime options ( Transient , Scoped , or
Singleton ). See Dependency Injection to understand how each of these scope options will affect the behavior of your
service.
Once the service has been configured, running the application and navigating to the home page should display
the time-based message as expected:
TIP
See Test controller logic to learn how to explicitly request dependencies http://deviq.com/explicit-dependencies-principle/ in
controllers makes code easier to test.
ASP.NET Core's built-in dependency injection supports having only a single constructor for classes requesting
services. If you have more than one constructor, you may get an exception stating:
InvalidOperationException: Multiple constructors accepting all given argument types have been found in type
'ControllerDI.Controllers.HomeController'. There should only be one applicable constructor.
Microsoft.Extensions.DependencyInjection.ActivatorUtilities.FindApplicableConstructor(Type instanceType,
Type[] argumentTypes, ConstructorInfo& matchingConstructor, Nullable`1[]& parameterMap)
As the error message states, you can correct this problem with the use of a single constructor. You can also
replace the default dependency injection container with a third party implementation, many of which support
multiple constructors.
Action Injection with FromServices

Sometimes you don't need a service for more than one action within your controller. In this case, it may make
sense to inject the service as a parameter to the action method. This is done by marking the parameter with the
attribute [FromServices] as shown here:
public IActionResult About([FromServices] IDateTime dateTime)

{
ViewData["Message"] = "Currently on the server the time is " + dateTime.Now;
return View();
}
Accessing Settings from a Controller

Accessing application or configuration settings from within a controller is a common pattern. This access should
use the Options pattern described in configuration. You generally shouldn't request settings directly from your
controller using dependency injection. A better approach is to request an IOptions<T> instance, where T is the
configuration class you need.
To work with the options pattern, you need to create a class that represents the options, such as this one:
namespace ControllerDI.Model
{
public class SampleWebSettings
{
public int Updates { get; set; }
}
}
Then you need to configure the application to use the options model and add your configuration class to the
services collection in ConfigureServices :

{
.SetBasePath(env.ContentRootPath)
.AddJsonFile("samplewebsettings.json");
}
public IConfigurationRoot Configuration { get; set; }
// For more information on how to configure your application, visit http://go.microsoft.com/fwlink/?
LinkID=398940
{
// Required to use the Options<T> pattern
services.AddOptions();
// Add settings from configuration

services.Configure<SampleWebSettings>(Configuration);
// Uncomment to add settings from code

//services.Configure<SampleWebSettings>(settings =>
//{
// settings.Updates = 17;
//});
services.AddMvc();

services.AddTransient<IDateTime, SystemDateTime>();
}
NOTE
In the above listing, we are configuring the application to read the settings from a JSON-formatted file. You can also
configure the settings entirely in code, as is shown in the commented code above. See Configuration for further
configuration options.
Once you've specified a strongly-typed configuration object (in this case, SampleWebSettings ) and added it to the
services collection, you can request it from any Controller or Action method by requesting an instance of
IOptions<T> (in this case, IOptions<SampleWebSettings> ). The following code shows how one would request the
settings from a controller:
public class SettingsController : Controller
{
private readonly SampleWebSettings _settings;
public SettingsController(IOptions<SampleWebSettings> settingsOptions)

{
_settings = settingsOptions.Value;
}

{
ViewData["Title"] = _settings.Title;
ViewData["Updates"] = _settings.Updates;
return View();
}
}
Following the Options pattern allows settings and configuration to be decoupled from one another, and ensures
the controller is following separation of concerns, since it doesn't need to know how or where to find the settings
information. It also makes the controller easier to unit test Test controller logic, since there's no static cling or
direct instantiation of settings classes within the controller class.
Test controller logic in ASP.NET Core
By Steve Smith
Controllers play a central role in any ASP.NET Core MVC app. As such, you should have confidence that controllers
behave as intended. Automated tests can detect errors before the app is deployed to a production environment.
Unit tests of controller logic

Unit tests involve testing a part of an app in isolation from its infrastructure and dependencies. When unit testing
controller logic, only the contents of a single action are tested, not the behavior of its dependencies or of the
framework itself.
Set up unit tests of controller actions to focus on the controller's behavior. A controller unit test avoids scenarios
such as filters, routing, and model binding. Tests that cover the interactions among components that collectively
respond to a request are handled by integration tests. For more information on integration tests, see Integration
tests in ASP.NET Core.
If you're writing custom filters and routes, unit test them in isolation, not as part of tests on a particular controller
action.
To demonstrate controller unit tests, review the following controller in the sample app. The Home controller
displays a list of brainstorming sessions and allows the creation of new brainstorming sessions with a POST
request:
{
private readonly IBrainstormSessionRepository _sessionRepository;
public HomeController(IBrainstormSessionRepository sessionRepository)

{
_sessionRepository = sessionRepository;
}

{
var sessionList = await _sessionRepository.ListAsync();
var model = sessionList.Select(session => new StormSessionViewModel()

{
Id = session.Id,
DateCreated = session.DateCreated,
Name = session.Name,
IdeaCount = session.Ideas.Count
});
return View(model);
}
public class NewSessionModel

{
[Required]
public string SessionName { get; set; }
}
[HttpPost]
public async Task<IActionResult> Index(NewSessionModel model)
{
{
}
else
{
await _sessionRepository.AddAsync(new BrainstormSession()
{
DateCreated = DateTimeOffset.Now,
Name = model.SessionName
});
}
return RedirectToAction(actionName: nameof(Index));

}
}
The preceding controller:

Follows the Explicit Dependencies Principle.
Expects dependency injection (DI) to provide an instance of IBrainstormSessionRepository .
Can be tested with a mocked IBrainstormSessionRepository service using a mock object framework, such as
Moq. A mocked object is a fabricated object with a predetermined set of property and method behaviors used
for testing. For more information, see Introduction to integration tests.
The HTTP GET Index method has no looping or branching and only calls one method. The unit test for this action:
Mocks the IBrainstormSessionRepository service using the GetTestSessions method. GetTestSessions creates
two mock brainstorm sessions with dates and session names.
Executes the Index method.
Makes assertions on the result returned by the method:
A ViewResult is returned.
The ViewDataDictionary.Model is a StormSessionViewModel .
There are two brainstorming sessions stored in the ViewDataDictionary.Model .
[Fact]
public async Task Index_ReturnsAViewResult_WithAListOfBrainstormSessions()
{
// Arrange
var mockRepo = new Mock<IBrainstormSessionRepository>();
mockRepo.Setup(repo => repo.ListAsync())
.ReturnsAsync(GetTestSessions());
var controller = new HomeController(mockRepo.Object);
// Act
var result = await controller.Index();
// Assert
var viewResult = Assert.IsType<ViewResult>(result);
var model = Assert.IsAssignableFrom<IEnumerable<StormSessionViewModel>>(
viewResult.ViewData.Model);
Assert.Equal(2, model.Count());
}
private List<BrainstormSession> GetTestSessions()

{
var sessions = new List<BrainstormSession>();
sessions.Add(new BrainstormSession()
{
DateCreated = new DateTime(2016, 7, 2),
Id = 1,
Name = "Test One"
});
{
Id = 2,
Name = "Test Two"
});
return sessions;
}
The Home controller's HTTP POST Index method tests verifies that:
When ModelState.IsValid is false , the action method returns a 400 Bad Request ViewResult with the
appropriate data.
When ModelState.IsValid is true :
The Add method on the repository is called.
A RedirectToActionResult is returned with the correct arguments.
An invalid model state is tested by adding errors using AddModelError as shown in the first test below:
[Fact]
public async Task IndexPost_ReturnsBadRequestResult_WhenModelStateIsInvalid()
{
// Arrange
controller.ModelState.AddModelError("SessionName", "Required");
var newSession = new HomeController.NewSessionModel();
// Act
var result = await controller.Index(newSession);
// Assert
var badRequestResult = Assert.IsType<BadRequestObjectResult>(result);
Assert.IsType<SerializableError>(badRequestResult.Value);
}
[Fact]
public async Task IndexPost_ReturnsARedirectAndAddsSession_WhenModelStateIsValid()
{
// Arrange
mockRepo.Setup(repo => repo.AddAsync(It.IsAny<BrainstormSession>()))
.Returns(Task.CompletedTask)
.Verifiable();
var newSession = new HomeController.NewSessionModel()
{
SessionName = "Test Name"
};
// Act
// Assert
var redirectToActionResult = Assert.IsType<RedirectToActionResult>(result);
Assert.Null(redirectToActionResult.ControllerName);
Assert.Equal("Index", redirectToActionResult.ActionName);
mockRepo.Verify();
}
When ModelState isn't valid, the same ViewResult is returned as for a GET request. The test doesn't attempt to
pass in an invalid model. Passing an invalid model isn't a valid approach, since model binding isn't running
(although an integration test does use model binding). In this case, model binding isn't tested. These unit tests are
only testing the code in the action method.
The second test verifies that when the ModelState is valid:
A new BrainstormSession is added (via the repository).
The method returns a RedirectToActionResult with the expected properties.
Mocked calls that aren't called are normally ignored, but calling Verifiable at the end of the setup call allows mock
validation in the test. This is performed with the call to mockRepo.Verify , which fails the test if the expected method
wasn't called.
NOTE
The Moq library used in this sample makes it possible to mix verifiable, or "strict", mocks with non-verifiable mocks (also called
"loose" mocks or stubs). Learn more about customizing Mock behavior with Moq.
Another controller in the sample app displays information related to a particular brainstorming session. The
controller includes logic to deal with invalid id values (there are two return scenarios in the following example to
cover these scenarios). The final return statement returns a new StormSessionViewModel to the view:
public class SessionController : Controller

{
public SessionController(IBrainstormSessionRepository sessionRepository)

{
}
public async Task<IActionResult> Index(int? id)

{
if (!id.HasValue)
{
return RedirectToAction(actionName: nameof(Index),
controllerName: "Home");
}
var session = await _sessionRepository.GetByIdAsync(id.Value);

if (session == null)
{
return Content("Session not found.");
}
var viewModel = new StormSessionViewModel()

{
Id = session.Id
};
}
}
The unit tests include one test for each return scenario in the Session controller Index action:
[Fact]
public async Task IndexReturnsARedirectToIndexHomeWhenIdIsNull()
{
// Arrange
var controller = new SessionController(sessionRepository: null);
// Act
var result = await controller.Index(id: null);
// Assert
var redirectToActionResult =
Assert.IsType<RedirectToActionResult>(result);
Assert.Equal("Home", redirectToActionResult.ControllerName);
}
[Fact]
public async Task IndexReturnsContentWithSessionNotFoundWhenSessionNotFound()
{
// Arrange
int testSessionId = 1;
mockRepo.Setup(repo => repo.GetByIdAsync(testSessionId))
.ReturnsAsync((BrainstormSession)null);
var controller = new SessionController(mockRepo.Object);
// Act
var result = await controller.Index(testSessionId);
// Assert
var contentResult = Assert.IsType<ContentResult>(result);
Assert.Equal("Session not found.", contentResult.Content);
}
[Fact]
public async Task IndexReturnsViewResultWithStormSessionViewModel()
{
// Arrange
.ReturnsAsync(GetTestSessions().FirstOrDefault(
s => s.Id == testSessionId));
// Act
// Assert
var model = Assert.IsType<StormSessionViewModel>(
Assert.Equal("Test One", model.Name);
Assert.Equal(2, model.DateCreated.Day);
Assert.Equal(testSessionId, model.Id);
}
Moving to the Ideas controller, the app exposes functionality as a web API on the api/ideas route:
A list of ideas ( IdeaDTO ) associated with a brainstorming session is returned by the ForSession method.
The Create method adds new ideas to a session.
[HttpGet("forsession/{sessionId}")]
public async Task<IActionResult> ForSession(int sessionId)
{
var session = await _sessionRepository.GetByIdAsync(sessionId);
{
return NotFound(sessionId);
}
var result = session.Ideas.Select(idea => new IdeaDTO()

{
Id = idea.Id,
Name = idea.Name,
Description = idea.Description,
DateCreated = idea.DateCreated
}).ToList();
return Ok(result);
}
[HttpPost("create")]
public async Task<IActionResult> Create([FromBody]NewIdeaModel model)
{
{
}
var session = await _sessionRepository.GetByIdAsync(model.SessionId);

{
return NotFound(model.SessionId);
}
var idea = new Idea()

{
Description = model.Description,
Name = model.Name
};
session.AddIdea(idea);
await _sessionRepository.UpdateAsync(session);
return Ok(session);
}
Avoid returning business domain entities directly via API calls. Domain entities:
Often include more data than the client requires.
Unnecessarily couple the app's internal domain model with the publicly exposed API.
Mapping between domain entities and the types returned to the client can be performed:
Manually with a LINQ Select , as the sample app uses. For more information, see LINQ (Language Integrated
Query).
Automatically with a library, such as AutoMapper.
Next, the sample app demonstrates unit tests for the Create and ForSession API methods of the Ideas controller.
The sample app contains two ForSession tests. The first test determines if ForSession returns a
NotFoundObjectResult (HTTP Not Found) for an invalid session:
[Fact]
public async Task ForSession_ReturnsHttpNotFound_ForInvalidSession()
{
// Arrange
var controller = new IdeasController(mockRepo.Object);
// Act
var result = await controller.ForSession(testSessionId);
// Assert
var notFoundObjectResult = Assert.IsType<NotFoundObjectResult>(result);
Assert.Equal(testSessionId, notFoundObjectResult.Value);
}
The second ForSession test determines if ForSession returns a list of session ideas ( <List<IdeaDTO>> ) for a valid
session. The checks also examine the first idea to confirm its Name property is correct:
[Fact]
public async Task ForSession_ReturnsIdeasForSession()
{
// Arrange
.ReturnsAsync(GetTestSession());
// Act
// Assert
var okResult = Assert.IsType<OkObjectResult>(result);
var returnValue = Assert.IsType<List<IdeaDTO>>(okResult.Value);
var idea = returnValue.FirstOrDefault();
Assert.Equal("One", idea.Name);
}
To test the behavior of the Create method when the ModelState is invalid, the sample app adds a model error to
the controller as part of the test. Don't try to test model validation or model binding in unit tests—just test the
action method's behavior when confronted with an invalid ModelState :
[Fact]
public async Task Create_ReturnsBadRequest_GivenInvalidModel()
{
// Arrange & Act
controller.ModelState.AddModelError("error", "some error");
// Act
var result = await controller.Create(model: null);
// Assert
Assert.IsType<BadRequestObjectResult>(result);
}
The second test of Create depends on the repository returning null , so the mock repository is configured to
return null . There's no need to create a test database (in memory or otherwise) and construct a query that returns
this result. The test can be accomplished in a single statement, as the sample code illustrates:
[Fact]
public async Task Create_ReturnsHttpNotFound_ForInvalidSession()
{
// Arrange
// Act
var result = await controller.Create(new NewIdeaModel());
// Assert
Assert.IsType<NotFoundObjectResult>(result);
}
The third Create test, Create_ReturnsNewlyCreatedIdeaForSession , verifies that the repository's UpdateAsync
method is called. The mock is called with Verifiable , and the mocked repository's Verify method is called to
confirm the verifiable method is executed. It's not the unit test's responsibility to ensure that the UpdateAsync
method saved the data—that can be performed with an integration test.
[Fact]
public async Task Create_ReturnsNewlyCreatedIdeaForSession()
{
// Arrange
string testName = "test name";
string testDescription = "test description";
var testSession = GetTestSession();
.ReturnsAsync(testSession);
var newIdea = new NewIdeaModel()

{
Description = testDescription,
Name = testName,
SessionId = testSessionId
};
mockRepo.Setup(repo => repo.UpdateAsync(testSession))
.Verifiable();
// Act
var result = await controller.Create(newIdea);
// Assert
var returnSession = Assert.IsType<BrainstormSession>(okResult.Value);
mockRepo.Verify();
Assert.Equal(2, returnSession.Ideas.Count());
Assert.Equal(testName, returnSession.Ideas.LastOrDefault().Name);
Assert.Equal(testDescription, returnSession.Ideas.LastOrDefault().Description);
}
Test ActionResult<T>
In ASP.NET Core 2.1 or later, ActionResult<T> (ActionResult<TValue>) enables you to return a type deriving from
ActionResult or return a specific type.
The sample app includes a method that returns a List<IdeaDTO> for a given session id . If the session id doesn't
exist, the controller returns NotFound:
[HttpGet("forsessionactionresult/{sessionId}")]
public async Task<ActionResult<List<IdeaDTO>>> ForSessionActionResult(int sessionId)
{
{
}

{
Id = idea.Id,
Name = idea.Name,
}).ToList();
return result;
}
Two tests of the ForSessionActionResult controller are included in the ApiIdeasControllerTests .

The first test confirms that the controller returns an ActionResult but not a nonexistent list of ideas for a
nonexistent session id :
The ActionResult type is ActionResult<List<IdeaDTO>> .
The Result is a NotFoundObjectResult.
[Fact]
public async Task ForSessionActionResult_ReturnsNotFoundObjectResultForNonexistentSession()
{
// Arrange
var nonExistentSessionId = 999;
// Act
var result = await controller.ForSessionActionResult(nonExistentSessionId);
// Assert
var actionResult = Assert.IsType<ActionResult<List<IdeaDTO>>>(result);
Assert.IsType<NotFoundObjectResult>(actionResult.Result);
}
For for a valid session id , the second test confirms that the method returns:
An ActionResult with a List<IdeaDTO> type.
The ActionResult<T>.Value is a List<IdeaDTO> type.
The first item in the list is a valid idea matching the idea stored in the mock session (obtained by calling
GetTestSession ).
[Fact]
public async Task ForSessionActionResult_ReturnsIdeasForSession()
{
// Arrange
// Act
var result = await controller.ForSessionActionResult(testSessionId);
// Assert
var returnValue = Assert.IsType<List<IdeaDTO>>(actionResult.Value);
}
The sample app also includes a method to create a new Idea for a given session. The controller returns:
BadRequest for an invalid model.
NotFound if the session doesn't exist.
CreatedAtAction when the session is updated with the new idea.
[HttpPost("createactionresult")]
public async Task<ActionResult<BrainstormSession>> CreateActionResult([FromBody]NewIdeaModel model)
{
{
}
{
}

{
Name = model.Name
};
return CreatedAtAction(nameof(CreateActionResult), new { id = session.Id }, session);

}
Three tests of CreateActionResult are included in the ApiIdeasControllerTests .

The first text confirms that a BadRequest is returned for an invalid model.
[Fact]
public async Task CreateActionResult_ReturnsBadRequest_GivenInvalidModel()
{
// Arrange & Act
// Act
var result = await controller.CreateActionResult(model: null);
// Assert
var actionResult = Assert.IsType<ActionResult<BrainstormSession>>(result);
Assert.IsType<BadRequestObjectResult>(actionResult.Result);
}
The second test checks that a NotFound is returned if the session doesn't exist.
[Fact]
public async Task CreateActionResult_ReturnsNotFoundObjectResultForNonexistentSession()
{
// Arrange

{
Name = testName,
SessionId = nonExistentSessionId
};
// Act
var result = await controller.CreateActionResult(newIdea);
// Assert
}
For a valid session id , the final test confirms that:

The method returns an ActionResult with a BrainstormSession type.
The ActionResult<T>.Result is a CreatedAtActionResult. CreatedAtActionResult is analogous to a 201 Created
response with a Location header.
The ActionResult<T>.Value is a BrainstormSession type.
The mock call to update the session, UpdateAsync(testSession) , was invoked. The Verifiable method call is
checked by executing mockRepo.Verify() in the assertions.
Two Idea objects are returned for the session.
The last item (the Idea added by the mock call to UpdateAsync ) matches the newIdea added to the session in
the test.
[Fact]
public async Task CreateActionResult_ReturnsNewlyCreatedIdeaForSession()
{
// Arrange

{
Name = testName,
};
.Verifiable();
// Act
// Assert
var createdAtActionResult = Assert.IsType<CreatedAtActionResult>(actionResult.Result);
var returnValue = Assert.IsType<BrainstormSession>(createdAtActionResult.Value);
mockRepo.Verify();
Assert.Equal(2, returnValue.Ideas.Count());
Assert.Equal(testName, returnValue.Ideas.LastOrDefault().Name);
Assert.Equal(testDescription, returnValue.Ideas.LastOrDefault().Description);
}
Integration tests in ASP.NET Core
Create and run unit tests with Visual Studio.
Advanced topics for ASP.NET Core MVC
Work with the application model

Filters
Areas
Application parts
Custom Model Binding
Work with the application model in ASP.NET Core
By Steve Smith
ASP.NET Core MVC defines an application model representing the components of an MVC app. You can read and
manipulate this model to modify how MVC elements behave. By default, MVC follows certain conventions to
determine which classes are considered to be controllers, which methods on those classes are actions, and how
parameters and routing behave. You can customize this behavior to suit your app's needs by creating your own
conventions and applying them globally or as attributes.
Models and Providers

The ASP.NET Core MVC application model include both abstract interfaces and concrete implementation classes
that describe an MVC application. This model is the result of MVC discovering the app's controllers, actions, action
parameters, routes, and filters according to default conventions. By working with the application model, you can
modify your app to follow different conventions from the default MVC behavior. The parameters, names, routes,
and filters are all used as configuration data for actions and controllers.
The ASP.NET Core MVC Application Model has the following structure:
ApplicationModel
Controllers (ControllerModel)
Actions (ActionModel)
Parameters (ParameterModel)
Each level of the model has access to a common Properties collection, and lower levels can access and overwrite
property values set by higher levels in the hierarchy. The properties are persisted to the
ActionDescriptor.Properties when the actions are created. Then when a request is being handled, any properties a
convention added or modified can be accessed through ActionContext.ActionDescriptor.Properties . Using
properties is a great way to configure your filters, model binders, etc. on a per-action basis.
NOTE
The ActionDescriptor.Properties collection isn't thread safe (for writes) once app startup has finished. Conventions are
the best way to safely add data to this collection.
IApplicationModelProvider
ASP.NET Core MVC loads the application model using a provider pattern, defined by the
IApplicationModelProvider interface. This section covers some of the internal implementation details of how this
provider functions. This is an advanced topic - most apps that leverage the application model should do so by
working with conventions.
Implementations of the IApplicationModelProvider interface "wrap" one another, with each implementation calling
OnProvidersExecuting in ascending order based on its Order property. The OnProvidersExecuted method is then
called in reverse order. The framework defines several providers:
First ( Order=-1000 ):
DefaultApplicationModelProvider
Then ( Order=-990 ):
AuthorizationApplicationModelProvider
CorsApplicationModelProvider
NOTE
The order in which two providers with the same value for Order are called is undefined, and therefore shouldn't be relied
upon.
NOTE
IApplicationModelProvider is an advanced concept for framework authors to extend. In general, apps should use
conventions and frameworks should use providers. The key distinction is that providers always run before conventions.
The DefaultApplicationModelProvider establishes many of the default behaviors used by ASP.NET Core MVC. Its
responsibilities include:
Adding global filters to the context
Adding controllers to the context
Adding public controller methods as actions
Adding action method parameters to the context
Applying route and other attributes
Some built-in behaviors are implemented by the DefaultApplicationModelProvider . This provider is responsible for
constructing the ControllerModel , which in turn references ActionModel , PropertyModel , and ParameterModel
instances. The DefaultApplicationModelProvider class is an internal framework implementation detail that can and
will change in the future.
The AuthorizationApplicationModelProvider is responsible for applying the behavior associated with the
AuthorizeFilter and AllowAnonymousFilter attributes. Learn more about these attributes.
The implements behavior associated with the IEnableCorsAttribute and
CorsApplicationModelProvider
IDisableCorsAttribute , and the DisableCorsAuthorizationFilter . Learn more about CORS.
Conventions
The application model defines convention abstractions that provide a simpler way to customize the behavior of the
models than overriding the entire model or provider. These abstractions are the recommended way to modify your
app's behavior. Conventions provide a way for you to write code that will dynamically apply customizations. While
filters provide a means of modifying the framework's behavior, customizations let you control how the whole app
is wired together.
The following conventions are available:
IApplicationModelConvention
IControllerModelConvention
IActionModelConvention
IParameterModelConvention
Conventions are applied by adding them to MVC options or by implementing Attribute s and applying them to
controllers, actions, or action parameters (similar to Filters ). Unlike filters, conventions are only executed when
the app is starting, not as part of each request.
Sample: Modifying the ApplicationModel
The following convention is used to add a property to the application model.
namespace AppModelSample.Conventions
{
public class ApplicationDescription : IApplicationModelConvention
{
private readonly string _description;
public ApplicationDescription(string description)

{
_description = description;
}
public void Apply(ApplicationModel application)

{
application.Properties["description"] = _description;
}
}
}
Application model conventions are applied as options when MVC is added in ConfigureServices in Startup .

{
{
options.Conventions.Add(new ApplicationDescription("My Application Description"));
options.Conventions.Add(new NamespaceRoutingConvention());
//options.Conventions.Add(new IdsMustBeInRouteParameterModelConvention());
});
}
Properties are accessible from the ActionDescriptor properties collection within controller actions:
public class AppModelController : Controller

{
public string Description()
{
return "Description: " + ControllerContext.ActionDescriptor.Properties["description"];
}
}
Sample: Modifying the ControllerModel Description

As in the previous example, the controller model can also be modified to include custom properties. These will
override existing properties with the same name specified in the application model. The following convention
attribute adds a description at the controller level:
using System;
{
public class ControllerDescriptionAttribute : Attribute, IControllerModelConvention
{
public ControllerDescriptionAttribute(string description)

{
}
public void Apply(ControllerModel controllerModel)

{
controllerModel.Properties["description"] = _description;
}
}
}
This convention is applied as an attribute on a controller.
[ControllerDescription("Controller Description")]
public class DescriptionAttributesController : Controller
{
{
}
The "description" property is accessed in the same manner as in previous examples.

Sample: Modifying the ActionModel Description
A separate attribute convention can be applied to individual actions, overriding behavior already applied at the
application or controller level.
using System;
{
public class ActionDescriptionAttribute : Attribute, IActionModelConvention
{
public ActionDescriptionAttribute(string description)

{
}
public void Apply(ActionModel actionModel)

{
actionModel.Properties["description"] = _description;
}
}
}
Applying this to an action within the previous example's controller demonstrates how it overrides the controller-
level convention:
[ControllerDescription("Controller Description")]
public class DescriptionAttributesController : Controller
{
{
}
[ActionDescription("Action Description")]
public string UseActionDescriptionAttribute()
{
}
}
Sample: Modifying the ParameterModel

The following convention can be applied to action parameters to modify their BindingInfo . The following
convention requires that the parameter be a route parameter; other potential binding sources (such as query string
values) are ignored.
using System;
{
public class MustBeInRouteParameterModelConvention : Attribute, IParameterModelConvention
{
public void Apply(ParameterModel model)
{
if (model.BindingInfo == null)
{
model.BindingInfo = new BindingInfo();
}
model.BindingInfo.BindingSource = BindingSource.Path;
}
}
}
The attribute may be applied to any action parameter:
public class ParameterModelController : Controller

{
// Will bind: /ParameterModel/GetById/123
// WON'T bind: /ParameterModel/GetById?id=123
public string GetById([MustBeInRouteParameterModelConvention]int id)
{
return $"Bound to id: {id}";
}
}
Sample: Modifying the ActionModel Name

The following convention modifies the ActionModel to update the name of the action to which it's applied. The
new name is provided as a parameter to the attribute. This new name is used by routing, so it will affect the route
used to reach this action method.
using System;
{
public class CustomActionNameAttribute : Attribute, IActionModelConvention
{
private readonly string _actionName;
public CustomActionNameAttribute(string actionName)

{
_actionName = actionName;
}
public void Apply(ActionModel actionModel)

{
// this name will be used by routing
actionModel.ActionName = _actionName;
}
}
}
This attribute is applied to an action method in the HomeController :
// Route: /Home/MyCoolAction
[CustomActionName("MyCoolAction")]
public string SomeName()
{
return ControllerContext.ActionDescriptor.ActionName;
}
Even though the method name is SomeName , the attribute overrides the MVC convention of using the method
name and replaces the action name with MyCoolAction . Thus, the route used to reach this action is
/Home/MyCoolAction .
NOTE
This example is essentially the same as using the built-in ActionName attribute.
Sample: Custom Routing Convention

You can use an IApplicationModelConvention to customize how routing works. For example, the following
convention will incorporate Controllers' namespaces into their routes, replacing . in the namespace with / in
the route:
using System.Linq;
{
public class NamespaceRoutingConvention : IApplicationModelConvention
{
{
foreach (var controller in application.Controllers)
{
var hasAttributeRouteModels = controller.Selectors
.Any(selector => selector.AttributeRouteModel != null);
if (!hasAttributeRouteModels
&& controller.ControllerName.Contains("Namespace")) // affect one controller in this
sample
{
// Replace the . in the namespace with a / to create the attribute route
// Ex: MySite.Admin namespace will correspond to MySite/Admin attribute route
// Then attach [controller], [action] and optional {id?} token.
// [Controller] and [action] is replaced with the controller and action
// name to generate the final template
controller.Selectors[0].AttributeRouteModel = new AttributeRouteModel()
{
Template = controller.ControllerType.Namespace.Replace('.', '/') +
"/[controller]/[action]/{id?}"
};
}
}
// You can continue to put attribute route templates for the controller actions depending on the
way you want them to behave
}
}
}
The convention is added as an option in Startup.

{
{
options.Conventions.Add(new ApplicationDescription("My Application Description"));
options.Conventions.Add(new NamespaceRoutingConvention());
//options.Conventions.Add(new IdsMustBeInRouteParameterModelConvention());
});
}
TIP
You can add conventions to your middleware by accessing MvcOptions using
services.Configure<MvcOptions>(c => c.Conventions.Add(YOURCONVENTION));
This sample applies this convention to routes that are not using attribute routing where the controller has
"Namespace" in its name. The following controller demonstrates this convention:
namespace AppModelSample.Controllers
{
public class NamespaceRoutingController : Controller
{
// using NamespaceRoutingConvention
// route: /AppModelSample/Controllers/NamespaceRouting/Index
{
return "This demonstrates namespace routing.";
}
}
}
Application Model Usage in WebApiCompatShim

ASP.NET Core MVC uses a different set of conventions from ASP.NET Web API 2. Using custom conventions, you
can modify an ASP.NET Core MVC app's behavior to be consistent with that of a Web API app. Microsoft ships the
WebApiCompatShim specifically for this purpose.
NOTE
Learn more about migration from ASP.NET Web API.
To use the Web API Compatibility Shim, you need to add the package to your project and then add the
conventions to MVC by calling AddWebApiConventions in Startup :
services.AddMvc().AddWebApiConventions();
The conventions provided by the shim are only applied to parts of the app that have had certain attributes applied
to them. The following four attributes are used to control which controllers should have their conventions modified
by the shim's conventions:
UseWebApiActionConventionsAttribute
UseWebApiOverloadingAttribute
UseWebApiParameterConventionsAttribute
UseWebApiRoutesAttribute
Action Conventions
The UseWebApiActionConventionsAttribute is used to map the HTTP method to actions based on their name (for
instance, Get would map to HttpGet ). It only applies to actions that don't use attribute routing.
Overloading
The UseWebApiOverloadingAttribute is used to apply the WebApiOverloadingApplicationModelConvention convention.
This convention adds an OverloadActionConstraint to the action selection process, which limits candidate actions
to those for which the request satisfies all non-optional parameters.
Parameter Conventions
The UseWebApiParameterConventionsAttribute is used to apply the
WebApiParameterConventionsApplicationModelConvention action convention. This convention specifies that simple
types used as action parameters are bound from the URI by default, while complex types are bound from the
request body.
Routes
The UseWebApiRoutesAttribute controls whether the WebApiApplicationModelConvention controller convention is
applied. When enabled, this convention is used to add support for areas to the route.
In addition to a set of conventions, the compatibility package includes a System.Web.Http.ApiController base class
that replaces the one provided by Web API. This allows your controllers written for Web API and inheriting from
its ApiController to work as they were designed, while running on ASP.NET Core MVC. This base controller class
is decorated with all of the UseWebApi* attributes listed above. The ApiController exposes properties, methods,
and result types that are compatible with those found in Web API.
Using ApiExplorer to Document Your App

The application model exposes an ApiExplorer property at each level that can be used to traverse the app's
structure. This can be used to generate help pages for your Web APIs using tools like Swagger. The ApiExplorer
property exposes an IsVisible property that can be set to specify which parts of your app's model should be
exposed. You can configure this setting using a convention:
{
public class EnableApiExplorerApplicationConvention : IApplicationModelConvention
{
{
application.ApiExplorer.IsVisible = true;
}
}
}
Using this approach (and additional conventions if required), you can enable or disable API visibility at any level
within your app.
Filters in ASP.NET Core
By Rick Anderson, Tom Dykstra, and Steve Smith

Filters in ASP.NET Core MVC allow you to run code before or after specific stages in the request processing
pipeline.
IMPORTANT
This topic does not apply to Razor Pages. ASP.NET Core 2.1 and later supports IPageFilter and IAsyncPageFilter for Razor
Pages. For more information, see Filter methods for Razor Pages.
Built-in filters handle tasks such as:

Authorization (preventing access to resources a user isn't authorized for).
Ensuring that all requests use HTTPS.
Response caching (short-circuiting the request pipeline to return a cached response).
Custom filters can be created to handle cross-cutting concerns. Filters can avoid duplicating code across
actions. For example, an error handling exception filter could consolidate error handling.
How do filters work?

Filters run within the MVC action invocation pipeline, sometimes referred to as the filter pipeline. The filter
pipeline runs after MVC selects the action to execute.
Filter types
Each filter type is executed at a different stage in the filter pipeline.
Authorization filters run first and are used to determine whether the current user is authorized for the
current request. They can short-circuit the pipeline if a request is unauthorized.
Resource filters are the first to handle a request after authorization. They can run code before the rest of
the filter pipeline, and after the rest of the pipeline has completed. They're useful to implement caching
or otherwise short-circuit the filter pipeline for performance reasons. They run before model binding, so
they can influence model binding.
Action filters can run code immediately before and after an individual action method is called. They can
be used to manipulate the arguments passed into an action and the result returned from the action.
Exception filters are used to apply global policies to unhandled exceptions that occur before anything
has been written to the response body.
Result filters can run code immediately before and after the execution of individual action results. They
run only when the action method has executed successfully. They are useful for logic that must surround
view or formatter execution.
The following diagram shows how these filter types interact in the filter pipeline.
Implementation
Filters support both synchronous and asynchronous implementations through different interface definitions.
Synchronous filters that can run code both before and after their pipeline stage define OnStageExecuting and
OnStageExecuted methods. For example, OnActionExecuting is called before the action method is called, and
OnActionExecuted is called after the action method returns.
using FiltersSample.Helper;
namespace FiltersSample.Filters
{
public class SampleActionFilter : IActionFilter
{
public void OnActionExecuting(ActionExecutingContext context)
{
// do something before the action executes
}
public void OnActionExecuted(ActionExecutedContext context)

{
// do something after the action executes
}
}
}
Asynchronous filters define a single OnStageExecutionAsync method. This method takes a

FilterTypeExecutionDelegate delegate which executes the filter's pipeline stage. For example,
ActionExecutionDelegate calls the action method or next action filter, and you can execute code before and after
you call it.
{
public class SampleAsyncActionFilter : IAsyncActionFilter
{
public async Task OnActionExecutionAsync(
ActionExecutingContext context,
ActionExecutionDelegate next)
{
var resultContext = await next();
// do something after the action executes; resultContext.Result will be set
}
}
}
You can implement interfaces for multiple filter stages in a single class. For example, the ActionFilterAttribute
class implements IActionFilter , IResultFilter , and their async equivalents.
NOTE
Implement either the synchronous or the async version of a filter interface, not both. The framework checks first to see if
the filter implements the async interface, and if so, it calls that. If not, it calls the synchronous interface's method(s). If you
were to implement both interfaces on one class, only the async method would be called. When using abstract classes like
ActionFilterAttribute you would override only the synchronous methods or the async method for each filter type.
IFilterFactory
IFilterFactory implements IFilterMetadata. Therefore, an IFilterFactory instance can be used as an
IFilterMetadata instance anywhere in the filter pipeline. When the framework prepares to invoke the filter, it
attempts to cast it to an IFilterFactory . If that cast succeeds, the CreateInstance method is called to create the
IFilterMetadata instance that will be invoked. This provides a flexible design, since the precise filter pipeline
doesn't need to be set explicitly when the app starts.
You can implement IFilterFactory on your own attribute implementations as another approach to creating
filters:
public class AddHeaderWithFactoryAttribute : Attribute, IFilterFactory
{
// Implement IFilterFactory
public IFilterMetadata CreateInstance(IServiceProvider serviceProvider)
{
return new InternalAddHeaderFilter();
}
private class InternalAddHeaderFilter : IResultFilter

{
{
"Internal", new string[] { "Header Added" });
}

{
}
}
public bool IsReusable

{
get
{
return false;
}
}
}
Built-in filter attributes

The framework includes built-in attribute-based filters that you can subclass and customize. For example, the
following Result filter adds a header to the response.
{
{
private readonly string _value;
public AddHeaderAttribute(string name, string value)

{
_name = name;
_value = value;
}

{
_name, new string[] { _value });
base.OnResultExecuting(context);
}
}
}
Attributes allow filters to accept arguments, as shown in the example above. You would add this attribute to a
controller or action method and specify the name and value of the HTTP header:
[AddHeader("Author", "Steve Smith @ardalis")]
public class SampleController : Controller
{
{
return Content("Examine the headers using developer tools.");
}
[ShortCircuitingResourceFilter]
public IActionResult SomeResource()
{
return Content("Successful access to resource - header should be set.");
}
The result of the Index action is shown below - the response headers are displayed on the bottom right.
Several of the filter interfaces have corresponding attributes that can be used as base classes for custom
implementations.
Filter attributes:
ActionFilterAttribute
ExceptionFilterAttribute
ResultFilterAttribute
FormatFilterAttribute
ServiceFilterAttribute
TypeFilterAttribute
TypeFilterAttribute and ServiceFilterAttribute are explained later in this article.
Filter scopes and order of execution

A filter can be added to the pipeline at one of three scopes. You can add a filter to a particular action method or
to a controller class by using an attribute. Or you can register a filter globally for all controllers and actions.
Filters are added globally by adding it to the MvcOptions.Filters collection in ConfigureServices :
{
{
options.Filters.Add(new AddHeaderAttribute("GlobalAddHeader",
"Result filter added to MvcOptions.Filters")); // an instance
options.Filters.Add(typeof(SampleActionFilter)); // by type
options.Filters.Add(new SampleGlobalActionFilter()); // an instance
});
services.AddScoped<AddHeaderFilterWithDi>();
}
Default order of execution

When there are multiple filters for a particular stage of the pipeline, scope determines the default order of filter
execution. Global filters surround class filters, which in turn surround method filters. This is sometimes referred
to as "Russian doll" nesting, as each increase in scope is wrapped around the previous scope, like a nesting doll.
You generally get the desired overriding behavior without having to explicitly determine ordering.
As a result of this nesting, the after code of filters runs in the reverse order of the before code. The sequence
looks like this:
The before code of filters applied globally
The before code of filters applied to controllers
The before code of filters applied to action methods
The after code of filters applied to action methods
The after code of filters applied to controllers
The after code of filters applied globally
Here's an example that illustrates the order in which filter methods are called for synchronous Action filters.
SEQUENCE FILTER SCOPE FILTER METHOD
1 Global OnActionExecuting
2 Controller OnActionExecuting
3 Method OnActionExecuting
4 Method OnActionExecuted
5 Controller OnActionExecuted
6 Global OnActionExecuted
This sequence shows:

The method filter is nested within the controller filter.
The controller filter is nested within the global filter.
To put it another way, if you're inside an async filter's OnStageExecutionAsync method, all of the filters with a
tighter scope run while your code is on the stack.
NOTE
Every controller that inherits from the Controller base class includes OnActionExecuting and OnActionExecuted
methods. These methods wrap the filters that run for a given action: OnActionExecuting is called before any of the
filters, and OnActionExecuted is called after all of the filters.
Overriding the default order

You can override the default sequence of execution by implementing IOrderedFilter . This interface exposes an
Order property that takes precedence over scope to determine the order of execution. A filter with a lower
Order value will have its before code executed before that of a filter with a higher value of Order . A filter with
a lower Order value will have its after code executed after that of a filter with a higher Order value. You can
set the Order property by using a constructor parameter:
[MyFilter(Name = "Controller Level Attribute", Order=1)]
If you have the same 3 Action filters shown in the preceding example but set the Order property of the
controller and global filters to 1 and 2 respectively, the order of execution would be reversed.
SEQUENCE FILTER SCOPE ORDER PROPERTY FILTER METHOD
1 Method 0 OnActionExecuting
2 Controller 1 OnActionExecuting
3 Global 2 OnActionExecuting
4 Global 2 OnActionExecuted
5 Controller 1 OnActionExecuted
6 Method 0 OnActionExecuted
The Order property trumps scope when determining the order in which filters will run. Filters are sorted first
by order, then scope is used to break ties. All of the built-in filters implement IOrderedFilter and set the
default Order value to 0. For built-in filters, scope determines order unless you set Order to a non-zero value.
Cancellation and short circuiting

You can short-circuit the filter pipeline at any point by setting the Result property on the context parameter
provided to the filter method. For instance, the following Resource filter prevents the rest of the pipeline from
executing.
using System;
{
public class ShortCircuitingResourceFilterAttribute : Attribute,
IResourceFilter
{
public void OnResourceExecuting(ResourceExecutingContext context)
{
context.Result = new ContentResult()
{
Content = "Resource unavailable - header should not be set"
};
}
public void OnResourceExecuted(ResourceExecutedContext context)

{
}
}
}
In the following code, both the ShortCircuitingResourceFilter and the AddHeader filter target the
SomeResource action method. The ShortCircuitingResourceFilter :
Runs first, because it's a Resource Filter and AddHeader is an Action Filter.
Short-circuits the rest of the pipeline.
Therefore the AddHeader filter never runs for the SomeResource action. This behavior would be the same if both
filters were applied at the action method level, provided the ShortCircuitingResourceFilter ran first. The
ShortCircuitingResourceFilter runs first because of its filter type, or by explicit use of Order property.
[AddHeader("Author", "Steve Smith @ardalis")]

public class SampleController : Controller
{
{
return Content("Examine the headers using developer tools.");
}
[ShortCircuitingResourceFilter]
public IActionResult SomeResource()
{
return Content("Successful access to resource - header should be set.");
}
Filters can be added by type or by instance. If you add an instance, that instance will be used for every request.
If you add a type, it will be type-activated, meaning an instance will be created for each request and any
constructor dependencies will be populated by dependency injection (DI). Adding a filter by type is equivalent
to filters.Add(new TypeFilterAttribute(typeof(MyFilter))) .
Filters that are implemented as attributes and added directly to controller classes or action methods cannot
have constructor dependencies provided by dependency injection (DI). This is because attributes must have
their constructor parameters supplied where they're applied. This is a limitation of how attributes work.
If your filters have dependencies that you need to access from DI, there are several supported approaches. You
can apply your filter to a class or action method using one of the following:
TypeFilterAttribute
IFilterFactory implemented on your attribute
NOTE
One dependency you might want to get from DI is a logger. However, avoid creating and using filters purely for logging
purposes, since the built-in framework logging features may already provide what you need. If you're going to add
logging to your filters, it should focus on business domain concerns or behavior specific to your filter, rather than MVC
actions or other framework events.
A ServiceFilter retrieves an instance of the filter from DI. You add the filter to the container in
ConfigureServices , and reference it in a ServiceFilter attribute

{
{
options.Filters.Add(new AddHeaderAttribute("GlobalAddHeader",
"Result filter added to MvcOptions.Filters")); // an instance
options.Filters.Add(typeof(SampleActionFilter)); // by type
options.Filters.Add(new SampleGlobalActionFilter()); // an instance
});
services.AddScoped<AddHeaderFilterWithDi>();
}
[ServiceFilter(typeof(AddHeaderFilterWithDi))]
{
return View();
}
Using ServiceFilter without registering the filter type results in an exception:
System.InvalidOperationException: No service for type

'FiltersSample.Filters.AddHeaderFilterWithDI' has been registered.
ServiceFilterAttribute implements IFilterFactory . IFilterFactory exposes the CreateInstance method for

creating an IFilterMetadata instance. The CreateInstance method loads the specified type from the services
container (DI).
TypeFilterAttribute
TypeFilterAttribute is similar to ServiceFilterAttribute , but its type isn't resolved directly from the DI
container. It instantiates the type by using Microsoft.Extensions.DependencyInjection.ObjectFactory .
Because of this difference:
Types that are referenced using the TypeFilterAttribute don't need to be registered with the container first.
They do have their dependencies fulfilled by the container.
TypeFilterAttribute can optionally accept constructor arguments for the type.
The following example demonstrates how to pass arguments to a type using TypeFilterAttribute :
[TypeFilter(typeof(AddHeaderAttribute),
Arguments = new object[] { "Author", "Steve Smith (@ardalis)" })]
public IActionResult Hi(string name)
{
return Content($"Hi {name}");
}
IFilterFactory implemented on your attribute

If you have a filter that:
Doesn't require any arguments.
Has constructor dependencies that need to be filled by DI.
You can use your own named attribute on classes and methods instead of [TypeFilter(typeof(FilterType))] ).
The following filter shows how this can be implemented:
public class SampleActionFilterAttribute : TypeFilterAttribute

{
public SampleActionFilterAttribute():base(typeof(SampleActionFilterImpl))
{
}
private class SampleActionFilterImpl : IActionFilter

{
public SampleActionFilterImpl(ILoggerFactory loggerFactory)
{
_logger = loggerFactory.CreateLogger<SampleActionFilterAttribute>();
}

{
_logger.LogInformation("Business action starting...");
// perform some business logic work

{
// perform some business logic work
_logger.LogInformation("Business action completed.");
}
}
}
This filter can be applied to classes or methods using the [SampleActionFilter] syntax, instead of having to use
[TypeFilter] or [ServiceFilter] .
Authorization filters
*Authorization filters:
Control access to action methods.
Are the first filters to be executed within the filter pipeline.
Have a before method, but no after method.
You should only write a custom authorization filter if you are writing your own authorization framework. Prefer
configuring your authorization policies or writing a custom authorization policy over writing a custom filter.
The built-in filter implementation is just responsible for calling the authorization system.
You shouldn't throw exceptions within authorization filters, since nothing will handle the exception (exception
filters won't handle them). Consider issuing a challenge when an exception occurs.
Learn more about Authorization.
Resource filters
Implement either the IResourceFilter or IAsyncResourceFilter interface,
Their execution wraps most of the filter pipeline.
Only Authorization filters run before Resource filters.
Resource filters are useful to short-circuit most of the work a request is doing. For example, a caching filter can
avoid the rest of the pipeline if the response is in the cache.
The short circuiting resource filter shown earlier is one example of a resource filter. Another example is
DisableFormValueModelBindingAttribute:
It prevents model binding from accessing the form data.
It's useful for large file uploads and want to prevent the form from being read into memory.
Action filters
Action filters:
Implement either the IActionFilter or IAsyncActionFilter interface.
Their execution surrounds the execution of action methods.
Here's a sample action filter:
public class SampleActionFilter : IActionFilter

{
{
}

{
// do something after the action executes
}
}
The ActionExecutingContext provides the following properties:

ActionArguments - lets you manipulate the inputs to the action.
Controller - lets you manipulate the controller instance.
Result - setting this short-circuits execution of the action method and subsequent action filters. Throwing
an exception also prevents execution of the action method and subsequent filters, but is treated as a failure
instead of a successful result.
The ActionExecutedContext provides Controller and Result plus the following properties:
Canceled - will be true if the action execution was short-circuited by another filter.
Exception - will be non-null if the action or a subsequent action filter threw an exception. Setting this
property to null effectively 'handles' an exception, and Result will be executed as if it were returned from
the action method normally.
For an IAsyncActionFilter , a call to the ActionExecutionDelegate :
Executes any subsequent action filters and the action method.
returns ActionExecutedContext .
To short-circuit, assign ActionExecutingContext.Result to some result instance and don't call the
ActionExecutionDelegate .
The framework provides an abstract ActionFilterAttribute that you can subclass.
You can use an action filter to validate model state and return any errors if the state is invalid:
{
public class ValidateModelAttribute : ActionFilterAttribute
{
public override void OnActionExecuting(ActionExecutingContext context)
{
if (!context.ModelState.IsValid)
{
context.Result = new BadRequestObjectResult(context.ModelState);
}
}
}
}
The OnActionExecuted method runs after the action method and can see and manipulate the results of the
action through the ActionExecutedContext.Result property. ActionExecutedContext.Canceled will be set to true
if the action execution was short-circuited by another filter. ActionExecutedContext.Exception will be set to a
non-null value if the action or a subsequent action filter threw an exception. Setting
ActionExecutedContext.Exception to null:
Effectively 'handles' an exception.

ActionExectedContext.Result is executed as if it were returned normally from the action method.
Exception filters
Exception filters implement either the IExceptionFilter or IAsyncExceptionFilter interface. They can be used
to implement common error handling policies for an app.
The following sample exception filter uses a custom developer error view to display details about exceptions
that occur when the app is in development:
public class CustomExceptionFilterAttribute : ExceptionFilterAttribute
{
private readonly IHostingEnvironment _hostingEnvironment;
private readonly IModelMetadataProvider _modelMetadataProvider;
public CustomExceptionFilterAttribute(
IHostingEnvironment hostingEnvironment,
IModelMetadataProvider modelMetadataProvider)
{
_hostingEnvironment = hostingEnvironment;
_modelMetadataProvider = modelMetadataProvider;
}
public override void OnException(ExceptionContext context)

{
if (!_hostingEnvironment.IsDevelopment())
{
// do nothing
return;
}
var result = new ViewResult {ViewName = "CustomError"};
result.ViewData = new ViewDataDictionary(_modelMetadataProvider,context.ModelState);
result.ViewData.Add("Exception", context.Exception);
// TODO: Pass additional detailed data via ViewData
context.Result = result;
}
}
Exception filters:
Don't have before and after events.
Implement OnException or OnExceptionAsync .
Handle unhandled exceptions that occur in controller creation, model binding, action filters, or action
methods.
Do not catch exceptions that occur in Resource filters, Result filters, or MVC Result execution.
To handle an exception, set the ExceptionContext.ExceptionHandled property to true or write a response. This
stops propagation of the exception. An Exception filter can't turn an exception into a "success". Only an Action
filter can do that.
NOTE
In ASP.NET Core 1.1, the response isn't sent if you set ExceptionHandled to true and write a response. In that
scenario, ASP.NET Core 1.0 does send the response, and ASP.NET Core 1.1.2 will return to the 1.0 behavior. For more
information, see issue #5594 in the GitHub repository.
Exception filters:
Are good for trapping exceptions that occur within MVC actions.
Are not as flexible as error handling middleware.
Prefer middleware for exception handling. Use exception filters only where you need to do error handling
differently based on which MVC action was chosen. For example, your app might have action methods for both
API endpoints and for views/HTML. The API endpoints could return error information as JSON, while the
view -based actions could return an error page as HTML.
The ExceptionFilterAttribute can be subclassed.
Result filters
Implement either the IResultFilter or IAsyncResultFilter interface.
Their execution surrounds the execution of action results.
Here's an example of a Result filter that adds an HTTP header.
public class AddHeaderFilterWithDi : IResultFilter

{
private ILogger _logger;
public AddHeaderFilterWithDi(ILoggerFactory loggerFactory)
{
_logger = loggerFactory.CreateLogger<AddHeaderFilterWithDi>();
}

{
var headerName = "OnResultExecuting";
headerName, new string[] { "ResultExecutingSuccessfully" });
_logger.LogInformation($"Header added: {headerName}");
}

{
// Can't add to headers here because response has already begun.
}
}
The kind of result being executed depends on the action in question. An MVC action returning a view would
include all razor processing as part of the ViewResult being executed. An API method might perform some
serialization as part of the execution of the result. Learn more about action results
Result filters are only executed for successful results - when the action or action filters produce an action result.
Result filters are not executed when exception filters handle an exception.
The OnResultExecuting method can short-circuit execution of the action result and subsequent result filters by
setting ResultExecutingContext.Cancel to true. You should generally write to the response object when short-
circuiting to avoid generating an empty response. Throwing an exception will:
Prevent execution of the action result and subsequent filters.
Be treated as a failure instead of a successful result.
When the OnResultExecuted method runs, the response has likely been sent to the client and cannot be
changed further (unless an exception was thrown). ResultExecutedContext.Canceled will be set to true if the
action result execution was short-circuited by another filter.
ResultExecutedContext.Exception will be set to a non-null value if the action result or a subsequent result filter
threw an exception. Setting Exception to null effectively 'handles' an exception and prevents the exception
from being rethrown by MVC later in the pipeline. When you're handling an exception in a result filter, you
might not be able to write any data to the response. If the action result throws partway through its execution,
and the headers have already been flushed to the client, there's no reliable mechanism to send a failure code.
For an IAsyncResultFilter a call to await next on the ResultExecutionDelegate executes any subsequent
result filters and the action result. To short-circuit, set ResultExecutingContext.Cancel to true and don't call the
ResultExectionDelegate .
The framework provides an abstract ResultFilterAttribute that you can subclass. The AddHeaderAttribute
class shown earlier is an example of a result filter attribute.
Using middleware in the filter pipeline
Resource filters work like middleware in that they surround the execution of everything that comes later in the
pipeline. But filters differ from middleware in that they're part of MVC, which means that they have access to
MVC context and constructs.
In ASP.NET Core 1.1, you can use middleware in the filter pipeline. You might want to do that if you have a
middleware component that needs access to MVC route data, or one that should run only for certain
controllers or actions.
To use middleware as a filter, create a type with a Configure method that specifies the middleware that you
want to inject into the filter pipeline. Here's an example that uses the localization middleware to establish the
current culture for a request:
public class LocalizationPipeline

{
public void Configure(IApplicationBuilder applicationBuilder)
{
{
};
var options = new RequestLocalizationOptions

{
DefaultRequestCulture = new RequestCulture(culture: "en-US", uiCulture: "en-US"),

SupportedCultures = supportedCultures,
SupportedUICultures = supportedCultures
};
options.RequestCultureProviders = new[]
{ new RouteDataRequestCultureProvider() { Options = options } };
applicationBuilder.UseRequestLocalization(options);
}
}
You can then use the MiddlewareFilterAttribute to run the middleware for a selected controller or action or
globally:
[Route("{culture}/[controller]/[action]")]
[MiddlewareFilter(typeof(LocalizationPipeline))]
public IActionResult CultureFromRouteData()
{
return Content($"CurrentCulture:{CultureInfo.CurrentCulture.Name},"
+ $"CurrentUICulture:{CultureInfo.CurrentUICulture.Name}");
}
Middleware filters run at the same stage of the filter pipeline as Resource filters, before model binding and
after the rest of the pipeline.
Next actions
To experiment with filters, download, test and modify the sample.
By Dhananjay Kumar and Rick Anderson

Areas are an ASP.NET MVC feature used to organize related functionality into a group as a separate namespace
(for routing) and folder structure (for views). Using areas creates a hierarchy for the purpose of routing by
adding another route parameter, area , to controller and action .
Areas provide a way to partition a large ASP.NET Core MVC Web app into smaller functional groupings. An
area is effectively an MVC structure inside an application. In an MVC project, logical components like Model,
Controller, and View are kept in different folders, and MVC uses naming conventions to create the relationship
between these components. For a large app, it may be advantageous to partition the app into separate high level
areas of functionality. For instance, an e-commerce app with multiple business units, such as checkout, billing,
and search etc. Each of these units have their own logical component views, controllers, and models. In this
scenario, you can use Areas to physically partition the business components in the same project.
An area can be defined as smaller functional units in an ASP.NET Core MVC project with its own set of
controllers, views, and models.
Consider using Areas in an MVC project when:
Your application is made of multiple high-level functional components that should be logically separated
You want to partition your MVC project so that each functional area can be worked on independently
Area features:
An ASP.NET Core MVC app can have any number of areas.
Each area has its own controllers, models, and views.
Areas allow you to organize large MVC projects into multiple high-level components that can be worked
on independently.
Areas support multiple controllers with the same name, as long as they have different areas.
Let's take a look at an example to illustrate how Areas are created and used. Let's say you have a store app that
has two distinct groupings of controllers and views: Products and Services. A typical folder structure for that
using MVC areas looks like below:
Project name
Areas
Products
Controllers
HomeController.cs
ManageController.cs
Views
Home
Index.cshtml
Manage
Index.cshtml
Services
Controllers
HomeController.cs
Views
Home
Index.cshtml
When MVC tries to render a view in an Area, by default, it tries to look in the following locations:
/Areas/<Area-Name>/Views/<Controller-Name>/<Action-Name>.cshtml
/Areas/<Area-Name>/Views/Shared/<Action-Name>.cshtml
/Views/Shared/<Action-Name>.cshtml
These are the default locations which can be changed via the AreaViewLocationFormats on the
Microsoft.AspNetCore.Mvc.Razor.RazorViewEngineOptions .
For example, in the below code instead of having the folder name as 'Areas', it has been changed to 'Categories'.
services.Configure<RazorViewEngineOptions>(options =>
{
options.AreaViewLocationFormats.Clear();
options.AreaViewLocationFormats.Add("/Categories/{2}/Views/{1}/{0}.cshtml");
options.AreaViewLocationFormats.Add("/Categories/{2}/Views/Shared/{0}.cshtml");
options.AreaViewLocationFormats.Add("/Views/Shared/{0}.cshtml");
});
One thing to note is that the structure of the Views folder is the only one which is considered important here and
the content of the rest of the folders like Controllers and Models does not matter. For example, you need not
have a Controllers and Models folder at all. This works because the content of Controllers and Models is just code
which gets compiled into a .dll where as the content of the Views isn't until a request to that view has been made.
Once you've defined the folder hierarchy, you need to tell MVC that each controller is associated with an area.
You do that by decorating the controller name with the [Area] attribute.
...
namespace MyStore.Areas.Products.Controllers
{
[Area("Products")]
{
// GET: /Products/Home/Index
{
return View();
}
// GET: /Products/Home/Create
{
return View();
}
}
}
Set up a route definition that works with your newly created areas. The Route to controller actions article goes
into detail about how to create route definitions, including using conventional routes versus attribute routes. In
this example, we'll use a conventional route. To do so, open the Startup.cs file and modify it by adding the
areaRoute named route definition below.
...
{
routes.MapRoute(
name: "areaRoute",
template: "{area:exists}/{controller=Home}/{action=Index}/{id?}");
routes.MapRoute(
name: "default",
});
Browsing to http://<yourApp>/products , the Index action method of the HomeController in the Products area
will be invoked.
Link Generation
Generating links from an action within an area based controller to another action within the same
controller.
Let's say the current request's path is like /Products/Home/Create
HtmlHelper syntax: @Html.ActionLink("Go to Product's Home Page", "Index")
TagHelper syntax: <a asp-action="Index">Go to Product's Home Page</a>
Note that we need not supply the 'area' and 'controller' values here as they're already available in the
context of the current request. These kind of values are called ambient values.
Generating links from an action within an area based controller to another action on a different controller
HtmlHelper syntax: @Html.ActionLink("Go to Manage Products Home Page", "Index", "Manage")
TagHelper syntax: <a asp-controller="Manage" asp-action="Index">Go to Manage Products Home Page</a>

Note that here the ambient value of an 'area' is used but the 'controller' value is specified explicitly above.
and a different area.
HtmlHelper syntax:
@Html.ActionLink("Go to Services Home Page", "Index", "Home", new { area = "Services" })
TagHelper syntax:
<a asp-area="Services" asp-controller="Home" asp-action="Index">Go to Services Home Page</a>
Note that here no ambient values are used.

and not in an area.
HtmlHelper syntax:
@Html.ActionLink("Go to Manage Products Home Page", "Index", "Home", new { area = "" })
TagHelper syntax:
<a asp-area="" asp-controller="Manage" asp-action="Index">Go to Manage Products Home Page</a>
Since we want to generate links to a non-area based controller action, we empty the ambient value for
'area' here.
Publishing Areas
All *.cshtml and wwwroot/** files are published to output when <Project Sdk="Microsoft.NET.Sdk.Web"> is
included in the .csproj file.
Application Parts in ASP.NET Core

An Application Part is an abstraction over the resources of an application, from which MVC features like
controllers, view components, or tag helpers may be discovered. One example of an application part is an
AssemblyPart, which encapsulates an assembly reference and exposes types and compilation references. Feature
providers work with application parts to populate the features of an ASP.NET Core MVC app. The main use case
for application parts is to allow you to configure your app to discover (or avoid loading) MVC features from an
assembly.
Introducing Application Parts

MVC apps load their features from application parts. In particular, the AssemblyPart class represents an application
part that's backed by an assembly. You can use these classes to discover and load MVC features, such as
controllers, view components, tag helpers, and razor compilation sources. The ApplicationPartManager is
responsible for tracking the application parts and feature providers available to the MVC app. You can interact with
the ApplicationPartManager in Startup when you configure MVC:
// create an assembly part from a class's assembly

var assembly = typeof(Startup).GetTypeInfo().Assembly;
services.AddMvc()
.AddApplicationPart(assembly);
// OR
var assembly = typeof(Startup).GetTypeInfo().Assembly;
var part = new AssemblyPart(assembly);
services.AddMvc()
.ConfigureApplicationPartManager(apm => apm.ApplicationParts.Add(part));
By default MVC will search the dependency tree and find controllers (even in other assemblies). To load an
arbitrary assembly (for instance, from a plugin that isn't referenced at compile time), you can use an application
part.
You can use application parts to avoid looking for controllers in a particular assembly or location. You can control
which parts (or assemblies) are available to the app by modifying the ApplicationParts collection of the
ApplicationPartManager . The order of the entries in the ApplicationParts collection isn't important. It's important
to fully configure the ApplicationPartManager before using it to configure services in the container. For example,
you should fully configure the ApplicationPartManager before invoking AddControllersAsServices . Failing to do so,
will mean that controllers in application parts added after that method call won't be affected (won't get registered
as services) which might result in incorrect behavior of your application.
If you have an assembly that contains controllers you don't want to be used, remove it from the
ApplicationPartManager :
services.AddMvc()
.ConfigureApplicationPartManager(apm =>
{
var dependentLibrary = apm.ApplicationParts
.FirstOrDefault(part => part.Name == "DependentLibrary");
if (dependentLibrary != null)
{
apm.ApplicationParts.Remove(dependentLibrary);
}
})
In addition to your project's assembly and its dependent assemblies, the ApplicationPartManager will include parts
for Microsoft.AspNetCore.Mvc.TagHelpers and Microsoft.AspNetCore.Mvc.Razor by default.
Application Feature Providers

Application Feature Providers examine application parts and provide features for those parts. There are built-in
feature providers for the following MVC features:
Controllers
Metadata Reference
Tag Helpers
View Components
Feature providers inherit from IApplicationFeatureProvider<T> , where T is the type of the feature. You can
implement your own feature providers for any of MVC's feature types listed above. The order of feature providers
in the ApplicationPartManager.FeatureProviders collection can be important, since later providers can react to
actions taken by previous providers.
Sample: Generic controller feature
By default, ASP.NET Core MVC ignores generic controllers (for example, SomeController<T> ). This sample uses a
controller feature provider that runs after the default provider and adds generic controller instances for a specified
list of types (defined in EntityTypes.Types ):
public class GenericControllerFeatureProvider : IApplicationFeatureProvider<ControllerFeature>

{
public void PopulateFeature(IEnumerable<ApplicationPart> parts, ControllerFeature feature)
{
// This is designed to run after the default ControllerTypeProvider,
// so the list of 'real' controllers has already been populated.
foreach (var entityType in EntityTypes.Types)
{
var typeName = entityType.Name + "Controller";
if (!feature.Controllers.Any(t => t.Name == typeName))
{
// There's no 'real' controller for this entity, so add the generic version.
var controllerType = typeof(GenericController<>)
.MakeGenericType(entityType.AsType()).GetTypeInfo();
feature.Controllers.Add(controllerType);
}
}
}
}
The entity types:

public static class EntityTypes
{
public static IReadOnlyList<TypeInfo> Types => new List<TypeInfo>()
{
typeof(Sprocket).GetTypeInfo(),
typeof(Widget).GetTypeInfo(),
};
public class Sprocket { }

public class Widget { }
}
The feature provider is added in Startup :
services.AddMvc()
.ConfigureApplicationPartManager(apm =>
apm.FeatureProviders.Add(new GenericControllerFeatureProvider()));
By default, the generic controller names used for routing would be of the form GenericController`1 [Widget]
instead of Widget. The following attribute is used to modify the name to correspond to the generic type used by
the controller:
using System;
namespace AppPartsSample
{
// Used to set the controller name for routing purposes. Without this convention the
// names would be like 'GenericController`1[Widget]' instead of 'Widget'.
//
// Conventions can be applied as attributes or added to MvcOptions.Conventions.
[AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = true)]
public class GenericControllerNameConvention : Attribute, IControllerModelConvention
{
public void Apply(ControllerModel controller)
{
if (controller.ControllerType.GetGenericTypeDefinition() !=
typeof(GenericController<>))
{
// Not a GenericController, ignore.
return;
}
var entityType = controller.ControllerType.GenericTypeArguments[0];

controller.ControllerName = entityType.Name;
}
}
}
The GenericController class:

namespace AppPartsSample
{
[GenericControllerNameConvention] // Sets the controller name based on typeof(T).Name
public class GenericController<T> : Controller
{
{
return Content($"Hello from a generic {typeof(T).Name} controller.");
}
}
}
The result, when a matching route is requested:
Sample: Display available features

You can iterate through the populated features available to your app by requesting an ApplicationPartManager
through dependency injection and using it to populate instances of the appropriate features:
using AppPartsSample.ViewModels;
using Microsoft.AspNetCore.Mvc.ApplicationParts;
using Microsoft.AspNetCore.Mvc.Controllers;
using System.Linq;
using Microsoft.AspNetCore.Mvc.Razor.Compilation;
using Microsoft.AspNetCore.Mvc.ViewComponents;
namespace AppPartsSample.Controllers
{
public class FeaturesController : Controller
{
private readonly ApplicationPartManager _partManager;
public FeaturesController(ApplicationPartManager partManager)

{
_partManager = partManager;
}

{
var viewModel = new FeaturesViewModel();
var controllerFeature = new ControllerFeature();

_partManager.PopulateFeature(controllerFeature);
viewModel.Controllers = controllerFeature.Controllers.ToList();
var metaDataReferenceFeature = new MetadataReferenceFeature();

_partManager.PopulateFeature(metaDataReferenceFeature);
viewModel.MetadataReferences = metaDataReferenceFeature.MetadataReferences
.ToList();
var tagHelperFeature = new TagHelperFeature();

_partManager.PopulateFeature(tagHelperFeature);
viewModel.TagHelpers = tagHelperFeature.TagHelpers.ToList();
var viewComponentFeature = new ViewComponentFeature();

_partManager.PopulateFeature(viewComponentFeature);
viewModel.ViewComponents = viewComponentFeature.ViewComponents.ToList();
}
}
}
Example output:
Custom Model Binding in ASP.NET Core
By Steve Smith
Model binding allows controller actions to work directly with model types (passed in as method arguments), rather
than HTTP requests. Mapping between incoming request data and application models is handled by model
binders. Developers can extend the built-in model binding functionality by implementing custom model binders
(though typically, you don't need to write your own provider).
View or download sample from GitHub
Default model binder limitations

The default model binders support most of the common .NET Core data types and should meet most developers`
needs. They expect to bind text-based input from the request directly to model types. You might need to transform
the input prior to binding it. For example, when you have a key that can be used to look up model data. You can
use a custom model binder to fetch data based on the key.
Model binding review

Model binding uses specific definitions for the types it operates on. A simple type is converted from a single string
in the input. A complex type is converted from multiple input values. The framework determines the difference
based on the existence of a TypeConverter . We recommended you create a type converter if you have a simple
string -> SomeType mapping that doesn't require external resources.
Before creating your own custom model binder, it's worth reviewing how existing model binders are implemented.
Consider the ByteArrayModelBinder which can be used to convert base64-encoded strings into byte arrays. The
byte arrays are often stored as files or database BLOB fields.
Working with the ByteArrayModelBinder
Base64-encoded strings can be used to represent binary data. For example, the following image can be encoded as
a string.
A small portion of the encoded string is shown in the following image:

Follow the instructions in the sample's README to convert the base64-encoded string into a file.
ASP.NET Core MVC can take a base64-encoded strings and use a ByteArrayModelBinder to convert it into a byte
array. The ByteArrayModelBinderProvider which implements IModelBinderProvider maps byte[] arguments to
ByteArrayModelBinder :
public IModelBinder GetBinder(ModelBinderProviderContext context)

{
{
}
if (context.Metadata.ModelType == typeof(byte[]))
{
return new ByteArrayModelBinder();
}
return null;
}
When creating your own custom model binder, you can implement your own IModelBinderProvider type, or use
the ModelBinderAttribute.
The following example shows how to use ByteArrayModelBinder to convert a base64-encoded string to a byte[]
and save the result to a file:
// POST: api/image
[HttpPost]
public void Post(byte[] file, string filename)
{
string filePath = Path.Combine(_env.ContentRootPath, "wwwroot/images/upload", filename);
if (System.IO.File.Exists(filePath)) return;
System.IO.File.WriteAllBytes(filePath, file);
}
You can POST a base64-encoded string to this api method using a tool like Postman:
As long as the binder can bind request data to appropriately named properties or arguments, model binding will
succeed. The following example shows how to use ByteArrayModelBinder with a view model:
[HttpPost("Profile")]
public void SaveProfile(ProfileViewModel model)
{
string filePath = Path.Combine(_env.ContentRootPath, "wwwroot/images/upload", model.FileName);
if (System.IO.File.Exists(model.FileName)) return;
System.IO.File.WriteAllBytes(filePath, model.File);
}
public class ProfileViewModel

{
public byte[] File { get; set; }
public string FileName { get; set; }
}
Custom model binder sample

In this section we'll implement a custom model binder that:
Converts incoming request data into strongly typed key arguments.
Uses Entity Framework Core to fetch the associated entity.
Passes the associated entity as an argument to the action method.
The following sample uses the ModelBinder attribute on the Author model:
using CustomModelBindingSample.Binders;
using System;
using System.Linq;
namespace CustomModelBindingSample.Data
{
[ModelBinder(BinderType = typeof(AuthorEntityBinder))]
public class Author
{
public string GitHub { get; set; }
public string Twitter { get; set; }
public string BlogUrl { get; set; }
}
}
In the preceding code, the ModelBinder attribute specifies the type of IModelBinder that should be used to bind
Author action parameters.
The AuthorEntityBinder is used to bind an Author parameter by fetching the entity from a data source using
Entity Framework Core and an authorId :
public class AuthorEntityBinder : IModelBinder
{
public AuthorEntityBinder(AppDbContext db)
{
_db = db;
}
public Task BindModelAsync(ModelBindingContext bindingContext)

{
if (bindingContext == null)
{
throw new ArgumentNullException(nameof(bindingContext));
}
// Specify a default argument name if none is set by ModelBinderAttribute

var modelName = bindingContext.BinderModelName;
if (string.IsNullOrEmpty(modelName))
{
modelName = "authorId";
}
// Try to fetch the value of the argument by name

var valueProviderResult =
bindingContext.ValueProvider.GetValue(modelName);
if (valueProviderResult == ValueProviderResult.None)
{
}
bindingContext.ModelState.SetModelValue(modelName,
valueProviderResult);
var value = valueProviderResult.FirstValue;
// Check if the argument value is null or empty

if (string.IsNullOrEmpty(value))
{
}
int id = 0;
if (!int.TryParse(value, out id))
{
// Non-integer arguments result in model state errors
bindingContext.ModelState.TryAddModelError(
bindingContext.ModelName,
"Author Id must be an integer.");
}
// Model will be null if not found, including for

// out of range id values (0, -3, etc.)
var model = _db.Authors.Find(id);
bindingContext.Result = ModelBindingResult.Success(model);
}
}
The following code shows how to use the AuthorEntityBinder in an action method:
[HttpGet("get/{authorId}")]
public IActionResult Get(Author author)
{
return Ok(author);
}
The ModelBinder attribute can be used to apply the AuthorEntityBinder to parameters that don't use default
conventions:
[HttpGet("{id}")]
public IActionResult GetById([ModelBinder(Name = "id")]Author author)
{
if (author == null)
{
return NotFound();
}
{
}
return Ok(author);
}
In this example, since the name of the argument isn't the default authorId , it's specified on the parameter using
ModelBinder attribute. Note that both the controller and action method are simplified compared to looking up the
entity in the action method. The logic to fetch the author using Entity Framework Core is moved to the model
binder. This can be considerable simplification when you have several methods that bind to the author model, and
can help you to follow the DRY principle.
You can apply the ModelBinder attribute to individual model properties (such as on a viewmodel) or to action
method parameters to specify a certain model binder or model name for just that type or action.
Implementing a ModelBinderProvider
Instead of applying an attribute, you can implement IModelBinderProvider . This is how the built-in framework
binders are implemented. When you specify the type your binder operates on, you specify the type of argument it
produces, not the input your binder accepts. The following binder provider works with the AuthorEntityBinder .
When it's added to MVC's collection of providers, you don't need to use the ModelBinder attribute on Author or
Author typed parameters.
using CustomModelBindingSample.Data;
using Microsoft.AspNetCore.Mvc.ModelBinding.Binders;
using System;
namespace CustomModelBindingSample.Binders
{
public class AuthorEntityBinderProvider : IModelBinderProvider
{
public IModelBinder GetBinder(ModelBinderProviderContext context)
{
{
}
if (context.Metadata.ModelType == typeof(Author))
{
return new BinderTypeModelBinder(typeof(AuthorEntityBinder));
}
return null;
}
}
}
Note: The preceding code returns a BinderTypeModelBinder . BinderTypeModelBinder acts as a factory for model
binders and provides dependency injection (DI). The AuthorEntityBinder requires DI to access EF Core. Use
BinderTypeModelBinder if your model binder requires services from DI.
To use a custom model binder provider, add it in ConfigureServices :

{
services.AddDbContext<AppDbContext>(options => options.UseInMemoryDatabase());
{
// add custom binder to beginning of collection
options.ModelBinderProviders.Insert(0, new AuthorEntityBinderProvider());
});
}
When evaluating model binders, the collection of providers is examined in order. The first provider that returns a
binder is used.
The following image shows the default model binders from the debugger.
Adding your provider to the end of the collection may result in a built-in model binder being called before your
custom binder has a chance. In this example, the custom provider is added to the beginning of the collection to
ensure it's used for Author action arguments.

{
services.AddDbContext<AppDbContext>(options => options.UseInMemoryDatabase());
{
// add custom binder to beginning of collection
options.ModelBinderProviders.Insert(0, new AuthorEntityBinderProvider());
});
}
Recommendations and best practices

Custom model binders:
Shouldn't attempt to set status codes or return results (for example, 404 Not Found). If model binding fails, an
action filter or logic within the action method itself should handle the failure.
Are most useful for eliminating repetitive code and cross-cutting concerns from action methods.
Typically shouldn't be used to convert a string into a custom type, a TypeConverter is usually a better option.
Compatibility version for ASP.NET Core MVC
By Rick Anderson
introduced in ASP.NET Core MVC 2.1 or later. These potentially breaking behavior changes are generally in how
the MVC subsystem behaves and how your code is called by the runtime. By opting in, you get the latest
behavior, and the long-term behavior of ASP.NET Core.
The following code sets the compatibility mode to ASP.NET Core 2.1:

{
services.AddMvc()
}
We recommend you test your app using the latest version ( CompatibilityVersion.Version_2_1 ). We anticipate that
most apps won't have breaking behavior changes using the latest version.
Apps that call SetCompatibilityVersion(CompatibilityVersion.Version_2_0) are protected from potentially
breaking behavior changes introduced in the ASP.NET Core 2.1 MVC and later 2.x versions. This protection:
Does not apply to all 2.1 and later changes, it's targeted to potentially breaking ASP.NET Core runtime
behavior changes in the MVC subsystem.
Does not extend to the next major version.
The default compatibility for ASP.NET Core 2.1 and later 2.x apps that do not call SetCompatibilityVersion is 2.0
compatibility. That is, not calling SetCompatibilityVersion is the same as calling
SetCompatibilityVersion(CompatibilityVersion.Version_2_0) .
The following code sets the compatibility mode to ASP.NET Core 2.1, except for the following behaviors:
AllowCombiningAuthorizeFilters
InputFormatterExceptionPolicy

{
services.AddMvc()
// Include the 2.1 behaviors
// Except for the following.
.AddMvcOptions(options =>
{
// Don't combine authorize filters (keep 2.0 behavior).
options.AllowCombiningAuthorizeFilters = false;
// All exceptions thrown by an IInputFormatter are treated
// as model state errors (keep 2.0 behavior).
options.InputFormatterExceptionPolicy =
InputFormatterExceptionPolicy.AllExceptions;
});
}
For apps that encounter breaking behavior changes, using the appropriate compatibility switches:
Allows you to use the latest release and opt out of specific breaking behavior changes.
Gives you time to update your app so it works with the latest changes.
The MvcOptions class source comments have a good explanation of what changed and why the changes are an
improvement for most users.
At some future date, there will be an ASP.NET Core 3.0 version. Old behaviors supported by compatibility
switches will be removed in the 3.0 version. We feel these are positive changes benefitting nearly all users. By
introducing these changes now, most apps can benefit now, and the others will have time to update their apps.
By Scott Addie
This document explains how to build a web API in ASP.NET Core and when it's most appropriate to use each
feature.
Derive class from ControllerBase

Inherit from the ControllerBase class in a controller that's intended to serve as a web API. For example:
{

{
}
[HttpGet]
public async Task<ActionResult<List<Pet>>> GetAllAsync()
{
return await _repository.GetPetsAsync();
}
[HttpGet("{id}")]
public async Task<ActionResult<Pet>> GetByIdAsync(int id)
{
if (pet == null)
{
return NotFound();
}
return pet;
}
[HttpPost]
public async Task<ActionResult<Pet>> CreateAsync(Pet pet)
{
{
}
}
}
{

{
}
[HttpGet]
[ProducesResponseType(typeof(IEnumerable<Pet>), 200)]
public async Task<IActionResult> GetAllAsync()
{
var pets = await _repository.GetPetsAsync();
return Ok(pets);
}
[HttpGet("{id}")]
public async Task<IActionResult> GetByIdAsync(int id)
{
if (pet == null)
{
return NotFound();
}
return Ok(pet);
}
[HttpPost]
public async Task<IActionResult> CreateAsync([FromBody] Pet pet)
{
{
}
}
}
The ControllerBase class provides access to several properties and methods. In the preceding code, examples
include BadRequest(ModelStateDictionary) and CreatedAtAction(String, Object, Object). These methods are
called within action methods to return HTTP 400 and 201 status codes, respectively. The ModelState property,
also provided by ControllerBase , is accessed to handle request model validation.
Annotate class with ApiControllerAttribute

ASP.NET Core 2.1 introduces the [ApiController] attribute to denote a web API controller class. For example:
[ApiController]
A compatibility version of 2.1 or later, set via SetCompatibilityVersion, is required to use this attribute. For
example, the highlighted code in Startup.ConfigureServices sets the 2.1 compatibility flag:
services.AddMvc()
The [ApiController] attribute is commonly coupled with ControllerBase to enable REST-specific behavior for
controllers. ControllerBase provides access to methods such as NotFound and File.
Another approach is to create a custom base controller class annotated with the [ApiController] attribute:
[ApiController]
public class MyBaseController
{
}
The following sections describe convenience features added by the attribute.

Automatic HTTP 400 responses
Validation errors automatically trigger an HTTP 400 response. The following code becomes unnecessary in your
actions:
{
}
The default behavior is disabled when the SuppressModelStateInvalidFilter property is set to true . Add the
following code in Startup.ConfigureServices after
{
});
Binding source parameter inference

A binding source attribute defines the location at which an action parameter's value is found. The following
binding source attributes exist:
[FromBody] Request body
[FromForm] Form data in the request body

[FromHeader] Request header
[FromQuery] Request query string parameter
[FromRoute] Route data from the current request
[FromServices] The request service injected as an action parameter
WARNING
Don't use [FromRoute] when values might contain %2f (that is / ). %2f won't be unescaped to / . Use
[FromQuery] if the value might contain %2f .
Without the [ApiController] attribute, binding source attributes are explicitly defined. In the following example,
the [FromQuery] attribute indicates that the discontinuedOnly parameter value is provided in the request URL's
query string:
[HttpGet]
public async Task<ActionResult<List<Product>>> GetAsync(
[FromQuery] bool discontinuedOnly = false)
{
List<Product> products = null;
if (discontinuedOnly)
{
products = await _repository.GetDiscontinuedProductsAsync();
}
else
{
products = await _repository.GetProductsAsync();
}
return products;
}
Inference rules are applied for the default data sources of action parameters. These rules configure the binding
sources you're otherwise likely to manually apply to the action parameters. The binding source attributes behave
as follows:
[FromBody] is inferred for complex type parameters. An exception to this rule is any complex, built-in type
with a special meaning, such as IFormCollection and CancellationToken. The binding source inference code
ignores those special types. [FromBody] isn't inferred for simple types such as string or int . Therefore, the
[FromBody] attribute should be used for simple types when that functionality is desired. When an action has
more than one parameter explicitly specified (via [FromBody] ) or inferred as bound from the request body, an
exception is thrown. For example, the following action signatures cause an exception:
// Don't do this. All of the following actions result in an exception.
[HttpPost]
Order order) => null;
[HttpPost]
[HttpPost]
public IActionResult Action3([FromBody] Product product,
[FromForm ] is inferred for action parameters of type IFormFile and IFormFileCollection. It's not inferred for
any simple or user-defined types.
[FromRoute] is inferred for any action parameter name matching a parameter in the route template. When
more than one route matches an action parameter, any route value is considered [FromRoute] .
[FromQuery] is inferred for any other action parameters.
The default inference rules are disabled when the SuppressInferBindingSourcesForParameters property is set to
{
});
Multipart/form-data request inference

When an action parameter is annotated with the [FromForm] attribute, the multipart/form-data request content
type is inferred.
The default behavior is disabled when the SuppressConsumesConstraintForFormFileParameters property is set
to true . Add the following code in Startup.ConfigureServices after
{
});
Attribute routing requirement

Attribute routing becomes a requirement. For example:
[ApiController]
Actions are inaccessible via conventional routes defined in UseMvc or by UseMvcWithDefaultRoute in

Startup.Configure.
Controller action return types in ASP.NET Core Web API
Controller action return types in ASP.NET Core Web
API
By Scott Addie
ASP.NET Core offers the following options for Web API controller action return types:
Specific type
IActionResult
ActionResult<T>
Specific type
IActionResult
This document explains when it's most appropriate to use each return type.
Specific type
The simplest action returns a primitive or complex data type (for example, string or a custom object type).
Consider the following action, which returns a collection of custom Product objects:
[HttpGet]
public IEnumerable<Product> Get()
{
return _repository.GetProducts();
}
Without known conditions to safeguard against during action execution, returning a specific type could suffice.
The preceding action accepts no parameters, so parameter constraints validation isn't needed.
When known conditions need to be accounted for in an action, multiple return paths are introduced. In such a
case, it's common to mix an ActionResult return type with the primitive or complex return type. Either
IActionResult or ActionResult<T> are necessary to accommodate this type of action.
IActionResult type
The IActionResult return type is appropriate when multiple ActionResult return types are possible in an action.
The ActionResult types represent various HTTP status codes. Some common return types falling into this
category are BadRequestResult (400), NotFoundResult (404), and OkObjectResult (200).
Because there are multiple return types and paths in the action, liberal use of the [ProducesResponseType]
attribute is necessary. This attribute produces more descriptive response details for API help pages generated by
tools like Swagger. [ProducesResponseType] indicates the known types and HTTP status codes to be returned by
the action.
Synchronous action
Consider the following synchronous action in which there are two possible return types:
[HttpGet("{id}")]
[ProducesResponseType(200, Type = typeof(Product))]
public IActionResult GetById(int id)
{
if (!_repository.TryGetProduct(id, out var product))
{
return NotFound();
}
return Ok(product);
}
In the preceding action, a 404 status code is returned when the product represented by id doesn't exist in the
underlying data store. The NotFound helper method is invoked as a shortcut to return new NotFoundResult(); . If
the product does exist, a Product object representing the payload is returned with a 200 status code. The Ok
helper method is invoked as the shorthand form of return new OkObjectResult(product); .
Asynchronous action
Consider the following asynchronous action in which there are two possible return types:
[HttpPost]
[ProducesResponseType(201, Type = typeof(Product))]
public async Task<IActionResult> CreateAsync([FromBody] Product product)
{
{
}
await _repository.AddProductAsync(product);
return CreatedAtAction(nameof(GetById), new { id = product.Id }, product);

}
In the preceding action, a 400 status code is returned when model validation fails and the BadRequest helper
method is invoked. For example, the following model indicates that requests must provide the Name property
and a value. Therefore, failure to provide a proper Name in the request causes model validation to fail.

{
[Required]

}
The preceding action's other known return code is a 201, which is generated by the CreatedAtAction helper
method. In this path, the Product object is returned.
ActionResult<T> type
ASP.NET Core 2.1 introduces the ActionResult<T> return type for Web API controller actions. It enables you to
return a type deriving from ActionResult or return a specific type. ActionResult<T> offers the following benefits
over the IActionResult type:
The [ProducesResponseType] attribute's property can be excluded. For example,
Type
[ProducesResponseType(200, Type = typeof(Product))] is simplified to [ProducesResponseType(200)] . The
action's expected return type is instead inferred from the T in ActionResult<T> .
Implicit cast operators support the conversion of both T and ActionResult to ActionResult<T> . T converts
to ObjectResult, which means return new ObjectResult(T); is simplified to return T; .
C# doesn't support implicit cast operators on interfaces. Consequently, conversion of the interface to a concrete
type is necessary to use ActionResult<T> . For example, use of IEnumerable in the following example doesn't
work:
[HttpGet]
public ActionResult<IEnumerable<Product>> Get()
{
return _repository.GetProducts();
}
One option to fix the preceding code is to return _repository.GetProducts().ToList(); .

Most actions have a specific return type. Unexpected conditions can occur during action execution, in which case
the specific type isn't returned. For example, an action's input parameter may fail model validation. In such a case,
it's common to return the appropriate ActionResult type instead of the specific type.
Synchronous action
Consider a synchronous action in which there are two possible return types:
[HttpGet("{id}")]
public ActionResult<Product> GetById(int id)
{
if (!_repository.TryGetProduct(id, out var product))
{
return NotFound();
}
return product;
}
In the preceding code, a 404 status code is returned when the product doesn't exist in the database. If the product
does exist, the corresponding Product object is returned. Before ASP.NET Core 2.1, the return product; line
would have been return Ok(product); .
TIP
As of ASP.NET Core 2.1, action parameter binding source inference is enabled when a controller class is decorated with the
[ApiController] attribute. A parameter name matching a name in the route template is automatically bound using the
request route data. Consequently, the preceding action's id parameter isn't explicitly annotated with the [FromRoute]
attribute.
Asynchronous action
Consider an asynchronous action in which there are two possible return types:
[HttpPost]
public async Task<ActionResult<Product>> CreateAsync(Product product)
{
{
}
await _repository.AddProductAsync(product);
return CreatedAtAction(nameof(GetById), new { id = product.Id }, product);

}
If model validation fails, the BadRequest method is invoked to return a 400 status code. The ModelState property
containing the specific validation errors is passed to it. If model validation succeeds, the product is created in the
database. A 201 status code is returned.
TIP
As of ASP.NET Core 2.1, action parameter binding source inference is enabled when a controller class is decorated with the
[ApiController] attribute. Complex type parameters are automatically bound using the request body. Consequently,
the preceding action's product parameter isn't explicitly annotated with the [FromBody] attribute.
Handle requests with controllers in ASP.NET Core MVC
Model validation in ASP.NET Core MVC
Advanced topics for ASP.NET Core Web API
Custom formatters
Format response data
By Tom Dykstra
ASP.NET Core MVC has built-in support for data exchange in web APIs by using JSON, XML, or plain text
formats. This article shows how to add support for additional formats by creating custom formatters.
When to use custom formatters

Use a custom formatter when you want the content negotiation process to support a content type that isn't
supported by the built-in formatters (JSON, XML, and plain text).
For example, if some of the clients for your web API can handle the Protobuf format, you might want to use
Protobuf with those clients because it's more efficient. Or you might want your web API to send contact names
and addresses in vCard format, a commonly used format for exchanging contact data. The sample app provided
with this article implements a simple vCard formatter.
Overview of how to use a custom formatter

Here are the steps to create and use a custom formatter:
Create an output formatter class if you want to serialize data to send to the client.
Create an input formatter class if you want to deserialize data received from the client.
Add instances of your formatters to the InputFormatters and OutputFormatters collections in MvcOptions.
The following sections provide guidance and code examples for each of these steps.
How to create a custom formatter class

To create a formatter:
Derive the class from the appropriate base class.
Specify valid media types and encodings in the constructor.
Override CanReadType / CanWriteType methods
Override ReadRequestBodyAsync / WriteResponseBodyAsync methods
Derive from the appropriate base class
For text media types (for example, vCard), derive from the TextInputFormatter or TextOutputFormatter base class.
public class VcardOutputFormatter : TextOutputFormatter
For binary types, derive from the InputFormatter or OutputFormatter base class.
Specify valid media types and encodings
In the constructor, specify valid media types and encodings by adding to the SupportedMediaTypes and
SupportedEncodings collections.
public VcardOutputFormatter()
{
SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("text/vcard"));
SupportedEncodings.Add(Encoding.UTF8);
SupportedEncodings.Add(Encoding.Unicode);
}
NOTE
You can't do constructor dependency injection in a formatter class. For example, you can't get a logger by adding a logger
parameter to the constructor. To access services, you have to use the context object that gets passed in to your methods. A
code example below shows how to do this.
Override CanReadType/CanWriteType
Specify the type you can deserialize into or serialize from by overriding the CanReadType or CanWriteType
methods. For example, you might only be able to create vCard text from a Contact type and vice versa.
protected override bool CanWriteType(Type type)

{
if (typeof(Contact).IsAssignableFrom(type)
|| typeof(IEnumerable<Contact>).IsAssignableFrom(type))
{
return base.CanWriteType(type);
}
return false;
}
The CanWriteResult method

In some scenarios you have to override CanWriteResult instead of CanWriteType . Use CanWriteResult if the
following conditions are true:
Your action method returns a model class.
There are derived classes which might be returned at runtime.
You need to know at runtime which derived class was returned by the action.
For example, suppose your action method signature returns a Person type, but it may return a Student or
Instructor type that derives from Person . If you want your formatter to handle only Student objects, check the
type of Object in the context object provided to the CanWriteResult method. Note that it's not necessary to use
CanWriteResult when the action method returns IActionResult ; in that case, the CanWriteType method receives
the runtime type.
Override ReadRequestBodyAsync/WriteResponseBodyAsync
You do the actual work of deserializing or serializing in ReadRequestBodyAsync or WriteResponseBodyAsync . The
highlighted lines in the following example show how to get services from the dependency injection container (you
can't get them from constructor parameters).
public override Task WriteResponseBodyAsync(OutputFormatterWriteContext context, Encoding selectedEncoding)
{
IServiceProvider serviceProvider = context.HttpContext.RequestServices;
var logger = serviceProvider.GetService(typeof(ILogger<VcardOutputFormatter>)) as ILogger;
var buffer = new StringBuilder();

if (context.Object is IEnumerable<Contact>)
{
foreach (Contact contact in context.Object as IEnumerable<Contact>)
{
FormatVcard(buffer, contact, logger);
}
}
else
{
var contact = context.Object as Contact;
FormatVcard(buffer, contact, logger);
}
return response.WriteAsync(buffer.ToString());
}
private static void FormatVcard(StringBuilder buffer, Contact contact, ILogger logger)

{
buffer.AppendLine("BEGIN:VCARD");
buffer.AppendLine("VERSION:2.1");
buffer.AppendFormat($"N:{contact.LastName};{contact.FirstName}\r\n");
buffer.AppendFormat($"FN:{contact.FirstName} {contact.LastName}\r\n");
buffer.AppendFormat($"UID:{contact.ID}\r\n");
buffer.AppendLine("END:VCARD");
logger.LogInformation($"Writing {contact.FirstName} {contact.LastName}");
}
How to configure MVC to use a custom formatter

To use a custom formatter, add an instance of the formatter class to the InputFormatters or OutputFormatters
collection.
{
options.InputFormatters.Insert(0, new VcardInputFormatter());
options.OutputFormatters.Insert(0, new VcardOutputFormatter());
});
Formatters are evaluated in the order you insert them. The first one takes precedence.
Next steps
See the sample application, which implements simple vCard input and output formatters. The application reads
and writes vCards that look like the following example:
BEGIN:VCARD
VERSION:2.1
N:Davolio;Nancy
FN:Nancy Davolio
UID:20293482-9240-4d68-b475-325df4a83728
END:VCARD
To see vCard output, run the application and send a Get request with Accept header "text/vcard" to
(when running from Visual Studio) or
http://localhost:63313/api/contacts/ http://localhost:5000/api/contacts/
(when running from the command line).
To add a vCard to the in-memory collection of contacts, send a Post request to the same URL, with Content-Type
header "text/vcard" and with vCard text in the body, formatted like the example above.
By Steve Smith
ASP.NET Core MVC has built-in support for formatting response data, using fixed formats or in response to
client specifications.
Format-Specific Action Results

Some action result types are specific to a particular format, such as JsonResult and ContentResult . Actions can
return specific results that are always formatted in a particular manner. For example, returning a JsonResult will
return JSON -formatted data, regardless of client preferences. Likewise, returning a ContentResult will return
plain-text-formatted string data (as will simply returning a string).
NOTE
An action isn't required to return any particular type; MVC supports any object return value. If an action returns an
IActionResult implementation and the controller inherits from Controller , developers have many helper methods
corresponding to many of the choices. Results from actions that return objects that are not IActionResult types will be
serialized using the appropriate IOutputFormatter implementation.
To return data in a specific format from a controller that inherits from the Controller base class, use the built-in
helper method Json to return JSON and Content for plain text. Your action method should return either the
specific result type (for instance, JsonResult ) or IActionResult .
Returning JSON -formatted data:
// GET: api/authors
[HttpGet]
public JsonResult Get()
{
return Json(_authorRepository.List());
}
Sample response from this action:

Note that the content type of the response is application/json , shown both in the list of network requests and in
the Response Headers section. Also note the list of options presented by the browser (in this case, Microsoft
Edge) in the Accept header in the Request Headers section. The current technique is ignoring this header; obeying
it is discussed below.
To return plain text formatted data, use ContentResult and the Content helper:
// GET api/authors/about
[HttpGet("About")]
public ContentResult About()
{
return Content("An API listing authors of docs.asp.net.");
}
A response from this action:

Note in this case the Content-Type returned is text/plain . You can also achieve this same behavior using just a
string response type:
// GET api/authors/version
[HttpGet("version")]
public string Version()
{
return "Version 1.0.0";
}
TIP
For non-trivial actions with multiple return types or options (for example, different HTTP status codes based on the result of
operations performed), prefer IActionResult as the return type.
Content Negotiation
Content negotiation (conneg for short) occurs when the client specifies an Accept header. The default format used
by ASP.NET Core MVC is JSON. Content negotiation is implemented by ObjectResult . It's also built into the
status code specific action results returned from the helper methods (which are all based on ObjectResult ). You
can also return a model type (a class you've defined as your data transfer type) and the framework will
automatically wrap it in an ObjectResult for you.
The following action method uses the Ok and NotFound helper methods:
// GET: api/authors/search?namelike=th
[HttpGet("Search")]
public IActionResult Search(string namelike)
{
var result = _authorRepository.GetByNameSubstring(namelike);
if (!result.Any())
{
return NotFound(namelike);
}
return Ok(result);
}
A JSON -formatted response will be returned unless another format was requested and the server can return the
requested format. You can use a tool like Fiddler to create a request that includes an Accept header and specify
another format. In that case, if the server has a formatter that can produce a response in the requested format,
the result will be returned in the client-preferred format.
In the above screenshot, the Fiddler Composer has been used to generate a request, specifying
Accept: application/xml . By default, ASP.NET Core MVC only supports JSON, so even when another format is
specified, the result returned is still JSON -formatted. You'll see how to add additional formatters in the next
section.
Controller actions can return POCOs (Plain Old CLR Objects), in which case ASP.NET Core MVC automatically
creates an ObjectResult for you that wraps the object. The client will get the formatted serialized object (JSON
format is the default; you can configure XML or other formats). If the object being returned is null , then the
framework will return a 204 No Content response.
Returning an object type:
// GET api/authors/ardalis
[HttpGet("{alias}")]
public Author Get(string alias)
{
return _authorRepository.GetByAlias(alias);
}
In the sample, a request for a valid author alias will receive a 200 OK response with the author's data. A request
for an invalid alias will receive a 204 No Content response. Screenshots showing the response in XML and JSON
formats are shown below.
Content Negotiation Process
Content negotiation only takes place if an Accept header appears in the request. When a request contains an
accept header, the framework will enumerate the media types in the accept header in preference order and will try
to find a formatter that can produce a response in one of the formats specified by the accept header. In case no
formatter is found that can satisfy the client's request, the framework will try to find the first formatter that can
produce a response (unless the developer has configured the option on MvcOptions to return 406 Not Acceptable
instead). If the request specifies XML, but the XML formatter has not been configured, then the JSON formatter
will be used. More generally, if no formatter is configured that can provide the requested format, then the first
formatter that can format the object is used. If no header is given, the first formatter that can handle the object to
be returned will be used to serialize the response. In this case, there isn't any negotiation taking place - the server
is determining what format it will use.
NOTE
If the Accept header contains */* , the Header will be ignored unless RespectBrowserAcceptHeader is set to true on
MvcOptions .
Browsers and Content Negotiation

Unlike typical API clients, web browsers tend to supply Accept headers that include a wide array of formats,
including wildcards. By default, when the framework detects that the request is coming from a browser, it will
ignore the Accept header and instead return the content in the application's configured default format (JSON
unless otherwise configured). This provides a more consistent experience when using different browsers to
consume APIs.
If you would prefer your application honor browser accept headers, you can configure this as part of MVC's
configuration by setting RespectBrowserAcceptHeader to true in the ConfigureServices method in Startup.cs.
{
options.RespectBrowserAcceptHeader = true; // false by default
});
Configuring Formatters
If your application needs to support additional formats beyond the default of JSON, you can add NuGet
packages and configure MVC to support them. There are separate formatters for input and output. Input
formatters are used by Model Binding; output formatters are used to format responses. You can also configure
Custom Formatters.
Adding XML Format Support
To add support for XML formatting, install the Microsoft.AspNetCore.Mvc.Formatters.Xml NuGet package.
Add the XmlSerializerFormatters to MVC's configuration in Startup.cs:
services.AddMvc()
.AddXmlSerializerFormatters();
Alternately, you can add just the output formatter:
{
options.OutputFormatters.Add(new XmlSerializerOutputFormatter());
});
These two approaches will serialize results using System.Xml.Serialization.XmlSerializer . If you prefer, you can
use the System.Runtime.Serialization.DataContractSerializer by adding its associated formatter:
{
options.OutputFormatters.Add(new XmlDataContractSerializerOutputFormatter());
});
Once you've added support for XML formatting, your controller methods should return the appropriate format
based on the request's Accept header, as this Fiddler example demonstrates:
You can see in the Inspectors tab that the Raw GET request was made with an Accept: application/xml header
set. The response pane shows the Content-Type: application/xml header, and the Author object has been
serialized to XML.
Use the Composer tab to modify the request to specify application/json in the Accept header. Execute the
request, and the response will be formatted as JSON:
In this screenshot, you can see the request sets a header of Accept: application/json and the response specifies
the same as its Content-Type . The Author object is shown in the body of the response, in JSON format.
Forcing a Particular Format
If you would like to restrict the response formats for a specific action you can, you can apply the [Produces] filter.
The [Produces] filter specifies the response formats for a specific action (or controller). Like most Filters, this can
be applied at the action, controller, or global scope.
public class AuthorsController
The [Produces] filter will force all actions within the AuthorsController to return JSON -formatted responses,
even if other formatters were configured for the application and the client provided an Accept header requesting
a different, available format. See Filters to learn more, including how to apply filters globally.
Special Case Formatters
Some special cases are implemented using built-in formatters. By default, string return types will be formatted
as text/plain (text/html if requested via Accept header). This behavior can be removed by removing the
TextOutputFormatter . You remove formatters in the Configure method in Startup.cs (shown below ). Actions that
have a model object return type will return a 204 No Content response when returning null . This behavior can
be removed by removing the HttpNoContentOutputFormatter . The following code removes the
TextOutputFormatter and HttpNoContentOutputFormatter .
{
options.OutputFormatters.RemoveType<TextOutputFormatter>();
options.OutputFormatters.RemoveType<HttpNoContentOutputFormatter>();
});
Without the TextOutputFormatter , string return types return 406 Not Acceptable, for example. Note that if an
XML formatter exists, it will format string return types if the TextOutputFormatter is removed.
Without the HttpNoContentOutputFormatter , null objects are formatted using the configured formatter. For
example, the JSON formatter will simply return a response with a body of null , while the XML formatter will
return an empty XML element with the attribute xsi:nil="true" set.
Response Format URL Mappings

Clients can request a particular format as part of the URL, such as in the query string or part of the path, or by
using a format-specific file extension such as .xml or .json. The mapping from request path should be specified in
the route the API is using. For example:
[FormatFilter]
public class ProductsController
{
[Route("[controller]/[action]/{id}.{format?}")]
public Product GetById(int id)
This route would allow the requested format to be specified as an optional file extension. The [FormatFilter]
attribute checks for the existence of the format value in the RouteData and will map the response format to the
appropriate formatter when the response is created.
ROUTE FORMATTER
/products/GetById/5 The default output formatter
/products/GetById/5.json The JSON formatter (if configured)
/products/GetById/5.xml The XML formatter (if configured)

ASP.NET Core SignalR
Introduction
Get started
Server concepts
Supported platforms
Hubs
HubContext
Users and groups
Publish to Azure
Clients
.NET client
Java client
Java API reference
JavaScript client
WebPack and TypeScript
Configuration
MessagePack Hub Protocol
Streaming
Differences between SignalR versions
Introduction to ASP.NET Core SignalR
What is SignalR?
ASP.NET Core SignalR is an open-source library that simplifies adding real-time web functionality to apps. Real-
time web functionality enables server-side code to push content to clients instantly.
Good candidates for SignalR:
Apps that require high frequency updates from the server. Examples are gaming, social networks, voting,
auction, maps, and GPS apps.
Dashboards and monitoring apps. Examples include company dashboards, instant sales updates, or travel
alerts.
Collaborative apps. Whiteboard apps and team meeting software are examples of collaborative apps.
Apps that require notifications. Social networks, email, chat, games, travel alerts, and many other apps use
notifications.
SignalR provides an API for creating server-to-client remote procedure calls (RPC ). The RPCs call JavaScript
functions on clients from server-side .NET Core code.
Here are some features of SignalR for ASP.NET Core:
Handles connection management automatically.
Sends messages to all connected clients simultaneously. For example, a chat room.
Sends messages to specific clients or groups of clients.
Scales to handle increasing traffic.
The source is hosted in a SignalR repository on GitHub.
Transports
SignalR supports several techniques for handling real-time communications:
WebSockets
Server-Sent Events
Long Polling
SignalR automatically chooses the best transport method that is within the capabilities of the server and client.
Hubs
SignalR uses hubs to communicate between clients and servers.
A hub is a high-level pipeline that allows a client and server to call methods on each other. SignalR handles the
dispatching across machine boundaries automatically, allowing clients to call methods on the server and vice
versa. You can pass strongly-typed parameters to methods, which enables model binding. SignalR provides two
built-in hub protocols: a text protocol based on JSON and a binary protocol based on MessagePack.
MessagePack generally creates smaller messages compared to JSON. Older browsers must support XHR level 2
to provide MessagePack protocol support.
Hubs call client-side code by sending messages that contain the name and parameters of the client-side method.
Objects sent as method parameters are deserialized using the configured protocol. The client tries to match the
name to a method in the client-side code. When the client finds a match, it calls the method and passes to it the
deserialized parameter data.
Get started with SignalR for ASP.NET Core
Supported Platforms
Hubs
JavaScript client
This tutorial teaches the basics of building a real-time app using SignalR. You learn how to:
Create a web app that uses SignalR on ASP.NET Core.
Create a SignalR hub on the server.
Connect to the SignalR hub from JavaScript clients.
Use the hub to send messages from any client to all connected clients.
At the end, you'll have a working chat app:
View or download sample code (how to download).
Prerequisites
Visual Studio
Visual Studio Code
Create the project

Visual Studio
Visual Studio Code
From the menu, select File > New Project.
In the New Project dialog, select Installed > Visual C# > Web > ASP.NET Core Web Application.
Name the project SignalRChat.
Select Web Application to create a project that uses Razor Pages.
Select a target framework of .NET Core, select ASP.NET Core 2.1, and click OK.
Add the SignalR client library

The SignalR server library is included in the Microsoft.AspNetCore.App metapackage. The JavaScript client
library isn't automatically included in the project. For this tutorial, you use Library Manager (LibMan) to get the
client library from unpkg. unpkg is a content delivery network that can deliver anything found in npm, the
Node.js package manager.
Visual Studio
Visual Studio Code
In Solution Explorer, right-click the project, and select Add > Client-Side Library.
In the Add Client-Side Library dialog, for Provider select unpkg.
For Library, enter _@aspnet/signalr@1_, and select the latest version that isn't preview.
Select Choose specific files, expand the dist/browser folder, and select signalr.js and signalr.min.js.
Set Target Location to wwwroot/lib/signalr/, and select Install.
LibMan creates a wwwroot/lib/signalr folder and copies the selected files to it.
Create the SignalR hub

A hub is a class that serves as a high-level pipeline that handles client-server communication.
In the SignalRChat project folder, create a Hubs folder.
In the Hubs folder, create a ChatHub.cs file with the following code:
namespace SignalRChat.Hubs
{
{
{
}
}
}
The ChatHub class inherits from the SignalR Hub class. The Hub class manages connections, groups, and
messaging.
The SendMessage method can be called by any connected client. It sends the received message to all
clients. SignalR code is asynchronous to provide maximum scalability.
Configure the project to use SignalR

The SignalR server must be configured to pass SignalR requests to SignalR.
Add the following highlighted code to the Startup.cs file.
{
{
{
}
{
{
// This lambda determines whether user consent for non-essential cookies is needed for
a given request.
});
}
pipeline.
{
{
}
else
{
app.UseHsts();
}
{
routes.MapHub<ChatHub>("/chatHub");
});
app.UseMvc();
}
}
}
These changes add SignalR to the dependency injection system and the middleware pipeline.
Create the SignalR client code

Replace the content in Pages\Index.cshtml with the following code:
@page
<div class="row"> </div>
<div class="row">
<div class="col-6">
User..........<input type="text" id="userInput" />
<br />
Message...<input type="text" id="messageInput" />
<input type="button" id="sendButton" value="Send Message" />
</div>
</div>
<div class="row">
<div class="col-12">
<hr />
</div>
</div>
<div class="row">
<div class="col-6">
<ul id="messagesList"></ul>
</div>
</div>
</div>
<script src="~/lib/signalr/dist/browser/signalr.js"></script>
<script src="~/js/chat.js"></script>
The preceding code:

Creates text boxes for name and message text, and a submit button.
Creates a list with id="messagesList" for displaying messages that are received from the SignalR hub.
Includes script references to SignalR and the chat.js application code that you create in the next step.
In the wwwroot/js folder, create a chat.js file with the following code:
"use strict";
var connection = new signalR.HubConnectionBuilder().withUrl("/chatHub").build();
connection.on("ReceiveMessage", function (user, message) {

var msg = message.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">");
var encodedMsg = user + " says " + msg;
});
connection.start().catch(function (err) {
});
document.getElementById("sendButton").addEventListener("click", function (event) {

var user = document.getElementById("userInput").value;
var message = document.getElementById("messageInput").value;
connection.invoke("SendMessage", user, message).catch(function (err) {
});
event.preventDefault();
});
The preceding code:

Creates and starts a connection.
Adds to the submit button a handler that sends messages to the hub.
Adds to the connection object a handler that receives messages from the hub and adds them to the list.
Run the app

Visual Studio
Visual Studio Code
Press CTRL+F5 to run the app without debugging.
Copy the URL from the address bar, open another browser instance or tab, and paste the URL in the
address bar.
Choose either browser, enter a name and message, and select the Send button.
The name and message are displayed on both pages instantly.
TIP
If the app doesn't work, open your browser developer tools (F12) and go to the console. You might see errors related to
your HTML and JavaScript code. For example, suppose you put signalr.js in a different folder than directed. In that case the
reference to that file won't work and you'll see a 404 error in the console.
Next steps
If you want clients to connect to a SignalR app from different domains, you have to enable Cross-Origin
Resource Sharing (CORS ). For more information, see Cross-origin resource sharing.
To learn more about SignalR, hubs, and JavaScript clients, see these resources:
Introduction to SignalR for ASP.NET Core
By Rachel Appel and Kevin Griffin

What is a SignalR hub

The SignalR Hubs API enables you to call methods on connected clients from the server. In the server code, you
define methods that are called by client. In the client code, you define methods that are called from the server.
SignalR takes care of everything behind the scenes that makes real-time client-to-server and server-to-client
communications possible.
Configure SignalR hubs

The SignalR middleware requires some services, which are configured by calling services.AddSignalR .
When adding SignalR functionality to an ASP.NET Core app, setup SignalR routes by calling app.UseSignalR in the
Startup.Configure method.
app.UseSignalR(route =>
{
route.MapHub<ChatHub>("/chathub");
});
Create and use hubs

Create a hub by declaring a class that inherits from Hub , and add public methods to it. Clients can call methods
that are defined as public .
{
{
await Clients.All.SendAsync("ReceiveMessage", user,message);
}
public Task SendMessageToCaller(string message)

{
return Clients.Caller.SendAsync("ReceiveMessage", message);
}
public Task SendMessageToGroups(string message)

{
List<string> groups = new List<string>() { "SignalR Users" };
return Clients.Groups(groups).SendAsync("ReceiveMessage", message);
}
public override async Task OnConnectedAsync()

{
await Groups.AddToGroupAsync(Context.ConnectionId, "SignalR Users");
await base.OnConnectedAsync();
}
public override async Task OnDisconnectedAsync(Exception exception)

{
await Groups.RemoveFromGroupAsync(Context.ConnectionId, "SignalR Users");
await base.OnDisconnectedAsync(exception);
}
}
You can specify a return type and parameters, including complex types and arrays, as you would in any C# method.
SignalR handles the serialization and deserialization of complex objects and arrays in your parameters and return
values.
The Context object

The Hub class has a Context property that contains the following properties with information about the
connection:
ConnectionId Gets the unique ID for the connection, assigned by SignalR.

There is one connection ID for each connection.
UserIdentifier Gets the user identifier. By default, SignalR uses the

ClaimTypes.NameIdentifier from the ClaimsPrincipal
associated with the connection as the user identifier.
User Gets the ClaimsPrincipal associated with the current user.
Items Gets a key/value collection that can be used to share data

within the scope of this connection. Data can be stored in this
collection and it will persist for the connection across different
hub method invocations.
Features Gets the collection of features available on the connection. For

now, this collection isn't needed in most scenarios, so it isn't
documented in detail yet.
ConnectionAborted Gets a CancellationToken that notifies when the connection

is aborted.
Hub.Context also contains the following methods:
METHOD DESCRIPTION
GetHttpContext Returns the HttpContext for the connection, or null if the

connection is not associated with an HTTP request. For HTTP
connections, you can use this method to get information such
as HTTP headers and query strings.
Abort Aborts the connection.
The Clients object

The Hub class has a Clients property that contains the following properties for communication between server
and client:
All Calls a method on all connected clients
Caller Calls a method on the client that invoked the hub method
Others Calls a method on all connected clients except the client that
invoked the method
Hub.Clients also contains the following methods:
METHOD DESCRIPTION
AllExcept Calls a method on all connected clients except for the specified
connections
Client Calls a method on a specific connected client
Clients Calls a method on specific connected clients
Group Calls a method to all connections in the specified group
GroupExcept Calls a method to all connections in the specified group, except

the specified connections
Groups Calls a method to multiple groups of connections
OthersInGroup Calls a method to a group of connections, excluding the client

that invoked the hub method
User Calls a method to all connections associated with a specific

user
METHOD DESCRIPTION
Users Calls a method to all connections associated with the specified

users
Each property or method in the preceding tables returns an object with a SendAsync method. The SendAsync
method allows you to supply the name and parameters of the client method to call.
Send messages to clients

To make calls to specific clients, use the properties of the Clients object. In the following example, the
SendMessageToCaller method demonstrates sending a message to the connection that invoked the hub method.
The SendMessageToGroups method sends a message to the groups stored in a List named groups .

{
}

{
}
Strongly typed hubs

A drawback of using SendAsync is that it relies on a magic string to specify the client method to be called. This
leaves code open to runtime errors if the method name is misspelled or missing from the client.
An alternative to using SendAsync is to strongly type the Hub with Hub<T>. In the following example, the ChatHub
client methods have been extracted out into an interface called IChatClient .
public interface IChatClient

{
Task ReceiveMessage(string user, string message);
Task ReceiveMessage(string message);
}
This interface can be used to refactor the preceding ChatHub example.
public class StronglyTypedChatHub : Hub<IChatClient>

{
{
await Clients.All.ReceiveMessage(user, message);
}

{
return Clients.Caller.ReceiveMessage(message);
}
}
Using Hub<IChatClient> enables compile-time checking of the client methods. This prevents issues caused by using
magic strings, since Hub<T> can only provide access to the methods defined in the interface.
Using a strongly typed Hub<T> disables the ability to use SendAsync .
Handle events for a connection

The SignalR Hubs API provides the OnConnectedAsync and OnDisconnectedAsync virtual methods to manage and
track connections. Override the OnConnectedAsync virtual method to perform actions when a client connects to the
Hub, such as adding it to a group.

{
}

{
}
Handle errors
Exceptions thrown in your hub methods are sent to the client that invoked the method. On the JavaScript client, the
invoke method returns a JavaScript Promise. When the client receives an error with a handler attached to the
promise using catch , it's invoked and passed as a JavaScript Error object.
connection.invoke("SendMessage", user, message).catch(err => console.error(err));
Related resources
Intro to ASP.NET Core SignalR
JavaScript client
Publish to Azure
ASP.NET Core SignalR supported platforms
Server system requirements

SignalR for ASP.NET Core supports any server platform ASP.NET Core supports.
Client system requirements

Browser support
The SignalR for ASP.NET Core JavaScript client supports the following browsers:
BROWSER VERSION
Microsoft Internet Explorer 11
Microsoft Edge current
Mozilla Firefox current
Google Chrome; includes Android current
Safari; includes iOS current
.NET Client support

Any server platform supported by ASP.NET Core. When using IIS, the WebSockets transport requires IIS 8.0 or
higher, on Windows Server 2012 or higher. Other transports are supported on all platforms.
By Rachel Appel and Kevin Griffin

What is a SignalR hub

The SignalR Hubs API enables you to call methods on connected clients from the server. In the server code,
you define methods that are called by client. In the client code, you define methods that are called from the
server. SignalR takes care of everything behind the scenes that makes real-time client-to-server and server-to-
client communications possible.
Configure SignalR hubs

The SignalR middleware requires some services, which are configured by calling services.AddSignalR .
When adding SignalR functionality to an ASP.NET Core app, setup SignalR routes by calling app.UseSignalR
in the Startup.Configure method.
app.UseSignalR(route =>
{
route.MapHub<ChatHub>("/chathub");
});
Create and use hubs

Create a hub by declaring a class that inherits from Hub , and add public methods to it. Clients can call methods
that are defined as public .
{
{
}

{
}

{
}

{
}

{
}
}
You can specify a return type and parameters, including complex types and arrays, as you would in any C#
method. SignalR handles the serialization and deserialization of complex objects and arrays in your parameters
and return values.
The Context object

The Hub class has a Context property that contains the following properties with information about the
connection:
ConnectionId Gets the unique ID for the connection, assigned by SignalR.

There is one connection ID for each connection.
UserIdentifier Gets the user identifier. By default, SignalR uses the

ClaimTypes.NameIdentifier from the ClaimsPrincipal
associated with the connection as the user identifier.
User Gets the ClaimsPrincipal associated with the current

user.
Items Gets a key/value collection that can be used to share data

within the scope of this connection. Data can be stored in
this collection and it will persist for the connection across
different hub method invocations.
Features Gets the collection of features available on the connection.

For now, this collection isn't needed in most scenarios, so it
isn't documented in detail yet.
ConnectionAborted Gets a CancellationToken that notifies when the

connection is aborted.
Hub.Context also contains the following methods:
METHOD DESCRIPTION
GetHttpContext Returns the HttpContext for the connection, or null if

the connection is not associated with an HTTP request. For
HTTP connections, you can use this method to get
information such as HTTP headers and query strings.
Abort Aborts the connection.
The Clients object

The Hub class has a Clients property that contains the following properties for communication between
server and client:
All Calls a method on all connected clients
Caller Calls a method on the client that invoked the hub method
Others Calls a method on all connected clients except the client that
invoked the method
Hub.Clients also contains the following methods:
METHOD DESCRIPTION
AllExcept Calls a method on all connected clients except for the

specified connections
Client Calls a method on a specific connected client
Clients Calls a method on specific connected clients
Group Calls a method to all connections in the specified group
GroupExcept Calls a method to all connections in the specified group,

except the specified connections
Groups Calls a method to multiple groups of connections
OthersInGroup Calls a method to a group of connections, excluding the

client that invoked the hub method
User Calls a method to all connections associated with a specific

user
METHOD DESCRIPTION
Users Calls a method to all connections associated with the

specified users
Each property or method in the preceding tables returns an object with a SendAsync method. The SendAsync
method allows you to supply the name and parameters of the client method to call.
Send messages to clients

To make calls to specific clients, use the properties of the Clients object. In the following example, the
SendMessageToCaller method demonstrates sending a message to the connection that invoked the hub
method. The SendMessageToGroups method sends a message to the groups stored in a List named groups .

{
}

{
}
Strongly typed hubs

A drawback of using SendAsync is that it relies on a magic string to specify the client method to be called. This
leaves code open to runtime errors if the method name is misspelled or missing from the client.
An alternative to using SendAsync is to strongly type the Hub with Hub<T>. In the following example, the
ChatHub client methods have been extracted out into an interface called IChatClient .
public interface IChatClient

{
Task ReceiveMessage(string user, string message);
Task ReceiveMessage(string message);
}
This interface can be used to refactor the preceding ChatHub example.
public class StronglyTypedChatHub : Hub<IChatClient>

{
{
await Clients.All.ReceiveMessage(user, message);
}

{
return Clients.Caller.ReceiveMessage(message);
}
}
Using Hub<IChatClient> enables compile-time checking of the client methods. This prevents issues caused by
using magic strings, since Hub<T> can only provide access to the methods defined in the interface.
Using a strongly typed Hub<T> disables the ability to use SendAsync .
Handle events for a connection

The SignalR Hubs API provides the OnConnectedAsync and OnDisconnectedAsync virtual methods to manage
and track connections. Override the OnConnectedAsync virtual method to perform actions when a client
connects to the Hub, such as adding it to a group.

{
}

{
}
Handle errors
Exceptions thrown in your hub methods are sent to the client that invoked the method. On the JavaScript
client, the invoke method returns a JavaScript Promise. When the client receives an error with a handler
attached to the promise using catch , it's invoked and passed as a JavaScript Error object.
connection.invoke("SendMessage", user, message).catch(err => console.error(err));
Related resources
Intro to ASP.NET Core SignalR
JavaScript client
Publish to Azure
Send messages from outside a hub
By Mikael Mengistu
The SignalR hub is the core abstraction for sending messages to clients connected to the SignalR server. It's also
possible to send messages from other places in your app using the IHubContext service. This article explains how
to access a SignalR IHubContext to send notifications to clients from outside a hub.
Get an instance of IHubContext

In ASP.NET Core SignalR, you can access an instance of IHubContext via dependency injection. You can inject an
instance of IHubContext into a controller, middleware, or other DI service. Use the instance to send messages to
clients.
NOTE
This differs from ASP.NET 4.x SignalR which used GlobalHost to provide access to the IHubContext . ASP.NET Core has a
dependency injection framework that removes the need for this global singleton.
Inject an instance of IHubContext in a controller

You can inject an instance of IHubContext into a controller by adding it to your constructor:

{
private readonly IHubContext<NotificationHub> _hubContext;
public HomeController(IHubContext<NotificationHub> hubContext)

{
_hubContext = hubContext;
}
}
Now, with access to an instance of IHubContext , you can call hub methods as if you were in the hub itself.

{
await _hubContext.Clients.All.SendAsync("Notify", $"Home page loaded at: {DateTime.Now}");
return View();
}
Get an instance of IHubContext in middleware

Access the IHubContext within the middleware pipeline like so:
app.Use(next => async (context) =>
{
var hubContext = context.RequestServices
.GetRequiredService<IHubContext<MyHub>>();
//...
});
NOTE
When hub methods are called from outside of the Hub class, there's no caller associated with the invocation. Therefore,
there's no access to the ConnectionId , Caller , and Others properties.
Related resources
Get started
Hubs
Publish to Azure
Manage users and groups in SignalR
By Brennan Conroy
SignalR allows messages to be sent to all connections associated with a specific user, as well as to named groups
of connections.
Users in SignalR
SignalR allows you to send messages to all connections associated with a specific user. By default, SignalR uses
the ClaimTypes.NameIdentifier from the ClaimsPrincipal associated with the connection as the user identifier. A
single user can have multiple connections to a SignalR app. For example, a user could be connected on their
desktop as well as their phone. Each device has a separate SignalR connection, but they're all associated with the
same user. If a message is sent to the user, all of the connections associated with that user receive the message.
The user identifier for a connection can be accessed by the Context.UserIdentifier property in your hub.
Send a message to a specific user by passing the user identifier to the User function in your hub method as
shown in the following example:
NOTE
The user identifier is case-sensitive.
public Task SendPrivateMessage(string user, string message)

{
return Clients.User(user).SendAsync("ReceiveMessage", message);
}
The user identifier can be customized by creating an IUserIdProvider , and registering it in ConfigureServices .
public class CustomUserIdProvider : IUserIdProvider

{
public virtual string GetUserId(HubConnectionContext connection)
{
return connection.User?.FindFirst(ClaimTypes.Email)?.Value;
}
}

{
services.AddSingleton<IUserIdProvider, CustomUserIdProvider>();
}
NOTE
AddSignalR must be called before registering your custom SignalR services.
Groups in SignalR
A group is a collection of connections associated with a name. Messages can be sent to all connections in a group.
Groups are the recommended way to send to a connection or multiple connections because the groups are
managed by the application. A connection can be a member of multiple groups. This makes groups ideal for
something like a chat application, where each room can be represented as a group. Connections can be added to
or removed from groups via the AddToGroupAsync and RemoveFromGroupAsync methods.
public async Task AddToGroup(string groupName)

{
await Groups.AddToGroupAsync(Context.ConnectionId, groupName);
await Clients.Group(groupName).SendAsync("Send", $"{Context.ConnectionId} has joined the group

{groupName}.");
}
public async Task RemoveFromGroup(string groupName)

{
await Groups.RemoveFromGroupAsync(Context.ConnectionId, groupName);
await Clients.Group(groupName).SendAsync("Send", $"{Context.ConnectionId} has left the group

{groupName}.");
}
Group membership isn't preserved when a connection reconnects. The connection needs to rejoin the group when
it's re-established. It's not possible to count the members of a group, since this information is not available if the
application is scaled to multiple servers.
NOTE
Group names are case-sensitive.
Related resources
Get started
Hubs
Publish to Azure
Publish an ASP.NET Core SignalR app to an Azure
Web App
Azure Web App is a Microsoft cloud computing platform service for hosting web apps, including ASP.NET Core.
NOTE
This article refers to publishing an ASP.NET Core SignalR app from Visual Studio. Visit SignalR service for Azure for more
information about using SignalR on Azure.
Publish the app

Visual Studio provides built-in tools for publishing to an Azure Web App. Visual Studio Code user can use Azure
CLI commands to publish apps to Azure. This article covers publishing using the tools in Visual Studio. To
publish an app using Azure CLI, see Publish an ASP.NET Core app to Azure with command line tools.
Right-click on the project in Solution Explorer and select Publish. Confirm that Create new is checked in the
Pick a publish target dialog, and select Publish.
Enter the following information in the Create App Service dialog and select Create.
ITEM DESCRIPTION
App name A unique name of the app.
Subscription The Azure subscription that the app uses.
Resource Group The group of related resources to which the app belongs.
Hosting Plan The pricing plan for the web app.
Visual Studio completes the following tasks:

Creates a Publish Profile containing publish settings.
Creates or uses an existing Azure Web App with the provided details.
Publishes the app.
Launches a browser, with the published web app loaded.
Notice the format of the URL for the app is {app name}.azurewebsites.net. For example, an app named
SignalRChattR has a URL that looks like https://signalrchattr.azurewebsites.net .
If an HTTP 502.2 error occurs, see Deploy ASP.NET Core preview release to Azure App Service to resolve it.
Configure SignalR web app

ASP.NET Core SignalR apps that are published as an Azure Web App must have ARR Affinity enabled.
WebSockets should be enabled, to allow the WebSockets transport to function.
In the Azure portal, navigate to App Settings for your web app. Set WebSockets to On, and verify ARR
Affinity is On.
WebSockets and other transports are limited based on the App Service Plan.
Related resources
Publish an ASP.NET Core app to Azure with command line tools
Publish an ASP.NET Core app to Azure with Visual Studio
Host and deploy ASP.NET Core Preview apps on Azure
By Rachel Appel
The ASP.NET Core SignalR JavaScript client library enables developers to call server-side hub code.
Install the SignalR client package

The SignalR JavaScript client library is delivered as an npm package. If you're using Visual Studio, run npm install
from the Package Manager Console while in the root folder. For Visual Studio Code, run the command from the
Integrated Terminal.
npm init -y
npm installs the package contents in the node_modules\@aspnet\signalr\dist\browser folder. Create a new folder
named signalr under the wwwroot\lib folder. Copy the signalr.js file to the wwwroot\lib\signalr folder.
Use the SignalR JavaScript client

Reference the SignalR JavaScript client in the <script> element.
<script src="~/lib/signalr/signalr.js"></script>
Connect to a hub
The following code creates and starts a connection. The hub's name is case insensitive.

.withUrl("/chatHub")
.configureLogging(signalR.LogLevel.Information)
.build();
connection.start().catch(err => console.error(err.toString()));
Cross-origin connections
Typically, browsers load connections from the same domain as the requested page. However, there are occasions
when a connection to another domain is required.
To prevent a malicious site from reading sensitive data from another site, cross-origin connections are disabled by
default. To allow a cross-origin request, enable it in the Startup class.
{
{
{
}

{
{
});
services.AddMvc();
services.AddCors(options => options.AddPolicy("CorsPolicy",

builder =>
{
builder.AllowAnyMethod().AllowAnyHeader()
.WithOrigins("http://localhost:55830")
.AllowCredentials();
}));
}

{
{
}
else
{
app.UseHsts();
}
app.UseCors("CorsPolicy");
{
routes.MapHub<ChatHub>("/chathub");
});
app.UseMvc();
}
}
}
Call hub methods from client
JavaScript clients call public methods on hubs via the invoke method of the HubConnection. The invoke method
accepts two arguments:
The name of the hub method. In the following example, the method name on the hub is SendMessage .
Any arguments defined in the hub method. In the following example, the argument name is message .
connection.invoke("SendMessage", user, message).catch(err => console.error(err.toString()));
Call client methods from hub

To receive messages from the hub, define a method using the on method of the HubConnection .
The name of the JavaScript client method. In the following example, the method name is ReceiveMessage .
Arguments the hub passes to the method. In the following example, the argument value is message .
connection.on("ReceiveMessage", (user, message) => {

const encodedMsg = user + " says " + message;
const li = document.createElement("li");
});
The preceding code in connection.on runs when server-side code calls it using the SendAsync method.

{
}
SignalR determines which client method to call by matching the method name and arguments defined in
SendAsync and connection.on .
NOTE
As a best practice, call the start method on the HubConnection after on . Doing so ensures your handlers are registered
before any messages are received.
Error handling and logging

Chain a catch method to the end of the start method to handle client-side errors. Use console.error to output
errors to the browser's console.
Setup client-side log tracing by passing a logger and type of event to log when the connection is made. Messages
are logged with the specified log level and higher. Available log levels are as follows:
signalR.LogLevel.Error – Error messages. Logs Error messages only.
signalR.LogLevel.Warning – Warning messages about potential errors. Logs Warning , and Error messages.
signalR.LogLevel.Information – Status messages without errors. Logs Information , Warning , and Error
messages.
signalR.LogLevel.Trace – Trace messages. Logs everything, including data transported between hub and client.
Use the configureLogging method on HubConnectionBuilder to configure the log level. Messages are logged to the
browser console.

.build();
Hubs
.NET client
Publish to Azure
Enable Cross-Origin Requests (CORS ) in ASP.NET Core
ASP.NET Core SignalR .NET Client
The ASP.NET Core SignalR .NET client library lets you communicate with SignalR hubs from .NET apps.
NOTE
Xamarin has special requirements for Visual Studio version. For more information, see SignalR Client 2.1.1 in Xamarin.

The code sample in this article is a WPF app that uses the ASP.NET Core SignalR .NET client.
Install the SignalR .NET client package

The Microsoft.AspNetCore.SignalR.Client package is needed for .NET clients to connect to SignalR hubs. To install
the client library, run the following command in the Package Manager Console window:
Install-Package Microsoft.AspNetCore.SignalR.Client
Connect to a hub
To establish a connection, create a HubConnectionBuilder and call Build . The hub URL, protocol, transport type,
log level, headers, and other options can be configured while building a connection. Configure any required
options by inserting any of the HubConnectionBuilder methods into Build . Start the connection with StartAsync .
using System;
using System.Windows;
using Microsoft.AspNetCore.SignalR.Client;
namespace SignalRChatClient
{
public partial class MainWindow : Window
{
HubConnection connection;
public MainWindow()
{
InitializeComponent();
connection = new HubConnectionBuilder()

.WithUrl("http://localhost:53353/ChatHub")
.Build();
connection.Closed += async (error) =>

{
await Task.Delay(new Random().Next(0,5) * 1000);
await connection.StartAsync();
};
}
private async void connectButton_Click(object sender, RoutedEventArgs e)

{
connection.On<string, string>("ReceiveMessage", (user, message) =>
{
this.Dispatcher.Invoke(() =>
{
var newMessage = $"{user}: {message}";
messagesList.Items.Add(newMessage);
});
});
try
{
messagesList.Items.Add("Connection started");
connectButton.IsEnabled = false;
sendButton.IsEnabled = true;
}
{
messagesList.Items.Add(ex.Message);
}
}
private async void sendButton_Click(object sender, RoutedEventArgs e)

{
try
{
await connection.InvokeAsync("SendMessage",
userTextBox.Text, messageTextBox.Text);
}
{
}
}
}
}
Handle lost connection

Use the Closed event to respond to a lost connection. For example, you might want to automate reconnection.
The Closed event requires a delegate that returns a Task , which allows async code to run without using
async void . To satisfy the delegate signature in a Closed event handler that runs synchronously, return
Task.CompletedTask :
connection.Closed += (error) => {

// Do your close logic.
};
The main reason for the async support is so you can restart the connection. Starting a connection is an async
action.
In a Closed handler that restarts the connection, consider waiting for some random delay to prevent overloading
the server, as shown in the following example:
connection.Closed += async (error) =>

{
await Task.Delay(new Random().Next(0,5) * 1000);
};

InvokeAsync calls methods on the hub. Pass the hub method name and any arguments defined in the hub
method to InvokeAsync . SignalR is asynchronous, so use async and await when making the calls.

Define methods the hub calls using connection.On after building, but before starting the connection.
connection.On<string, string>("ReceiveMessage", (user, message) =>

{
this.Dispatcher.Invoke(() =>
{
var newMessage = $"{user}: {message}";
messagesList.Items.Add(newMessage);
});
});
The preceding code in connection.On runs when server-side code calls it using the SendAsync method.

{
}

Handle errors with a try-catch statement. Inspect the Exception object to determine the proper action to take
after an error occurs.
try
{
}
{
}
Hubs
JavaScript client
Publish to Azure
ASP.NET Core SignalR Java Client
By Mikael Mengistu
The Java client enables connecting to an ASP.NET Core SignalR server from Java code, including Android apps.
Like the JavaScript client and the .NET client, the Java client enables you to receive and send messages to a hub in
real time. The Java client is available in ASP.NET Core 2.2 and later.
The sample Java console app referenced in this article uses the SignalR Java client.
Install the SignalR Java client package

The signalr-0.1.0 -preview2 -35174 JAR file allows clients to connect to SignalR hubs. To find the latest JAR file
version number, see the Maven search results.
If using Gradle, add the following line to the dependencies section of your build.gradle file:
implementation 'com.microsoft.aspnet:signalr:0.1.0-preview2-35174'
If using Maven, add the following lines inside the <dependencies> element of your pom.xml file:
<dependency>
<groupId>com.microsoft.aspnet</groupId>
<artifactId>signalr</artifactId>
<version>0.1.0-preview2-35174</version>
</dependency>
Connect to a hub
To establish a HubConnection , the HubConnectionBuilder should be used. The hub URL and log level can be
configured while building a connection. Configure any required options by calling any of the HubConnectionBuilder
methods before build . Start the connection with start .
HubConnection hubConnection = new HubConnectionBuilder()

.withUrl(input)
.configureLogging(LogLevel.Information)
.build();

A call to send invokes a hub method. Pass the hub method name and any arguments defined in the hub method
to send .
hubConnection.send("Send", input);

Use hubConnection.on to define methods on the client that the hub can call. Define the methods after building but
before starting the connection.
hubConnection.on("Send", (message) -> {

System.out.println("New Message: " + message);
}, String.class);
Known limitations
This is an early preview release of the Java client. There are many features that aren't supported yet. The following
gaps are being worked on for future releases:
Only primitive types can be accepted as parameters and return types.
The APIs are synchronous.
Only the "Send" call type is supported at this time. "Invoke" and streaming of return values aren't supported.
Only the JSON protocol is supported.
Only the WebSockets transport is supported.
Java API reference
Publish an ASP.NET Core SignalR app to Azure Web App
By Rachel Appel
The ASP.NET Core SignalR JavaScript client library enables developers to call server-side hub code.
Install the SignalR client package

The SignalR JavaScript client library is delivered as an npm package. If you're using Visual Studio, run
npm install from the Package Manager Console while in the root folder. For Visual Studio Code, run the
command from the Integrated Terminal.
npm init -y
npm installs the package contents in the node_modules\@aspnet\signalr\dist\browser folder. Create a new
folder named signalr under the wwwroot\lib folder. Copy the signalr.js file to the wwwroot\lib\signalr folder.
Use the SignalR JavaScript client

Reference the SignalR JavaScript client in the <script> element.
Connect to a hub
The following code creates and starts a connection. The hub's name is case insensitive.

.build();
Cross-origin connections
Typically, browsers load connections from the same domain as the requested page. However, there are
occasions when a connection to another domain is required.
To prevent a malicious site from reading sensitive data from another site, cross-origin connections are disabled
by default. To allow a cross-origin request, enable it in the Startup class.
{
{
{
}

{
{
});
services.AddMvc();
services.AddCors(options => options.AddPolicy("CorsPolicy",

builder =>
{
builder.AllowAnyMethod().AllowAnyHeader()
.WithOrigins("http://localhost:55830")
}));
}

{
{
}
else
{
app.UseHsts();
}
app.UseCors("CorsPolicy");
{
routes.MapHub<ChatHub>("/chathub");
});
app.UseMvc();
}
}
}
JavaScript clients call public methods on hubs via the invoke method of the HubConnection. The invoke
method accepts two arguments:
The name of the hub method. In the following example, the method name on the hub is SendMessage .
Any arguments defined in the hub method. In the following example, the argument name is message .
connection.invoke("SendMessage", user, message).catch(err => console.error(err.toString()));

To receive messages from the hub, define a method using the on method of the HubConnection .
The name of the JavaScript client method. In the following example, the method name is ReceiveMessage .
Arguments the hub passes to the method. In the following example, the argument value is message .

const encodedMsg = user + " says " + message;
const li = document.createElement("li");
});
The preceding code in connection.on runs when server-side code calls it using the SendAsync method.

{
}
SignalR determines which client method to call by matching the method name and arguments defined in
SendAsync and connection.on .
NOTE
As a best practice, call the start method on the HubConnection after on . Doing so ensures your handlers are
registered before any messages are received.

Chain a catch method to the end of the start method to handle client-side errors. Use console.error to
output errors to the browser's console.
Setup client-side log tracing by passing a logger and type of event to log when the connection is made.
Messages are logged with the specified log level and higher. Available log levels are as follows:
signalR.LogLevel.Error– Error messages. Logs Error messages only.
signalR.LogLevel.Warning – Warning messages about potential errors. Logs Warning , and Error
messages.
signalR.LogLevel.Information – Status messages without errors. Logs Information , Warning , and Error
messages.
signalR.LogLevel.Trace – Trace messages. Logs everything, including data transported between hub and
client.
Use the configureLogging method on HubConnectionBuilder to configure the log level. Messages are logged
to the browser console.

.build();
Hubs
.NET client
Publish to Azure
Enable Cross-Origin Requests (CORS ) in ASP.NET Core
Use ASP.NET Core SignalR with TypeScript and
Webpack
By Sébastien Sougnez and Scott Addie

Webpack enables developers to bundle and build the client-side resources of a web app. This tutorial
demonstrates using Webpack in an ASP.NET Core SignalR web app whose client is written in TypeScript.
Scaffold a starter ASP.NET Core SignalR app
Configure the SignalR TypeScript client
Configure a build pipeline using Webpack
Configure the SignalR server
Enable communication between client and server
Prerequisites
Install the following software:
Visual Studio
.NET Core CLI
Node.js with npm
Visual Studio 2017 version 15.7.3 or later with the ASP.NET and web development workload
Create the ASP.NET Core web app

Visual Studio
.NET Core CLI
Configure Visual Studio to look for npm in the PATH environment variable. By default, Visual Studio uses the
version of npm found in its installation directory. Follow these instructions in Visual Studio:
1. Navigate to Tools > Options > Projects and solutions > Web Package Management > External Web
Tools.
2. Select the $ (PATH ) entry from the list. Click the up arrow to move the entry to the second position in the
list. As an aside, the first entry refers to the project's local packages.
Visual Studio configuration is completed. It's time to create the project.
1. Use the File > New > Project menu option and choose the ASP.NET Core Web Application template.
2. Name the project SignalRWebPack, and click the OK button.
3. Select .NET Core from the target framework drop-down, and select ASP.NET Core 2.1 from the framework
selector drop-down. Select the Empty template, and click the OK button.
Configure Webpack and TypeScript

The following steps configure the conversion of TypeScript to JavaScript and the bundling of client-side resources.
1. Execute the following command in the project root to create a package.json file:
npm init -y
2. Add the highlighted property to the package.json file:
{
"name": "SignalRWebPack",
"version": "1.0.0",
"private": true,
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC"
}
Setting the private property to true prevents package installation warnings in the next step.
3. Install the required npm packages. Execute the following command from the project root:
npm install -D -E [email protected] [email protected] [email protected] mini-css-
[email protected] [email protected] [email protected] [email protected] [email protected]
Some command details to note:

A version number follows the @ sign for each package name. npm installs those specific package
versions.
The -E option disables npm's default behavior of writing semantic versioning range operators to
package.json. For example, "webpack": "4.12.0" is used instead of "webpack": "^4.12.0" . This option
prevents unintended upgrades to newer package versions.
See the official npm-install docs for more detail.
4. Replace the scripts property of the package.json file with the following snippet:
"scripts": {
"build": "webpack --mode=development --watch",
"release": "webpack --mode=production",
"publish": "npm run release && dotnet publish -c Release"
},
Some explanation of the scripts:

build : Bundles your client-side resources in development mode and watches for file changes. The file
watcher causes the bundle to regenerate each time a project file changes. The mode option disables
production optimizations, such as tree shaking and minification. Only use build in development.
release : Bundles your client-side resources in production mode.
publish : Runs the release script to bundle the client-side resources in production mode. It calls the
.NET Core CLI's publish command to publish the app.
5. Create a file named webpack.config.js, in the project root, with the following content:
const path = require("path");
const HtmlWebpackPlugin = require("html-webpack-plugin");
const CleanWebpackPlugin = require("clean-webpack-plugin");
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
module.exports = {
entry: "./src/index.ts",
output: {
path: path.resolve(__dirname, "wwwroot"),
filename: "[name].[chunkhash].js",
publicPath: "/"
},
resolve: {
extensions: [".js", ".ts"]
},
module: {
rules: [
{
test: /\.ts$/,
use: "ts-loader"
},
{
test: /\.css$/,
use: [MiniCssExtractPlugin.loader, "css-loader"]
}
]
},
plugins: [
new CleanWebpackPlugin(["wwwroot/*"]),
new HtmlWebpackPlugin({
template: "./src/index.html"
}),
new MiniCssExtractPlugin({
filename: "css/[name].[chunkhash].css"
})
]
};
The preceding file configures the Webpack compilation. Some configuration details to note:
The output property overrides the default value of dist. The bundle is instead emitted in the wwwroot
directory.
The resolve.extensions array includes .js to import the SignalR client JavaScript.
6. Create a new src directory in the project root. Its purpose is to store the project's client-side assets.
7. Create src/index.html with the following content.
<!DOCTYPE html>
<html>
<head>
<title>ASP.NET Core SignalR</title>
</head>
<body>
<div id="divMessages" class="messages">
</div>
<div class="input-zone">
<label id="lblMessage" for="tbMessage">Message:</label>
<input id="tbMessage" class="input-zone-input" type="text" />
<button id="btnSend">Send</button>
</div>
</body>
</html>
The preceding HTML defines the homepage's boilerplate markup.
8. Create a new src/css directory. Its purpose is to store the project's .css files.
9. Create src/css/main.css with the following content:
*, *::before, *::after {
box-sizing: border-box;
}
html, body {
margin: 0;
padding: 0;
}
.input-zone {
align-items: center;
display: flex;
flex-direction: row;
margin: 10px;
}
.input-zone-input {
flex: 1;
margin-right: 10px;
}
.message-author {
font-weight: bold;
}
.messages {
border: 1px solid #000;
margin: 10px;
max-height: 300px;
min-height: 300px;
overflow-y: auto;
padding: 5px;
}
The preceding main.css file styles the app.

10. Create src/tsconfig.json with the following content:
{
"target": "es5"
}
}
The preceding code configures the TypeScript compiler to produce ECMAScript 5-compatible JavaScript.
11. Create src/index.ts with the following content:


send();
}
});
function send() {
}
The preceding TypeScript retrieves references to DOM elements and attaches two event handlers:
keyup : This event fires when the user types something in the textbox identified as tbMessage . The send
function is called when the user presses the Enter key.
click : This event fires when the user clicks the Send button. The send function is called.
Configure the ASP.NET Core app

1. The code provided in the Startup.Configure method displays Hello World!. Replace the app.Run method
call with calls to UseDefaultFiles and UseStaticFiles.
The preceding code allows the server to locate and serve the index.html file, whether the user enters its full
URL or the root URL of the web app.
2. Call AddSignalR in the Startup.ConfigureServices method. It adds the SignalR services to your project.
3. Map a /hub route to the ChatHub hub. Add the following lines at the end of the Startup.Configure method:
app.UseSignalR(options =>
{
options.MapHub<ChatHub>("/hub");
});
4. Create a new directory, called Hubs, in the project root. Its purpose is to store the SignalR hub, which is
created in the next step.
5. Create hub Hubs/ChatHub.cs with the following code:
{
{
}
}
6. Add the following code at the top of the Startup.cs file to resolve the ChatHub reference:
using SignalRWebPack.Hubs;
Enable client and server communication

The app currently displays a simple form to send messages. Nothing happens when you try to do so. The server is
listening to a specific route but does nothing with sent messages.
1. Execute the following command at the project root:
The preceding command installs the SignalR TypeScript client, which allows the client to send messages to
the server.
2. Add the highlighted code to the src/index.ts file:


.withUrl("/hub")
.build();

let m = document.createElement("div");
m.innerHTML =
`<div class="message__author">${username}</div><div>${message}</div>`;
divMessages.appendChild(m);
});

send();
}
});
function send() {
}
The preceding code supports receiving messages from the server. The HubConnectionBuilder class creates a
new builder for configuring the server connection. The withUrl function configures the hub URL.
SignalR enables the exchange of messages between a client and a server. Each message has a specific
name. For example, you can have messages with the name messageReceived that execute the logic
responsible for displaying the new message in the messages zone. Listening to a specific message can be
done via the on function. You can listen to any number of message names. It's also possible to pass
parameters to the message, such as the author's name and the content of the message received. Once the
client receives a message, a new div element is created with the author's name and the message content
in its innerHTML attribute. It's added to the main div element displaying the messages.
3. Now that the client can receive a message, configure it to send messages. Add the highlighted code to the
src/index.ts file:


.withUrl("/hub")
.build();

let messageContainer = document.createElement("div");
messageContainer.innerHTML =
`<div class="message-author">${username}</div><div>${message}</div>`;
divMessages.appendChild(messageContainer);
});

send();
}
});
function send() {
connection.send("newMessage", username, tbMessage.value)
.then(() => tbMessage.value = "");
}
Sending a message through the WebSockets connection requires calling the send method. The method's
first parameter is the message name. The message data inhabits the other parameters. In this example, a
message identified as newMessage is sent to the server. The message consists of the username and the user
input from a text box. If the send works, the text box value is cleared.
4. Add the highlighted method to the ChatHub class:
{
{
public async Task NewMessage(string username, string message)
{
await Clients.All.SendAsync("messageReceived", username, message);
}
}
}
The preceding code broadcasts received messages to all connected users once the server receives them. It's
unnecessary to have a generic on method to receive all the messages. A method named after the message
name suffices.
In this example, the TypeScript client sends a message identified as newMessage . The C# NewMessage
method expects the data sent by the client. A call is made to the SendAsync method on Clients.All. The
received messages are sent to all clients connected to the hub.
Test the app

Confirm that the app works with the following steps.
Visual Studio
.NET Core CLI
1. Run Webpack in release mode. Using the Package Manager Console window, execute the following
command in the project root:
npm run release
This command yields the client-side assets to be served when running the app. The assets are placed in the
wwwroot folder.
Webpack completed the following tasks:
Purged the contents of the wwwroot directory.
Converted the TypeScript to JavaScript—a process known as transpilation.
Mangled the generated JavaScript to reduce file size—a process known as minification.
Copied the processed JavaScript, CSS, and HTML files from src to the wwwroot directory.
Injected the following elements into the wwwroot/index.html file:
A <link> tag, referencing the wwwroot/main.<hash>.css file. This tag is placed immediately
before the closing </head> tag.
A <script> tag, referencing the minified wwwroot/main.<hash>.js file. This tag is placed
immediately before the closing </body> tag.
2. Select Debug > Start without debugging to launch the app in a browser without attaching the debugger.
The wwwroot/index.html file is served at http://localhost:<port_number> .
3. Open another browser instance (any browser). Paste the URL in the address bar.
4. Choose either browser, type something in the Message text box, and click the Send button. The unique
user name and message are displayed on both pages instantly.
ASP.NET Core SignalR configuration
JSON/MessagePack serialization options

ASP.NET Core SignalR supports two protocols for encoding messages: JSON and MessagePack. Each protocol
has serialization configuration options.
JSON serialization can be configured on the server using the AddJsonProtocol extension method, which can be
added after AddSignalR in your Startup.ConfigureServices method. The AddJsonProtocol method takes a
delegate that receives an options object. The PayloadSerializerSettings property on that object is a JSON.NET
JsonSerializerSettings object that can be used to configure serialization of arguments and return values. See the
JSON.NET Documentation for more details.
As an example, to configure the serializer to use "PascalCase" property names, instead of the default "camelCase"
names, use the following code:
services.AddSignalR()
.AddJsonProtocol(options => {
options.PayloadSerializerSettings.ContractResolver =
new DefaultContractResolver();
});
In the .NET client, the same AddJsonProtocol extension method exists on HubConnectionBuilder. The
Microsoft.Extensions.DependencyInjection namespace must be imported to resolve the extension method:
// At the top of the file:

// When constructing your connection:

var connection = new HubConnectionBuilder()
.AddJsonProtocol(options => {
options.PayloadSerializerSettings.ContractResolver =
new DefaultContractResolver();
})
.Build();
NOTE
It's not possible to configure JSON serialization in the JavaScript client at this time.
MessagePack serialization options

MessagePack serialization can be configured by providing a delegate to the AddMessagePackProtocol call. See
MessagePack in SignalR for more details.
NOTE
It's not possible to configure MessagePack serialization in the JavaScript client at this time.
Configure server options

The following table describes options for configuring SignalR hubs:
OPTION DEFAULT VALUE DESCRIPTION
HandshakeTimeout 15 seconds If the client doesn't send an initial

handshake message within this time
interval, the connection is closed. This is
an advanced setting that should only be
modified if handshake timeout errors
are occurring due to severe network
latency. For more detail on the
handshake process, see the SignalR Hub
Protocol Specification.
KeepAliveInterval 15 seconds If the server hasn't sent a message

within this interval, a ping message is
sent automatically to keep the
connection open. When changing
KeepAliveInterval , change the
ServerTimeout /
serverTimeoutInMilliseconds
setting on the client. The recommended
ServerTimeout /
serverTimeoutInMilliseconds value
is double the KeepAliveInterval
value.
SupportedProtocols All installed protocols Protocols supported by this hub. By

default, all protocols registered on the
server are allowed, but protocols can be
removed from this list to disable specific
protocols for individual hubs.
EnableDetailedErrors false If true , detailed exception messages

are returned to clients when an
exception is thrown in a Hub method.
The default is false , as these
exception messages can contain
sensitive information.
Options can be configured for all hubs by providing an options delegate to the AddSignalR call in

{
services.AddSignalR(hubOptions =>
{
hubOptions.EnableDetailedErrors = true;
hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});
}
Options for a single hub override the global options provided in AddSignalR and can be configured using
AddHubOptions<T>:
services.AddSignalR().AddHubOptions<MyHub>(options =>
{
options.EnableDetailedErrors = true;
});
Use HttpConnectionDispatcherOptions to configure advanced settings related to transports and memory buffer
management. These options are configured by passing a delegate to MapHub<T>.
ApplicationMaxBufferSize 32 KB The maximum number of bytes received

from the client that the server buffers.
Increasing this value allows the server
to receive larger messages, but can
negatively impact memory
consumption.
AuthorizationData Data automatically gathered from the A list of IAuthorizeData objects used to
Authorize attributes applied to the determine if a client is authorized to
Hub class. connect to the hub.
TransportMaxBufferSize 32 KB The maximum number of bytes sent by

the app that the server buffers.
Increasing this value allows the server
to send larger messages, but can
negatively impact memory
consumption.
Transports All Transports are enabled. A bitmask of HttpTransportType

values that can restrict the transports a
client can use to connect.
LongPolling See below. Additional options specific to the Long

Polling transport.
WebSockets See below. Additional options specific to the

WebSockets transport.
The Long Polling transport has additional options that can be configured using the LongPolling property:
PollTimeout 90 seconds The maximum amount of time the

server waits for a message to send to
the client before terminating a single
poll request. Decreasing this value
causes the client to issue new poll
requests more frequently.
The WebSocket transport has additional options that can be configured using the WebSockets property:
CloseTimeout 5 seconds After the server closes, if the client fails

to close within this time interval, the
connection is terminated.
SubProtocolSelector null A delegate that can be used to set the

Sec-WebSocket-Protocol header to a
custom value. The delegate receives the
values requested by the client as input
and is expected to return the desired
value.
Configure client options

Client options can be configured on the HubConnectionBuilder type (available in both .NET and JavaScript clients),
as well as on the HubConnection itself.
Configure logging
Logging is configured in the .NET Client using the ConfigureLogging method. Logging providers and filters can be
registered in the same way as they are on the server. See the Logging in ASP.NET Core documentation for more
information.
NOTE
In order to register Logging providers, you must install the necessary packages. See the Built-in logging providers section of
the docs for a full list.
For example, to enable Console logging, install the Microsoft.Extensions.Logging.Console NuGet package. Call the
AddConsole extension method:

.WithUrl("https://example.com/myhub")
.ConfigureLogging(logging => {
logging.SetMinimumLevel(LogLevel.Information);
})
.Build();
In the JavaScript client, a similar configureLogging method exists. Provide a LogLevel value indicating the
minimum level of log messages to produce. Logs are written to the browser console window.
let connection = new signalR.HubConnectionBuilder()

.withUrl("/myhub")
.build();
NOTE
To disable logging entirely, specify signalR.LogLevel.None in the configureLogging method.
Log levels available to the JavaScript client are listed below. Setting the log level to one of these values enables
logging of messages at or above that level.
LEVEL DESCRIPTION
None No messages are logged.

LEVEL DESCRIPTION
Critical Messages that indicate a failure in the entire app.
Error Messages that indicate a failure in the current operation.
Warning Messages that indicate a non-fatal problem.
Information Informational messages.
Debug Diagnostic messages useful for debugging.
Trace Very detailed diagnostic messages designed for diagnosing

specific issues.
Configure allowed transports

The transports used by SignalR can be configured in the WithUrl call ( withUrl in JavaScript). A bitwise-OR of the
values of HttpTransportType can be used to restrict the client to only use the specified transports. All transports are
enabled by default.
For example, to disable the Server-Sent Events transport, but allow WebSockets and Long Polling connections:

.WithUrl("https://example.com/myhub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
.Build();
In the JavaScript client, transports are configured by setting the transport field on the options object provided to
withUrl :

.withUrl("/myhub", { transport: signalR.HttpTransportType.WebSockets |
signalR.HttpTransportType.LongPolling })
.build();
Configure bearer authentication

To provide authentication data along with SignalR requests, use the AccessTokenProvider option (
accessTokenFactory in JavaScript) to specify a function that returns the desired access token. In the .NET Client,
this access token is passed in as an HTTP "Bearer Authentication" token (Using the Authorization header with a
type of Bearer ). In the JavaScript client, the access token is used as a Bearer token, except in a few cases where
browser APIs restrict the ability to apply headers (specifically, in Server-Sent Events and WebSockets requests). In
these cases, the access token is provided as a query string value access_token .
In the .NET client, the AccessTokenProvider option can be specified using the options delegate in WithUrl :
.WithUrl("https://example.com/myhub", options => {
options.AccessTokenProvider = async () => {
// Get and return the access token.
};
})
.Build();
In the JavaScript client, the access token is configured by setting the accessTokenFactory field on the options object
in withUrl :

.withUrl("/myhub", {
accessTokenFactory: () => {
// Get and return the access token.
// This function can return a JavaScript Promise if asynchronous
// logic is required to retrieve the access token.
}
})
.build();
Configure timeout and keep-alive options

Additional options for configuring timeout and keep-alive behavior are available on the HubConnection object
itself:
.NET OPTION JAVASCRIPT OPTION DEFAULT VALUE DESCRIPTION
ServerTimeout serverTimeoutInMilliseconds 30 seconds (30,000 Timeout for server activity. If

milliseconds) the server hasn't sent a
message in this interval, the
client considers the server
disconnected and triggers
the Closed event (
onclose in JavaScript). This
value must be large enough
for a ping message to be
sent from the server and
received by the client within
the timeout interval. The
recommended value is a
number at least double the
server's
KeepAliveInterval value,
to allow time for pings to
arrive.
HandshakeTimeout Not configurable 15 seconds Timeout for initial server

handshake. If the server
doesn't send a handshake
response in this interval, the
client cancels the handshake
and triggers the Closed
event ( onclose in
JavaScript). This is an
advanced setting that
should only be modified if
handshake timeout errors
are occurring due to severe
network latency. For more
detail on the Handshake
process, see the SignalR Hub
Protocol Specification.
In the .NET Client, timeout values are specified as TimeSpan values. In the JavaScript client, timeout values are
specified as a number indicating the duration in milliseconds.
Configure additional options
Additional options can be configured in the WithUrl ( withUrl in JavaScript) method on HubConnectionBuilder :
AccessTokenProvider accessTokenFactory null A function returning a string

that is provided as a Bearer
authentication token in
HTTP requests.
SkipNegotiation skipNegotiation false Set this to true to skip the

negotiation step. Only
supported when the
WebSockets transport is
the only enabled
transport. This setting can't
be enabled when using the
Azure SignalR Service.
ClientCertificates Not configurable * Empty A collection of TLS

certificates to send to
authenticate requests.
Cookies Not configurable * Empty A collection of HTTP cookies

to send with every HTTP
request.
Credentials Not configurable * Empty Credentials to send with

every HTTP request.
CloseTimeout Not configurable * 5 seconds WebSockets only. The

maximum amount of time
the client waits after closing
for the server to
acknowledge the close
request. If the server doesn't
acknowledge the close
within this time, the client
disconnects.
Headers Not configurable * Empty A dictionary of additional

HTTP headers to send with
every HTTP request.
HttpMessageHandlerFactory Not configurable * null A delegate that can be used

to configure or replace the
HttpMessageHandler used
to send HTTP requests. Not
used for WebSocket
connections. This delegate
must return a non-null
value, and it receives the
default value as a parameter.
Either modify settings on
that default value and return
it, or return a new
HttpMessageHandler
instance. When replacing
the handler make sure to
copy the settings you
want to keep from the
provided handler,
otherwise, the configured
options (such as Cookies
and Headers) won't apply
to the new handler.
Proxy Not configurable * null An HTTP proxy to use when

sending HTTP requests.
UseDefaultCredentials Not configurable * false Set this boolean to send the

default credentials for HTTP
and WebSockets requests.
This enables the use of
Windows authentication.
WebSocketConfiguration Not configurable * null A delegate that can be used

to configure additional
WebSocket options. Receives
an instance of
ClientWebSocketOptions
that can be used to
configure the options.
Options marked with an asterisk (*) aren't configurable in the JavaScript client, due to limitations in browser APIs.
In the .NET Client, these options can be modified by the options delegate provided to WithUrl :
.WithUrl("https://example.com/myhub", options => {
options.Headers["Foo"] = "Bar";
options.Cookies.Add(new Cookie(/* ... */);
options.ClientCertificates.Add(/* ... */);
})
.Build();
In the JavaScript Client, these options can be provided in a JavaScript object provided to withUrl :

.withUrl("/myhub", {
skipNegotiation: true,
transport: signalR.HttpTransportType.WebSockets
})
.build();
ASP.NET Core SignalR .NET Client
Use MessagePack Hub Protocol in SignalR for ASP.NET Core
ASP.NET Core SignalR supported platforms
Authentication and authorization in ASP.NET Core
SignalR
By Andrew Stanton-Nurse
Authenticate users connecting to a SignalR hub

SignalR can be used with ASP.NET Core Authentication to associate a user with each connection. In a hub,
authentication data can be accessed from the HubConnectionContext.User property. Authentication allows the hub
to call methods on all connections associated with a user (See Manage users and groups in SignalR for more
information). Multiple connections may be associated with a single user.
Cookie authentication
In a browser-based app, cookie authentication allows your existing user credentials to automatically flow to
SignalR connections. When using the browser client, no additional configuration is needed. If the user is logged in
to your app, the SignalR connection automatically inherits this authentication.
Cookie authentication isn't recommended unless the app only needs to authenticate users from the browser client.
When using the .NET Client, the Cookies property can be configured in the .WithUrl call in order to provide a
cookie. However, using cookie authentication from the .NET Client requires the app to provide an API to exchange
authentication data for a cookie.
Bearer token authentication
Bearer token authentication is the recommended approach when using clients other than the browser client. In this
approach, the client provides an access token that the server validates and uses to identify the user. The details of
bearer token authentication are beyond the scope of this document. On the server, bearer token authentication is
configured using the JWT Bearer middleware.
In the JavaScript client, the token can be provided using the accessTokenFactory option.
this.connection = new signalR.HubConnectionBuilder()

.withUrl("/hubs/chat", { accessTokenFactory: () => this.loginToken })
.build();
In the .NET client, there is a similar AccessTokenProvider property that can be used to configure the token:

.WithUrl("https://example.com/myhub", options =>
{
options.AccessTokenProvider = () => Task.FromResult(_myAccessToken);
})
.Build();
NOTE
The access token function you provide is called before every HTTP request made by SignalR. If you need to renew the token
in order to keep the connection active (because it may expire during the connection), do so from within this function and
return the updated token.
In standard web APIs, bearer tokens are sent in an HTTP header. However, SignalR is unable to set these headers
in browsers when using some transports. When using WebSockets and Server-Sent Events, the token is
transmitted as a query string parameter. In order to support this on the server, additional configuration is required:

{
services.AddAuthentication(options =>
{
// Identity made Cookie authentication the default.
// However, we want JWT Bearer Auth to be the default.
options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
})
.AddJwtBearer(options =>
{
// Configure JWT Bearer Auth to expect our security key
options.TokenValidationParameters =
new TokenValidationParameters
{
LifetimeValidator = (before, expires, token, param) =>
{
return expires > DateTime.UtcNow;
},
ValidateAudience = false,
ValidateIssuer = false,
ValidateActor = false,
ValidateLifetime = true,
IssuerSigningKey = SecurityKey
};
// We have to hook the OnMessageReceived event in order to

// allow the JWT authentication handler to read the access
// token from the query string when a WebSocket or
// Server-Sent Events request comes in.
options.Events = new JwtBearerEvents
{
OnMessageReceived = context =>
{
var accessToken = context.Request.Query["access_token"];
// If the request is for our hub...

var path = context.HttpContext.Request.Path;
if (!string.IsNullOrEmpty(accessToken) &&
(path.StartsWithSegments("/hubs/chat")))
{
// Read the token out of the query string
context.Token = accessToken;
}
}
};
});
});
// Change to use Name as the user identifier for SignalR

// WARNING: This requires that the source of your JWT token
// ensures that the Name claim is unique!
// If the Name claim isn't unique, users could receive messages
// intended for a different user!
services.AddSingleton<IUserIdProvider, NameUserIdProvider>();
}
Windows authentication
If Windows authentication is configured in your app, SignalR can use that identity to secure hubs. However, in
order to send messages to individual users, you need to add a custom User ID provider. This is because the
Windows authentication system doesn't provide the "Name Identifier" claim that SignalR uses to determine the
user name.
Add a new class that implements IUserIdProvider and retrieve one of the claims from the user to use as the
identifier. For example, to use the "Name" claim (which is the Windows username in the form [Domain]\[Username]
), create the following class:
public class NameUserIdProvider : IUserIdProvider

{
public string GetUserId(HubConnectionContext connection)
{
return connection.User?.FindFirst(ClaimTypes.Name)?.Value;
}
}
Rather than ClaimTypes.Name , you can use any value from the User (such as the Windows SID identifier, etc.).
NOTE
The value you choose must be unique among all the users in your system. Otherwise, a message intended for one user could
end up going to a different user.
Register this component in your Startup.ConfigureServices method after the call to .AddSignalR

{
// ... other services ...
services.AddSingleton<IUserIdProvider, NameUserIdProvider>();
}
In the .NET Client, Windows Authentication must be enabled by setting the UseDefaultCredentials property:

.WithUrl("https://example.com/myhub", options =>
{
options.UseDefaultCredentials = true;
})
.Build();
Windows Authentication is only supported by the browser client when using Microsoft Internet Explorer or
Microsoft Edge.
Authorize users to access hubs and hub methods

By default, all methods in a hub can be called by an unauthenticated user. In order to require authentication, apply
the Authorize attribute to the hub:
[Authorize]
public class ChatHub: Hub
{
}
You can use the constructor arguments and properties of the [Authorize] attribute to restrict access to only users
matching specific authorization policies. For example, if you have a custom authorization policy called
MyAuthorizationPolicy you can ensure that only users matching that policy can access the hub using the following
code:
[Authorize("MyAuthorizationPolicy")]
{
}
Individual hub methods can have the [Authorize] attribute applied as well. If the current user doesn't match the
policy applied to the method, an error is returned to the caller:
[Authorize]
{
public async Task Send(string message)
{
// ... send a message to all users ...
}
[Authorize("Administrators")]
public void BanUser(string userName)
{
// ... ban a user from the chat room (something only Administrators can do) ...
}
}
Security considerations in ASP.NET Core SignalR
By Andrew Stanton-Nurse
Overview
SignalR provides a number of security protections by default. It's important to understand how to configure these
protections.
Cross-origin resource sharing
Cross-origin resource sharing (CORS ) can be used to allow cross-origin SignalR connections in the browser. If
your JavaScript code is hosted on a different domain name from your SignalR app, you have to enable the
ASP.NET Core CORS middleware in order to allow the connection. In general, allow cross-origin requests only
from domains you control. For example, if your site is hosted on http://www.example.com and your SignalR app is
hosted on http://signalr.example.com , you should configure CORS in your SignalR app to only allow the origin
www.example.com .
For more information on configuring CORS, see the documentation on ASP.NET Core CORS. SignalR requires
the following CORS policies in order to operate correctly:
The policy must allow the specific origins you expect, or allow any origin (not recommended).
HTTP methods GET and POST must be allowed.
Credentials must be enabled, even when you aren't using authentication.
For example, the following CORS policy allows a SignalR browser client hosted on http://example.com to access
your SignalR app:

{
// ... other middleware ...
// Make sure the CORS middleware is ahead of SignalR.

app.UseCors(builder => {
builder.WithOrigins("http://example.com")
.AllowAnyHeader()
.WithMethods("GET", "POST")
});
app.UseSignalR();

}
NOTE
SignalR is not compatible with the built-in CORS feature in Azure App Service.
Access token logging

When using WebSockets or Server-Sent Events, the browser client sends the access token in the query string. This
is generally as secure as using the standard Authorization header, however many web servers log the URL for
each request, including the query string. This means the access token may be included in logs. Consider reviewing
the web server's logging settings to avoid logging this information.
Exceptions
Exception messages are generally considered sensitive data that shouldn't be revealed to a client. By default,
SignalR doesn't send the details of an exception thrown by a hub method to the client. Instead, the client receives a
generic message indicating an error occurred. You can override this behavior by setting the EnableDetailedErrors
setting.
Buffer management
SignalR uses per-connection buffers in order to manage incoming and outgoing messages. By default, SignalR
limits these buffers to 32KB. This means the largest possible message a client or server can send is 32KB. This also
means the maximum amount of memory consumed by a connection for messages is 32KB. If you know your
messages are always smaller than this limit, you can reduce this size to prevent a client from being able to send a
larger message and force the server to allocate memory to accept it. Similarly, if you know your messages are
larger than this limit, you can increase it. However, be aware that increasing this limit means that the client is able
to cause the server to allocate additional memory and may reduce the number of concurrent connections your app
can handle.
There are separate limits for incoming and outgoing messages, both can be configured on the
HttpConnectionDispatcherOptions object configured in MapHub :
ApplicationMaxBufferSize represents the maximum number of bytes from the client that the server buffers. If
the client attempts to send a message larger than this limit, the connection may be closed.
TransportMaxBufferSize represents the maximum number of bytes the server can send. If the server attempts
to send a message (includes return values from hub methods) larger than this limit, an exception will be thrown.
Setting the limit to 0 disables the limit entirely. However, this should be done with extreme caution. Removing the
limit allows a client to send a message of any size. This could be used by a malicious client to cause excess memory
to be allocated, which could dramatically reduce the number of concurrent connections your app can support.
Use MessagePack Hub Protocol in SignalR for
ASP.NET Core
By Brennan Conroy
This article assumes the reader is familiar with the topics covered in Get Started.
What is MessagePack?
MessagePack is a binary serialization format that is fast and compact. It's useful when performance and
bandwidth are a concern because it creates smaller messages compared to JSON. Because it's a binary format,
messages are unreadable when looking at network traces and logs unless the bytes are passed through a
MessagePack parser. SignalR has built-in support for the MessagePack format, and provides APIs for the client
and server to use.
Configure MessagePack on the server

To enable the MessagePack Hub Protocol on the server, install the
Microsoft.AspNetCore.SignalR.Protocols.MessagePack package in your app. In the Startup.cs file add
AddMessagePackProtocol to the AddSignalR call to enable MessagePack support on the server.
NOTE
JSON is enabled by default. Adding MessagePack enables support for both JSON and MessagePack clients.
.AddMessagePackProtocol();
To customize how MessagePack will format your data, AddMessagePackProtocol takes a delegate for configuring
options. In that delegate, the FormatterResolvers property can be used to configure MessagePack serialization
options. For more information on how the resolvers work, visit the MessagePack library at MessagePack-CSharp.
Attributes can be used on the objects you want to serialize to define how they should be handled.
.AddMessagePackProtocol(options =>
{
options.FormatterResolvers = new List<MessagePack.IFormatterResolver>()
{
MessagePack.Resolvers.StandardResolver.Instance
};
});
Configure MessagePack on the client

.NET client
To enable MessagePack in the .NET Client, install the Microsoft.AspNetCore.SignalR.Protocols.MessagePack package
and call AddMessagePackProtocol on HubConnectionBuilder .
var hubConnection = new HubConnectionBuilder()
.WithUrl("/chatHub")
.AddMessagePackProtocol()
.Build();
NOTE
This AddMessagePackProtocol call takes a delegate for configuring options just like the server.
JavaScript client
MessagePack support for the Javascript client is provided by the @aspnet/signalr-protocol-msgpack NPM package.
npm install @aspnet/signalr-protocol-msgpack
After installing the npm package, the module can be used directly via a JavaScript module loader or imported into
the browser by referencing the node_modules\@aspnet\signalr-protocol-msgpack\dist\browser\signalr-protocol-
msgpack.js file. In a browser the msgpack5 library must also be referenced. Use a <script> tag to create a
reference. The library can be found at node_modules\msgpack5\dist\msgpack5.js.
NOTE
When using the <script> element, the order is important. If signalr-protocol-msgpack.js is referenced before
msgpack5.js, an error occurs when trying to connect with MessagePack. signalr.js is also required before signalr-protocol-
msgpack.js.
<script src="~/lib/msgpack5/msgpack5.js"></script>
<script src="~/lib/signalr/signalr-protocol-msgpack.js"></script>
Adding .withHubProtocol(new signalR.protocols.msgpack.MessagePackHubProtocol()) to the HubConnectionBuilder

will configure the client to use the MessagePack protocol when connecting to a server.

.withHubProtocol(new signalR.protocols.msgpack.MessagePackHubProtocol())
.build();
NOTE
At this time, there are no configuration options for the MessagePack protocol on the JavaScript client.
Related resources
Get Started
.NET client
JavaScript client
Use streaming in ASP.NET Core SignalR
By Brennan Conroy
ASP.NET Core SignalR supports streaming return values of server methods. This is useful for scenarios where
fragments of data will come in over time. When a return value is streamed to the client, each fragment is sent to
the client as soon as it becomes available, rather than waiting for all the data to become available.
Set up the hub

A hub method automatically becomes a streaming hub method when it returns a ChannelReader<T> or a
Task<ChannelReader<T>> . Below is a sample that shows the basics of streaming data to the client. Whenever an
object is written to the ChannelReader that object is immediately sent to the client. At the end, the ChannelReader is
completed to tell the client the stream is closed.
NOTE
Write to the ChannelReader on a background thread and return the ChannelReader as soon as possible. Other hub
invocations will be blocked until a ChannelReader is returned.
public class StreamHub : Hub

{
public ChannelReader<int> Counter(int count, int delay)
{
var channel = Channel.CreateUnbounded<int>();
// We don't want to await WriteItems, otherwise we'd end up waiting

// for all the items to be written before returning the channel back to
// the client.
_ = WriteItems(channel.Writer, count, delay);
return channel.Reader;
}
private async Task WriteItems(ChannelWriter<int> writer, int count, int delay)

{
for (var i = 0; i < count; i++)
{
await writer.WriteAsync(i);
await Task.Delay(delay);
}
writer.TryComplete();
}
}
.NET client
The StreamAsChannelAsync method on HubConnection is used to invoke a streaming method. Pass the hub method
name, and arguments defined in the hub method to StreamAsChannelAsync . The generic parameter on
StreamAsChannelAsync<T> specifies the type of objects returned by the streaming method. A ChannelReader<T> is
returned from the stream invocation, and represents the stream on the client. To read data, a common pattern is to
loop over WaitToReadAsync and call TryRead when data is available. The loop will end when the stream has been
closed by the server, or the cancellation token passed to StreamAsChannelAsync is canceled.
var channel = await hubConnection.StreamAsChannelAsync<int>("Counter", 10, 500, CancellationToken.None);
// Wait asynchronously for data to become available

while (await channel.WaitToReadAsync())
{
// Read all currently available data synchronously, before waiting for more data
while (channel.TryRead(out var count))
{
Console.WriteLine($"{count}");
}
}
Console.WriteLine("Streaming completed");
JavaScript client
JavaScript clients call streaming methods on hubs by using connection.stream . The stream method accepts two
arguments:
The name of the hub method. In the following example, the hub method name is Counter .
Arguments defined in the hub method. In the following example, the arguments are: a count for the number of
stream items to receive, and the delay between stream items.
connection.stream returns an IStreamResult which contains a subscribe method. Pass an IStreamSubscriber to
subscribe and set the next , error , and complete callbacks to get notifications from the stream invocation.
connection.stream("Counter", 10, 500)

.subscribe({
next: (item) => {
li.textContent = item;
},
complete: () => {
li.textContent = "Stream completed";
},
error: (err) => {
li.textContent = err;
},
});
To end the stream from the client call the dispose method on the ISubscription that is returned from the
subscribe method.
Related resources
Hubs
.NET client
JavaScript client
Publish to Azure
Differences between ASP.NET SignalR and ASP.NET
Core SignalR
ASP.NET Core SignalR isn't compatible with clients or servers for ASP.NET SignalR. This article details features
which have been removed or changed in ASP.NET Core SignalR.
How to identify the SignalR version

ASP.NET SIGNALR ASP.NET CORE SIGNALR
Server NuGet Package Microsoft.AspNet.SignalR Microsoft.AspNetCore.App (.NET Core)

Microsoft.AspNetCore.SignalR (.NET
Framework)
Client NuGet Packages Microsoft.AspNet.SignalR.Client Microsoft.AspNetCore.SignalR.Client

Microsoft.AspNet.SignalR.JS
Client npm Package signalr @aspnet/signalr
Server App Type ASP.NET (System.Web) or OWIN Self- ASP.NET Core

Host
Supported Server Platforms .NET Framework 4.5 or later .NET Framework 4.6.1 or later
.NET Core 2.1 or later
Feature differences
Automatic reconnects
Automatic reconnects are no longer supported. Previously, SignalR tried to reconnect to the server if the
connection was dropped. Now, if the client is disconnected the user must explicitly start a new connection if they
want to reconnect.
Protocol support
ASP.NET Core SignalR supports JSON, as well as a new binary protocol based on MessagePack. Additionally,
custom protocols can be created.
Differences on the server

The ASP.NET Core SignalR server-side libraries are included in the Microsoft.AspNetCore.App metapackage
package that's part of the ASP.NET Core Web Application template for both Razor and MVC projects.
ASP.NET Core SignalR is an ASP.NET Core middleware, so it must be configured by calling AddSignalR in
To configure routing, map routes to hubs inside the UseSignalR method call in the Startup.Configure method.
{
routes.MapHub<ChatHub>("/hub");
});
Sticky sessions now required

Because of how scale-out worked in ASP.NET SignalR, clients could reconnect and send messages to any server in
the farm. Due to changes to the scale-out model, as well as not supporting reconnects, this is no longer supported.
Once the client connects to the server, it must interact with the same server for the duration of the connection.
Single hub per connection
In ASP.NET Core SignalR, the connection model has been simplified. Connections are made directly to a single
hub, rather than a single connection being used to share access to multiple hubs.
Streaming
ASP.NET Core SignalR now supports streaming data from the hub to the client.
State
The ability to pass arbitrary state between clients and the hub (often called HubState) has been removed, as well as
support for progress messages. There is no counterpart of hub proxies at the moment.
Differences on the client

TypeScript
The ASP.NET Core SignalR client is written in TypeScript. You can write in JavaScript or TypeScript when using
the JavaScript client.
The JavaScript client is hosted at npm
In previous versions, the JavaScript client was obtained through a NuGet package in Visual Studio. For the Core
versions, the @aspnet/signalr npm package contains the JavaScript libraries. This package isn't included in the
ASP.NET Core Web Application template. Use npm to obtain and install the @aspnet/signalr npm package.
npm init -y
jQuery
The dependency on jQuery has been removed, however projects can still use jQuery.
JavaScript client method syntax
The JavaScript syntax has changed from the previous version of SignalR. Rather than using the $connection
object, create a connection using the HubConnectionBuilder API.

.withUrl("/hub")
.build();
Use the on method to specify client methods that the hub can call.
const msg = message.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">");
const encodedMsg = user + " says " + msg;
log(encodedMsg);
});
After creating the client method, start the hub connection. Chain a catch method to log or handle errors.
Hub proxies
Hub proxies are no longer automatically generated. Instead, the method name is passed into the invoke API as a
string.
.NET and other clients
The Microsoft.AspNetCore.SignalR.Client NuGet package contains the .NET client libraries for ASP.NET Core
SignalR.
Use the HubConnectionBuilder to create and build an instance of a connection to a hub.
connection = new HubConnectionBuilder()

.WithUrl("url")
.Build();
Scaleout differences
ASP.NET SignalR supports both SQL Server and Redis. ASP.NET Core SignalR supports both Azure SignalR
Service and Redis.
ASP.NET
SignalR scaleout with Azure Service Bus
SignalR scaleout with Redis
SignalR scaleout with SQL Server
ASP.NET Core
Azure SignalR Service
Hubs
JavaScript client
.NET client
Supported platforms
Test
Unit Testing in .NET Core and .NET Standard
See how to use unit testing in .NET Core and .NET Standard projects.
Integration tests
Learn how integration tests ensure that an app's components function correctly at the infrastructure level,
including the database, file system, and network.
Discover how to create unit tests for Razor Pages apps.
Test controllers
Learn how to test controller logic in ASP.NET Core with Moq and xUnit.
Debug
Learn to debug using Visual Studio
Discover the features of the Visual Studio debugger in a step-by-step walkthrough.
Debugging with Visual Studio Code
Find out about the debugging support built into Visual Studio Code.
Debug ASP.NET Core 2.x source
Learn how to debug .NET Core and ASP.NET Core sources.
Remote debugging
Explore how to set up and configure a Visual Studio 2017 ASP.NET Core app, deploy it to IIS using Azure, and
attach the remote debugger from Visual Studio.
Snapshot debugging
Find out how to collect snapshots on your top-throwing exceptions so that you have the information you need to
diagnose issues in production.
Troubleshoot
Troubleshoot
Understand and troubleshoot warnings and errors with ASP.NET Core projects.
By Luke Latham and Steve Smith

Integration tests ensure that an app's components function correctly at a level that includes the app's supporting
infrastructure, such as the database, file system, and network. ASP.NET Core supports integration tests using a
unit test framework with a test web host and an in-memory test server.
This topic assumes a basic understanding of unit tests. If unfamiliar with test concepts, see the Unit Testing in
.NET Core and .NET Standard topic and its linked content.
The sample app is a Razor Pages app and assumes a basic understanding of Razor Pages. If unfamiliar with
Razor Pages, see the following topics:
NOTE
For testing SPAs, we recommended a tool such as Selenium, which can automate a browser.
Introduction to integration tests

Integration tests evaluate an app's components on a broader level than unit tests. Unit tests are used to test
isolated software components, such as individual class methods. Integration tests confirm that two or more app
components work together to produce an expected result, possibly including every component required to fully
process a request.
These broader tests are used to test the app's infrastructure and whole framework, often including the following
components:
Database
File system
Network appliances
Request-response pipeline
Unit tests use fabricated components, known as fakes or mock objects, in place of infrastructure components.
In contrast to unit tests, integration tests:
Use the actual components that the app uses in production.
Require more code and data processing.
Take longer to run.
Therefore, limit the use of integration tests to the most important infrastructure scenarios. If a behavior can be
tested using either a unit test or an integration test, choose the unit test.
TIP
Don't write integration tests for every possible permutation of data and file access with databases and file systems.
Regardless of how many places across an app interact with databases and file systems, a focused set of read, write, update,
and delete integration tests are usually capable of adequately testing database and file system components. Use unit tests
for routine tests of method logic that interact with these components. In unit tests, the use of infrastructure fakes/mocks
result in faster test execution.
NOTE
In discussions of integration tests, the tested project is frequently called the system under test, or "SUT" for short.
ASP.NET Core integration tests

Integration tests in ASP.NET Core require the following:
A test project is used to contain and execute the tests. The test project has a reference to the tested ASP.NET
Core project, called the system under test (SUT). "SUT" is used throughout this topic to refer to the tested app.
The test project creates a test web host for the SUT and uses a test server client to handle requests and
responses to the SUT.
A test runner is used to execute the tests and report the test results.
Integration tests follow a sequence of events that include the usual Arrange, Act, and Assert test steps:
1. The SUT's web host is configured.
2. A test server client is created to submit requests to the app.
3. The Arrange test step is executed: The test app prepares a request.
4. The Act test step is executed: The client submits the request and receives the response.
5. The Assert test step is executed: The actual response is validated as a pass or fail based on an expected
response.
6. The process continues until all of the tests are executed.
7. The test results are reported.
Usually, the test web host is configured differently than the app's normal web host for the test runs. For example,
a different database or different app settings might be used for the tests.
Infrastructure components, such as the test web host and in-memory test server ( TestServer), are provided or
managed by the Microsoft.AspNetCore.Mvc.Testing package. Use of this package streamlines test creation and
execution.
The Microsoft.AspNetCore.Mvc.Testing package handles the following tasks:
Copies the dependencies file (*.deps) from the SUT into the test project's bin folder.
Sets the content root to the SUT's project root so that static files and pages/views are found when the tests
are executed.
Provides the WebApplicationFactory class to streamline bootstrapping the SUT with TestServer .
The unit tests documentation describes how to set up a test project and test runner, along with detailed
instructions on how to run tests and recommendations for how to name tests and test classes.
NOTE
When creating a test project for an app, separate the unit tests from the integration tests into different projects. This helps
ensure that infrastructure testing components aren't accidently included in the unit tests. Separation of unit and
integration tests also allows control over which set of tests are run.
There's virtually no difference between the configuration for tests of Razor Pages apps and MVC apps. The only
difference is in how the tests are named. In a Razor Pages app, tests of page endpoints are usually named after
the page model class (for example, IndexPageTests to test component integration for the Index page). In an MVC
app, tests are usually organized by controller classes and named after the controllers they test (for example,
HomeControllerTests to test component integration for the Home controller ).
Test app prerequisites

The test project must:
Reference the following packages:
Microsoft.AspNetCore.Mvc.Testing
Specify the Web SDK in the project file ( <Project Sdk="Microsoft.NET.Sdk.Web"> ). The Web SDK is required
when referencing the Microsoft.AspNetCore.App metapackage.
These prerequisites can be seen in the sample app. Inspect the
tests/RazorPagesProject.Tests/RazorPagesProject.Tests.csproj file. The sample app uses the xUnit test framework
and the AngleSharp parser library, so the sample app also references:
xunit
xunit.runner.visualstudio
AngleSharp
Basic tests with the default WebApplicationFactory

WebApplicationFactory<TEntryPoint> is used to create a TestServer for the integration tests. TEntryPoint is the
entry point class of the SUT, usually the Startup class.
Test classes implement a class fixture interface ( IClassFixture ) to indicate the class contains tests and provide
shared object instances across the tests in the class.
Basic test of app endpoints
The following test class, BasicTests , uses the WebApplicationFactory to bootstrap the SUT and provide an
HttpClient to a test method, Get_EndpointsReturnSuccessAndCorrectContentType . The method checks if the
response status code is successful (status codes in the range 200-299) and the Content-Type header is
text/html; charset=utf-8 for several app pages.
CreateClient creates an instance of HttpClient that automatically follows redirects and handles cookies.
public class BasicTests
: IClassFixture<WebApplicationFactory<RazorPagesProject.Startup>>
{
private readonly WebApplicationFactory<RazorPagesProject.Startup> _factory;
public BasicTests(WebApplicationFactory<RazorPagesProject.Startup> factory)

{
_factory = factory;
}
[Theory]
[InlineData("/")]
[InlineData("/Index")]
[InlineData("/About")]
[InlineData("/Privacy")]
[InlineData("/Contact")]
public async Task Get_EndpointsReturnSuccessAndCorrectContentType(string url)
{
// Arrange
var client = _factory.CreateClient();
// Act
var response = await client.GetAsync(url);
// Assert
response.EnsureSuccessStatusCode(); // Status Code 200-299
Assert.Equal("text/html; charset=utf-8",
response.Content.Headers.ContentType.ToString());
}
Test a secure endpoint

Another test in the BasicTests class checks that a secure endpoint redirects an unauthenticated user to the app's
Login page.
In the SUT, the /SecurePage page uses an AuthorizePage convention to apply an AuthorizeFilter to the page. For
more information, see Razor Pages authorization conventions.
services.AddMvc()
{
options.Conventions.AuthorizePage("/SecurePage");
});
In the Get_SecurePageRequiresAnAuthenticatedUser test, a WebApplicationFactoryClientOptions is set to disallow

redirects by setting AllowAutoRedirect to false :
[Fact]
public async Task Get_SecurePageRequiresAnAuthenticatedUser()
{
// Arrange
var client = _factory.CreateClient(
new WebApplicationFactoryClientOptions
{
AllowAutoRedirect = false
});
// Act
var response = await client.GetAsync("/SecurePage");
// Assert
Assert.Equal(HttpStatusCode.Redirect, response.StatusCode);
Assert.StartsWith("http://localhost/Identity/Account/Login",
response.Headers.Location.OriginalString);
}
By disallowing the client to follow the redirect, the following checks can be made:
The status code returned by the SUT can be checked against the expected HttpStatusCode.Redirect result, not
the final status code after the redirect to the Login page, which would be HttpStatusCode.OK.
The Location header value in the response headers is checked to confirm that it starts with
http://localhost/Identity/Account/Login , not the final Login page response, where the Location header
wouldn't be present.
For more information on WebApplicationFactoryClientOptions , see the Client options section.
Customize WebApplicationFactory
Web host configuration can be created independently of the test classes by inheriting from
WebApplicationFactory to create one or more custom factories:
1. Inherit from WebApplicationFactory and override ConfigureWebHost. The IWebHostBuilder allows the
configuration of the service collection with ConfigureServices:
public class CustomWebApplicationFactory<TStartup>
: WebApplicationFactory<RazorPagesProject.Startup>
{
protected override void ConfigureWebHost(IWebHostBuilder builder)
{
{
// Create a new service provider.
var serviceProvider = new ServiceCollection()
.AddEntityFrameworkInMemoryDatabase()
.BuildServiceProvider();
// Add a database context (ApplicationDbContext) using an in-memory

// database for testing.
{
options.UseInMemoryDatabase("InMemoryDbForTesting");
options.UseInternalServiceProvider(serviceProvider);
});
// Build the service provider.

var sp = services.BuildServiceProvider();
// Create a scope to obtain a reference to the database

// context (ApplicationDbContext).
using (var scope = sp.CreateScope())
{
var scopedServices = scope.ServiceProvider;
var db = scopedServices.GetRequiredService<ApplicationDbContext>();
var logger = scopedServices
.GetRequiredService<ILogger<CustomWebApplicationFactory<TStartup>>>();
// Ensure the database is created.

db.Database.EnsureCreated();
try
{
// Seed the database with test data.
Utilities.InitializeDbForTests(db);
}
{
logger.LogError(ex, $"An error occurred seeding the " +
"database with test messages. Error: {ex.Message}");
}
}
});
}
}
Database seeding in the sample app is performed by the InitializeDbForTests method. The method is
described in the Integration tests sample: Test app organization section.
2. Use the custom CustomWebApplicationFactory in test classes. The following example uses the factory in the
IndexPageTests class:
public class IndexPageTests : IClassFixture<CustomWebApplicationFactory<RazorPagesProject.Startup>>
{
private readonly HttpClient _client;
private readonly CustomWebApplicationFactory<RazorPagesProject.Startup> _factory;
public IndexPageTests(
CustomWebApplicationFactory<RazorPagesProject.Startup> factory)
{
_factory = factory;
_client = factory.CreateClient(new WebApplicationFactoryClientOptions
{
});
}
The sample app's client is configured to prevent the HttpClient from following redirects. As explained in
the Test a secure endpoint section, this permits tests to check the result of the app's first response. The
first response is a redirect in many of these tests with a Location header.
3. A typical test uses the HttpClient and helper methods to process the request and the response:
[Fact]
public async Task Post_DeleteAllMessagesHandler_ReturnsRedirectToRoot()
{
// Arrange
var defaultPage = await _client.GetAsync("/");
var content = await HtmlHelpers.GetDocumentAsync(defaultPage);
//Act
var response = await _client.SendAsync(
(IHtmlFormElement)content.QuerySelector("form[id='messages']"),
(IHtmlButtonElement)content.QuerySelector("button[id='deleteAllBtn']"));
// Assert
Assert.Equal(HttpStatusCode.OK, defaultPage.StatusCode);
Assert.Equal("/", response.Headers.Location.OriginalString);
}
Any POST request to the SUT must satisfy the antiforgery check that's automatically made by the app's data
protection antiforgery system. In order to arrange for a test's POST request, the test app must:
1. Make a request for the page.
2. Parse the antiforgery cookie and request validation token from the response.
3. Make the POST request with the antiforgery cookie and request validation token in place.
The SendAsync helper extension methods (Helpers/HttpClientExtensions.cs) and the GetDocumentAsync helper
method (Helpers/HtmlHelpers.cs) in the sample app use the AngleSharp parser to handle the antiforgery check
with the following methods:
GetDocumentAsync – Receives the HttpResponseMessage and returns an IHtmlDocument . GetDocumentAsync
uses a factory that prepares a virtual response based on the original HttpResponseMessage . For more
information, see the AngleSharp documentation.
SendAsync extension methods for the HttpClient compose an HttpRequestMessage and call
SendAsync(HttpRequestMessage) to submit requests to the SUT. Overloads for SendAsync accept the HTML
form ( IHtmlFormElement ) and the following:
Submit button of the form ( IHtmlElement )
Form values collection ( IEnumerable<KeyValuePair<string, string>> )
Submit button ( IHtmlElement ) and form values ( IEnumerable<KeyValuePair<string, string>> )
NOTE
AngleSharp is a third-party parsing library used for demonstration purposes in this topic and the sample app. AngleSharp
isn't supported or required for integration testing of ASP.NET Core apps. Other parsers can be used, such as the Html
Agility Pack (HAP). Another approach is to write code to handle the antiforgery system's request verification token and
antiforgery cookie directly.
Customize the client with WithWebHostBuilder

When additional configuration is required within a test method, WithWebHostBuilder creates a new
WebApplicationFactory with an IWebHostBuilder that is further customized by configuration.
The Post_DeleteMessageHandler_ReturnsRedirectToRoot test method of the sample app demonstrates the use of
WithWebHostBuilder . This test performs a record delete in the database by triggering a form submission in the
SUT.
Because another test in the IndexPageTests class performs an operation that deletes all of the records in the
database and may run before the Post_DeleteMessageHandler_ReturnsRedirectToRoot method, the database is
seeded in this test method to ensure that a record is present for the SUT to delete. Selecting the deleteBtn1
button of the messages form in the SUT is simulated in the request to the SUT:
[Fact]
public async Task Post_DeleteMessageHandler_ReturnsRedirectToRoot()
{
// Arrange
var client = _factory.WithWebHostBuilder(builder =>
{
{
var serviceProvider = services.BuildServiceProvider();
using (var scope = serviceProvider.CreateScope())

{
var scopedServices = scope.ServiceProvider;
var db = scopedServices
.GetRequiredService<ApplicationDbContext>();
var logger = scopedServices
.GetRequiredService<ILogger<IndexPageTests>>();
try
{
Utilities.InitializeDbForTests(db);
}
{
logger.LogError(ex, "An error occurred seeding " +
"the database with test messages. Error: " +
ex.Message);
}
}
});
})
.CreateClient(new WebApplicationFactoryClientOptions
{
});
var defaultPage = await client.GetAsync("/");
//Act
var response = await client.SendAsync(
(IHtmlFormElement)content.QuerySelector("form[id='messages']"),
(IHtmlButtonElement)content.QuerySelector("button[id='deleteBtn1']"));
// Assert
Assert.Equal(HttpStatusCode.OK, defaultPage.StatusCode);
Assert.Equal("/", response.Headers.Location.OriginalString);
}
Client options
The following table shows the default WebApplicationFactoryClientOptions available when creating HttpClient
instances.
OPTION DESCRIPTION DEFAULT
AllowAutoRedirect Gets or sets whether or not true

HttpClient instances should
automatically follow redirect responses.
BaseAddress Gets or sets the base address of http://localhost

HttpClient instances.
OPTION DESCRIPTION DEFAULT
HandleCookies Gets or sets whether HttpClient true

instances should handle cookies.
MaxAutomaticRedirections Gets or sets the maximum number of 7

redirect responses that HttpClient
instances should follow.
Create the WebApplicationFactoryClientOptions class and pass it to the CreateClient method (default values are
shown in the code example):
// Default client option values are shown

var clientOptions = new WebApplicationFactoryClientOptions();
clientOptions.AllowAutoRedirect = true;
clientOptions.BaseAddress = new Uri("http://localhost");
clientOptions.HandleCookies = true;
clientOptions.MaxAutomaticRedirections = 7;
_client = _factory.CreateClient(clientOptions);
Inject mock services

Services can be overridden in a test with a call to ConfigureTestServices on the host builder. To inject mock
services, the SUT must have a Startup class with a Startup.ConfigureServices method.
The sample SUT includes a scoped service that returns a quote. The quote is embedded in a hidden field on the
Index page when the Index page is requested.
Services/IQuoteService.cs:
public interface IQuoteService

{
Task<string> GenerateQuote();
}
Services/QuoteService.cs:
// Quote ©1975 BBC: The Doctor (Tom Baker); Dr. Who: Planet of Evil
// https://www.bbc.co.uk/programmes/p00pyrx6
public class QuoteService : IQuoteService
{
public Task<string> GenerateQuote()
{
return Task.FromResult<string>(
"Come on, Sarah. We've an appointment in London, " +
"and we're already 30,000 years late.");
}
}
Startup.cs:
services.AddScoped<IQuoteService, QuoteService>();
Pages/Index.cshtml.cs:
{
private readonly ApplicationDbContext _db;
private readonly IQuoteService _quoteService;
public IndexModel(ApplicationDbContext db, IQuoteService quoteService)

{
_db = db;
_quoteService = quoteService;
}
[BindProperty]
public Message Message { get; set; }
public IList<Message> Messages { get; private set; }
[TempData]
public string MessageAnalysisResult { get; set; }
public string Quote { get; private set; }

{
Messages = await _db.GetMessagesAsync();
Quote = await _quoteService.GenerateQuote();

}
Pages/Index.cs:
<input id="quote" type="hidden" value="@Model.Quote">
The following markup is generated when the SUT app is run:
<input id="quote" type="hidden" value="Come on, Sarah. We've an appointment in

London, and we're already 30,000 years late.">
To test the service and quote injection in an integration test, a mock service is injected into the SUT by the test.
The mock service replaces the app's QuoteService with a service provided by the test app, called
TestQuoteService :
IntegrationTests.IndexPageTests.cs:
// Quote ©1975 BBC: The Doctor (Tom Baker); Pyramids of Mars

// https://www.bbc.co.uk/programmes/p00pys55
public class TestQuoteService : IQuoteService
{
public Task<string> GenerateQuote()
{
return Task.FromResult<string>(
"Something's interfering with time, Mr. Scarman, " +
"and time is my business.");
}
}
ConfigureTestServices is called, and the scoped service is registered:

[Fact]
public async Task Get_QuoteService_ProvidesQuoteInPage()
{
// Arrange
var client = _factory.WithWebHostBuilder(builder =>
{
builder.ConfigureTestServices(services =>
{
services.AddScoped<IQuoteService, TestQuoteService>();
});
})
.CreateClient();
//Act
var defaultPage = await client.GetAsync("/");
var quoteElement = content.QuerySelector("#quote");
// Assert
Assert.Equal("Something's interfering with time, Mr. Scarman, " +
"and time is my business.", quoteElement.Attributes["value"].Value);
}
The markup produced during the test's execution reflects the quote text supplied by TestQuoteService , thus the
assertion passes:
<input id="quote" type="hidden" value="Something's interfering with time,

Mr. Scarman, and time is my business.">
How the test infrastructure infers the app content root path
The WebApplicationFactory constructor infers the app content root path by searching for a
WebApplicationFactoryContentRootAttribute on the assembly containing the integration tests with a key equal
to the TEntryPoint assembly System.Reflection.Assembly.FullName . In case an attribute with the correct key isn't
found, WebApplicationFactory falls back to searching for a solution file (*.sln) and appends the TEntryPoint
assembly name to the solution directory. The app root directory (the content root path) is used to discover views
and content files.
In most cases, it isn't necessary to explicitly set the app content root, as the search logic usually finds the correct
content root at runtime. In special scenarios where the content root isn't found using the built-in search
algorithm, the app content root can be specified explicitly or by using custom logic. To set the app content root in
those scenarios, call the UseSolutionRelativeContentRoot extension method from the
Microsoft.AspNetCore.TestHost package. Supply the solution's relative path and optional solution file name or
glob pattern (default = *.sln ).
Call the UseSolutionRelativeContentRoot extension method using ONE of the following approaches:
When configuring test classes with WebApplicationFactory , provide a custom configuration with the
IWebHostBuilder:
public IndexPageTests(
WebApplicationFactory<RazorPagesProject.Startup> factory)
{
var _factory = factory.WithWebHostBuilder(builder =>
{
builder.UseSolutionRelativeContentRoot("<SOLUTION-RELATIVE-PATH>");
...
});
}
When configuring test classes with a custom WebApplicationFactory , inherit from WebApplicationFactory
and override ConfigureWebHost:
public class CustomWebApplicationFactory<TStartup>

: WebApplicationFactory<RazorPagesProject.Startup>
{
protected override void ConfigureWebHost(IWebHostBuilder builder)
{
{
builder.UseSolutionRelativeContentRoot("<SOLUTION-RELATIVE-PATH>");
...
});
}
}
Disable shadow copying

Shadow copying causes the tests to execute in a different folder than the output folder. For tests to work
properly, shadow copying must be disabled. The sample app uses xUnit and disables shadow copying for xUnit
by including an xunit.runner.json file with the correct configuration setting. For more information, see
Configuring xUnit.net with JSON.
Add the xunit.runner.json file to root of the test project with the following content:
{
"shadowCopy": false
}
Integration tests sample

The sample app is composed of two apps:
APP PROJECT FOLDER DESCRIPTION
Message app (the SUT) src/RazorPagesProject Allows a user to add, delete one, delete
all, and analyze messages.
Test app tests/RazorPagesProject.Tests Used to integration test the SUT.
The tests can be run using the built-in test features of an IDE, such as Visual Studio. If using Visual Studio Code
or the command line, execute the following command at a command prompt in the
tests/RazorPagesProject.Tests folder:
dotnet test
Message app (SUT ) organization

The SUT is a Razor Pages message system with the following characteristics:
The Index page of the app (Pages/Index.cshtml and Pages/Index.cshtml.cs) provides a UI and page model
methods to control the addition, deletion, and analysis of messages (average words per message).
A message is described by the Message class (Data/Message.cs) with two properties: Id (key) and Text
(message). The Text property is required and limited to 200 characters.
Messages are stored using Entity Framework's in-memory database†.
The app contains a data access layer (DAL ) in its database context class, AppDbContext
(Data/AppDbContext.cs).
If the database is empty on app startup, the message store is initialized with three messages.
The app includes a /SecurePage that can only be accessed by an authenticated user.
†The EF topic, Test with InMemory, explains how to use an in-memory database for tests with MSTest. This topic
uses the xUnit test framework. Test concepts and test implementations across different test frameworks are
similar but not identical.
Although the app doesn't use the repository pattern and isn't an effective example of the Unit of Work (UoW )
pattern, Razor Pages supports these patterns of development. For more information, see Designing the
infrastructure persistence layer, Repository pattern with ASP.NET Core, and Test controller logic (the sample
implements the repository pattern).
Test app organization
The test app is a console app inside the tests/RazorPagesProject.Tests folder.
TEST APP FOLDER DESCRIPTION
BasicTests BasicTests.cs contains test methods for routing, accessing a

secure page by an unauthenticated user, and obtaining a
GitHub user profile and checking the profile's user login.
IntegrationTests IndexPageTests.cs contains the integration tests for the Index

page using custom WebApplicationFactory class.
Helpers/Utilities Utilities.cs contains the InitializeDbForTests

method used to seed the database with test data.
HtmlHelpers.cs provides a method to return an
AngleSharp IHtmlDocument for use by the test
methods.
HttpClientExtensions.cs provide overloads for
SendAsync to submit requests to the SUT.
The test framework is xUnit. Integration tests are conducted using the Microsoft.AspNetCore.TestHost, which
includes the TestServer. Because the Microsoft.AspNetCore.Mvc.Testing package is used to configure the test
host and test server, the TestHost and TestServer packages don't require direct package references in the test
app's project file or developer configuration in the test app.
Seeding the database for testing
Integration tests usually require a small dataset in the database prior to the test execution. For example, a delete
test calls for a database record deletion, so the database must have at least one record for the delete request to
succeed.
The sample app seeds the database with three messages in Utilities.cs that tests can use when they execute:
public static void InitializeDbForTests(ApplicationDbContext db)

{
db.Messages.AddRange(GetSeedingMessages());
db.SaveChanges();
}
public static List<Message> GetSeedingMessages()

{
return new List<Message>()
{
new Message(){ Text = "TEST RECORD: You're standing on my scarf." },
new Message(){ Text = "TEST RECORD: Would you like a jelly baby?" },
new Message(){ Text = "TEST RECORD: To the rational mind, " +
"nothing is inexplicable; only unexplained." }
};
}
Unit tests
Middleware
Test controllers
By Luke Latham
ASP.NET Core supports unit tests of Razor Pages apps. Tests of the data access layer (DAL ) and page models
help ensure:
Parts of a Razor Pages app work independently and together as a unit during app construction.
Classes and methods have limited scopes of responsibility.
Additional documentation exists on how the app should behave.
Regressions, which are errors brought about by updates to the code, are found during automated building
and deployment.
This topic assumes that you have a basic understanding of Razor Pages apps and unit tests. If you're unfamiliar
with Razor Pages apps or test concepts, see the following topics:
Unit testing C# in .NET Core using dotnet test and xUnit
The sample project is composed of two apps:
APP PROJECT FOLDER DESCRIPTION
Message app src/RazorPagesTestSample Allows a user to add, delete one, delete

all, and analyze messages.
Test app tests/RazorPagesTestSample.Tests Used to unit test the message app:

Data access layer (DAL) and Index page
model.
The tests can be run using the built-in test features of an IDE, such as Visual Studio. If using Visual Studio Code
or the command line, execute the following command at a command prompt in the
tests/RazorPagesTestSample.Tests folder:
dotnet test
Message app organization

The message app is a simple Razor Pages message system with the following characteristics:
The Index page of the app (Pages/Index.cshtml and Pages/Index.cshtml.cs) provides a UI and page model
methods to control the addition, deletion, and analysis of messages (average words per message).
A message is described by the Message class (Data/Message.cs) with two properties: Id (key) and Text
(message). The Text property is required and limited to 200 characters.
Messages are stored using Entity Framework's in-memory database†.
The app contains a data access layer (DAL ) in its database context class, AppDbContext
(Data/AppDbContext.cs). The DAL methods are marked virtual , which allows mocking the methods for use
in the tests.
If the database is empty on app startup, the message store is initialized with three messages. These seeded
messages are also used in tests.
†The EF topic, Test with InMemory, explains how to use an in-memory database for tests with MSTest. This topic
uses the xUnit test framework. Test concepts and test implementations across different test frameworks are
similar but not identical.
Although the app doesn't use the repository pattern and isn't an effective example of the Unit of Work (UoW )
pattern, Razor Pages supports these patterns of development. For more information, see Designing the
infrastructure persistence layer, Repository pattern with ASP.NET Core, and Test controller logic (the sample
implements the repository pattern).
Test app organization

The test app is a console app inside the tests/RazorPagesTestSample.Tests folder.
TEST APP FOLDER DESCRIPTION
UnitTests DataAccessLayerTest.cs contains the unit tests for the

DAL.
IndexPageTests.cs contains the unit tests for the Index
page model.
Utilities Contains the TestingDbContextOptions method used to

create new database context options for each DAL unit test
so that the database is reset to its baseline condition for each
test.
The test framework is xUnit. The object mocking framework is Moq.
Unit tests of the data access layer (DAL)

The message app has a DAL with four methods contained in the AppDbContext class
(src/RazorPagesTestSample/Data/AppDbContext.cs). Each method has one or two unit tests in the test app.
DAL METHOD FUNCTION
GetMessagesAsync Obtains a List<Message> from the database sorted by the

Text property.
AddMessageAsync Adds a Message to the database.
DeleteAllMessagesAsync Deletes all Message entries from the database.
DeleteMessageAsync Deletes a single Message from the database by Id .
Unit tests of the DAL require DbContextOptions when creating a new AppDbContext for each test. One approach
to creating the DbContextOptions for each test is to use a DbContextOptionsBuilder:
var optionsBuilder = new DbContextOptionsBuilder<AppDbContext>()
.UseInMemoryDatabase("InMemoryDb");
using (var db = new AppDbContext(optionsBuilder.Options))

{
// Use the db here in the unit test.
}
The problem with this approach is that each test receives the database in whatever state the previous test left it.
This can be problematic when trying to write atomic unit tests that don't interfere with each other. To force the
AppDbContext to use a new database context for each test, supply a DbContextOptions instance that's based on a
new service provider. The test app shows how to do this using its Utilities class method
TestingDbContextOptions (tests/RazorPagesTestSample.Tests/Utilities/Utilities.cs):
public static DbContextOptions<AppDbContext> TestDbContextOptions()

{
// Create a new service provider to create a new in-memory database.
var serviceProvider = new ServiceCollection()
.AddEntityFrameworkInMemoryDatabase()
.BuildServiceProvider();
// Create a new options instance using an in-memory database and

// IServiceProvider that the context should resolve all of its
// services from.
var builder = new DbContextOptionsBuilder<AppDbContext>()
.UseInMemoryDatabase("InMemoryDb")
.UseInternalServiceProvider(serviceProvider);
return builder.Options;
}
Using the DbContextOptions in the DAL unit tests allows each test to run atomically with a fresh database
instance:
using (var db = new AppDbContext(Utilities.TestingDbContextOptions()))

{
// Use the db here in the unit test.
}
Each test method in the DataAccessLayerTest class (UnitTests/DataAccessLayerTest.cs) follows a similar Arrange-
Act-Assert pattern:
1. Arrange: The database is configured for the test and/or the expected outcome is defined.
2. Act: The test is executed.
3. Assert: Assertions are made to determine if the test result is a success.
For example, the DeleteMessageAsync method is responsible for removing a single message identified by its Id
(src/RazorPagesTestSample/Data/AppDbContext.cs):
public async virtual Task DeleteMessageAsync(int id)
{
var message = await Messages.FindAsync(id);
if (message != null)
{
Messages.Remove(message);
await SaveChangesAsync();
}
}
There are two tests for this method. One test checks that the method deletes a message when the message is
present in the database. The other method tests that the database doesn't change if the message Id for deletion
doesn't exist. The DeleteMessageAsync_MessageIsDeleted_WhenMessageIsFound method is shown below:
[Fact]
public async Task DeleteMessageAsync_MessageIsDeleted_WhenMessageIsFound()
{
using (var db = new AppDbContext(Utilities.TestDbContextOptions()))
{
// Arrange
var seedMessages = AppDbContext.GetSeedingMessages();
await db.AddRangeAsync(seedMessages);
var recId = 1;
var expectedMessages =
seedMessages.Where(message => message.Id != recId).ToList();
// Act
await db.DeleteMessageAsync(recId);
// Assert
var actualMessages = await db.Messages.AsNoTracking().ToListAsync();
Assert.Equal(
expectedMessages.OrderBy(x => x.Id),
actualMessages.OrderBy(x => x.Id),
new Utilities.MessageComparer());
}
}
First, the method performs the Arrange step, where preparation for the Act step takes place. The seeding
messages are obtained and held in seedMessages . The seeding messages are saved into the database. The
message with an Id of 1 is set for deletion. When the DeleteMessageAsync method is executed, the expected
messages should have all of the messages except for the one with an Id of 1 . The expectedMessages variable
represents this expected outcome.
// Arrange
var seedMessages = AppDbContext.GetSeedingMessages();
await db.AddRangeAsync(seedMessages);
var recId = 1;
var expectedMessages =
seedMessages.Where(message => message.Id != recId).ToList();
The method acts: The DeleteMessageAsync method is executed passing in the recId of 1 :
// Act
Finally, the method obtains the Messages from the context and compares it to the expectedMessages asserting
that the two are equal:
// Assert
Assert.Equal(
expectedMessages.OrderBy(m => m.Id).Select(m => m.Text),
actualMessages.OrderBy(m => m.Id).Select(m => m.Text));
In order to compare that the two List<Message> are the same:

The messages are ordered by Id .
Message pairs are compared on the Text property.
A similar test method, DeleteMessageAsync_NoMessageIsDeleted_WhenMessageIsNotFound checks the result of
attempting to delete a message that doesn't exist. In this case, the expected messages in the database should be
equal to the actual messages after the DeleteMessageAsync method is executed. There should be no change to the
database's content:
[Fact]
public async Task DeleteMessageAsync_NoMessageIsDeleted_WhenMessageIsNotFound()
{
using (var db = new AppDbContext(Utilities.TestDbContextOptions()))
{
// Arrange
var expectedMessages = AppDbContext.GetSeedingMessages();
await db.AddRangeAsync(expectedMessages);
var recId = 4;
// Act
// Assert
Assert.Equal(
}
}
Unit tests of the page model methods

Another set of unit tests is responsible for tests of page model methods. In the message app, the Index page
models are found in the IndexModel class in src/RazorPagesTestSample/Pages/Index.cshtml.cs.
PAGE MODEL METHOD FUNCTION
OnGetAsync Obtains the messages from the DAL for the UI using the
GetMessagesAsync method.
OnPostAddMessageAsync If the ModelState is valid, calls AddMessageAsync to add a

message to the database.
OnPostDeleteAllMessagesAsync Calls DeleteAllMessagesAsync to delete all of the messages

in the database.
PAGE MODEL METHOD FUNCTION
OnPostDeleteMessageAsync Executes DeleteMessageAsync to delete a message with the

Id specified.
OnPostAnalyzeMessagesAsync If one or more messages are in the database, calculates the

average number of words per message.
The page model methods are tested using seven tests in the IndexPageTests class
(tests/RazorPagesTestSample.Tests/UnitTests/IndexPageTests.cs). The tests use the familiar Arrange-Assert-Act
pattern. These tests focus on:
Determining if the methods follow the correct behavior when the ModelState is invalid.
Confirming the methods produce the correct IActionResult .
Checking that property value assignments are made correctly.
This group of tests often mock the methods of the DAL to produce expected data for the Act step where a page
model method is executed. For example, the GetMessagesAsync method of the AppDbContext is mocked to
produce output. When a page model method executes this method, the mock returns the result. The data doesn't
come from the database. This creates predictable, reliable test conditions for using the DAL in the page model
tests.
The OnGetAsync_PopulatesThePageModel_WithAListOfMessages test shows how the GetMessagesAsync method is
mocked for the page model:
var mockAppDbContext = new Mock<AppDbContext>(optionsBuilder.Options);

mockAppDbContext.Setup(
db => db.GetMessagesAsync()).Returns(Task.FromResult(expectedMessages));
var pageModel = new IndexModel(mockAppDbContext.Object);
When the OnGetAsync method is executed in the Act step, it calls the page model's GetMessagesAsync method.
Unit test Act step (tests/RazorPagesTestSample.Tests/UnitTests/IndexPageTests.cs):
// Act
await pageModel.OnGetAsync();
IndexPage page model's OnGetAsync method (src/RazorPagesTestSample/Pages/Index.cshtml.cs):

{
Messages = await _db.GetMessagesAsync();
}
The GetMessagesAsync method in the DAL doesn't return the result for this method call. The mocked version of
the method returns the result.
In the Assert step, the actual messages ( actualMessages ) are assigned from the Messages property of the page
model. A type check is also performed when the messages are assigned. The expected and actual messages are
compared by their Text properties. The test asserts that the two List<Message> instances contain the same
messages.
// Assert
var actualMessages = Assert.IsAssignableFrom<List<Message>>(pageModel.Messages);
Assert.Equal(
Other tests in this group create page model objects that include the DefaultHttpContext , the
ModelStateDictionary , an ActionContext to establish the PageContext , a ViewDataDictionary , and a PageContext .
These are useful in conducting tests. For example, the message app establishes a ModelState error with
AddModelError to check that a valid PageResult is returned when OnPostAddMessageAsync is executed:
[Fact]
public async Task OnPostAddMessageAsync_ReturnsAPageResult_WhenModelStateIsInvalid()
{
// Arrange
var optionsBuilder = new DbContextOptionsBuilder<AppDbContext>()
.UseInMemoryDatabase("InMemoryDb");
var mockAppDbContext = new Mock<AppDbContext>(optionsBuilder.Options);
mockAppDbContext.Setup(db => db.GetMessagesAsync()).Returns(Task.FromResult(expectedMessages));
var httpContext = new DefaultHttpContext();
var modelState = new ModelStateDictionary();
var actionContext = new ActionContext(httpContext, new RouteData(), new PageActionDescriptor(),
modelState);
var modelMetadataProvider = new EmptyModelMetadataProvider();
var viewData = new ViewDataDictionary(modelMetadataProvider, modelState);
var tempData = new TempDataDictionary(httpContext, Mock.Of<ITempDataProvider>());
var pageContext = new PageContext(actionContext)
{
ViewData = viewData
};
var pageModel = new IndexModel(mockAppDbContext.Object)
{
PageContext = pageContext,
TempData = tempData,
Url = new UrlHelper(actionContext)
};
pageModel.ModelState.AddModelError("Message.Text", "The Text field is required.");
// Act
var result = await pageModel.OnPostAddMessageAsync();
// Assert
Assert.IsType<PageResult>(result);
}
Unit testing C# in .NET Core using dotnet test and xUnit
Test controllers
Unit Test Your Code (Visual Studio)
Integration tests
xUnit.net
Getting started with xUnit.net (.NET Core/ASP.NET Core)
Moq
Moq Quickstart
Test controller logic in ASP.NET Core
By Steve Smith
Controllers play a central role in any ASP.NET Core MVC app. As such, you should have confidence that
controllers behave as intended. Automated tests can detect errors before the app is deployed to a production
environment.
Unit tests of controller logic

Unit tests involve testing a part of an app in isolation from its infrastructure and dependencies. When unit testing
controller logic, only the contents of a single action are tested, not the behavior of its dependencies or of the
framework itself.
Set up unit tests of controller actions to focus on the controller's behavior. A controller unit test avoids scenarios
such as filters, routing, and model binding. Tests that cover the interactions among components that collectively
respond to a request are handled by integration tests. For more information on integration tests, see Integration
tests in ASP.NET Core.
If you're writing custom filters and routes, unit test them in isolation, not as part of tests on a particular controller
action.
To demonstrate controller unit tests, review the following controller in the sample app. The Home controller
displays a list of brainstorming sessions and allows the creation of new brainstorming sessions with a POST
request:
{
public HomeController(IBrainstormSessionRepository sessionRepository)

{
}

{
var sessionList = await _sessionRepository.ListAsync();
var model = sessionList.Select(session => new StormSessionViewModel()

{
Id = session.Id,
IdeaCount = session.Ideas.Count
});
return View(model);
}
public class NewSessionModel

{
[Required]
public string SessionName { get; set; }
}
[HttpPost]
public async Task<IActionResult> Index(NewSessionModel model)
{
{
}
else
{
await _sessionRepository.AddAsync(new BrainstormSession()
{
Name = model.SessionName
});
}
return RedirectToAction(actionName: nameof(Index));

}
}
The preceding controller:

Follows the Explicit Dependencies Principle.
Expects dependency injection (DI) to provide an instance of IBrainstormSessionRepository .
Can be tested with a mocked IBrainstormSessionRepository service using a mock object framework, such as
Moq. A mocked object is a fabricated object with a predetermined set of property and method behaviors used
for testing. For more information, see Introduction to integration tests.
The HTTP GET Index method has no looping or branching and only calls one method. The unit test for this action:
Mocks the IBrainstormSessionRepository service using the GetTestSessions method. GetTestSessions
creates two mock brainstorm sessions with dates and session names.
Executes the Index method.
Makes assertions on the result returned by the method:
A ViewResult is returned.
The ViewDataDictionary.Model is a StormSessionViewModel .
There are two brainstorming sessions stored in the ViewDataDictionary.Model .
[Fact]
public async Task Index_ReturnsAViewResult_WithAListOfBrainstormSessions()
{
// Arrange
// Act
var result = await controller.Index();
// Assert
var model = Assert.IsAssignableFrom<IEnumerable<StormSessionViewModel>>(
Assert.Equal(2, model.Count());
}
private List<BrainstormSession> GetTestSessions()

{
var sessions = new List<BrainstormSession>();
{
Id = 1,
Name = "Test One"
});
{
Id = 2,
Name = "Test Two"
});
return sessions;
}
The Home controller's HTTP POST Index method tests verifies that:
When ModelState.IsValid is false , the action method returns a 400 Bad Request ViewResult with the
appropriate data.
When ModelState.IsValid is true :
The Add method on the repository is called.
A RedirectToActionResult is returned with the correct arguments.
An invalid model state is tested by adding errors using AddModelError as shown in the first test below:
[Fact]
public async Task IndexPost_ReturnsBadRequestResult_WhenModelStateIsInvalid()
{
// Arrange
controller.ModelState.AddModelError("SessionName", "Required");
var newSession = new HomeController.NewSessionModel();
// Act
// Assert
var badRequestResult = Assert.IsType<BadRequestObjectResult>(result);
Assert.IsType<SerializableError>(badRequestResult.Value);
}
[Fact]
public async Task IndexPost_ReturnsARedirectAndAddsSession_WhenModelStateIsValid()
{
// Arrange
mockRepo.Setup(repo => repo.AddAsync(It.IsAny<BrainstormSession>()))
.Verifiable();
var newSession = new HomeController.NewSessionModel()
{
SessionName = "Test Name"
};
// Act
// Assert
var redirectToActionResult = Assert.IsType<RedirectToActionResult>(result);
Assert.Null(redirectToActionResult.ControllerName);
mockRepo.Verify();
}
When ModelState isn't valid, the same ViewResult is returned as for a GET request. The test doesn't attempt to
pass in an invalid model. Passing an invalid model isn't a valid approach, since model binding isn't running
(although an integration test does use model binding). In this case, model binding isn't tested. These unit tests
are only testing the code in the action method.
The second test verifies that when the ModelState is valid:
A new BrainstormSession is added (via the repository).
The method returns a RedirectToActionResult with the expected properties.
Mocked calls that aren't called are normally ignored, but calling Verifiable at the end of the setup call allows
mock validation in the test. This is performed with the call to mockRepo.Verify , which fails the test if the expected
method wasn't called.
NOTE
The Moq library used in this sample makes it possible to mix verifiable, or "strict", mocks with non-verifiable mocks (also
called "loose" mocks or stubs). Learn more about customizing Mock behavior with Moq.
Another controller in the sample app displays information related to a particular brainstorming session. The
controller includes logic to deal with invalid id values (there are two return scenarios in the following example
to cover these scenarios). The final return statement returns a new StormSessionViewModel to the view:
public class SessionController : Controller

{
public SessionController(IBrainstormSessionRepository sessionRepository)

{
}
public async Task<IActionResult> Index(int? id)

{
if (!id.HasValue)
{
return RedirectToAction(actionName: nameof(Index),
controllerName: "Home");
}
var session = await _sessionRepository.GetByIdAsync(id.Value);

{
return Content("Session not found.");
}
var viewModel = new StormSessionViewModel()

{
Id = session.Id
};
}
}
The unit tests include one test for each return scenario in the Session controller Index action:
[Fact]
public async Task IndexReturnsARedirectToIndexHomeWhenIdIsNull()
{
// Arrange
var controller = new SessionController(sessionRepository: null);
// Act
var result = await controller.Index(id: null);
// Assert
var redirectToActionResult =
Assert.IsType<RedirectToActionResult>(result);
Assert.Equal("Home", redirectToActionResult.ControllerName);
}
[Fact]
public async Task IndexReturnsContentWithSessionNotFoundWhenSessionNotFound()
{
// Arrange
// Act
// Assert
var contentResult = Assert.IsType<ContentResult>(result);
Assert.Equal("Session not found.", contentResult.Content);
}
[Fact]
public async Task IndexReturnsViewResultWithStormSessionViewModel()
{
// Arrange
.ReturnsAsync(GetTestSessions().FirstOrDefault(
s => s.Id == testSessionId));
// Act
// Assert
var model = Assert.IsType<StormSessionViewModel>(
Assert.Equal("Test One", model.Name);
Assert.Equal(2, model.DateCreated.Day);
Assert.Equal(testSessionId, model.Id);
}
Moving to the Ideas controller, the app exposes functionality as a web API on the api/ideas route:
A list of ideas ( IdeaDTO ) associated with a brainstorming session is returned by the ForSession method.
The Create method adds new ideas to a session.
[HttpGet("forsession/{sessionId}")]
public async Task<IActionResult> ForSession(int sessionId)
{
{
}

{
Id = idea.Id,
Name = idea.Name,
}).ToList();
return Ok(result);
}
[HttpPost("create")]
public async Task<IActionResult> Create([FromBody]NewIdeaModel model)
{
{
}

{
}

{
Name = model.Name
};
return Ok(session);
}
Avoid returning business domain entities directly via API calls. Domain entities:
Often include more data than the client requires.
Unnecessarily couple the app's internal domain model with the publicly exposed API.
Mapping between domain entities and the types returned to the client can be performed:
Manually with a LINQ Select , as the sample app uses. For more information, see LINQ (Language
Integrated Query).
Automatically with a library, such as AutoMapper.
Next, the sample app demonstrates unit tests for the Create and ForSession API methods of the Ideas
controller.
The sample app contains two ForSession tests. The first test determines if ForSession returns a
NotFoundObjectResult (HTTP Not Found) for an invalid session:
[Fact]
public async Task ForSession_ReturnsHttpNotFound_ForInvalidSession()
{
// Arrange
// Act
// Assert
var notFoundObjectResult = Assert.IsType<NotFoundObjectResult>(result);
Assert.Equal(testSessionId, notFoundObjectResult.Value);
}
The second ForSession test determines if ForSession returns a list of session ideas ( <List<IdeaDTO>> ) for a valid
session. The checks also examine the first idea to confirm its Name property is correct:
[Fact]
public async Task ForSession_ReturnsIdeasForSession()
{
// Arrange
// Act
// Assert
var returnValue = Assert.IsType<List<IdeaDTO>>(okResult.Value);
}
To test the behavior of the Create method when the ModelState is invalid, the sample app adds a model error to
the controller as part of the test. Don't try to test model validation or model binding in unit tests—just test the
action method's behavior when confronted with an invalid ModelState :
[Fact]
public async Task Create_ReturnsBadRequest_GivenInvalidModel()
{
// Arrange & Act
// Act
var result = await controller.Create(model: null);
// Assert
Assert.IsType<BadRequestObjectResult>(result);
}
The second test of Create depends on the repository returning null , so the mock repository is configured to
return null . There's no need to create a test database (in memory or otherwise) and construct a query that
returns this result. The test can be accomplished in a single statement, as the sample code illustrates:
[Fact]
public async Task Create_ReturnsHttpNotFound_ForInvalidSession()
{
// Arrange
// Act
var result = await controller.Create(new NewIdeaModel());
// Assert
Assert.IsType<NotFoundObjectResult>(result);
}
The third Create test, Create_ReturnsNewlyCreatedIdeaForSession , verifies that the repository's UpdateAsync
method is called. The mock is called with Verifiable , and the mocked repository's Verify method is called to
confirm the verifiable method is executed. It's not the unit test's responsibility to ensure that the UpdateAsync
method saved the data—that can be performed with an integration test.
[Fact]
public async Task Create_ReturnsNewlyCreatedIdeaForSession()
{
// Arrange

{
Name = testName,
};
.Verifiable();
// Act
var result = await controller.Create(newIdea);
// Assert
var returnSession = Assert.IsType<BrainstormSession>(okResult.Value);
mockRepo.Verify();
Assert.Equal(2, returnSession.Ideas.Count());
Assert.Equal(testName, returnSession.Ideas.LastOrDefault().Name);
Assert.Equal(testDescription, returnSession.Ideas.LastOrDefault().Description);
}
Test ActionResult<T>
In ASP.NET Core 2.1 or later, ActionResult<T> (ActionResult<TValue>) enables you to return a type deriving
from ActionResult or return a specific type.
The sample app includes a method that returns a List<IdeaDTO> for a given session id . If the session id
doesn't exist, the controller returns NotFound:
[HttpGet("forsessionactionresult/{sessionId}")]
public async Task<ActionResult<List<IdeaDTO>>> ForSessionActionResult(int sessionId)
{
{
}

{
Id = idea.Id,
Name = idea.Name,
}).ToList();
return result;
}
Two tests of the ForSessionActionResult controller are included in the ApiIdeasControllerTests .

The first test confirms that the controller returns an ActionResult but not a nonexistent list of ideas for a
nonexistent session id :
The ActionResult type is ActionResult<List<IdeaDTO>> .
The Result is a NotFoundObjectResult.
[Fact]
public async Task ForSessionActionResult_ReturnsNotFoundObjectResultForNonexistentSession()
{
// Arrange
// Act
var result = await controller.ForSessionActionResult(nonExistentSessionId);
// Assert
}
For for a valid session id , the second test confirms that the method returns:
An ActionResult with a List<IdeaDTO> type.
The ActionResult<T>.Value is a List<IdeaDTO> type.
The first item in the list is a valid idea matching the idea stored in the mock session (obtained by calling
GetTestSession ).
[Fact]
public async Task ForSessionActionResult_ReturnsIdeasForSession()
{
// Arrange
// Act
var result = await controller.ForSessionActionResult(testSessionId);
// Assert
var returnValue = Assert.IsType<List<IdeaDTO>>(actionResult.Value);
}
The sample app also includes a method to create a new Idea for a given session. The controller returns:
BadRequest for an invalid model.
NotFound if the session doesn't exist.
CreatedAtAction when the session is updated with the new idea.
[HttpPost("createactionresult")]
public async Task<ActionResult<BrainstormSession>> CreateActionResult([FromBody]NewIdeaModel model)
{
{
}
{
}

{
Name = model.Name
};
return CreatedAtAction(nameof(CreateActionResult), new { id = session.Id }, session);

}
Three tests of CreateActionResult are included in the ApiIdeasControllerTests .

The first text confirms that a BadRequest is returned for an invalid model.
[Fact]
public async Task CreateActionResult_ReturnsBadRequest_GivenInvalidModel()
{
// Arrange & Act
// Act
var result = await controller.CreateActionResult(model: null);
// Assert
Assert.IsType<BadRequestObjectResult>(actionResult.Result);
}
The second test checks that a NotFound is returned if the session doesn't exist.
[Fact]
public async Task CreateActionResult_ReturnsNotFoundObjectResultForNonexistentSession()
{
// Arrange

{
Name = testName,
SessionId = nonExistentSessionId
};
// Act
// Assert
}
For a valid session id , the final test confirms that:

The method returns an ActionResult with a BrainstormSession type.
The ActionResult<T>.Result is a CreatedAtActionResult. CreatedAtActionResult is analogous to a 201
Created response with a Location header.
The ActionResult<T>.Value is a BrainstormSession type.
The mock call to update the session, UpdateAsync(testSession) , was invoked. The Verifiable method call is
checked by executing mockRepo.Verify() in the assertions.
Two Idea objects are returned for the session.
The last item (the Idea added by the mock call to UpdateAsync ) matches the newIdea added to the session in
the test.
[Fact]
public async Task CreateActionResult_ReturnsNewlyCreatedIdeaForSession()
{
// Arrange

{
Name = testName,
};
.Verifiable();
// Act
// Assert
var createdAtActionResult = Assert.IsType<CreatedAtActionResult>(actionResult.Result);
var returnValue = Assert.IsType<BrainstormSession>(createdAtActionResult.Value);
mockRepo.Verify();
Assert.Equal(2, returnValue.Ideas.Count());
Assert.Equal(testName, returnValue.Ideas.LastOrDefault().Name);
Assert.Equal(testDescription, returnValue.Ideas.LastOrDefault().Description);
}
Create and run unit tests with Visual Studio.
Troubleshoot ASP.NET Core projects
By Rick Anderson
The following links provide troubleshooting guidance:
NDC Conference (London, 2018): Diagnosing issues in ASP.NET Core Applications
ASP.NET Blog: Troubleshooting ASP.NET Core Performance Problems
.NET Core SDK warnings

Both the 32 bit and 64 bit versions of the .NET Core SDK are installed
In the New Project dialog for ASP.NET Core, you may see the following warning:
Both 32 and 64 bit versions of the .NET Core SDK are installed. Only templates from the 64 bit version(s)
installed at 'C:\Program Files\dotnet\sdk\' will be displayed.
This warning appears when both 32-bit (x86) and 64-bit (x64) versions of the .NET Core SDK are installed.
Common reasons both versions may be installed include:
You originally downloaded the .NET Core SDK installer using a 32-bit machine but then copied it across and
installed it on a 64-bit machine.
The 32-bit .NET Core SDK was installed by another application.
The wrong version was downloaded and installed.
Uninstall the 32-bit .NET Core SDK to prevent this warning. Uninstall from Control Panel > Programs and
Features > Uninstall or change a program. If you understand why the warning occurs and its implications, you
can ignore the warning.
The .NET Core SDK is installed in multiple locations
The .NET Core SDK is installed in multiple locations. Only templates from the SDK(s) installed at 'C:\Program
Files\dotnet\sdk\' will be displayed.
You see this message when you have at least one installation of the .NET Core SDK in a directory outside of
C:\Program Files\dotnet\sdk\. Usually this happens when the .NET Core SDK has been deployed on a machine
using copy/paste instead of the MSI installer.
Uninstall the 32-bit .NET Core SDK to prevent this warning. Uninstall from Control Panel > Programs and
Features > Uninstall or change a program. If you understand why the warning occurs and its implications, you
can ignore the warning.
No .NET Core SDKs were detected
No .NET Core SDKs were detected, ensure they are included in the environment variable 'PATH'.
This warning appears when the environment variable PATH doesn't point to any .NET Core SDKs on the machine.
To resolve this problem:
Install or verify the .NET Core SDK is installed.
Verify that the PATH environment variable points to the location in which the SDK is installed. The installer
normally sets the PATH .
Get started with Razor Pages and Entity Framework Core using Visual Studio
Get started with Razor Pages and EF
Migrations
Read related data
Update related data
Get started with ASP.NET Core MVC and Entity Framework Core using Visual Studio
Get started
Migrations
Read related data
Update related data
Inheritance
Advanced topics
ASP.NET Core with EF Core - new database (Entity Framework Core documentation site)
ASP.NET Core with EF Core - existing database (Entity Framework Core documentation site)
Azure Storage
Get started with Azure Blob storage and Visual Studio Connected Services
Get started with Queue Storage and Visual Studio Connected Services
Get started with Azure Table Storage and Visual Studio Connected Services
Razor Pages with Entity Framework Core in
ASP.NET Core - Tutorial 1 of 8
The Contoso University sample web app demonstrates how to create an ASP.NET Core Razor Pages
app using Entity Framework (EF ) Core.
The sample app is a web site for a fictional Contoso University. It includes functionality such as student
admission, course creation, and instructor assignments. This page is the first in a series of tutorials that
explain how to build the Contoso University sample app.
Download or view the completed app. Download instructions.
Prerequisites
Visual Studio
.NET Core CLI
Familiarity with Razor Pages. New programmers should complete Get started with Razor Pages before
starting this series.
Troubleshooting
If you run into a problem you can't resolve, you can generally find the solution by comparing your code
to the completed project. A good way to get help is by posting a question to StackOverflow.com for
ASP.NET Core or EF Core.
The Contoso University web app

The app built in these tutorials is a basic university web site.
Users can view and update student, course, and instructor information. Here are a few of the screens
created in the tutorial.
The UI style of this site is close to what's generated by the built-in templates. The tutorial focus is on EF
Core with Razor Pages, not the UI.
Create the ContosoUniversity Razor Pages web app

Visual Studio
.NET Core CLI
Create a new ASP.NET Core Web Application. Name the project ContosoUniversity. It's important
to name the project ContosoUniversity so the namespaces match when code is copy/pasted.
For images of the preceding steps, see Create a Razor web app. Run the app.

A few changes set up the site menu, layout, and home page. Update Pages/Shared/_Layout.cshtml with
the following changes:
Change each occurrence of "ContosoUniversity" to "Contoso University". There are three
occurrences.
Add menu entries for Students, Courses, Instructors, and Departments, and delete the
Contact menu entry.
The changes are highlighted. (All the markup is not displayed.)
<!DOCTYPE html>
<html>
<head>
<title>@ViewData["Title"] : Contoso University</title>
</environment>
href="https://ajax.aspnetcdn.com/ajax/bootstrap/3.3.7/css/bootstrap.min.css"
asp-fallback-test-class="sr-only" asp-fallback-test-property="position" asp-fallback-
test-value="absolute" />
</environment>
</head>
<body>
target=".navbar-collapse">
</button>
<a asp-page="/Index" class="navbar-brand">Contoso University</a>
</div>
<li><a asp-page="/Students/Index">Students</a></li>
<li><a asp-page="/Courses/Index">Courses</a></li>
<li><a asp-page="/Instructors/Index">Instructors</a></li>
<li><a asp-page="/Departments/Index">Departments</a></li>
</ul>
</div>
</div>
</nav>

@RenderBody()
<hr />
<footer>
<p>© 2018 : Contoso University</p>
</footer>
</div>
@*Remaining markup not shown for brevity.*@
In Pages/Index.cshtml, replace the contents of the file with the following code to replace the text about
ASP.NET and MVC with text about this app:
@page
@model IndexModel
@{
ViewData["Title"] = "Home page";
}
</div>
<div class="row">
<p>
ASP.NET Core Razor Pages web app.
</p>
</div>
<p>
href="https://docs.microsoft.com/aspnet/core/data/ef-rp/intro">
See the tutorial »
</a>
</p>
</div>
<p>
href="https://github.com/aspnet/Docs/tree/master/aspnetcore/data/ef-
rp/intro/samples/cu-final">
See project source code »
</a>
</p>
</div>
</div>

Create entity classes for the Contoso University app. Start with the following three entities:
There's a one-to-many relationship between Student and Enrollment entities. There's a one-to-many
relationship between Course and Enrollment entities. A student can enroll in any number of courses. A
course can have any number of students enrolled in it.
In the following sections, a class for each one of these entities is created.
The Student entity
Create a Models folder. In the Models folder, create a class file named Student.cs with the following code:
using System;
{
{

}
}
The ID property becomes the primary key column of the database (DB ) table that corresponds to this
class. By default, EF Core interprets a property that's named ID or classnameID as the primary key. In
classnameID , classname is the name of the class. The alternative automatically recognized primary key
is StudentID in the preceding example.
The Enrollments property is a navigation property. Navigation properties link to other entities that are
related to this entity. In this case, the Enrollments property of a Student entity holds all of the
Enrollment entities that are related to that Student . For example, if a Student row in the DB has two
related Enrollment rows, the Enrollments navigation property contains those two Enrollment entities. A
related Enrollment row is a row that contains that student's primary key value in the StudentID column.
For example, suppose the student with ID=1 has two rows in the Enrollment table. The Enrollment
table has two rows with StudentID = 1. StudentID is a foreign key in the Enrollment table that specifies
the student in the Student table.
If a navigation property can hold multiple entities, the navigation property must be a list type, such as
ICollection<T> . ICollection<T> can be specified, or a type such as List<T> or HashSet<T> . When
ICollection<T> is used, EF Core creates a HashSet<T> collection by default. Navigation properties that
hold multiple entities come from many-to-many and one-to-many relationships.
In the Models folder, create Enrollment.cs with the following code:
{
public enum Grade
{
A, B, C, D, F
}

{

}
}
The EnrollmentID property is the primary key. This entity uses the classnameID pattern instead of ID
like the Student entity. Typically developers choose one pattern and use it throughout the data model.
In a later tutorial, using ID without classname is shown to make it easier to implement inheritance in the
data model.
The property is an enum . The question mark after the Grade type declaration indicates that the
Grade
Grade property is nullable. A grade that's null is different from a zero grade -- null means a grade isn't
known or hasn't been assigned yet.
The StudentIDproperty is a foreign key, and the corresponding navigation property is Student . An
Enrollment entity is associated with one Student entity, so the property contains a single Student
entity. The Student entity differs from the Student.Enrollments navigation property, which contains
multiple Enrollment entities.
The CourseID property is a foreign key, and the corresponding navigation property is Course . An
Enrollment entity is associated with one Course entity.
EF Core interprets a property as a foreign key if it's named
<navigation property name><primary key property name> . For example, StudentID for the Student
navigation property, since the Student entity's primary key is ID . Foreign key properties can also be
named <primary key property name> . For example, CourseID since the Course entity's primary key is
CourseID .
The Course entity
In the Models folder, create Course.cs with the following code:

{
public class Course
{

}
}
The Enrollments property is a navigation property. A Course entity can be related to any number of
Enrollment entities.
The DatabaseGenerated attribute allows the app to specify the primary key rather than having the DB
generate it.
Scaffold the student model

In this section, the student model is scaffolded. That is, the scaffolding tool produces pages for Create,
Read, Update, and Delete (CRUD ) operations for the student model.
Build the project.
Create the Pages/Students folder.
Visual Studio
.NET Core CLI
In Solution Explorer, right click on the Pages/Students folder > Add > New Scaffolded Item.
In the Model class drop-down, select Student (ContosoUniversity.Models).
In the Data context class row, select the + (plus) sign and change the generated name to
ContosoUniversity.Models.SchoolContext.
In the Data context class drop-down, select ContosoUniversity.Models.SchoolContext
Select Add.
See Scaffold the movie model if you have a problem with the preceding step.
Files created
Pages/Students Create, Delete, Details, Edit, Index.
Data/SchoolContext.cs
Files updates
Startup.cs : Changes to this file in are detailed the next section.
appsettings.json : The connection string used to connect to a local database is added.

ASP.NET Core is built with dependency injection. Services (such as the EF Core DB context) are
registered with dependency injection during application startup. Components that require these services
(such as Razor Pages) are provided these services via constructor parameters. The constructor code that
gets a db context instance is shown later in the tutorial.
The scaffolding tool automatically created a DB Context and registered it with the dependency injection
container.
Examine the ConfigureServices method in Startup.cs. The highlighted line was added by the scaffolder:
{
{
// This lambda determines whether user consent for
//non -essential cookies is needed for a given request.
});
options.UseSqlServer(Configuration.GetConnectionString("SchoolContext")));
}
The name of the connection string is passed in to the context by calling a method on a
DbContextOptions object. For local development, the ASP.NET Core configuration system reads the
connection string from the appsettings.json file.
Update main
Call the EnsureCreated.
Dispose the context when the EnsureCreated method completes.

using ContosoUniversity.Models; // SchoolContext
using Microsoft.Extensions.DependencyInjection; // CreateScope
using System;
{
{
{

{
try
{
}
{
}
}
host.Run();
}

}
}
EnsureCreated ensures that the database for the context exists. If it exists, no action is taken. If it does
not exist, then the database and all its schema are created. EnsureCreated does not use migrations to
create the database. A database that is created with EnsureCreated cannot be later updated using
migrations.
EnsureCreated is called on app start, which allows the following work flow:
Delete the DB.
Change the DB schema (for example, add an EmailAddress field).
Run the app.
EnsureCreated creates a DB with the EmailAddress column.
EnsureCreated is convenient early in development when the schema is rapidly evolving. Later in the
tutorial the DB is deleted and migrations are used.
Test the app
Run the app and accept the cookie policy. This app doesn't keep personal information. You can read
about the cookie policy at EU General Data Protection Regulation (GDPR ) support.
Select the Students link and then Create New.
Examine the SchoolContext DB context
The main class that coordinates EF Core functionality for a given data model is the DB context class. The
data context is derived from Microsoft.EntityFrameworkCore.DbContext. The data context specifies
which entities are included in the data model. In this project, the class is named SchoolContext .
Update SchoolContext.cs with the following code:
{
{
public SchoolContext(DbContextOptions<SchoolContext> options)
: base(options)
{
}

public DbSet<Course> Course { get; set; }
}
}
The highlighted code creates a DbSet<TEntity> property for each entity set. In EF Core terminology:
An entity set typically corresponds to a DB table.
An entity corresponds to a row in the table.
DbSet<Enrollment> and DbSet<Course> could be omitted. EF Core includes them implicitly because the
Student entity references the Enrollment entity, and the Enrollment entity references the Course
entity. For this tutorial, keep DbSet<Enrollment> and DbSet<Course> in the SchoolContext .
The connection string specifies SQL Server LocalDB. LocalDB is a lightweight version of the SQL Server
Express Database Engine and is intended for app development, not production use. LocalDB starts on
demand and runs in user mode, so there's no complex configuration. By default, LocalDB creates .mdf
DB files in the C:/Users/<user> directory.
Add code to initialize the DB with test data

EF Core creates an empty DB. In this section, an Initialize method is written to populate it with test
data.
In the Data folder, create a new class file named DbInitializer.cs and add the following code:
using System;
using System.Linq;
{
{
{
// context.Database.EnsureCreated();

{
}

{
new
Student{FirstMidName="Carson",LastName="Alexander",EnrollmentDate=DateTime.Parse("2005-09-01")},
new
Student{FirstMidName="Meredith",LastName="Alonso",EnrollmentDate=DateTime.Parse("2002-09-01")},
new Student{FirstMidName="Arturo",LastName="Anand",EnrollmentDate=DateTime.Parse("2003-
09-01")},
new
Student{FirstMidName="Gytis",LastName="Barzdukas",EnrollmentDate=DateTime.Parse("2002-09-01")},
new Student{FirstMidName="Yan",LastName="Li",EnrollmentDate=DateTime.Parse("2002-09-
01")},
new Student{FirstMidName="Peggy",LastName="Justice",EnrollmentDate=DateTime.Parse("2001-
09-01")},
new Student{FirstMidName="Laura",LastName="Norman",EnrollmentDate=DateTime.Parse("2003-
09-01")},
new Student{FirstMidName="Nino",LastName="Olivetto",EnrollmentDate=DateTime.Parse("2005-
09-01")}
};
{
}

{
};
{
context.Course.Add(c);
}

{
};
{
}
}
}
}
The code checks if there are any students in the DB. If there are no students in the DB, the DB is
initialized with test data. It loads test data into arrays rather than List<T> collections to optimize
performance.
The EnsureCreated method automatically creates the DB for the DB context. If the DB exists,
EnsureCreated returns without modifying the DB.
In Program.cs, modify the Main method to call Initialize :

{
{

{
try
{
// using ContosoUniversity.Data;
}
{
}
}
host.Run();
}

}
Delete any student records and restart the app. If the DB is not initialized, set a break point in
Initialize to diagnose the problem.
View the DB
Open SQL Server Object Explorer (SSOX) from the View menu in Visual Studio. In SSOX, click
(localdb)\MSSQLLocalDB > Databases > ContosoUniversity1.
Expand the Tables node.
Right-click the Student table and click View Data to see the columns created and the rows inserted
into the table.
Asynchronous code
A web server has a limited number of threads available, and in high load situations all of the available
threads might be in use. When that happens, the server can't process new requests until the threads are
freed up. With synchronous code, many threads may be tied up while they aren't actually doing any
work because they're waiting for I/O to complete. With asynchronous code, when a process is waiting
for I/O to complete, its thread is freed up for the server to use for processing other requests. As a result,
asynchronous code enables server resources to be used more efficiently, and the server is enabled to
handle more traffic without delays.
Asynchronous code does introduce a small amount of overhead at run time. For low traffic situations,
the performance hit is negligible, while for high traffic situations, the potential performance
improvement is substantial.
In the following code, the async keyword, Task<T> return value, await keyword, and ToListAsync
method make the code execute asynchronously.

{
Student = await _context.Student.ToListAsync();
}
The async keyword tells the compiler to:

Generate callbacks for parts of the method body.
Automatically create the Task object that's returned. For more information, see Task Return
Type.
The implicit return type Task represents ongoing work.
The await keyword causes the compiler to split the method into two parts. The first part ends
with the operation that's started asynchronously. The second part is put into a callback method
that's called when the operation completes.
Some things to be aware of when writing asynchronous code that uses EF Core:
Only statements that cause queries or commands to be sent to the DB are executed asynchronously.
That includes, ToListAsync , SingleOrDefaultAsync , FirstOrDefaultAsync , and SaveChangesAsync . It
doesn't include statements that just change an IQueryable , such as
An EF Core context isn't thread safe: don't try to do multiple operations in parallel.
To take advantage of the performance benefits of async code, verify that library packages (such as for
paging) use async if they call EF Core methods that send queries to the DB.
For more information about asynchronous programming in .NET, see Async Overview and
Asynchronous programming with async and await.
In the next tutorial, basic CRUD (create, read, update, delete) operations are examined.
NEXT
ASP.NET Core MVC with EF Core - tutorial series
This tutorial teaches ASP.NET Core MVC and Entity Framework Core with controllers and views. Razor Pages is a
new alternative in ASP.NET Core 2.0, a page-based programming model that makes building web UI easier and
more productive. We recommend the Razor Pages tutorial over the MVC version. The Razor Pages tutorial:
1. Get started
4. Migrations
9. Inheritance
10. Advanced topics
Get Started with ASP.NET Core and Entity Framework
6
By Paweł Grudzień, Damien Pontifex, and Tom Dykstra

This article shows how to use Entity Framework 6 in an ASP.NET Core application.
Overview
To use Entity Framework 6, your project has to compile against .NET Framework, as Entity Framework 6 doesn't
support .NET Core. If you need cross-platform features you will need to upgrade to Entity Framework Core.
The recommended way to use Entity Framework 6 in an ASP.NET Core application is to put the EF6 context and
model classes in a class library project that targets the full framework. Add a reference to the class library from the
ASP.NET Core project. See the sample Visual Studio solution with EF6 and ASP.NET Core projects.
You can't put an EF6 context in an ASP.NET Core project because .NET Core projects don't support all of the
functionality that EF6 commands such as Enable-Migrations require.
Regardless of project type in which you locate your EF6 context, only EF6 command-line tools work with an EF6
context. For example, Scaffold-DbContext is only available in Entity Framework Core. If you need to do reverse
engineering of a database into an EF6 model, see Code First to an Existing Database.
Reference full framework and EF6 in the ASP.NET Core project

Your ASP.NET Core project needs to reference .NET framework and EF6. For example, the .csproj file of your
ASP.NET Core project will look similar to the following example (only relevant parts of the file are shown).
<PropertyGroup>
<TargetFramework>net452</TargetFramework>
<PreserveCompilationContext>true</PreserveCompilationContext>
<AssemblyName>MVCCore</AssemblyName>
<OutputType>Exe</OutputType>
<PackageId>MVCCore</PackageId>
</PropertyGroup>
When creating a new project, use the ASP.NET Core Web Application (.NET Framework) template.
Handle connection strings

The EF6 command-line tools that you'll use in the EF6 class library project require a default constructor so they
can instantiate the context. But you'll probably want to specify the connection string to use in the ASP.NET Core
project, in which case your context constructor must have a parameter that lets you pass in the connection string.
Here's an example.

{
public SchoolContext(string connString) : base(connString)
{
}
Since your EF6 context doesn't have a parameterless constructor, your EF6 project has to provide an
implementation of IDbContextFactory. The EF6 command-line tools will find and use that implementation so they
can instantiate the context. Here's an example.
public class SchoolContextFactory : IDbContextFactory<SchoolContext>

{
public SchoolContext Create()
{
return new EF6.SchoolContext("Server=
(localdb)\\mssqllocaldb;Database=EF6MVCCore;Trusted_Connection=True;MultipleActiveResultSets=true");
}
}
In this sample code, the IDbContextFactory implementation passes in a hard-coded connection string. This is the
connection string that the command-line tools will use. You'll want to implement a strategy to ensure that the class
library uses the same connection string that the calling application uses. For example, you could get the value from
an environment variable in both projects.
Set up dependency injection in the ASP.NET Core project

In the Core project's Startup.cs file, set up the EF6 context for dependency injection (DI) in ConfigureServices . EF
context objects should be scoped for a per-request lifetime.

{
services.AddMvc();
services.AddScoped<SchoolContext>(_ => new
SchoolContext(Configuration.GetConnectionString("DefaultConnection")));
}
You can then get an instance of the context in your controllers by using DI. The code is similar to what you'd write
for an EF Core context:
public class StudentsController : Controller

{
public StudentsController(SchoolContext context)

{
_context = context;
}
Sample application
For a working sample application, see the sample Visual Studio solution that accompanies this article.
This sample can be created from scratch by the following steps in Visual Studio:
Create a solution.
Add > New Project > Web > ASP.NET Core Web Application
In project template selection dialog, select API and .NET Framework in dropdown
Add > New Project > Windows Desktop > Class Library (.NET Framework)
In Package Manager Console (PMC ) for both projects, run the command
Install-Package Entityframework .
In the class library project, create data model classes and a context class, and an implementation of
IDbContextFactory .
In PMC for the class library project, run the commands Enable-Migrations and Add-Migration Initial . If
you have set the ASP.NET Core project as the startup project, add -StartupProjectName EF6 to these
commands.
In the Core project, add a project reference to the class library project.
In the Core project, in Startup.cs, register the context for DI.
In the Core project, in appsettings.json, add the connection string.
In the Core project, add a controller and view (s) to verify that you can read and write data. (Note that
ASP.NET Core MVC scaffolding won't work with the EF6 context referenced from the class library.)
Summary
This article has provided basic guidance for using Entity Framework 6 in an ASP.NET Core application.
Entity Framework - Code-Based Configuration
Azure Storage in ASP.NET Core
Adding Azure Storage by using Visual Studio Connected Services

Get Started with Blob storage and Visual Studio Connected Services
Get Started with Queue Storage and Visual Studio Connected Services
Get Started with Table Storage and Visual Studio Connected Services
This is a collection of guidance for getting the most out of Azure services with ASP.NET Core.
Guides

Docs | PDF
By Cam Soper and Scott Addie

This guide is available as a downloadable PDF e-book.
Welcome
Welcome to the Azure Development Lifecycle guide for .NET! This guide introduces the basic concepts of building
a development lifecycle around Azure using .NET tools and processes. After finishing this guide, you'll reap the
benefits of a mature DevOps toolchain.
Who this guide is for

You should be an experienced ASP.NET Core developer (200-300 level). You don't need to know anything about
Azure, as we'll cover that in this introduction. This guide may also be useful for DevOps engineers who are more
focused on operations than development.
This guide targets Windows developers. However, Linux and macOS are fully supported by .NET Core. To adapt
this guide for Linux/macOS, watch for callouts for Linux/macOS differences.
What this guide doesn't cover

This guide is focused on an end-to-end continuous deployment experience for .NET developers. It's not an
exhaustive guide to all things Azure, and it doesn't focus extensively on .NET APIs for Azure services. The
emphasis is all around continuous integration, deployment, monitoring, and debugging. Near the end of the guide,
recommendations for next steps are offered. Included in the suggestions are Azure platform services that are
useful to ASP.NET Core developers.
What's in this guide

Tools and downloads
Learn where to acquire the tools used in this guide.
Deploy to App Service
Learn the various methods for deploying an ASP.NET Core app to Azure App Service.
Build an end-to-end continuous integration and deployment solution for your ASP.NET Core app with GitHub,
Azure DevOps Services, and Azure.
Monitor and debug
Use Azure's tools to monitor, troubleshoot, and tune your application.
Next steps
Other learning paths for the ASP.NET Core developer learning Azure.
Additional introductory reading

If this is your first exposure to cloud computing, these articles explain the basics.
What is Cloud Computing?
Examples of Cloud Computing
What is IaaS?
What is PaaS?
Tools and downloads
Azure has several interfaces for provisioning and managing resources, such as the Azure portal, Azure CLI, Azure
PowerShell, Azure Cloud Shell, and Visual Studio. This guide takes a minimalist approach and uses the Azure
Cloud Shell whenever possible to reduce the steps required. However, the Azure portal must be used for some
portions.
Prerequisites
The following subscriptions are required:
Azure — If you don't have an account, get a free trial.
Azure DevOps Services — your Azure DevOps subscription and organization is created in Chapter 4.
GitHub — If you don't have an account, sign up for free.
The following tools are required:
Git — A fundamental understanding of Git is recommended for this guide. Review the Git documentation,
specifically git remote and git push.
.NET Core SDK — Version 2.1.300 or later is required to build and run the sample app. If Visual Studio is
installed with the .NET Core cross-platform development workload, the .NET Core SDK is already
installed.
Verify your .NET Core SDK installation. Open a command shell, and run the following command:
dotnet --version
Recommended tools (Windows only)

Visual Studio's robust Azure tools provide a GUI for most of the functionality described in this guide. Any
edition of Visual Studio will work, including the free Visual Studio Community Edition. The tutorials are
written to demonstrate development, deployment, and DevOps both with and without Visual Studio.
Confirm that Visual Studio has the following workloads installed:
Azure development
Deploy an app to App Service
Azure App Service is Azure's web hosting platform. Deploying a web app to Azure App Service can be done
manually or by an automated process. This section of the guide discusses deployment methods that can be
triggered manually or by script using the command line, or triggered manually using Visual Studio.
In this section, you'll accomplish the following tasks:
Download and build the sample app.
Create an Azure App Service Web App using the Azure Cloud Shell.
Deploy the sample app to Azure using Git.
Deploy a change to the app using Visual Studio.
Add a staging slot to the web app.
Deploy an update to the staging slot.
Swap the staging and production slots.
Download and test the app

The app used in this guide is a pre-built ASP.NET Core app, Simple Feed Reader. It's a Razor Pages app that uses
the Microsoft.SyndicationFeed.ReaderWriter API to retrieve an RSS/Atom feed and display the news items in a list.
Feel free to review the code, but it's important to understand that there's nothing special about this app. It's just a
simple ASP.NET Core app for illustrative purposes.
From a command shell, download the code, build the project, and run it as follows.
Note: Linux/macOS users should make appropriate changes for paths, e.g., using forward slash ( / ) rather
than back slash ( \ ).
1. Clone the code to a folder on your local machine.
git clone https://github.com/Azure-Samples/simple-feed-reader/
2. Change your working folder to the simple-feed -reader folder that was created.
cd .\simple-feed-reader\SimpleFeedReader
3. Restore the packages, and build the solution.
dotnet build
4. Run the app.
dotnet run
5. Open a browser and navigate to http://localhost:5000 . The app allows you to type or paste a syndication
feed URL and view a list of news items.
6. Once you're satisfied the app is working correctly, shut it down by pressing Ctrl+C in the command shell.
Create the Azure App Service Web App

To deploy the app, you'll need to create an App Service Web App. After creation of the Web App, you'll deploy to it
from your local machine using Git.
1. Sign in to the Azure Cloud Shell. Note: When you sign in for the first time, Cloud Shell prompts to create a
storage account for configuration files. Accept the defaults or provide a unique name.
2. Use the Cloud Shell for the following steps.
a. Declare a variable to store your web app's name. The name must be unique to be used in the default URL.
Using the $RANDOM Bash function to construct the name guarantees uniqueness and results in the format
webappname99999 .
webappname=mywebapp$RANDOM
b. Create a resource group. Resource groups provide a means to aggregate Azure resources to be managed
as a group.
az group create --location centralus --name AzureTutorial
The az command invokes the Azure CLI. The CLI can be run locally, but using it in the Cloud Shell saves
time and configuration.
c. Create an App Service plan in the S1 tier. An App Service plan is a grouping of web apps that share the
same pricing tier. The S1 tier isn't free, but it's required for the staging slots feature.
az appservice plan create --name $webappname --resource-group AzureTutorial --sku S1
d. Create the web app resource using the App Service plan in the same resource group.
az webapp create --name $webappname --resource-group AzureTutorial --plan $webappname
e. Set the deployment credentials. These deployment credentials apply to all the web apps in your
subscription. Don't use special characters in the user name.
az webapp deployment user set --user-name REPLACE_WITH_USER_NAME --password REPLACE_WITH_PASSWORD
f. Configure the web app to accept deployments from local Git and display the Git deployment URL. Note
this URL for reference later.
echo Git deployment URL: $(az webapp deployment source config-local-git --name $webappname --resource-
group AzureTutorial --query url --output tsv)
g. Display the web app URL. Browse to this URL to see the blank web app. Note this URL for reference
later.
echo Web app URL: http://$webappname.azurewebsites.net
3. Using a command shell on your local machine, navigate to the web app's project folder (for example,
.\simple-feed-reader\SimpleFeedReader ). Execute the following commands to set up Git to push to the
deployment URL:
a. Add the remote URL to the local repository.
git remote add azure-prod GIT_DEPLOYMENT_URL
b. Push the local master branch to the azure-prod remote's master branch.
git push azure-prod master
You'll be prompted for the deployment credentials you created earlier. Observe the output in the command
shell. Azure builds the ASP.NET Core app remotely.
4. In a browser, navigate to the Web app URL and note the app has been built and deployed. Additional
changes can be committed to the local Git repository with git commit . These changes are pushed to Azure
with the preceding git push command.
Deployment with Visual Studio
Note: This section applies to Windows only. Linux and macOS users should make the change described in step
2 below. Save the file, and commit the change to the local repository with git commit . Finally, push the change
with git push , as in the first section.
The app has already been deployed from the command shell. Let's use Visual Studio's integrated tools to deploy
an update to the app. Behind the scenes, Visual Studio accomplishes the same thing as the command line tooling,
but within Visual Studio's familiar UI.
1. Open SimpleFeedReader.sln in Visual Studio.
2. In Solution Explorer, open Pages\Index.cshtml. Change <h2>Simple Feed Reader</h2> to
<h2>Simple Feed Reader - V2</h2> .
3. Press Ctrl+Shift+B to build the app.

4. In Solution Explorer, right-click on the project and click Publish.
5. Visual Studio can create a new App Service resource, but this update will be published over the existing
deployment. In the Pick a publish target dialog, select App Service from the list on the left, and then
select Select Existing. Click Publish.
6. In the App Service dialog, confirm that the Microsoft or Organizational account used to create your Azure
subscription is displayed in the upper right. If it's not, click the drop-down and add it.
7. Confirm that the correct Azure Subscription is selected. For View, select Resource Group. Expand the
AzureTutorial resource group and then select the existing web app. Click OK.
Visual Studio builds and deploys the app to Azure. Browse to the web app URL. Validate that the <h2> element
modification is live.
Deployment slots
Deployment slots support the staging of changes without impacting the app running in production. Once the
staged version of the app is validated by a quality assurance team, the production and staging slots can be
swapped. The app in staging is promoted to production in this manner. The following steps create a staging slot,
deploy some changes to it, and swap the staging slot with production after verification.
1. Sign in to the Azure Cloud Shell, if not already signed in.
2. Create the staging slot.
a. Create a deployment slot with the name staging.
az webapp deployment slot create --name $webappname --resource-group AzureTutorial --slot staging
b. Configure the staging slot to use deployment from local Git and get the staging deployment URL. Note
this URL for reference later.
echo Git deployment URL for staging: $(az webapp deployment source config-local-git --name $webappname -
-resource-group AzureTutorial --slot staging --query url --output tsv)
c. Display the staging slot's URL. Browse to the URL to see the empty staging slot. Note this URL for
reference later.
echo Staging web app URL: http://$webappname-staging.azurewebsites.net
3. In a text editor or Visual Studio, modify Pages/Index.cshtml again so that the <h2> element reads
<h2>Simple Feed Reader - V3</h2> and save the file.
4. Commit the file to the local Git repository, using either the Changes page in Visual Studio's Team Explorer
tab, or by entering the following using the local machine's command shell:
git commit -a -m "upgraded to V3"
5. Using the local machine's command shell, add the staging deployment URL as a Git remote and push the
committed changes:
a. Add the remote URL for staging to the local Git repository.
git remote add azure-staging <Git_staging_deployment_URL>
b. Push the local master branch to the azure-staging remote's master branch.
git push azure-staging master
Wait while Azure builds and deploys the app.

6. To verify that V3 has been deployed to the staging slot, open two browser windows. In one window,
navigate to the original web app URL. In the other window, navigate to the staging web app URL. The
production URL serves V2 of the app. The staging URL serves V3 of the app.
7. In the Cloud Shell, swap the verified/warmed-up staging slot into production.
az webapp deployment slot swap --name $webappname --resource-group AzureTutorial --slot staging
8. Verify that the swap occurred by refreshing the two browser windows.
Summary
In this section, the following tasks were completed:
Downloaded and built the sample app.
Created an Azure App Service Web App using the Azure Cloud Shell.
Deployed the sample app to Azure using Git.
Deployed a change to the app using Visual Studio.
Added a staging slot to the web app.
Deployed an update to the staging slot.
Swapped the staging and production slots.
In the next section, you'll learn how to build a DevOps pipeline with Azure Pipelines.
Additional reading
Web Apps overview
Build a .NET Core and SQL Database web app in Azure App Service
Configure deployment credentials for Azure App Service
Set up staging environments in Azure App Service
In the previous chapter, you created a local Git repository for the Simple Feed Reader app. In this chapter, you'll
publish that code to a GitHub repository and construct an Azure DevOps Services pipeline using Azure Pipelines.
The pipeline enables continuous builds and deployments of the app. Any commit to the GitHub repository triggers
a build and a deployment to the Azure Web App's staging slot.
In this section, you'll complete the following tasks:
Publish the app's code to GitHub
Disconnect local Git deployment
Create an Azure DevOps organization
Create a team project in Azure DevOps Services
Create a build definition
Create a release pipeline
Commit changes to GitHub and automatically deploy to Azure
Examine the Azure Pipelines pipeline
Publish the app's code to GitHub

1. Open a browser window, and navigate to https://github.com .
2. Click the + drop-down in the header, and select New repository:
3. Select your account in the Owner drop-down, and enter simple-feed -reader in the Repository name
textbox.
4. Click the Create repository button.
5. Open your local machine's command shell. Navigate to the directory in which the simple-feed -reader Git
repository is stored.
6. Rename the existing origin remote to upstream. Execute the following command:
git remote rename origin upstream
7. Add a new origin remote pointing to your copy of the repository on GitHub. Execute the following
command:
git remote add origin https://github.com/<GitHub_username>/simple-feed-reader/

8. Publish your local Git repository to the newly created GitHub repository. Execute the following command:
git push -u origin master
9. Open a browser window, and navigate to https://github.com/<GitHub_username>/simple-feed-reader/ .

Validate that your code appears in the GitHub repository.
Disconnect local Git deployment

Remove the local Git deployment with the following steps. Azure Pipelines (an Azure DevOps service) both
replaces and augments that functionality.
1. Open the Azure portal, and navigate to the staging (mywebapp<unique_number>/staging ) Web App. The
Web App can be quickly located by entering staging in the portal's search box:
2. Click Deployment options. A new panel appears. Click Disconnect to remove the local Git source control
configuration that was added in the previous chapter. Confirm the removal operation by clicking the Yes
button.
3. Navigate to the mywebapp<unique_number> App Service. As a reminder, the portal's search box can be
used to quickly locate the App Service.
4. Click Deployment options. A new panel appears. Click Disconnect to remove the local Git source control
configuration that was added in the previous chapter. Confirm the removal operation by clicking the Yes
button.
Create an Azure DevOps organization

1. Open a browser, and navigate to the Azure DevOps organization creation page.
2. Type a unique name into the Pick a memorable name textbox to form the URL for accessing your Azure
DevOps organization.
3. Select the Git radio button, since the code is hosted in a GitHub repository.
4. Click the Continue button. After a short wait, an account and a team project, named MyFirstProject, are
created.
5. Open the confirmation email indicating that the Azure DevOps organization and project are ready for use.
Click the Start your project button:
6. A browser opens to <account_name>.visualstudio.com. Click the MyFirstProject link to begin configuring

the project's DevOps pipeline.
Configure the Azure Pipelines pipeline

There are three distinct steps to complete. Completing the steps in the following three sections results in an
operational DevOps pipeline.
Grant Azure DevOps access to the GitHub repository
1. Expand the or build code from an external repository accordion. Click the Setup Build button:
2. Select the GitHub option from the Select a source section:
3. Authorization is required before Azure DevOps can access your GitHub repository. Enter
<GitHub_username> GitHub connection in the Connection name textbox. For example:
4. If two-factor authentication is enabled on your GitHub account, a personal access token is required. In that
case, click the Authorize with a GitHub personal access token link. See the official GitHub personal
access token creation instructions for help. Only the repo scope of permissions is needed. Otherwise, click
the Authorize using OAuth button.
5. When prompted, sign in to your GitHub account. Then select Authorize to grant access to your Azure
DevOps organization. If successful, a new service endpoint is created.
6. Click the ellipsis button next to the Repository button. Select the <GitHub_username>/simple-feed -reader
repository from the list. Click the Select button.
7. Select the master branch from the Default branch for manual and scheduled builds drop-down. Click
the Continue button. The template selection page appears.
Create the build definition
1. From the template selection page, enter ASP.NET Core in the search box:
2. The template search results appear. Hover over the ASP.NET Core template, and click the Apply button.
3. The Tasks tab of the build definition appears. Click the Triggers tab.
4. Check the Enable continuous integration box. Under the Branch filters section, confirm that the Type
drop-down is set to Include. Set the Branch specification drop-down to master.
These settings cause a build to trigger when any change is pushed to the master branch of the GitHub
repository. Continuous integration is tested in the Commit changes to GitHub and automatically deploy to
Azure section.
5. Click the Save & queue button, and select the Save option:
6. The following modal dialog appears:
Use the default folder of \, and click the Save button.

Create the release pipeline
1. Click the Releases tab of your team project. Click the New pipeline button.
The template selection pane appears.
2. From the template selection page, enter App Service in the search box:
3. The template search results appear. Hover over the Azure App Service Deployment with Slot template,
and click the Apply button. The Pipeline tab of the release pipeline appears.
4. Click the Add button in the Artifacts box. The Add artifact panel appears:
5. Select the Build tile from the Source type section. This type allows for the linking of the release pipeline to
the build definition.
6. Select MyFirstProject from the Project drop-down.
7. Select the build definition name, MyFirstProject-ASP.NET Core-CI, from the Source (Build definition)
drop-down.
8. Select Latest from the Default version drop-down. This option builds the artifacts produced by the latest
run of the build definition.
9. Replace the text in the Source alias textbox with Drop.
10. Click the Add button. The Artifacts section updates to display the changes.
11. Click the lightning bolt icon to enable continuous deployments:
With this option enabled, a deployment occurs each time a new build is available.
12. A Continuous deployment trigger panel appears to the right. Click the toggle button to enable the
feature. It isn't necessary to enable the Pull request trigger.
13. Click the Add drop-down in the Build branch filters section. Choose the Build Definition's default
branch option. This filter causes the release to trigger only for a build from the GitHub repository's master
branch.
14. Click the Save button. Click the OK button in the resulting Save modal dialog.
15. Click the Environment 1 box. An Environment panel appears to the right. Change the Environment 1 text
in the Environment name textbox to Production.
16. Click the 1 phase, 2 tasks link in the Production box:
The Tasks tab of the environment appears.

17. Click the Deploy Azure App Service to Slot task. Its settings appear in a panel to the right.
18. Select the Azure subscription associated with the App Service from the Azure subscription drop-down.
Once selected, click the Authorize button.
19. Select Web App from the App type drop-down.
20. Select mywebapp/<unique_number/> from the App service name drop-down.
21. Select AzureTutorial from the Resource group drop-down.
22. Select staging from the Slot drop-down.
23. Click the Save button.
24. Hover over the default release pipeline name. Click the pencil icon to edit it. Use MyFirstProject-ASP.NET
Core-CD as the name.
25. Click the Save button.

Commit changes to GitHub and automatically deploy to Azure
1. Open SimpleFeedReader.sln in Visual Studio.
2. In Solution Explorer, open Pages\Index.cshtml. Change <h2>Simple Feed Reader - V3</h2> to
<h2>Simple Feed Reader - V4</h2> .
3. Press Ctrl+Shift+B to build the app.

4. Commit the file to the GitHub repository. Use either the Changes page in Visual Studio's Team Explorer
tab, or execute the following using the local machine's command shell:
git commit -a -m "upgraded to V4"
5. Push the change in the master branch to the origin remote of your GitHub repository:
git push origin master
The commit appears in the GitHub repository's master branch:
The build is triggered, since continuous integration is enabled in the build definition's Triggers tab:
6. Navigate to the Queued tab of the Azure Pipelines > Builds page in Azure DevOps Services. The queued
build shows the branch and commit that triggered the build:
7. Once the build succeeds, a deployment to Azure occurs. Navigate to the app in the browser. Notice that the
"V4" text appears in the heading:
Examine the Azure Pipelines pipeline
Build definition
A build definition was created with the name MyFirstProject-ASP.NET Core-CI. Upon completion, the build
produces a .zip file including the assets to be published. The release pipeline deploys those assets to Azure.
The build definition's Tasks tab lists the individual steps being used. There are five build tasks.
1. Restore — Executes the dotnet restore command to restore the app's NuGet packages. The default
package feed used is nuget.org.
2. Build — Executes the dotnet build --configuration release command to compile the app's code. This
--configuration option is used to produce an optimized version of the code, which is suitable for
deployment to a production environment. Modify the BuildConfiguration variable on the build definition's
Variables tab if, for example, a debug configuration is needed.
3. Test — Executes the
dotnet test --configuration release --logger trx --results-directory <local_path_on_build_agent>
command to run the app's unit tests. Unit tests are executed within any C# project matching the
**/*Tests/*.csproj glob pattern. Test results are saved in a .trx file at the location specified by the
--results-directory option. If any tests fail, the build fails and isn't deployed.
NOTE
To verify the unit tests work, modify SimpleFeedReader.Tests\Services\NewsServiceTests.cs to purposefully break one
of the tests. For example, change Assert.True(result.Count > 0); to Assert.False(result.Count > 0); in the
Returns_News_Stories_Given_Valid_Uri method. Commit and push the change to GitHub. The build is triggered
and fails. The build pipeline status changes to failed. Revert the change, commit, and push again. The build succeeds.
4. Publish — Executes the dotnet publish --configuration release --output <local_path_on_build_agent>

command to produce a .zip file with the artifacts to be deployed. The --output option specifies the publish
location of the .zip file. That location is specified by passing a predefined variable named
$(build.artifactstagingdirectory) . That variable expands to a local path, such as c:\agent_work\1\a, on the
build agent.
5. Publish Artifact — Publishes the .zip file produced by the Publish task. The task accepts the .zip file
location as a parameter, which is the predefined variable $(build.artifactstagingdirectory) . The .zip file is
published as a folder named drop.
Click the build definition's Summary link to view a history of builds with the definition:
On the resulting page, click the link corresponding to the unique build number:
A summary of this specific build is displayed. Click the Artifacts tab, and notice the drop folder produced by the
build is listed:
Use the Download and Explore links to inspect the published artifacts.
Release pipeline
A release pipeline was created with the name MyFirstProject-ASP.NET Core-CD:
The two major components of the release pipeline are the Artifacts and the Environments. Clicking the box in
the Artifacts section reveals the following panel:
The Source (Build definition) value represents the build definition to which this release pipeline is linked. The
.zip file produced by a successful run of the build definition is provided to the Production environment for
deployment to Azure. Click the 1 phase, 2 tasks link in the Production environment box to view the release pipeline
tasks:
The release pipeline consists of two tasks: Deploy Azure App Service to Slot and Manage Azure App Service - Slot
Swap. Clicking the first task reveals the following task configuration:
The Azure subscription, service type, web app name, resource group, and deployment slot are defined in the
deployment task. The Package or folder textbox holds the .zip file path to be extracted and deployed to the
staging slot of the mywebapp<unique_number> web app.
Clicking the slot swap task reveals the following task configuration:
The subscription, resource group, service type, web app name, and deployment slot details are provided. The Swap
with Production checkbox is checked. Consequently, the bits deployed to the staging slot are swapped into the
production environment.
Additional reading
Create your first pipeline with Azure Pipelines
Build and .NET Core project
Deploy a web app with Azure Pipelines
Monitor and debug
Having deployed the app and built a DevOps pipeline, it's important to understand how to monitor and
troubleshoot the app.
In this section, you'll complete the following tasks:
Find basic monitoring and troubleshooting data in the Azure portal
Learn how Azure Monitor provides a deeper look at metrics across all Azure services
Connect the web app with Application Insights for app profiling
Turn on logging and learn where to download logs
Stream logs in real time
Learn where to set up alerts
Learn about remote debugging Azure App Service web apps.
Basic monitoring and troubleshooting

App Service web apps are easily monitored in real time. The Azure portal renders metrics in easy-to-understand
charts and graphs.
1. Open the Azure portal, and then navigate to the mywebapp<unique_number> App Service.
2. The Overview tab displays useful "at-a-glance" information, including graphs displaying recent metrics.
Http 5xx: Count of server-side errors, usually exceptions in ASP.NET Core code.
Data In: Data ingress coming into your web app.
Data Out: Data egress from your web app to clients.
Requests: Count of HTTP requests.
Average Response Time: Average time for the web app to respond to HTTP requests.
Several self-service tools for troubleshooting and optimization are also found on this page.
Diagnose and solve problems is a self-service troubleshooter.

Application Insights is for profiling performance and app behavior, and is discussed later in this
section.
App Service Advisor makes recommendations to tune your app experience.
Advanced monitoring
Azure Monitor is the centralized service for monitoring all metrics and setting alerts across Azure services. Within
Azure Monitor, administrators can granularly track performance and identify trends. Each Azure service offers its
own set of metrics to Azure Monitor.
Profile with Application Insights

Application Insights is an Azure service for analyzing the performance and stability of web apps and how users use
them. The data from Application Insights is broader and deeper than that of Azure Monitor. The data can provide
developers and administrators with key information for improving apps. Application Insights can be added to an
Azure App Service resource without code changes.
1. Open the Azure portal, and then navigate to the mywebapp<unique_number> App Service.
2. From the Overview tab, click the Application Insights tile.
3. Select the Create new resource radio button. Use the default resource name, and select the location for the
Application Insights resource. The location doesn't need to match that of your web app.
4. For Runtime/Framework, select ASP.NET Core. Accept the default settings.

5. Select OK. If prompted to confirm, select Continue.
6. After the resource has been created, click the name of Application Insights resource to navigate directly to
the Application Insights page.
As the app is used, data accumulates. Select Refresh to reload the blade with new data.
Application Insights provides useful server-side information with no additional configuration. To get the most
value from Application Insights, instrument your app with the Application Insights SDK. When properly
configured, the service provides end-to-end monitoring across the web server and browser, including client-side
performance. For more information, see the Application Insights documentation.
Logging
Web server and app logs are disabled by default in Azure App Service. Enable the logs with the following steps:
1. Open the Azure portal, and navigate to the mywebapp<unique_number> App Service.
2. In the menu to the left, scroll down to the Monitoring section. Select Diagnostics logs.
3. Turn on Application Logging (Filesystem ). If prompted, click the box to install the extensions to enable
app logging in the web app.
4. Set Web server logging to File System.
5. Enter the Retention Period in days. For example, 30.
6. Click Save.
ASP.NET Core and web server (App Service) logs are generated for the web app. They can be downloaded using
the FTP/FTPS information displayed. The password is the same as the deployment credentials created earlier in
this guide. The logs can be streamed directly to your local machine with PowerShell or Azure CLI. Logs can also be
viewed in Application Insights.
Log streaming
App and web server logs can be streamed in real time through the portal.
1. Open the Azure portal, and navigate to the mywebapp<unique_number> App Service.
2. In the menu to the left, scroll down to the Monitoring section and select Log stream.
Logs can also be streamed via Azure CLI or Azure PowerShell, including through the Cloud Shell.
Alerts
Azure Monitor also provides real time alerts based on metrics, administrative events, and other criteria.
Note: Currently alerting on web app metrics is only available in the Alerts (classic) service.
The Alerts (classic) service can be found in Azure Monitor or under the Monitoring section of the App Service
settings.
Live debugging
Azure App Service can be debugged remotely with Visual Studio when logs don't provide enough information.
However, remote debugging requires the app to be compiled with debug symbols. Debugging shouldn't be done
in production, except as a last resort.
Conclusion
In this section, you completed the following tasks:
Find basic monitoring and troubleshooting data in the Azure portal
Learn how Azure Monitor provides a deeper look at metrics across all Azure services
Connect the web app with Application Insights for app profiling
Turn on logging and learn where to download logs
Stream logs in real time
Learn where to set up alerts
Learn about remote debugging Azure App Service web apps.
Additional reading
Monitor Azure web app performance with Application Insights
Enable diagnostics logging for web apps in Azure App Service
Troubleshoot a web app in Azure App Service using Visual Studio
Create classic metric alerts in Azure Monitor for Azure services - Azure portal
Next steps
In this guide, you created a DevOps pipeline for an ASP.NET Core sample app. Congratulations! We hope you
enjoyed learning to publish ASP.NET Core web apps to Azure App Service and automate the continuous
integration of changes.
Beyond web hosting and DevOps, Azure has a wide array of Platform-as-a-Service (PaaS ) services useful to
ASP.NET Core developers. This section gives a brief overview of some of the most commonly used services.
Storage and databases

Redis Cache is high-throughput, low -latency data caching available as a service. It can be used for caching page
output, reducing database requests, and providing ASP.NET Core session state across multiple instances of an app.
Azure Storage is Azure's massively scalable cloud storage. Developers can take advantage of Queue Storage for
reliable message queuing, and Table Storage is a NoSQL key-value store designed for rapid development using
massive, semi-structured data sets.
Azure SQL Database provides familiar relational database functionality as a service using the Microsoft SQL
Server Engine.
Cosmos DB globally distributed, multi-model NoSQL database service. Multiple APIs are available, including SQL
API (formerly called DocumentDB ), Cassandra, and MongoDB.
Identity
Azure Active Directory and Azure Active Directory B2C are both identity services. Azure Active Directory is
designed for enterprise scenarios and enables Azure AD B2B (business-to-business) collaboration, while Azure
Active Directory B2C is intended business-to-customer scenarios, including social network sign-in.
Mobile
Notification Hubs is a multi-platform, scalable push-notification engine to quickly send millions of messages to
apps running on various types of devices.
Web infrastructure
Azure Container Service manages your hosted Kubernetes environment, making it quick and easy to deploy and
manage containerized apps without container orchestration expertise.
Azure Search is used to create an enterprise search solution over private, heterogenous content.
Service Fabric is a distributed systems platform that makes it easy to package, deploy, and manage scalable and
reliable microservices and containers.
Client-side development in ASP.NET Core
Use Gulp
Use Grunt
Use LibMan
LibMan CLI
LibMan in Visual Studio
Style apps with LESS, Sass, and Font Awesome
Bundle and minify
TypeScript
Use Browser Link
Use JavaScriptServices for SPAs
Use the SPA project templates
Angular project template
React project template
React with Redux project template
Use Gulp in ASP.NET Core
By Erik Reitan, Scott Addie, Daniel Roth, and Shayne Boyer

In a typical modern web app, the build process might:
Bundle and minify JavaScript and CSS files.
Run tools to call the bundling and minification tasks before each build.
Compile LESS or SASS files to CSS.
Compile CoffeeScript or TypeScript files to JavaScript.
A task runner is a tool which automates these routine development tasks and more. Visual Studio provides built-
in support for two popular JavaScript-based task runners: Gulp and Grunt.
Gulp
Gulp is a JavaScript-based streaming build toolkit for client-side code. It's commonly used to stream client-side
files through a series of processes when a specific event is triggered in a build environment. For instance, Gulp can
be used to automate bundling and minification or the cleansing of a development environment before a new
build.
A set of Gulp tasks is defined in gulpfile.js. The following JavaScript includes Gulp modules and specifies file paths
to be referenced within the forthcoming tasks:
/// <binding Clean='clean' />

"use strict";
var gulp = require("gulp"),

rimraf = require("rimraf"),
concat = require("gulp-concat"),
cssmin = require("gulp-cssmin"),
uglify = require("gulp-uglify");
var paths = {
webroot: "./wwwroot/"
};
paths.js = paths.webroot + "js/**/*.js";

paths.minJs = paths.webroot + "js/**/*.min.js";
paths.css = paths.webroot + "css/**/*.css";
paths.minCss = paths.webroot + "css/**/*.min.css";
paths.concatJsDest = paths.webroot + "js/site.min.js";
paths.concatCssDest = paths.webroot + "css/site.min.css";
The above code specifies which Node modules are required. The require function imports each module so that
the dependent tasks can utilize their features. Each of the imported modules is assigned to a variable. The
modules can be located either by name or path. In this example, the modules named gulp , rimraf , gulp-concat ,
gulp-cssmin , and gulp-uglify are retrieved by name. Additionally, a series of paths are created so that the
locations of CSS and JavaScript files can be reused and referenced within the tasks. The following table provides
descriptions of the modules included in gulpfile.js.
MODULE NAME DESCRIPTION
gulp The Gulp streaming build system. For more information, see
gulp.
rimraf A Node deletion module. For more information, see rimraf.
gulp-concat A module that concatenates files based on the operating

system's newline character. For more information, see gulp-
concat.
gulp-cssmin A module that minifies CSS files. For more information, see
gulp-cssmin.
gulp-uglify A module that minifies .js files. For more information, see
gulp-uglify.
Once the requisite modules are imported, the tasks can be specified. Here there are six tasks registered,
represented by the following code:
gulp.task("clean:js", function (cb) {

rimraf(paths.concatJsDest, cb);
});
gulp.task("clean:css", function (cb) {

rimraf(paths.concatCssDest, cb);
});
gulp.task("clean", ["clean:js", "clean:css"]);
gulp.task("min:js", function () {
return gulp.src([paths.js, "!" + paths.minJs], { base: "." })
.pipe(concat(paths.concatJsDest))
.pipe(uglify())
.pipe(gulp.dest("."));
});
gulp.task("min:css", function () {
return gulp.src([paths.css, "!" + paths.minCss])
.pipe(concat(paths.concatCssDest))
.pipe(cssmin())
});
gulp.task("min", ["min:js", "min:css"]);
The following table provides an explanation of the tasks specified in the code above:
TASK NAME DESCRIPTION
clean:js A task that uses the rimraf Node deletion module to remove
the minified version of the site.js file.
clean:css A task that uses the rimraf Node deletion module to remove
the minified version of the site.css file.
clean A task that calls the clean:js task, followed by the

clean:css task.
TASK NAME DESCRIPTION
min:js A task that minifies and concatenates all .js files within the js
folder. The .min.js files are excluded.
min:css A task that minifies and concatenates all .css files within the
css folder. The .min.css files are excluded.
min A task that calls the min:js task, followed by the min:css
task.
Running default tasks

If you haven't already created a new Web app, create a new ASP.NET Web Application project in Visual Studio.
1. Add a new JavaScript file to your project and name it gulpfile.js, then copy the following code.
/// <binding Clean='clean' />

"use strict";

rimraf = require("rimraf"),
uglify = require("gulp-uglify");
var paths = {
webroot: "./wwwroot/"
};
paths.js = paths.webroot + "js/**/*.js";

paths.minJs = paths.webroot + "js/**/*.min.js";
paths.css = paths.webroot + "css/**/*.css";
paths.minCss = paths.webroot + "css/**/*.min.css";
paths.concatJsDest = paths.webroot + "js/site.min.js";
paths.concatCssDest = paths.webroot + "css/site.min.css";
gulp.task("clean:js", function (cb) {

rimraf(paths.concatJsDest, cb);
});
gulp.task("clean:css", function (cb) {

rimraf(paths.concatCssDest, cb);
});
gulp.task("clean", ["clean:js", "clean:css"]);
return gulp.src([paths.js, "!" + paths.minJs], { base: "." })
.pipe(concat(paths.concatJsDest))
.pipe(uglify())
});
return gulp.src([paths.css, "!" + paths.minCss])
.pipe(concat(paths.concatCssDest))
.pipe(cssmin())
});
gulp.task("min", ["min:js", "min:css"]);

2. Open the package.json file (add if not there) and add the following.
{
"devDependencies": {
"gulp": "3.9.1",
"gulp-concat": "2.6.1",
"gulp-cssmin": "0.1.7",
"gulp-uglify": "2.0.1",
"rimraf": "2.6.1"
}
}
3. In Solution Explorer, right-click gulpfile.js, and select Task Runner Explorer.
Task Runner Explorer shows the list of Gulp tasks. (You might have to click the Refresh button that
appears to the left of the project name.)
IMPORTANT
The Task Runner Explorer context menu item appears only if gulpfile.js is in the root project directory.
4. Underneath Tasks in Task Runner Explorer, right-click clean, and select Run from the pop-up menu.
Task Runner Explorer will create a new tab named clean and execute the clean task as it's defined in
gulpfile.js.
5. Right-click the clean task, then select Bindings > Before Build.
The Before Build binding configures the clean task to run automatically before each build of the project.
The bindings you set up with Task Runner Explorer are stored in the form of a comment at the top of your
gulpfile.js and are effective only in Visual Studio. An alternative that doesn't require Visual Studio is to configure
automatic execution of gulp tasks in your .csproj file. For example, put this in your .csproj file:
<Target Name="MyPreCompileTarget" BeforeTargets="Build">

<Exec Command="gulp clean" />
</Target>
Now the clean task is executed when you run the project in Visual Studio or from a command prompt using the
dotnet run command (run npm install first).
Defining and running a new task

To define a new Gulp task, modify gulpfile.js.
1. Add the following JavaScript to the end of gulpfile.js:
gulp.task("first", function () {
console.log('first task! <-----');
});
This task is named first , and it simply displays a string.

2. Save gulpfile.js.
3. In Solution Explorer, right-click gulpfile.js, and select Task Runner Explorer.
4. In Task Runner Explorer, right-click first, and select Run.
The output text is displayed. To see examples based on common scenarios, see Gulp Recipes.
Defining and running tasks in a series

When you run multiple tasks, the tasks run concurrently by default. However, if you need to run tasks in a specific
order, you must specify when each task is complete, as well as which tasks depend on the completion of another
task.
1. To define a series of tasks to run in order, replace the first task that you added above in gulpfile.js with
the following:
gulp.task("series:first", function () {
console.log('first task! <-----');
});
gulp.task("series:second", ["series:first"], function () {

console.log('second task! <-----');
});
gulp.task("series", ["series:first", "series:second"], function () {});
You now have three tasks: series:first , series:second , and series . The series:second task includes a
second parameter which specifies an array of tasks to be run and completed before the series:second task
will run. As specified in the code above, only the series:first task must be completed before the
series:second task will run.
2. Save gulpfile.js.
3. In Solution Explorer, right-click gulpfile.js and select Task Runner Explorer if it isn't already open.
4. In Task Runner Explorer, right-click series and select Run.
IntelliSense
IntelliSense provides code completion, parameter descriptions, and other features to boost productivity and to
decrease errors. Gulp tasks are written in JavaScript; therefore, IntelliSense can provide assistance while
developing. As you work with JavaScript, IntelliSense lists the objects, functions, properties, and parameters that
are available based on your current context. Select a coding option from the pop-up list provided by IntelliSense
to complete the code.
For more information about IntelliSense, see JavaScript IntelliSense.
Development, staging, and production environments

When Gulp is used to optimize client-side files for staging and production, the processed files are saved to a local
staging and production location. The _Layout.cshtml file uses the environment tag helper to provide two
different versions of CSS files. One version of CSS files is for development and the other version is optimized for
both staging and production. In Visual Studio 2017, when you change the ASPNETCORE_ENVIRONMENT
environment variable to Production , Visual Studio will build the Web app and link to the minimized CSS files. The
following markup shows the environment tag helpers containing link tags to the Development CSS files and the
minified Staging, Production CSS files.
</environment>
</script>
</script>
</environment>
Switching between environments

To switch between compiling for different environments, modify the ASPNETCORE_ENVIRONMENT
environment variable's value.
1. In Task Runner Explorer, verify that the min task has been set to run Before Build.
2. In Solution Explorer, right-click the project name and select Properties.
The property sheet for the Web app is displayed.
3. Click the Debug tab.
4. Set the value of the Hosting:Environment environment variable to Production .
5. Press F5 to run the application in a browser.
6. In the browser window, right-click the page and select View Source to view the HTML for the page.
Notice that the stylesheet links point to the minified CSS files.
7. Close the browser to stop the Web app.
8. In Visual Studio, return to the property sheet for the Web app and change the Hosting:Environment
environment variable back to Development .
9. Press F5 to run the application in a browser again.
10. In the browser window, right-click the page and select View Source to see the HTML for the page.
Notice that the stylesheet links point to the unminified versions of the CSS files.
For more information related to environments in ASP.NET Core, see Use multiple environments.
Task and module details

A Gulp task is registered with a function name. You can specify dependencies if other tasks must run before the
current task. Additional functions allow you to run and watch the Gulp tasks, as well as set the source (src) and
destination (dest) of the files being modified. The following are the primary Gulp API functions:
GULP FUNCTION SYNTAX DESCRIPTION
task gulp.task(name[, deps], fn) { } The task function creates a task. The
name parameter defines the name of
the task. The deps parameter
contains an array of tasks to be
completed before this task runs. The
fn parameter represents a callback
function which performs the operations
of the task.
watch gulp.watch(glob [, opts], tasks) The watch function monitors files and
{ } runs tasks when a file change occurs.
The glob parameter is a string or
array that determines which files to
watch. The opts parameter provides
additional file watching options.
src gulp.src(globs[, options]) { } The src function provides files that

match the glob value(s). The glob
parameter is a string or array that
determines which files to read. The
options parameter provides
additional file options.
dest gulp.dest(path[, options]) { } The dest function defines a location

to which files can be written. The path
parameter is a string or function that
determines the destination folder. The
options parameter is an object that
specifies output folder options.
For additional Gulp API reference information, see Gulp Docs API.
Gulp recipes
The Gulp community provides Gulp Recipes. These recipes consist of Gulp tasks to address common scenarios.
Gulp documentation
Bundling and minification in ASP.NET Core
Use Grunt in ASP.NET Core
Use Grunt in ASP.NET Core
By Noel Rice
Grunt is a JavaScript task runner that automates script minification, TypeScript compilation, code quality "lint"
tools, CSS pre-processors, and just about any repetitive chore that needs doing to support client development.
Grunt is fully supported in Visual Studio, though the ASP.NET project templates use Gulp by default (see Use
Gulp).
This example uses an empty ASP.NET Core project as its starting point, to show how to automate the client build
process from scratch.
The finished example cleans the target deployment directory, combines JavaScript files, checks code quality,
condenses JavaScript file content and deploys to the root of your web application. We will use the following
packages:
grunt: The Grunt task runner package.
grunt-contrib-clean: A plugin that removes files or directories.
grunt-contrib-jshint: A plugin that reviews JavaScript code quality.
grunt-contrib-concat: A plugin that joins files into a single file.
grunt-contrib-uglify: A plugin that minifies JavaScript to reduce size.
grunt-contrib-watch: A plugin that watches file activity.
Preparing the application

To begin, set up a new empty web application and add TypeScript example files. TypeScript files are automatically
compiled into JavaScript using default Visual Studio settings and will be our raw material to process using Grunt.
1. In Visual Studio, create a new ASP.NET Web Application .
2. In the New ASP.NET Project dialog, select the ASP.NET Core Empty template and click the OK button.
3. In the Solution Explorer, review the project structure. The \src folder includes empty wwwroot and
Dependencies nodes.
4. Add a new folder named TypeScript to your project directory.
5. Before adding any files, make sure that Visual Studio has the option 'compile on save' for TypeScript files
checked. Navigate to Tools > Options > Text Editor > Typescript > Project:
6. Right-click the TypeScript directory and select Add > New Item from the context menu. Select the
JavaScript file item and name the file Tastes.ts (note the *.ts extension). Copy the line of TypeScript code
below into the file (when you save, a new Tastes.js file will appear with the JavaScript source).
enum Tastes { Sweet, Sour, Salty, Bitter }
7. Add a second file to the TypeScript directory and name it Food.ts . Copy the code below into the file.
class Food {
constructor(name: string, calories: number) {
this._name = name;
this._calories = calories;
}
private _name: string;

get Name() {
return this._name;
}
private _calories: number;

get Calories() {
return this._calories;
}
private _taste: Tastes;

get Taste(): Tastes { return this._taste }
set Taste(value: Tastes) {
this._taste = value;
}
}
Configuring NPM
Next, configure NPM to download grunt and grunt-tasks.
1. In the Solution Explorer, right-click the project and select Add > New Item from the context menu. Select
the NPM configuration file item, leave the default name, package.json, and click the Add button.
2. In the package.json file, inside the devDependencies object braces, enter "grunt". Select grunt from the
Intellisense list and press the Enter key. Visual Studio will quote the grunt package name, and add a colon.
To the right of the colon, select the latest stable version of the package from the top of the Intellisense list
(press Ctrl-Space if Intellisense doesn't appear).
NOTE
NPM uses semantic versioning to organize dependencies. Semantic versioning, also known as SemVer, identifies
packages with the numbering scheme ... Intellisense simplifies semantic versioning by showing only a few common
choices. The top item in the Intellisense list (0.4.5 in the example above) is considered the latest stable version of the
package. The caret (^) symbol matches the most recent major version and the tilde (~) matches the most recent
minor version. See the NPM semver version parser reference as a guide to the full expressivity that SemVer provides.
3. Add more dependencies to load grunt-contrib-* packages for clean, jshint, concat, uglify, and watch as
shown in the example below. The versions don't need to match the example.
"grunt": "0.4.5",
"grunt-contrib-clean": "0.6.0",
"grunt-contrib-jshint": "0.11.0",
"grunt-contrib-concat": "0.5.1",
"grunt-contrib-uglify": "0.8.0",
"grunt-contrib-watch": "0.6.1"
}
4. Save the package.json file.

The packages for each devDependencies item will download, along with any files that each package requires. You
can find the package files in the node_modules directory by enabling the Show All Files button in the Solution
Explorer.
NOTE
If you need to, you can manually restore dependencies in Solution Explorer by right-clicking on Dependencies\NPM and
selecting the Restore Packages menu option.
Configuring Grunt
Grunt is configured using a manifest named Gruntfile.js that defines, loads and registers tasks that can be run
manually or configured to run automatically based on events in Visual Studio.
1. Right-click the project and select Add > New Item. Select the Grunt Configuration file option, leave the
default name, Gruntfile.js, and click the Add button.
The initial code includes a module definition and the grunt.initConfig() method. The initConfig() is
used to set options for each package, and the remainder of the module will load and register tasks.
module.exports = function (grunt) {

grunt.initConfig({
});
};
2. Inside the initConfig() method, add options for the clean task as shown in the example Gruntfile.js
below. The clean task accepts an array of directory strings. This task removes files from wwwroot/lib and
removes the entire /temp directory.
module.exports = function (grunt) {

grunt.initConfig({
clean: ["wwwroot/lib/*", "temp/"],
});
};
3. Below the initConfig() method, add a call to grunt.loadNpmTasks() . This will make the task runnable from
Visual Studio.
grunt.loadNpmTasks("grunt-contrib-clean");
4. Save Gruntfile.js. The file should look something like the screenshot below.
5. Right-click Gruntfile.js and select Task Runner Explorer from the context menu. The Task Runner Explorer
window will open.
6. Verify that clean shows under Tasks in the Task Runner Explorer.
7. Right-click the clean task and select Run from the context menu. A command window displays progress of
the task.
NOTE
There are no files or directories to clean yet. If you like, you can manually create them in the Solution Explorer and
then run the clean task as a test.
8. In the initConfig() method, add an entry for concat using the code below.
The src property array lists files to combine, in the order that they should be combined. The dest
property assigns the path to the combined file that's produced.
concat: {
all: {
src: ['TypeScript/Tastes.js', 'TypeScript/Food.js'],
dest: 'temp/combined.js'
}
},
NOTE
The all property in the code above is the name of a target. Targets are used in some Grunt tasks to allow
multiple build environments. You can view the built-in targets using Intellisense or assign your own.
9. Add the jshint task using the code below.

The jshint code-quality utility is run against every JavaScript file found in the temp directory.
jshint: {
files: ['temp/*.js'],
options: {
'-W069': false,
}
},
NOTE
The option "-W069" is an error produced by jshint when JavaScript uses bracket syntax to assign a property instead
of dot notation, i.e. Tastes["Sweet"] instead of Tastes.Sweet . The option turns off the warning to allow the rest
of the process to continue.
10. Add the uglify task using the code below.

The task minifies the combined.js file found in the temp directory and creates the result file in wwwroot/lib
following the standard naming convention <file name>.min.js.
uglify: {
all: {
src: ['temp/combined.js'],
dest: 'wwwroot/lib/combined.min.js'
}
},
11. Under the call grunt.loadNpmTasks() that loads grunt-contrib-clean, include the same call for jshint, concat
and uglify using the code below.
grunt.loadNpmTasks('grunt-contrib-jshint');
grunt.loadNpmTasks('grunt-contrib-concat');
grunt.loadNpmTasks('grunt-contrib-uglify');
12. Save Gruntfile.js. The file should look something like the example below.
13. Notice that the Task Runner Explorer Tasks list includes clean , concat , jshint and uglify tasks. Run
each task in order and observe the results in Solution Explorer. Each task should run without errors.
The concat task creates a new combined.js file and places it into the temp directory. The jshint task simply
runs and doesn't produce output. The uglify task creates a new combined.min.js file and places it into
wwwroot/lib. On completion, the solution should look something like the screenshot below:
NOTE
For more information on the options for each package, visit https://www.npmjs.com/ and lookup the package name
in the search box on the main page. For example, you can look up the grunt-contrib-clean package to get a
documentation link that explains all of its parameters.
All together now

Use the Grunt registerTask() method to run a series of tasks in a particular sequence. For example, to run the
example steps above in the order clean -> concat -> jshint -> uglify, add the code below to the module. The code
should be added to the same level as the loadNpmTasks() calls, outside initConfig.
grunt.registerTask("all", ['clean', 'concat', 'jshint', 'uglify']);
The new task shows up in Task Runner Explorer under Alias Tasks. You can right-click and run it just as you would
other tasks. The all task will run clean , concat , jshint and uglify , in order.
Watching for changes
A watch task keeps an eye on files and directories. The watch triggers tasks automatically if it detects changes.
Add the code below to initConfig to watch for changes to *.js files in the TypeScript directory. If a JavaScript file is
changed, watch will run the all task.
watch: {
files: ["TypeScript/*.js"],
tasks: ["all"]
}
Add a call to loadNpmTasks() to show the watch task in Task Runner Explorer.
grunt.loadNpmTasks('grunt-contrib-watch');
Right-click the watch task in Task Runner Explorer and select Run from the context menu. The command window
that shows the watch task running will display a "Waiting…" message. Open one of the TypeScript files, add a
space, and then save the file. This will trigger the watch task and trigger the other tasks to run in order. The
screenshot below shows a sample run.
Binding to Visual Studio events

Unless you want to manually start your tasks every time you work in Visual Studio, you can bind tasks to Before
Build, After Build, Clean, and Project Open events.
Let’s bind watch so that it runs every time Visual Studio opens. In Task Runner Explorer, right-click the watch
task and select Bindings > Project Open from the context menu.
Unload and reload the project. When the project loads again, the watch task will start running automatically.
Summary
Grunt is a powerful task runner that can be used to automate most client-build tasks. Grunt leverages NPM to
deliver its packages, and features tooling integration with Visual Studio. Visual Studio's Task Runner Explorer
detects changes to configuration files and provides a convenient interface to run tasks, view running tasks, and
bind tasks to Visual Studio events.
Use Gulp
Client-side library acquisition in ASP.NET Core with
LibMan
By Scott Addie
Library Manager (LibMan) is a lightweight, client-side library acquisition tool. LibMan downloads popular
libraries and frameworks from the file system or from a content delivery network (CDN ) . The supported CDNs
include CDNJS and unpkg. The selected library files are fetched and placed in the appropriate location within the
ASP.NET Core project.
LibMan use cases

LibMan offers the following benefits:
Only the library files you need are downloaded.
Additional tooling, such as Node.js, npm, and WebPack, isn't necessary to acquire a subset of files in a library.
Files can be placed in a specific location without resorting to build tasks or manual file copying.
For more information about LibMan's benefits, watch Modern front-end web development in Visual Studio 2017:
LibMan segment.
LibMan isn't a package management system. If you're already using a package manager, such as npm oryarn,
continue doing so. LibMan wasn't developed to replace those tools.
Use LibMan with ASP.NET Core in Visual Studio
Use the LibMan command-line interface (CLI) with ASP.NET Core
LibMan GitHub repository
Use the LibMan command-line interface (CLI) with
ASP.NET Core
By Scott Addie
The LibMan CLI is a cross-platform tool that's supported everywhere .NET Core is supported.
Prerequisites
Installation
To install the LibMan CLI:
dotnet tool install -g Microsoft.Web.LibraryManager.Cli
A .NET Core Global Tool is installed from the Microsoft.Web.LibraryManager.Cli NuGet package.
To install the LibMan CLI from a specific NuGet package source:
dotnet tool install -g Microsoft.Web.LibraryManager.Cli --version 1.0.94-g606058a278 --add-source C:\Temp\
In the preceding example, a .NET Core Global Tool is installed from the local Windows machine's
C:\Temp\Microsoft.Web.LibraryManager.Cli.1.0.94 -g606058a278.nupkg file.
Usage
After successful installation of the CLI, the following command can be used:
libman
To view the installed CLI version:
libman --version
To view the available CLI commands:
libman --help
The preceding command displays output similar to the following:

1.0.163+g45474d37ed
Usage: libman [options] [command]
Options:
--help|-h Show help information
--version Show version information
Commands:
cache List or clean libman cache contents
clean Deletes all library files defined in libman.json from the project
init Create a new libman.json
install Add a library definition to the libman.json file, and download the
library to the specified location
restore Downloads all files from provider and saves them to specified
destination
uninstall Deletes all files for the specified library from their specified
destination, then removes the specified library definition from
libman.json
update Updates the specified library
Use "libman [command] --help" for more information about a command.
The following sections outline the available CLI commands.
Initialize LibMan in the project

The libman init command creates a libman.json file if one doesn't exist. The file is created with the default item
template content.
Synopsis
libman init [-d|--default-destination] [-p|--default-provider] [--verbosity]

libman init [-h|--help]
Options
The following options are available for the libman init command:
-d|--default-destination <PATH>
A path relative to the current folder. Library files are installed in this location if no destination property is
defined for a library in libman.json. The <PATH> value is written to the defaultDestination property of
libman.json.
-p|--default-provider <PROVIDER>
The provider to use if no provider is defined for a given library. The <PROVIDER> value is written to the
defaultProvider property of libman.json. Replace <PROVIDER> with one of the following values:
cdnjs
filesystem
unpkg
-h|--help
Show help information.

--verbosity <LEVEL>
Set the verbosity of the output. Replace <LEVEL> with one of the following values:
quiet
normal
detailed
Examples
To create a libman.json file in an ASP.NET Core project:
Navigate to the project root.
Run the following command:
libman init
Type the name of the default provider, or press Enter to use the default CDNJS provider. Valid values
include:
cdnjs
filesystem
unpkg
A libman.json file is added to the project root with the following content:
{
"version": "1.0",
"defaultProvider": "cdnjs",
"libraries": []
}
Add library files

The libman install command downloads and installs library files into the project. A libman.json file is added if
one doesn't exist. The libman.json file is modified to store configuration details for the library files.
Synopsis
libman install <LIBRARY> [-d|--destination] [--files] [-p|--provider] [--verbosity]

libman install [-h|--help]
Arguments
LIBRARY
The name of the library to install. This name may include version number notation (for example, @1.2.0 ).
Options
The following options are available for the libman install command:
-d|--destination <PATH>
The location to install the library. If not specified, the default location is used. If no defaultDestination
property is specified in libman.json, this option is required.
--files <FILE>
Specify the name of the file to install from the library. If not specified, all files from the library are installed.
Provide one --files option per file to be installed. Relative paths are supported too. For example:
--files dist/browser/signalr.js .
-p|--provider <PROVIDER>
The name of the provider to use for the library acquisition. Replace <PROVIDER> with one of the following
values:
cdnjs
filesystem
unpkg
If not specified, the defaultProvider property in libman.json is used. If no defaultProvider property is
specified in libman.json, this option is required.
-h|--help

--verbosity <LEVEL>
quiet
normal
detailed
Examples
Consider the following libman.json file:
{
"version": "1.0",
"libraries": []
}
To install the jQuery version 3.2.1 jquery.min.js file to the wwwroot/scripts/jquery folder using the CDNJS
provider:
libman install [email protected] --provider cdnjs --destination wwwroot/scripts/jquery --files jquery.min.js
The libman.json file resembles the following:

{
"version": "1.0",
"libraries": [
{
"library": "[email protected]",
"destination": "wwwroot/scripts/jquery",
"files": [
"jquery.min.js"
]
}
]
}
To install the calendar.js and calendar.css files from C:\temp\contosoCalendar\ using the file system provider:
libman install C:\temp\contosoCalendar\ --provider filesystem --files calendar.js --files calendar.css
The following prompt appears for two reasons:

The libman.json file doesn't contain a defaultDestination property.
The libman install command doesn't contain the -d|--destination option.
After accepting the default destination, the libman.json file resembles the following:
{
"version": "1.0",
"libraries": [
{
"destination": "wwwroot/scripts/jquery",
"files": [
"jquery.min.js"
]
},
{
"library": "C:\\temp\\contosoCalendar\\",
"provider": "filesystem",
"destination": "wwwroot/lib/contosoCalendar",
"files": [
"calendar.js",
"calendar.css"
]
}
]
}
Restore library files
The libman restore command installs library files defined in libman.json. The following rules apply:
If no libman.json file exists in the project root, an error is returned.
If a library specifies a provider, the defaultProvider property in libman.json is ignored.
If a library specifies a destination, the defaultDestination property in libman.json is ignored.
Synopsis
libman restore [--verbosity]

libman restore [-h|--help]
Options
The following options are available for the libman restore command:
-h|--help

--verbosity <LEVEL>
quiet
normal
detailed
Examples
To restore the library files defined in libman.json:
libman restore
Delete library files

The libman clean command deletes library files previously restored via LibMan. Folders that become empty after
this operation are deleted. The library files' associated configurations in the libraries property of libman.json
aren't removed.
Synopsis
libman clean [--verbosity]

libman clean [-h|--help]
Options
The following options are available for the libman clean command:
-h|--help

--verbosity <LEVEL>
quiet
normal
detailed
Examples
To delete library files installed via LibMan:
libman clean
Uninstall library files

The libman uninstall command:
Deletes all files associated with the specified library from the destination in libman.json.
Removes the associated library configuration from libman.json.
An error occurs when:
No libman.json file exists in the project root.
The specified library doesn't exist.
If more than one library with the same name is installed, you're prompted to choose one.
Synopsis
libman uninstall <LIBRARY> [--verbosity]

libman uninstall [-h|--help]
Arguments
LIBRARY
The name of the library to uninstall. This name may include version number notation (for example, @1.2.0 ).
Options
The following options are available for the libman uninstall command:
-h|--help

--verbosity <LEVEL>
quiet
normal
detailed
Examples
Consider the following libman.json file:
{
"version": "1.0",
"libraries": [
{
"files": [
"jquery.min.js",
"jquery.js",
"jquery.min.map"
],
"destination": "wwwroot/lib/jquery/"
},
{
"provider": "unpkg",
"destination": "wwwroot/lib/bootstrap/"
},
{
"library": "C:\\temp\\lodash\\",
"files": [
"lodash.js",
"lodash.min.js"
],
"destination": "wwwroot/lib/lodash/"
}
]
}
To uninstall jQuery, either of the following commands succeed:
libman uninstall jquery
libman uninstall [email protected]
To uninstall the Lodash files installed via the filesystem provider:
libman uninstall C:\temp\lodash\
Update library version

The libman update command updates a library installed via LibMan to the specified version.
An error occurs when:
No libman.json file exists in the project root.
The specified library doesn't exist.
If more than one library with the same name is installed, you're prompted to choose one.
Synopsis
libman update <LIBRARY> [-pre] [--to] [--verbosity]

libman update [-h|--help]
Arguments
LIBRARY
The name of the library to update.

Options
The following options are available for the libman update command:
-pre
Obtain the latest prerelease version of the library.

--to <VERSION>
Obtain a specific version of the library.

-h|--help

--verbosity <LEVEL>
quiet
normal
detailed
Examples
To update jQuery to the latest version:
libman update jquery
To update jQuery to version 3.3.1:
libman update jquery --to 3.3.1
To update jQuery to the latest prerelease version:
libman update jquery -pre
Manage library cache

The libman cache command manages the LibMan library cache. The filesystem provider doesn't use the library
cache.
Synopsis
libman cache clean [<PROVIDER>] [--verbosity]

libman cache list [--files] [--libraries] [--verbosity]
libman cache [-h|--help]
Arguments
PROVIDER
Only used with the clean command. Specifies the provider cache to clean. Valid values include:
cdnjs
filesystem
unpkg
Options
The following options are available for the libman cache command:
--files
List the names of files that are cached.

--libraries
List the names of libraries that are cached.

-h|--help

--verbosity <LEVEL>
quiet
normal
detailed
Examples
To view the names of cached libraries per provider, use one of the following commands:
libman cache list
libman cache list --libraries
Output similar to the following is displayed:
Cache contents:
---------------
unpkg:
knockout
react
vue
cdnjs:
font-awesome
jquery
knockout
lodash.js
react
To view the names of cached library files per provider:
libman cache list --files
Output similar to the following is displayed:

Cache contents:
---------------
unpkg:
knockout:
<list omitted for brevity>
react:
vue:
cdnjs:
font-awesome
metadata.json
jquery
metadata.json
3.2.1\core.js
3.2.1\jquery.js
3.2.1\jquery.min.js
3.2.1\jquery.min.map
3.2.1\jquery.slim.js
3.2.1\jquery.slim.min.js
3.2.1\jquery.slim.min.map
3.3.1\core.js
3.3.1\jquery.js
3.3.1\jquery.min.js
3.3.1\jquery.min.map
3.3.1\jquery.slim.js
3.3.1\jquery.slim.min.js
3.3.1\jquery.slim.min.map
knockout
metadata.json
3.4.2\knockout-debug.js
3.4.2\knockout-min.js
lodash.js
metadata.json
4.17.10\lodash.js
4.17.10\lodash.min.js
react
metadata.json
Notice the preceding output shows that jQuery versions 3.2.1 and 3.3.1 are cached under the CDNJS
provider.
To empty the library cache for the CDNJS provider:
libman cache clean cdnjs
After emptying the CDNJS provider cache, the libman cache list command displays the following:
Cache contents:
---------------
unpkg:
knockout
react
vue
cdnjs:
(empty)
To empty the cache for all supported providers:
libman cache clean

After emptying all provider caches, the libman cache list command displays the following:
Cache contents:
---------------
unpkg:
(empty)
cdnjs:
(empty)
Install a Global Tool
By Scott Addie
Visual Studio has built-in support for LibMan in ASP.NET Core projects, including:
Support for configuring and running LibMan restore operations on build.
Menu items for triggering LibMan restore and clean operations.
Search dialog for finding libraries and adding the files to a project.
Editing support for libman.json—the LibMan manifest file.
Prerequisites
Add library files

Library files can be added to an ASP.NET Core project in two different ways:
1. Use the Add Client-Side Library dialog
2. Manually configure LibMan manifest file entries
Use the Add Client-Side Library dialog
Follow these steps to install a client-side library:
In Solution Explorer, right-click the project folder in which the files should be added. Choose Add >
Client-Side Library. The Add Client-Side Library dialog appears:
Select the library provider from the Provider drop down. CDNJS is the default provider.
Type the library name to fetch in the Library text box. IntelliSense provides a list of libraries beginning with
the provided text.
Select the library from the IntelliSense list. Notice the library name is suffixed with the @ symbol and the
latest stable version known to the selected provider.
Decide which files to include:
Select the Include all library files radio button to include all of the library's files.
Select the Choose specific files radio button to include a subset of the library's files. When the radio
button is selected, the file selector tree is enabled. Check the boxes to the left of the file names to
download.
Specify the project folder for storing the files in the Target Location text box. As a recommendation, store
each library in a separate folder.
The suggested Target Location folder is based on the location from which the dialog launched:
If launched from the project root:
wwwroot/lib is used if wwwroot exists.
lib is used if wwwroot doesn't exist.
If launched from a project folder, the corresponding folder name is used.
The folder suggestion is suffixed with the library name. The following table illustrates folder suggestions
when installing jQuery in a Razor Pages project.
LAUNCH LOCATION SUGGESTED FOLDER
project root (if wwwroot exists) wwwroot/lib/jquery/
project root (if wwwroot doesn't exist) lib/jquery/
Pages folder in project Pages/jquery/
Click the Install button to download the files, per the configuration in libman.json.
Review the Library Manager feed of the Output window for installation details. For example:
Restore operation started...

Restoring libraries for project LibManSample
Restoring library [email protected]... (LibManSample)
wwwroot/lib/jquery/jquery.min.js written to destination (LibManSample)
wwwroot/lib/jquery/jquery.js written to destination (LibManSample)
wwwroot/lib/jquery/jquery.min.map written to destination (LibManSample)
Restore operation completed
1 libraries restored in 2.32 seconds
Manually configure LibMan manifest file entries

All LibMan operations in Visual Studio are based on the content of the project root's LibMan manifest
(libman.json). You can manually edit libman.json to configure library files for the project. Visual Studio restores all
library files once libman.json is saved.
To open libman.json for editing, the following options exist:
Double-click the libman.json file in Solution Explorer.
Right-click the project in Solution Explorer and select Manage Client-Side Libraries. †
Select Manage Client-Side Libraries from the Visual Studio Project menu. †
† If the libman.json file doesn't already exist in the project root, it will be created with the default item template
content.
Visual Studio offers rich JSON editing support such as colorization, formatting, IntelliSense, and schema
validation. The LibMan manifest's JSON schema is found at http://json.schemastore.org/libman.
With the following manifest file, LibMan retrieves files per the configuration defined in the libraries property.
An explanation of the object literals defined within libraries follows:
A subset of jQuery version 3.3.1 is retrieved from the CDNJS provider. The subset is defined in the files
property—jquery.min.js, jquery.js, and jquery.min.map. The files are placed in the project's wwwroot/lib/jquery
folder.
The entirety of Bootstrap version 4.1.3 is retrieved and placed in a wwwroot/lib/bootstrap folder. The object
literal's provider property overrides the defaultProvider property value. LibMan retrieves the Bootstrap files
from the unpkg provider.
A subset of Lodash was approved by a governing body within the organization. The lodash.js and lodash.min.js
files are retrieved from the local file system at C:\temp\lodash\. The files are copied to the project's
wwwroot/lib/lodash folder.
{
"version": "1.0",
"libraries": [
{
"files": [
"jquery.min.js",
"jquery.js",
"jquery.min.map"
],
"destination": "wwwroot/lib/jquery/"
},
{
"provider": "unpkg",
"destination": "wwwroot/lib/bootstrap/"
},
{
"library": "C:\\temp\\lodash\\",
"files": [
"lodash.js",
"lodash.min.js"
],
"destination": "wwwroot/lib/lodash/"
}
]
}
NOTE
LibMan only supports one version of each library from each provider. The libman.json file fails schema validation if it
contains two libraries with the same library name for a given provider.
Restore library files

To restore library files from within Visual Studio, there must be a valid libman.json file in the project root. Restored
files are placed in the project at the location specified for each library.
Library files can be restored in an ASP.NET Core project in two ways:
1. Restore files during build
2. Restore files manually
Restore files during build
LibMan can restore the defined library files as part of the build process. By default, the restore-on-build behavior
is disabled.
To enable and test the restore-on-build behavior:
Right-click libman.json in Solution Explorer and select Enable Restore Client-Side Libraries on Build
from the context menu.
Click the Yes button when prompted to install a NuGet package. The Microsoft.Web.LibraryManager.Build
NuGet package is added to the project:
<PackageReference Include="Microsoft.Web.LibraryManager.Build" Version="1.0.113" />
Build the project to confirm LibMan file restoration occurs. The Microsoft.Web.LibraryManager.Build
package injects an MSBuild target that runs LibMan during the project's build operation.
Review the Build feed of the Output window for a LibMan activity log:
1>------ Build started: Project: LibManSample, Configuration: Debug Any CPU ------
1>
1>Restore operation started...
1>Restoring library [email protected]...
1>Restoring library [email protected]...
1>
1>2 libraries restored in 10.66 seconds
1>LibManSample -> C:\LibManSample\bin\Debug\netcoreapp2.1\LibManSample.dll
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========
When the restore-on-build behavior is enabled, the libman.json context menu displays a Disable Restore Client-
Side Libraries on Build option. Selecting this option removes the Microsoft.Web.LibraryManager.Build package
reference from the project file. Consequently, the client-side libraries are no longer restored on each build.
Regardless of the restore-on-build setting, you can manually restore at any time from the libman.json context
menu. For more information, see Restore files manually.
Restore files manually
To manually restore library files:
For all projects in the solution:
Right-click the solution name in Solution Explorer.
Select the Restore Client-Side Libraries option.
For a specific project:
Right-click the libman.json file in Solution Explorer.
Select the Restore Client-Side Libraries option.
While the restore operation is running:
The Task Status Center (TSC ) icon on the Visual Studio status bar will be animated and will read Restore
operation started. Clicking the icon opens a tooltip listing the known background tasks.
Messages will be sent to the status bar and the Library Manager feed of the Output window. For
example:
Restore operation started...
Restoring libraries for project LibManSample
Restoring library [email protected]... (LibManSample)
wwwroot/lib/jquery/jquery.min.js written to destination (LibManSample)
wwwroot/lib/jquery/jquery.js written to destination (LibManSample)
wwwroot/lib/jquery/jquery.min.map written to destination (LibManSample)
Restore operation completed
1 libraries restored in 2.32 seconds
Delete library files

To perform the clean operation, which deletes library files previously restored in Visual Studio:
Right-click the libman.json file in Solution Explorer.
Select the Clean Client-Side Libraries option.
To prevent unintentional removal of non-library files, the clean operation doesn't delete whole directories. It only
removes files that were included in the previous restore.
While the clean operation is running:
The TSC icon on the Visual Studio status bar will be animated and will read Client libraries operation started.
Clicking the icon opens a tooltip listing the known background tasks.
Messages are sent to the status bar and the Library Manager feed of the Output window. For example:
Clean libraries operation started...

Clean libraries operation completed
2 libraries were successfully deleted in 1.91 secs
The clean operation only deletes files from the project. Library files stay in the cache for faster retrieval on future
restore operations. To manage library files stored in the local machine's cache, use the LibMan CLI.
Uninstall library files

To uninstall library files:
Open libman.json.
Position the caret inside the corresponding libraries object literal.
Click the light bulb icon that appears in the left margin, and select Uninstall
<library_name>@<library_version>:
Alternatively, you can manually edit and save the LibMan manifest (libman.json). The restore operation runs when
the file is saved. Library files that are no longer defined in libman.json are removed from the project.
Update library version
To check for an updated library version:
Open libman.json.
Position the caret inside the corresponding libraries object literal.
Click the light bulb icon that appears in the left margin. Hover over Check for updates.
LibMan checks for a library version newer than the version installed. The following outcomes can occur:
A No updates found message is displayed if the latest version is already installed.
The latest stable version is displayed if not already installed.
If a pre-release newer than the installed version is available, the pre-release is displayed.
To downgrade to an older library version, manually edit the libman.json file. When the file is saved, the LibMan
restore operation:
Removes redundant files from the previous version.
Adds new and updated files from the new version.
Use the LibMan command-line interface (CLI) with ASP.NET Core
Manage client-side packages with Bower in ASP.NET
Core
By Rick Anderson, Noel Rice, and Scott Addie
IMPORTANT
While Bower is maintained, its maintainers recommend using a different solution. Library Manager (LibMan for short) is
Visual Studio's new client-side library acquisition tool (Visual Studio 15.8 or later). For more information, see Client-side
library acquisition in ASP.NET Core with LibMan. Bower is supported in Visual Studio through version 15.5.
Yarn with Webpack is one popular alternative for which migration instructions are available.
Bower calls itself "A package manager for the web". Within the .NET ecosystem, it fills the void left by NuGet's
inability to deliver static content files. For ASP.NET Core projects, these static files are inherent to client-side
libraries like jQuery and Bootstrap. For .NET libraries, you still use NuGet package manager.
New projects created with the ASP.NET Core project templates set up the client-side build process. jQuery and
Bootstrap are installed, and Bower is supported.
Client-side packages are listed in the bower.json file. The ASP.NET Core project templates configures bower.json
with jQuery, jQuery validation, and Bootstrap.
In this tutorial, we'll add support for Font Awesome. Bower packages can be installed with the Manage Bower
Packages UI or manually in the bower.json file.
Installation via Manage Bower Packages UI
Create a new ASP.NET Core Web app with the ASP.NET Core Web Application (.NET Core) template.
Select Web Application and No Authentication.
Right-click the project in Solution Explorer and select Manage Bower Packages (alternatively from the
main menu, Project > Manage Bower Packages).
In the Bower: <project name> window, click the "Browse" tab, and then filter the packages list by entering
font-awesome in the search box:
Confirm that the "Save changes to bower.json" checkbox is checked. Select a version from the drop-down
list and click the Install button. The Output window shows the installation details.
Manual installation in bower.json
Open the bower.json file and add "font-awesome" to the dependencies. IntelliSense shows the available packages.
When a package is selected, the available versions are displayed. The images below are older and won't match
what you see.
Bower uses semantic versioning to organize dependencies. Semantic versioning, also known as SemVer, identifies
packages with the numbering scheme <major>.<minor>.<patch>. IntelliSense simplifies semantic versioning by
showing only a few common choices. The top item in the IntelliSense list (4.6.3 in the example above) is
considered the latest stable version of the package. The caret (^) symbol matches the most recent major version
and the tilde (~) matches the most recent minor version.
Save the bower.json file. Visual Studio watches the bower.json file for changes. Upon saving, the bower install
command is executed. See the Output window's Bower/npm view for the exact command executed.
Open the .bowerrc file under bower.json. The directory property is set to wwwroot/lib which indicates the
location Bower will install the package assets.
{
"directory": "wwwroot/lib"
}
You can use the search box in Solution Explorer to find and display the font-awesome package.
Open the Views\Shared_Layout.cshtml file and add the font-awesome CSS file to the environment Tag Helper for
Development . From Solution Explorer, drag and drop font-awesome.css inside the
<environment names="Development"> element.
<link href="~/lib/font-awesome/css/font-awesome.css" rel="stylesheet" />
</environment>
In a production app you would add font-awesome.min.css to the environment tag helper for Staging,Production .
Replace the contents of the Views\Home\About.cshtml Razor file with the following markup:
@{
}
<div class="list-group">
<a class="list-group-item" href="#"><i class="fa fa-home fa-fw" aria-hidden="true"></i> Home</a>
<a class="list-group-item" href="#"><i class="fa fa-book fa-fw" aria-hidden="true"></i> Library</a>
<a class="list-group-item" href="#"><i class="fa fa-pencil fa-fw" aria-hidden="true"></i>
Applications</a>
<a class="list-group-item" href="#"><i class="fa fa-cog fa-fw" aria-hidden="true"></i> Settings</a>
</div>
Run the app and navigate to the About view to verify the font-awesome package works.
Exploring the client-side build process

Most ASP.NET Core project templates are already configured to use Bower. This next walkthrough starts with an
empty ASP.NET Core project and adds each piece manually, so you can get a feel for how Bower is used in a
project. You can see what happens to the project structure and the runtime output as each configuration change is
made.
The general steps to use the client-side build process with Bower are:
Define packages used in your project.
Reference packages from your web pages.
Define packages
Once you list packages in the bower.json file, Visual Studio will download them. The following example uses Bower
to load jQuery and Bootstrap to the wwwroot folder.
Create a new ASP.NET Core Web app with the ASP.NET Core Web Application (.NET Core) template.
Select the Empty project template and click OK.
In Solution Explorer, right-click the project > Add New Item and select Bower Configuration File. Note:
A .bowerrc file is also added.
Open bower.json, and add jquery and bootstrap to the dependencies section. The resulting bower.json file
will look like the following example. The versions will change over time and may not match the image
below.
{
"name": "asp.net",
"private": true,
"dependencies": {
"jquery": "3.1.1",
"bootstrap": "3.3.7"
}
}
Save the bower.json file.

Verify the project includes the bootstrap and jQuery directories in wwwroot/lib. Bower uses the .bowerrc
file to install the assets in wwwroot/lib.
Note: The "Manage Bower Packages" UI provides an alternative to manual file editing.
Enable static files
Add the Microsoft.AspNetCore.StaticFiles NuGet package to the project.
Enable static files to be served with the Static file middleware. Add a call to UseStaticFiles to the Configure
method of Startup .

{
{

{
});
}
}
Reference packages
In this section, you will create an HTML page to verify it can access the deployed packages.
Add a new HTML page named Index.html to the wwwroot folder. Note: You must add the HTML file to the
wwwroot folder. By default, static content cannot be served outside wwwroot. See Static files for more
information.
Replace the contents of Index.html with the following markup:
<!DOCTYPE html>
<html>
<head>
<title>Bower Example</title>
<link href="lib/bootstrap/dist/css/bootstrap.css" rel="stylesheet" />
</head>
<body>
<h1>Using the jumbotron style</h1>
<p>
<a class="btn btn-primary btn-lg" role="button">Stateful button</a>
</p>
</div>
<script src="lib/jquery/dist/jquery.js"></script>
<script src="lib/bootstrap/dist/js/bootstrap.js"></script>
<script>
$(".btn").click(function () {
$(this).text('loading')
.delay(1000)
.queue(function () {
$(this).text('reset');
$(this).dequeue();
});
});
</script>
</body>
</html>
Run the app and navigate to http://localhost:<port>/Index.html . Alternatively, with Index.html opened,
press Ctrl+Shift+W . Verify that the jumbotron styling is applied, the jQuery code responds when the button
is clicked, and that the Bootstrap button changes state.
Build beautiful, responsive sites with Bootstrap and
ASP.NET Core
By Steve Smith
Bootstrap is currently the most popular web framework for developing responsive web applications. It offers a
number of features and benefits that can improve your users' experience with your web site, whether you're a
novice at front-end design and development or an expert. Bootstrap is deployed as a set of CSS and JavaScript
files, and is designed to help your website or application scale efficiently from phones to tablets to desktops.
Get started
There are several ways to get started with Bootstrap. If you're starting a new web application in Visual Studio, you
can choose the default starter template for ASP.NET Core, in which case Bootstrap will come pre-installed:
Adding Bootstrap to an ASP.NET Core project is simply a matter of adding it to bower.json as a dependency:
{
"name": "asp.net",
"private": true,
"dependencies": {
"bootstrap": "3.3.6",
"jquery": "2.2.0",
"jquery-validation": "1.14.0",
"jquery-validation-unobtrusive": "3.2.6"
}
}
This is the recommended way to add Bootstrap to an ASP.NET Core project.

You can also install bootstrap using one of several package managers, such as Bower, npm, or NuGet. In each
case, the process is essentially the same:
Bower
bower install bootstrap
npm
npm install bootstrap
NuGet
Install-Package bootstrap
NOTE
The recommended way to install client-side dependencies like Bootstrap in ASP.NET Core is via Bower (using bower.json, as
shown above). The use of npm/NuGet are shown to demonstrate how easily Bootstrap can be added to other kinds of web
applications, including earlier versions of ASP.NET.
If you're referencing your own local versions of Bootstrap, you'll need to reference them in any pages that will use
it. In production you should reference bootstrap using a CDN. In the default ASP.NET Core site template, the
_Layout.cshtml file does so like this:
<!DOCTYPE html>
<html>
<head>
<title>@ViewData["Title"] - WebApplication1</title>
</environment>
value="absolute" />
</environment>
</head>
<body>
collapse">
</button>
<a asp-area="" asp-controller="Home" asp-action="Index" class="navbar-
brand">WebApplication1</a>
</div>
</ul>
</div>
</div>
</div>
@RenderBody()
<hr />
<footer>
<p>© 2016 - WebApplication1</p>
</footer>
</div>
</environment>
</script>
asp-fallback-test="window.jQuery && window.jQuery.fn && window.jQuery.fn.modal">
</script>
</environment>

</body>
</html>
NOTE
If you're going to be using any of Bootstrap's jQuery plugins, you will also need to reference jQuery.
Basic templates and features

The most basic Bootstrap template looks very much like the _Layout.cshtml file shown above, and simply includes
a basic menu for navigation and a place to render the rest of the page.
Basic navigation
The default template uses a set of <div> elements to render a top navbar and the main body of the page. If you're
using HTML5, you can replace the first <div> tag with a <nav> tag to get the same effect, but with more precise
semantics. Within this first <div> you can see there are several others. First, a <div> with a class of "container",
and then within that, two more <div> elements: "navbar-header" and "navbar-collapse". The navbar-header div
includes a button that will appear when the screen is below a certain minimum width, showing 3 horizontal lines
(a so-called "hamburger icon"). The icon is rendered using pure HTML and CSS; no image is required. This is the
code that displays the icon, with each of the tags rendering one of the white bars:
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">

</button>
It also includes the application name, which appears in the top left. The main navigation menu is rendered by the
<ul> element within the second div, and includes links to Home, About, and Contact. Below the navigation, the
main body of each page is rendered in another <div> , marked with the "container" and "body-content" classes. In
the simple default _Layout file shown here, the contents of the page are rendered by the specific View associated
with the page, and then a simple <footer> is added to the end of the <div> element. You can see how the built-in
About page appears using this template:
The collapsed navbar, with "hamburger" button in the top right, appears when the window drops below a certain
width:
Clicking the icon reveals the menu items in a vertical drawer that slides down from the top of the page:
Typography and links
Bootstrap sets up the site's basic typography, colors, and link formatting in its CSS file. This CSS file includes
default styles for tables, buttons, form elements, images, and more (learn more). One particularly useful feature is
the grid layout system, covered next.
Grids
One of the most popular features of Bootstrap is its grid layout system. Modern web applications should avoid
using the <table> tag for layout, instead restricting the use of this element to actual tabular data. Instead,
columns and rows can be laid out using a series of <div> elements and the appropriate CSS classes. There are
several advantages to this approach, including the ability to adjust the layout of grids to display vertically on
narrow screens, such as on phones.
Bootstrap's grid layout system is based on twelve columns. This number was chosen because it can be divided
evenly into 1, 2, 3, or 4 columns, and column widths can vary to within 1/12th of the vertical width of the screen.
To start using the grid layout system, you should begin with a container <div> and then add a row <div> , as
shown here:
<div class="row">
...
</div>
</div>
Next, add additional <div> elements for each column, and specify the number of columns that <div> should
occupy (out of 12) as part of a CSS class starting with "col-md-". For instance, if you want to simply have two
columns of equal size, you would use a class of "col-md-6" for each one. In this case "md" is short for "medium"
and refers to standard-sized desktop computer display sizes. There are four different options you can choose from,
and each will be used for higher widths unless overridden (so if you want the layout to be fixed regardless of
screen width, you can just specify xs classes).
CSS CLASS PREFIX DEVICE TIER WIDTH
col-xs- Phones < 768px
col-sm- Tablets >= 768px
col-md- Desktops >= 992px
col-lg- Larger Desktop Displays >= 1200px
When specifying two columns both with "col-md-6" the resulting layout will be two columns at desktop
resolutions, but these two columns will stack vertically when rendered on smaller devices (or a narrower browser
window on a desktop), allowing users to easily view content without the need to scroll horizontally.
Bootstrap will always default to a single-column layout, so you only need to specify columns when you want more
than one column. The only time you would want to explicitly specify that a <div> take up all 12 columns would be
to override the behavior of a larger device tier. When specifying multiple device tier classes, you may need to reset
the column rendering at certain points. Adding a clearfix div that's only visible within a certain viewport can
achieve this, as shown here:
In the above example, One and Two share a row in the "md" layout, while Two and Three share a row in the "xs"
layout. Without the clearfix <div> , Two and Three are not shown correctly in the "xs" view (note that only One,
Four, and Five are shown):
In this example, only a single row <div> was used, and Bootstrap still mostly did the right thing with regard to the
layout and stacking of the columns. Typically, you should specify a row <div> for each horizontal row your layout
requires, and of course you can nest Bootstrap grids within one another. When you do, each nested grid will
occupy 100% of the width of the element in which it's placed, which can then be subdivided using column classes.
Jumbotron
If you've used the default ASP.NET Core MVC templates in Visual Studio 2012 or 2013, you've probably seen the
Jumbotron in action. It refers to a large full-width section of a page that can be used to display a large background
image, a call to action, a rotator, or similar elements. To add a jumbotron to a page, simply add a <div> and give it
a class of "jumbotron", then place a container <div> inside and add your content. We can easily adjust the
standard About page to use a jumbotron for the main headings it displays:
Buttons
The default button classes and their colors are shown in the figure below.
Badges
Badges refer to small, usually numeric callouts next to a navigation item. They can indicate a number of messages
or notifications waiting, or the presence of updates. Specifying such badges is as simple as adding a <span>
containing the text, with a class of "badge":
Alerts
You may need to display some kind of notification, alert, or error message to your application's users. That's where
the standard alert classes are useful. There are four different severity levels with associated color schemes:
Navbars and menus
Our layout already includes a standard navbar, but the Bootstrap theme supports additional styling options. We
can also easily opt to display the navbar vertically rather than horizontally if that's preferred, as well as adding
sub-navigation items in flyout menus. Simple navigation menus, like tab strips, are built on top of <ul> elements.
These can be created very simply by just providing them with the CSS classes "nav" and "nav-tabs":
Navbars are built similarly, but are a bit more complex. They start with a <nav> or <div> with a class of "navbar",
within which a container div holds the rest of the elements. Our page includes a navbar in its header already – the
one shown below simply expands on this, adding support for a dropdown menu:
Additional elements
The default theme can also be used to present HTML tables in a nicely formatted style, including support for
striped views. There are labels with styles that are similar to those of the buttons. You can create custom
Dropdown menus that support additional styling options beyond the standard HTML <select> element, along
with Navbars like the one our default starter site is already using. If you need a progress bar, there are several
styles to choose from, as well as List Groups and panels that include a title and content. Explore additional options
within the standard Bootstrap Theme here:
http://getbootstrap.com/examples/theme/
More themes
You can extend the standard Bootstrap theme by overriding some or all of its CSS, adjusting the colors and styles
to suit your own application's needs. If you'd like to start from a ready-made theme, there are several theme
galleries available online that specialize in Bootstrap themes, such as WrapBootstrap.com (which has a variety of
commercial themes) and Bootswatch.com (which offers free themes). Some of the paid templates available
provide a great deal of functionality on top of the basic Bootstrap theme, such as rich support for administrative
menus, and dashboards with rich charts and gauges. An example of a popular paid template is Inspinia, which is
shown in the following screenshot:
If you want to change your Bootstrap theme, put the bootstrap.css file for the theme you want in the
wwwroot/css folder and change the references in _Layout.cshtml to point it. Change the links for all
environments:
<link rel="stylesheet" href="~/css/bootstrap.css" />
<link rel="stylesheet" href="~/css/bootstrap.min.css" />
If you want to build your own dashboard, you can start from the free example available here:
http://getbootstrap.com/examples/dashboard/.
Components
In addition to those elements already discussed, Bootstrap includes support for a variety of built-in UI
components.
Glyphicons
Bootstrap includes icon sets from Glyphicons (http://glyphicons.com), with over 200 icons freely available for use
within your Bootstrap-enabled web application. Here's just a small sample:
Input groups
Input groups allow bundling of additional text or buttons with an input element, providing the user with a more
intuitive experience:
Breadcrumbs
Breadcrumbs are a common UI component used to show a user their recent history or depth within a site's
navigation hierarchy. Add them easily by applying the "breadcrumb" class to any <ol> list element. Include built-
in support for pagination by using the "pagination" class on a <ul> element within a <nav> . Add responsive
embedded slideshows and video by using <iframe> , <embed> , <video> , or <object> elements, which Bootstrap
will style automatically. Specify a particular aspect ratio by using specific classes like "embed-responsive-16by9".
JavaScript support
Bootstrap's JavaScript library includes API support for the included components, allowing you to control their
behavior programmatically within your application. In addition, bootstrap.js includes over a dozen custom jQuery
plugins, providing additional features like transitions, modal dialogs, scroll detection (updating styles based on
where the user has scrolled in the document), collapse behavior, carousels, and affixing menus to the window so
they don't scroll off the screen. There's not sufficient room to cover all of the JavaScript add-ons built into
Bootstrap – to learn more please visit http://getbootstrap.com/javascript/.
Summary
Bootstrap provides a web framework that can be used to quickly and productively lay out and style a wide variety
of websites and applications. Its basic typography and styles provide a pleasant look and feel that can easily be
manipulated through custom theme support, which can be hand-crafted or purchased commercially. It supports a
host of web components that in the past would've required expensive third-party controls to accomplish, while
supporting modern and open web standards.
Less, Sass, and Font Awesome in ASP.NET Core
By Steve Smith
Users of web applications have increasingly high expectations when it comes to style and overall experience.
Modern web applications frequently leverage rich tools and frameworks for defining and managing their look and
feel in a consistent manner. Frameworks like Bootstrap can go a long way toward defining a common set of styles
and layout options for web sites. However, most non-trivial sites also benefit from being able to effectively define
and maintain styles and cascading style sheet (CSS ) files, as well as having easy access to non-image icons that
help make the site's interface more intuitive. That's where languages and tools that support Less and Sass, and
libraries like Font Awesome, come in.
CSS preprocessor languages

Languages that are compiled into other languages, in order to improve the experience of working with the
underlying language, are referred to as preprocessors. There are two popular preprocessors for CSS: Less and
Sass. These preprocessors add features to CSS, such as support for variables and nested rules, which improve the
maintainability of large, complex stylesheets. CSS as a language is very basic, lacking support even for something
as simple as variables, and this tends to make CSS files repetitive and bloated. Adding real programming language
features via preprocessors can help reduce duplication and provide better organization of styling rules. Visual
Studio provides built-in support for both Less and Sass, as well as extensions that can further improve the
development experience when working with these languages.
As a quick example of how preprocessors can improve readability and maintainability of style information,
consider this CSS:
.header {
color: black;
font-weight: bold;
font-size: 18px;
font-family: Helvetica, Arial, sans-serif;
}
.small-header {
color: black;
font-weight: bold;
font-size: 14px;
}
Using Less, this can be rewritten to eliminate all of the duplication, using a mixin (so named because it allows you
to "mix in" properties from one class or rule-set into another):
.header {
color: black;
font-weight: bold;
font-size: 18px;
}
.small-header {
.header;
font-size: 14px;
}
Less
The Less CSS preprocessor runs using Node.js. To install Less, use Node Package Manager (npm) from a
command prompt (-g means "global"):
npm install -g less
If you're using Visual Studio, you can get started with Less by adding one or more Less files to your project, and
then configuring Gulp (or Grunt) to process them at compile-time. Add a Styles folder to your project, and then
add a new Less file named main.less to this folder.
Once added, your folder structure should look something like this:
Now you can add some basic styling to the file, which will be compiled into CSS and deployed to the wwwroot
folder by Gulp.
Modify main.less to include the following content, which creates a simple color palette from a single base color.
@base: #663333;
@background: spin(@base, 180);
@lighter: lighten(spin(@base, 5), 10%);
@lighter2: lighten(spin(@base, 10), 20%);
@darker: darken(spin(@base, -5), 10%);
@darker2: darken(spin(@base, -10), 20%);
body {
background-color:@background;
}
.baseColor {color:@base}
.bgLight {color:@lighter}
.bgLight2 {color:@lighter2}
.bgDark {color:@darker}
.bgDark2 {color:@darker2}
@base and the other @-prefixed items are variables. Each of them represents a color. Except for @base , they're set
using color functions: lighten, darken, and spin. Lighten and darken do pretty much what you would expect; spin
adjusts the hue of a color by a number of degrees (around the color wheel). The Less processor is smart enough to
ignore variables that aren't used, so to demonstrate how these variables work, we need to use them somewhere.
The classes .baseColor , etc. will demonstrate the calculated values of each of the variables in the CSS file that's
produced.
Get started
Create an npm Configuration File (package.json) in your project folder and edit it to reference gulp and
gulp-less :
{
"version": "1.0.0",
"name": "asp.net",
"private": true,
"gulp": "3.9.1",
"gulp-less": "3.3.0"
}
}
Install the dependencies either at a command prompt in your project folder, or in Visual Studio Solution Explorer
(Dependencies > npm > Restore packages).
npm install
In the project folder, create a Gulp Configuration File (gulpfile.js) to define the automated process. Add a variable
at the top of the file to represent Less, and a task to run Less:

fs = require("fs"),
less = require("gulp-less");
gulp.task("less", function () {
return gulp.src('Styles/main.less')
.pipe(less())
.pipe(gulp.dest('wwwroot/css'));
});
Open the Task Runner Explorer (View > Other Windows > Task Runner Explorer). Among the tasks, you
should see a new task named less . You might have to refresh the window.
Run the less task, and you see output similar to what is shown here:
The wwwroot/css folder now contains a new file, main.css:

Open main.css and you see something like the following:
body {
}
.baseColor {
color: #663333;
}
.bgLight {
color: #884a44;
}
.bgLight2 {
color: #aa6355;
}
.bgDark {
color: #442225;
}
.bgDark2 {
color: #221114;
}
Add a simple HTML page to the wwwroot folder, and reference main.css to see the color palette in action.
<!DOCTYPE html>
<html>
<head>
<link href="css/main.css" rel="stylesheet" />
<title></title>
</head>
<body>
<div>
<div class="baseColor">BaseColor</div>
<div class="bgLight">Light</div>
<div class="bgLight2">Light2</div>
<div class="bgDark">Dark</div>
<div class="bgDark2">Dark2</div>
</div>
</body>
</html>
You can see that the 180 degree spin on @base used to produce @background resulted in the color wheel opposing
color of @base :
Less also provides support for nested rules, as well as nested media queries. For example, defining nested
hierarchies like menus can result in verbose CSS rules like these:
nav {
height: 40px;
width: 100%;
}
nav li {
height: 38px;
width: 100px;
}
nav li a:link {
color: #000;
text-decoration: none;
}
nav li a:visited {
text-decoration: none;
color: #CC3333;
}
nav li a:hover {
text-decoration: underline;
font-weight: bold;
}
nav li a:active {
text-decoration: underline;
}
Ideally all of the related style rules will be placed together within the CSS file, but in practice there's nothing
enforcing this rule except convention and perhaps block comments.
Defining these same rules using Less looks like this:
nav {
height: 40px;
width: 100%;
li {
height: 38px;
width: 100px;
a {
color: #000;
&:link { text-decoration:none}
&:visited { color: #CC3333; text-decoration:none}
&:hover { text-decoration:underline; font-weight:bold}
&:active {text-decoration:underline}
}
}
}
Note that in this case, all of the subordinate elements of nav are contained within its scope. There's no longer any
repetition of parent elements ( nav , li , a ), and the total line count has dropped as well (though some of that's a
result of putting values on the same lines in the second example). It can be very helpful, organizationally, to see all
of the rules for a given UI element within an explicitly bounded scope, in this case set off from the rest of the file by
curly braces.
The & syntax is a Less selector feature, with & representing the current selector parent. So, within the a {...} block,
& represents an a tag, and thus &:link is equivalent to a:link .
Media queries, extremely useful in creating responsive designs, can also contribute heavily to repetition and
complexity in CSS. Less allows media queries to be nested within classes, so that the entire class definition doesn't
need to be repeated within different top-level @media elements. For example, here is CSS for a responsive menu:
.navigation {
margin-top: 30%;
width: 100%;
}
@media screen and (min-width: 40em) {
.navigation {
margin: 0;
}
}
.navigation {
width: 960px;
margin: 0;
}
}
This can be better defined in Less as:
.navigation {
margin-top: 30%;
width: 100%;
margin: 0;
}
width: 960px;
margin: 0;
}
}
Another feature of Less that we have already seen is its support for mathematical operations, allowing style
attributes to be constructed from pre-defined variables. This makes updating related styles much easier, since the
base variable can be modified and all dependent values change automatically.
CSS files, especially for large sites (and especially if media queries are being used), tend to get quite large over
time, making working with them unwieldy. Less files can be defined separately, then pulled together using @import
directives. Less can also be used to import individual CSS files, as well, if desired.
Mixins can accept parameters, and Less supports conditional logic in the form of mixin guards, which provide a
declarative way to define when certain mixins take effect. A common use for mixin guards is to adjust colors based
on how light or dark the source color is. Given a mixin that accepts a parameter for color, a mixin guard can be
used to modify the mixin based on that color:
.box (@color) when (lightness(@color) >= 50%) {
}
.box (@color) when (lightness(@color) < 50%) {
background-color: #FFF;
}
.box (@color) {
color: @color;
}
.feature {
.box (@base);
}
Given our current @base value of #663333 , this Less script will produce the following CSS:
.feature {
background-color: #FFF;
color: #663333;
}
Less provides a number of additional features, but this should give you some idea of the power of this
preprocessing language.
Sass
Sass is similar to Less, providing support for many of the same features, but with slightly different syntax. It's built
using Ruby, rather than JavaScript, and so has different setup requirements. The original Sass language didn't use
curly braces or semicolons, but instead defined scope using white space and indentation. In version 3 of Sass, a
new syntax was introduced, SCSS ("Sassy CSS"). SCSS is similar to CSS in that it ignores indentation levels and
whitespace, and instead uses semicolons and curly braces.
To install Sass, typically you would first install Ruby (pre-installed on macOS ), and then run:
gem install sass
However, if you're running Visual Studio, you can get started with Sass in much the same way as you would with
Less. Open package.json and add the "gulp-sass" package to devDependencies :
"gulp": "3.9.1",
"gulp-less": "3.3.0",
"gulp-sass": "3.1.0"
}
Next, modify gulpfile.js to add a sass variable and a task to compile your Sass files and place the results in the
wwwroot folder:
fs = require("fs"),
less = require("gulp-less"),
sass = require("gulp-sass");
// other content removed
gulp.task("sass", function () {
return gulp.src('Styles/main2.scss')
.pipe(sass())
.pipe(gulp.dest('wwwroot/css'));
});
Now you can add the Sass file main2.scss to the Styles folder in the root of the project:
Open main2.scss and add the following:
$base: #CC0000;
body {
background-color: $base;
}
Save all of your files. Now when you refresh Task Runner Explorer, you see a sass task. Run it, and look in the
/wwwroot/css folder. There's now a main2.css file, with these contents:
body {
background-color: #CC0000;
}
Sass supports nesting in much the same was that Less does, providing similar benefits. Files can be split up by
function and included using the @import directive:
@import 'anotherfile';
Sass supports mixins as well, using the @mixin keyword to define them and @include to include them, as in this
example from sass-lang.com:
@mixin border-radius($radius) {
-webkit-border-radius: $radius;
-moz-border-radius: $radius;
-ms-border-radius: $radius;
border-radius: $radius;
}
.box { @include border-radius(10px); }
In addition to mixins, Sass also supports the concept of inheritance, allowing one class to extend another. It's
conceptually similar to a mixin, but results in less CSS code. It's accomplished using the @extend keyword. To try
out mixins, add the following to your main2.scss file:
@mixin alert {
border: 1px solid black;
padding: 5px;
color: #333333;
}
.success {
@include alert;
border-color: green;
}
.error {
@include alert;
color: red;
border-color: red;
font-weight:bold;
}
Examine the output in main2.css after running the sass task in Task Runner Explorer:
.success {
padding: 5px;
color: #333333;
}
.error {
padding: 5px;
color: #333333;
color: red;
border-color: red;
font-weight: bold;
}
Notice that all of the common properties of the alert mixin are repeated in each class. The mixin did a good job of
helping eliminate duplication at development time, but it's still creating CSS with a lot of duplication in it, resulting
in larger than necessary CSS files - a potential performance issue.
Now replace the alert mixin with a .alert class, and change @include to @extend (remembering to extend
.alert , not alert ):
.alert {
padding: 5px;
color: #333333;
}
.success {
@extend .alert;
}
.error {
@extend .alert;
color: red;
border-color: red;
font-weight:bold;
}
Run Sass once more, and examine the resulting CSS:
.alert, .success, .error {

padding: 5px;
color: #333333;
}
.success {
}
.error {
color: red;
border-color: red;
font-weight: bold;
}
Now the properties are defined only as many times as needed, and better CSS is generated.
Sass also includes functions and conditional logic operations, similar to Less. In fact, the two languages' capabilities
are very similar.
Less or Sass?
There's still no consensus as to whether it's generally better to use Less or Sass (or even whether to prefer the
original Sass or the newer SCSS syntax within Sass). Probably the most important decision is to use one of these
tools, as opposed to just hand-coding your CSS files. Once you've made that decision, both Less and Sass are
good choices.
Font Awesome
In addition to CSS preprocessors, another great resource for styling modern web applications is Font Awesome.
Font Awesome is a toolkit that provides over 500 scalable vector icons that can be freely used in your web
applications. It was originally designed to work with Bootstrap, but it has no dependency on that framework or on
any JavaScript libraries.
The easiest way to get started with Font Awesome is to add a reference to it, using its public content delivery
network (CDN ) location:
<link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">
You can also add it to your Visual Studio project by adding it to the "dependencies" in bower.json:
{
"name": "ASP.NET",
"private": true,
"dependencies": {
"bootstrap": "3.0.0",
"jquery": "1.10.2",
"jquery-validation": "1.11.1",
"jquery-validation-unobtrusive": "3.2.2",
"hammer.js": "2.0.4",
"bootstrap-touch-carousel": "0.8.0",
"Font-Awesome": "4.3.0"
}
}
Once you have a reference to Font Awesome on a page, you can add icons to your application by applying Font
Awesome classes, typically prefixed with "fa-", to your inline HTML elements (such as <span> or <i> ). For
example, you can add icons to simple lists and menus using code like this:
<!DOCTYPE html>
<html>
<head>
<title></title>
<link href="lib/font-awesome/css/font-awesome.css" rel="stylesheet" />
</head>
<body>
<ul class="fa-ul">
<li><i class="fa fa-li fa-home"></i> Home</li>
<li><i class="fa fa-li fa-cog"></i> Settings</li>
</ul>
</body>
</html>
This produces the following in the browser - note the icon beside each item:
You can view a complete list of the available icons here:

http://fontawesome.io/icons/
Summary
Modern web applications increasingly demand responsive, fluid designs that are clean, intuitive, and easy to use
from a variety of devices. Managing the complexity of the CSS stylesheets required to achieve these goals is best
done using a preprocessor like Less or Sass. In addition, toolkits like Font Awesome quickly provide well-known
icons to textual navigation menus and buttons, improving the overall user experience of your application.
Bundle and minify static assets in ASP.NET Core
By Scott Addie
This article explains the benefits of applying bundling and minification, including how these features can be used
with ASP.NET Core web apps.
What is bundling and minification

Bundling and minification are two distinct performance optimizations you can apply in a web app. Used together,
bundling and minification improve performance by reducing the number of server requests and reducing the size
of the requested static assets.
Bundling and minification primarily improve the first page request load time. Once a web page has been
requested, the browser caches the static assets (JavaScript, CSS, and images). Consequently, bundling and
minification don't improve performance when requesting the same page, or pages, on the same site requesting
the same assets. If the expires header isn't set correctly on the assets and if bundling and minification isn't used,
the browser's freshness heuristics mark the assets stale after a few days. Additionally, the browser requires a
validation request for each asset. In this case, bundling and minification provide a performance improvement even
after the first page request.
Bundling
Bundling combines multiple files into a single file. Bundling reduces the number of server requests which are
necessary to render a web asset, such as a web page. You can create any number of individual bundles specifically
for CSS, JavaScript, etc. Fewer files means fewer HTTP requests from the browser to the server or from the
service providing your application. This results in improved first page load performance.
Minification
Minification removes unnecessary characters from code without altering functionality. The result is a significant
size reduction in requested assets (such as CSS, images, and JavaScript files). Common side effects of minification
include shortening variable names to one character and removing comments and unnecessary whitespace.
Consider the following JavaScript function:
AddAltToImg = function (imageTagAndImageID, imageContext) {

///<signature>
///<summary> Adds an alt tab to the image
// </summary>
//<param name="imgElement" type="String">The image selector.</param>
//<param name="ContextForImage" type="String">The image context.</param>
///</signature>
var imageElement = $(imageTagAndImageID, imageContext);
imageElement.attr('alt', imageElement.attr('id').replace(/ID/, ''));
}
Minification reduces the function to the following:
AddAltToImg=function(n,t){var i=$(n,t);i.attr("alt",i.attr("id").replace(/ID/,""))};
In addition to removing the comments and unnecessary whitespace, the following parameter and variable names
were renamed as follows:
ORIGINAL RENAMED
imageTagAndImageID t
imageContext a
imageElement r
Impact of bundling and minification

The following table outlines differences between individually loading assets and using bundling and minification:
ACTION WITH B/M WITHOUT B/M CHANGE
File Requests 7 18 157%
KB Transferred 156 264.68 70%
Load Time (ms) 885 2360 167%
Browsers are fairly verbose with regard to HTTP request headers. The total bytes sent metric saw a significant
reduction when bundling. The load time shows a significant improvement, however this example ran locally.
Greater performance gains are realized when using bundling and minification with assets transferred over a
network.
Choose a bundling and minification strategy

The MVC and Razor Pages project templates provide an out-of-the-box solution for bundling and minification
consisting of a JSON configuration file. Third-party tools, such as the Gulp and Grunt task runners, accomplish
the same tasks with a bit more complexity. A third-party tool is a great fit when your development workflow
requires processing beyond bundling and minification—such as linting and image optimization. By using design-
time bundling and minification, the minified files are created prior to the app's deployment. Bundling and
minifying before deployment provides the advantage of reduced server load. However, it's important to recognize
that design-time bundling and minification increases build complexity and only works with static files.
Configure bundling and minification

The MVC and Razor Pages project templates provide a bundleconfig.json configuration file which defines the
options for each bundle. By default, a single bundle configuration is defined for the custom JavaScript
(wwwroot/js/site.js) and stylesheet (wwwroot/css/site.css) files:
[
{
"outputFileName": "wwwroot/css/site.min.css",
"inputFiles": [
"wwwroot/css/site.css"
]
},
{
"outputFileName": "wwwroot/js/site.min.js",
"inputFiles": [
"wwwroot/js/site.js"
],
"minify": {
"enabled": true,
"renameLocals": true
},
"sourceMap": false
}
]
Configuration options include:

outputFileName : The name of the bundle file to output. Can contain a relative path from the bundleconfig.json
file. required
inputFiles : An array of files to bundle together. These are relative paths to the configuration file. optional,
*an empty value results in an empty output file. globbing patterns are supported.
minify : The minification options for the output type. optional, default - minify: { enabled: true }
Configuration options are available per output file type.
CSS Minifier
JavaScript Minifier
HTML Minifier
includeInProject : Flag indicating whether to add generated files to project file. optional, default - false
sourceMap : Flag indicating whether to generate a source map for the bundled file. optional, default - false
sourceMapRootPath : The root path for storing the generated source map file.
Build-time execution of bundling and minification

The BuildBundlerMinifier NuGet package enables the execution of bundling and minification at build time. The
package injects MSBuild Targets which run at build and clean time. The bundleconfig.json file is analyzed by the
build process to produce the output files based on the defined configuration.
NOTE
BuildBundlerMinifier belongs to a community-driven project on GitHub for which Microsoft provides no support. Issues
should be filed here.
Visual Studio
.NET Core CLI
Add the BuildBundlerMinifier package to your project.
Build the project. The following appears in the Output window:
1>------ Build started: Project: BuildBundlerMinifierApp, Configuration: Debug Any CPU ------
1>
1>Bundler: Begin processing bundleconfig.json
1> Minified wwwroot/css/site.min.css
1> Minified wwwroot/js/site.min.js
1>Bundler: Done processing bundleconfig.json
1>BuildBundlerMinifierApp -> C:\BuildBundlerMinifierApp\bin\Debug\netcoreapp2.0\BuildBundlerMinifierApp.dll
Clean the project. The following appears in the Output window:
1>------ Clean started: Project: BuildBundlerMinifierApp, Configuration: Debug Any CPU ------
1>
1>Bundler: Cleaning output from bundleconfig.json
1>Bundler: Done cleaning output file from bundleconfig.json
========== Clean: 1 succeeded, 0 failed, 0 skipped ==========
Ad hoc execution of bundling and minification

It's possible to run the bundling and minification tasks on an ad hoc basis, without building the project. Add the
BundlerMinifier.Core NuGet package to your project:
<DotNetCliToolReference Include="BundlerMinifier.Core" Version="2.6.362" />
NOTE
BundlerMinifier.Core belongs to a community-driven project on GitHub for which Microsoft provides no support. Issues
should be filed here.
This package extends the .NET Core CLI to include the dotnet-bundle tool. The following command can be
executed in the Package Manager Console (PMC ) window or in a command shell:
dotnet bundle
IMPORTANT
NuGet Package Manager adds dependencies to the *.csproj file as <PackageReference /> nodes. The dotnet bundle
command is registered with the .NET Core CLI only when a <DotNetCliToolReference /> node is used. Modify the *.csproj
file accordingly.
Add files to workflow

Consider an example in which an additional custom.css file is added resembling the following:
.about, [role=main], [role=complementary] {

margin-top: 60px;
}
footer {
margin-top: 10px;
}
To minify custom.css and bundle it with site.css into a site.min.css file, add the relative path to bundleconfig.json:
[
{
"outputFileName": "wwwroot/css/site.min.css",
"inputFiles": [
"wwwroot/css/site.css",
"wwwroot/css/custom.css"
]
},
{
"outputFileName": "wwwroot/js/site.min.js",
"inputFiles": [
"wwwroot/js/site.js"
],
"minify": {
"enabled": true,
"renameLocals": true
},
"sourceMap": false
}
]
NOTE
Alternatively, the following globbing pattern could be used:
"inputFiles": ["wwwroot/**/*(*.css|!(*.min.css))"]
This globbing pattern matches all CSS files and excludes the minified file pattern.
Build the application. Open site.min.css and notice the content of custom.css is appended to the end of the file.
Environment-based bundling and minification

As a best practice, the bundled and minified files of your app should be used in a production environment. During
development, the original files make for easier debugging of the app.
Specify which files to include in your pages by using the Environment Tag Helper in your views. The Environment
Tag Helper only renders its contents when running in specific environments.
The following environment tag renders the unprocessed CSS files when running in the Development environment:
ASP.NET Core 2.x
ASP.NET Core 1.x
</environment>
The following environment tag renders the bundled and minified CSS files when running in an environment other
than Development . For example, running in Production or Staging triggers the rendering of these stylesheets:
ASP.NET Core 2.x
ASP.NET Core 1.x
value="absolute" />
</environment>
Consume bundleconfig.json from Gulp

There are cases in which an app's bundling and minification workflow requires additional processing. Examples
include image optimization, cache busting, and CDN asset processing. To satisfy these requirements, you can
convert the bundling and minification workflow to use Gulp.
Use the Bundler & Minifier extension
The Visual Studio Bundler & Minifier extension handles the conversion to Gulp.
NOTE
The Bundler & Minifier extension belongs to a community-driven project on GitHub for which Microsoft provides no
support. Issues should be filed here.
Right-click the bundleconfig.json file in Solution Explorer and select Bundler & Minifier > Convert To Gulp...:
The gulpfile.js and package.json files are added to the project. The supporting npm packages listed in the
package.json file's devDependencies section are installed.
Run the following command in the PMC window to install the Gulp CLI as a global dependency:
npm i -g gulp-cli
The gulpfile.js file reads the bundleconfig.json file for the inputs, outputs, and settings.
"use strict";

htmlmin = require("gulp-htmlmin"),
uglify = require("gulp-uglify"),
merge = require("merge-stream"),
del = require("del"),
bundleconfig = require("./bundleconfig.json");
// Code omitted for brevity

Convert manually
If Visual Studio and/or the Bundler & Minifier extension aren't available, convert manually.
Add a package.json file, with the following devDependencies , to the project root:
"del": "^3.0.0",
"gulp": "^3.9.1",
"gulp-concat": "^2.6.1",
"gulp-cssmin": "^0.2.0",
"gulp-htmlmin": "^3.0.0",
"gulp-uglify": "^3.0.0",
"merge-stream": "^1.0.1"
}
Install the dependencies by running the following command at the same level as package.json:
npm i
Install the Gulp CLI as a global dependency:
npm i -g gulp-cli
Copy the gulpfile.js file below to the project root:
"use strict";

htmlmin = require("gulp-htmlmin"),
uglify = require("gulp-uglify"),
merge = require("merge-stream"),
del = require("del"),
bundleconfig = require("./bundleconfig.json");
var regex = {
css: /\.css$/,
html: /\.(html|htm)$/,
js: /\.js$/
};
gulp.task("min", ["min:js", "min:css", "min:html"]);
var tasks = getBundles(regex.js).map(function (bundle) {
return gulp.src(bundle.inputFiles, { base: "." })
.pipe(concat(bundle.outputFileName))
.pipe(uglify())
});
return merge(tasks);
});
var tasks = getBundles(regex.css).map(function (bundle) {
.pipe(cssmin())
});
});
gulp.task("min:html", function () {
var tasks = getBundles(regex.html).map(function (bundle) {
.pipe(htmlmin({ collapseWhitespace: true, minifyCSS: true, minifyJS: true }))
});
});
gulp.task("clean", function () {
var files = bundleconfig.map(function (bundle) {
return bundle.outputFileName;
});
return del(files);
});
gulp.task("watch", function () {
getBundles(regex.js).forEach(function (bundle) {
gulp.watch(bundle.inputFiles, ["min:js"]);
});
getBundles(regex.css).forEach(function (bundle) {
gulp.watch(bundle.inputFiles, ["min:css"]);
});
getBundles(regex.html).forEach(function (bundle) {
gulp.watch(bundle.inputFiles, ["min:html"]);
});
});
function getBundles(regexPattern) {
return bundleconfig.filter(function (bundle) {
return regexPattern.test(bundle.outputFileName);
});
}
Run Gulp tasks

To trigger the Gulp minification task before the project builds in Visual Studio, add the following MSBuild Target
to the *.csproj file:
<Target Name="MyPreCompileTarget" BeforeTargets="Build">

<Exec Command="gulp min" />
</Target>
In this example, any tasks defined within the MyPreCompileTarget target run before the predefined Build target.
Output similar to the following appears in Visual Studio's Output window:
1>------ Build started: Project: BuildBundlerMinifierApp, Configuration: Debug Any CPU ------
1>BuildBundlerMinifierApp -> C:\BuildBundlerMinifierApp\bin\Debug\netcoreapp2.0\BuildBundlerMinifierApp.dll
1>[14:17:49] Using gulpfile C:\BuildBundlerMinifierApp\gulpfile.js
1>[14:17:49] Starting 'min:js'...
1>[14:17:49] Starting 'min:css'...
1>[14:17:49] Starting 'min:html'...
1>[14:17:49] Finished 'min:js' after 83 ms
1>[14:17:49] Finished 'min:css' after 88 ms
Alternatively, Visual Studio's Task Runner Explorer may be used to bind Gulp tasks to specific Visual Studio
events. See Running default tasks for instructions on doing that.
Use Gulp
Use Grunt
Use multiple environments
Tag Helpers
Browser Link in ASP.NET Core
By Nicolò Carandini, Mike Wasson, and Tom Dykstra

Browser Link is a feature in Visual Studio that creates a communication channel between the development
environment and one or more web browsers. You can use Browser Link to refresh your web application in several
browsers at once, which is useful for cross-browser testing.
Browser Link setup

When converting an ASP.NET Core 2.0 project to ASP.NET Core 2.1 and transitioning to the
Microsoft.AspNetCore.App metapackage, install the Microsoft.VisualStudio.Web.BrowserLink package for
BrowserLink functionality. The ASP.NET Core 2.1 project templates use the Microsoft.AspNetCore.App
metapackage by default.
The ASP.NET Core 2.0 Web Application, Empty, and Web API project templates use the
Microsoft.AspNetCore.All metapackage, which contains a package reference for
Microsoft.VisualStudio.Web.BrowserLink. Therefore, using the Microsoft.AspNetCore.All metapackage requires no
further action to make Browser Link available for use.
The ASP.NET Core 1.x Web Application project template has a package reference for the
Microsoft.VisualStudio.Web.BrowserLink package. The Empty or Web API template projects require you to add a
package reference to Microsoft.VisualStudio.Web.BrowserLink .
Since this is a Visual Studio feature, the easiest way to add the package to an Empty or Web API template project
is to open the Package Manager Console (View > Other Windows > Package Manager Console) and run
the following command:
install-package Microsoft.VisualStudio.Web.BrowserLink
Alternatively, you can use NuGet Package Manager. Right-click the project name in Solution Explorer and
choose Manage NuGet Packages:
Find and install the package:
Configuration
In the Startup.Configure method:
Usually the code is inside an if block that only enables Browser Link in the Development environment, as shown
here:
{
}
For more information, see Use multiple environments.
How to use Browser Link

When you have an ASP.NET Core project open, Visual Studio shows the Browser Link toolbar control next to the
Debug Target toolbar control:
From the Browser Link toolbar control, you can:

Refresh the web application in several browsers at once.
Open the Browser Link Dashboard.
Enable or disable Browser Link. Note: Browser Link is disabled by default in Visual Studio 2017 (15.3).
Enable or disable CSS Auto-Sync.
NOTE
Some Visual Studio plug-ins, most notably Web Extension Pack 2015 and Web Extension Pack 2017, offer extended
functionality for Browser Link, but some of the additional features don't work with ASP.NET Core projects.
Refresh the web app in several browsers at once

To choose a single web browser to launch when starting the project, use the drop-down menu in the Debug
Target toolbar control:
To open multiple browsers at once, choose Browse with... from the same drop-down. Hold down the CTRL key to
select the browsers you want, and then click Browse:
Here's a screenshot showing Visual Studio with the Index view open and two open browsers:
Hover over the Browser Link toolbar control to see the browsers that are connected to the project:
Change the Index view, and all connected browsers are updated when you click the Browser Link refresh button:
Browser Link also works with browsers that you launch from outside Visual Studio and navigate to the application
URL.
The Browser Link Dashboard
Open the Browser Link Dashboard from the Browser Link drop down menu to manage the connection with open
browsers:
If no browser is connected, you can start a non-debugging session by selecting the View in Browser link:
Otherwise, the connected browsers are shown with the path to the page that each browser is showing:
If you like, you can click on a listed browser name to refresh that single browser.
Enable or disable Browser Link
When you re-enable Browser Link after disabling it, you must refresh the browsers to reconnect them.
Enable or disable CSS Auto -Sync
When CSS Auto-Sync is enabled, connected browsers are automatically refreshed when you make any change to
CSS files.
How it works
Browser Link uses SignalR to create a communication channel between Visual Studio and the browser. When
Browser Link is enabled, Visual Studio acts as a SignalR server that multiple clients (browsers) can connect to.
Browser Link also registers a middleware component in the ASP.NET Core request pipeline. This component
injects special <script> references into every page request from the server. You can see the script references by
selecting View source in the browser and scrolling to the end of the <body> tag content:


<script type="application/json" id="__browserLink_initializationData">
{"requestId":"a717d5a07c1741949a7cefd6fa2bad08","requestMappingFromServer":false}
</script>
<script type="text/javascript" src="http://localhost:54139/b6e36e429d034f578ebccd6a79bf19bf/browserLink"
async="async"></script>

</body>
Your source files aren't modified. The middleware component injects the script references dynamically.
Because the browser-side code is all JavaScript, it works on all browsers that SignalR supports without requiring a
browser plug-in.
Use JavaScriptServices to Create Single Page
Applications in ASP.NET Core
By Scott Addie and Fiyaz Hasan

A Single Page Application (SPA) is a popular type of web application due to its inherent rich user experience.
Integrating client-side SPA frameworks or libraries, such as Angular or React, with server-side frameworks like
ASP.NET Core can be difficult. JavaScriptServices was developed to reduce friction in the integration process. It
enables seamless operation between the different client and server technology stacks.
What is JavaScriptServices
JavaScriptServices is a collection of client-side technologies for ASP.NET Core. Its goal is to position ASP.NET
Core as developers' preferred server-side platform for building SPAs.
JavaScriptServices consists of three distinct NuGet packages:
Microsoft.AspNetCore.NodeServices (NodeServices)
Microsoft.AspNetCore.SpaServices (SpaServices)
Microsoft.AspNetCore.SpaTemplates (SpaTemplates)
These packages are useful if you:
Run JavaScript on the server
Use a SPA framework or library
Build client-side assets with Webpack
Much of the focus in this article is placed on using the SpaServices package.
What is SpaServices
SpaServices was created to position ASP.NET Core as developers' preferred server-side platform for building
SPAs. SpaServices isn't required to develop SPAs with ASP.NET Core, and it doesn't lock you into a particular
client framework.
SpaServices provides useful infrastructure such as:
Server-side prerendering
Webpack Dev Middleware
Hot Module Replacement
Routing helpers
Collectively, these infrastructure components enhance both the development workflow and the runtime
experience. The components can be adopted individually.
Prerequisites for using SpaServices

To work with SpaServices, install the following:
Node.js (version 6 or later) with npm
To verify these components are installed and can be found, run the following from the command line:
To verify these components are installed and can be found, run the following from the command line:
node -v && npm -v
Note: If you're deploying to an Azure web site, you don't need to do anything here — Node.js is installed and
available in the server environments.
If you're on Windows using Visual Studio 2017, the SDK is installed by selecting the .NET Core cross-
platform development workload.
Microsoft.AspNetCore.SpaServices NuGet package
Server-side prerendering
A universal (also known as isomorphic) application is a JavaScript application capable of running both on the
server and the client. Angular, React, and other popular frameworks provide a universal platform for this
application development style. The idea is to first render the framework components on the server via Node.js, and
then delegate further execution to the client.
ASP.NET Core Tag Helpers provided by SpaServices simplify the implementation of server-side prerendering by
invoking the JavaScript functions on the server.
Prerequisites
aspnet-prerendering npm package:
npm i -S aspnet-prerendering
Configuration
The Tag Helpers are made discoverable via namespace registration in the project's _ViewImports.cshtml file:
@using SpaServicesSampleApp
@addTagHelper "*, Microsoft.AspNetCore.Mvc.TagHelpers"
@addTagHelper "*, Microsoft.AspNetCore.SpaServices"
These Tag Helpers abstract away the intricacies of communicating directly with low -level APIs by leveraging an
HTML -like syntax inside the Razor view:
<app asp-prerender-module="ClientApp/dist/main-server">Loading...</app>
The asp-prerender-module Tag Helper

The asp-prerender-module Tag Helper, used in the preceding code example, executes ClientApp/dist/main-server.js
on the server via Node.js. For clarity's sake, main-server.js file is an artifact of the TypeScript-to-JavaScript
transpilation task in the Webpack build process. Webpack defines an entry point alias of main-server ; and,
traversal of the dependency graph for this alias begins at the ClientApp/boot-server.ts file:
entry: { 'main-server': './ClientApp/boot-server.ts' },
In the following Angular example, the ClientApp/boot-server.ts file utilizes the createServerRenderer function and
RenderResult type of the aspnet-prerendering npm package to configure server rendering via Node.js. The HTML
markup destined for server-side rendering is passed to a resolve function call, which is wrapped in a strongly-
typed JavaScript Promise object. The Promise object's significance is that it asynchronously supplies the HTML
markup to the page for injection in the DOM's placeholder element.
import { createServerRenderer, RenderResult } from 'aspnet-prerendering';
export default createServerRenderer(params => {

const providers = [
{ provide: INITIAL_CONFIG, useValue: { document: '<app></app>', url: params.url } },
{ provide: 'ORIGIN_URL', useValue: params.origin }
];
return platformDynamicServer(providers).bootstrapModule(AppModule).then(moduleRef => {

const appRef = moduleRef.injector.get(ApplicationRef);
const state = moduleRef.injector.get(PlatformState);
const zone = moduleRef.injector.get(NgZone);
return new Promise<RenderResult>((resolve, reject) => {

zone.onError.subscribe(errorInfo => reject(errorInfo));
appRef.isStable.first(isStable => isStable).subscribe(() => {
// Because 'onStable' fires before 'onError', we have to delay slightly before
// completing the request in case there's an error to report
setImmediate(() => {
resolve({
html: state.renderToString()
});
moduleRef.destroy();
});
});
});
});
});
The asp-prerender-data Tag Helper

When coupled with the asp-prerender-module Tag Helper, the asp-prerender-data Tag Helper can be used to pass
contextual information from the Razor view to the server-side JavaScript. For example, the following markup
passes user data to the main-server module:
<app asp-prerender-module="ClientApp/dist/main-server"
asp-prerender-data='new {
UserName = "John Doe"
}'>Loading...</app>
The received UserName argument is serialized using the built-in JSON serializer and is stored in the params.data
object. In the following Angular example, the data is used to construct a personalized greeting within an h1
element:

const providers = [
];


const result = `<h1>Hello, ${params.data.userName}</h1>`;

resolve({
html: result
});
});
});
});
});
});
Note: Property names passed in Tag Helpers are represented with PascalCase notation. Contrast that to
JavaScript, where the same property names are represented with camelCase. The default JSON serialization
configuration is responsible for this difference.
To expand upon the preceding code example, data can be passed from the server to the view by hydrating the
globals property provided to the resolve function:

const providers = [
];


const result = `<h1>Hello, ${params.data.userName}</h1>`;

resolve({
html: result,
globals: {
postList: [
'Introduction to ASP.NET Core',
'Making apps with Angular and ASP.NET Core'
]
}
});
});
});
});
});
});
The postList array defined inside the globals object is attached to the browser's global window object. This
variable hoisting to global scope eliminates duplication of effort, particularly as it pertains to loading the same
data once on the server and again on the client.
Webpack Dev Middleware

Webpack Dev Middleware introduces a streamlined development workflow whereby Webpack builds resources on
demand. The middleware automatically compiles and serves client-side resources when a page is reloaded in the
browser. The alternate approach is to manually invoke Webpack via the project's npm build script when a third-
party dependency or the custom code changes. An npm build script in the package.json file is shown in the
following example:
"build": "npm run build:vendor && npm run build:custom",
Prerequisites
aspnet-webpack npm package:
npm i -D aspnet-webpack
Configuration
Webpack Dev Middleware is registered into the HTTP request pipeline via the following code in the Startup.cs file's
Configure method:
{
app.UseWebpackDevMiddleware();
}
else
{
}
// Call UseWebpackDevMiddleware before UseStaticFiles

The extension method must be called before registering static file hosting via the
UseWebpackDevMiddleware
UseStaticFiles extension method. For security reasons, register the middleware only when the app runs in
development mode.
The webpack.config.js file's output.publicPath property tells the middleware to watch the dist folder for
changes:
module.exports = (env) => {

output: {
filename: '[name].js',
publicPath: '/dist/' // Webpack dev middleware, if enabled, handles requests for this URL prefix
},
Hot Module Replacement

Think of Webpack's Hot Module Replacement (HMR ) feature as an evolution of Webpack Dev Middleware. HMR
introduces all the same benefits, but it further streamlines the development workflow by automatically updating
page content after compiling the changes. Don't confuse this with a refresh of the browser, which would interfere
with the current in-memory state and debugging session of the SPA. There's a live link between the Webpack Dev
Middleware service and the browser, which means changes are pushed to the browser.
Prerequisites
webpack-hot-middleware npm package:
npm i -D webpack-hot-middleware
Configuration
The HMR component must be registered into MVC's HTTP request pipeline in the Configure method:
app.UseWebpackDevMiddleware(new WebpackDevMiddlewareOptions {
HotModuleReplacement = true
});
As was true with Webpack Dev Middleware, the UseWebpackDevMiddleware extension method must be called before
the UseStaticFiles extension method. For security reasons, register the middleware only when the app runs in
development mode.
The webpack.config.js file must define a plugins array, even if it's left empty:
module.exports = (env) => {

plugins: [new CheckerPlugin()]
After loading the app in the browser, the developer tools' Console tab provides confirmation of HMR activation:
Routing helpers
In most ASP.NET Core-based SPAs, you'll want client-side routing in addition to server-side routing. The SPA and
MVC routing systems can work independently without interference. There's, however, one edge case posing
challenges: identifying 404 HTTP responses.
Consider the scenario in which an extensionless route of /some/page is used. Assume the request doesn't pattern-
match a server-side route, but its pattern does match a client-side route. Now consider an incoming request for
/images/user-512.png , which generally expects to find an image file on the server. If that requested resource path
doesn't match any server-side route or static file, it's unlikely that the client-side application would handle it — you
generally want to return a 404 HTTP status code.
Prerequisites
The client-side routing npm package. Using Angular as an example:
npm i -S @angular/router
Configuration
An extension method named MapSpaFallbackRoute is used in the Configure method:
{
routes.MapRoute(
name: "default",
routes.MapSpaFallbackRoute(
name: "spa-fallback",
defaults: new { controller = "Home", action = "Index" });
});
Tip: Routes are evaluated in the order in which they're configured. Consequently, the default route in the
preceding code example is used first for pattern matching.
Creating a new project

JavaScriptServices provides pre-configured application templates. SpaServices is used in these templates, in
conjunction with different frameworks and libraries such as Angular, React, and Redux.
These templates can be installed via the .NET Core CLI by running the following command:
dotnet new --install Microsoft.AspNetCore.SpaTemplates::*
A list of available SPA templates is displayed:
TEMPLATES SHORT NAME LANGUAGE TAGS
MVC ASP.NET Core with angular [C#] Web/MVC/SPA

Angular
MVC ASP.NET Core with react [C#] Web/MVC/SPA

React.js
MVC ASP.NET Core with reactredux [C#] Web/MVC/SPA

React.js and Redux
To create a new project using one of the SPA templates, include the Short Name of the template in the dotnet
new command. The following command creates an Angular application with ASP.NET Core MVC configured for
the server side:
dotnet new angular
Set the runtime configuration mode

Two primary runtime configuration modes exist:
Development:
Includes source maps to ease debugging.
Doesn't optimize the client-side code for performance.
Production:
Excludes source maps.
Optimizes the client-side code via bundling & minification.
ASP.NET Core uses an environment variable named ASPNETCORE_ENVIRONMENT to store the configuration mode. See
Set the environment for more information.
Running with .NET Core CLI
Restore the required NuGet and npm packages by running the following command at the project root:
dotnet restore && npm i
Build and run the application:
dotnet run
The application starts on localhost according to the runtime configuration mode. Navigating to
http://localhost:5000 in the browser displays the landing page.
Running with Visual Studio 2017

Open the .csproj file generated by the dotnet new command. The required NuGet and npm packages are restored
automatically upon project open. This restoration process may take up to a few minutes, and the application is
ready to run when it completes. Click the green run button or press Ctrl + F5 , and the browser opens to the
application's landing page. The application runs on localhost according to the runtime configuration mode.
Testing the app

SpaServices templates are pre-configured to run client-side tests using Karma and Jasmine. Jasmine is a popular
unit testing framework for JavaScript, whereas Karma is a test runner for those tests. Karma is configured to work
with the Webpack Dev Middleware such that the developer isn't required to stop and run the test every time
changes are made. Whether it's the code running against the test case or the test case itself, the test runs
automatically.
Using the Angular application as an example, two Jasmine test cases are already provided for the
CounterComponent in the counter.component.spec.ts file:
it('should display a title', async(() => {

const titleText = fixture.nativeElement.querySelector('h1').textContent;
expect(titleText).toEqual('Counter');
}));
it('should start with count 0, then increments by 1 when clicked', async(() => {
const countElement = fixture.nativeElement.querySelector('strong');
expect(countElement.textContent).toEqual('0');
const incrementButton = fixture.nativeElement.querySelector('button');

incrementButton.click();
fixture.detectChanges();
expect(countElement.textContent).toEqual('1');
}));
Open the command prompt in the ClientApp directory. Run the following command:
npm test
The script launches the Karma test runner, which reads the settings defined in the karma.conf.js file. Among other
settings, the karma.conf.js identifies the test files to be executed via its files array:
module.exports = function (config) {

config.set({
files: [
'../../wwwroot/dist/vendor.js',
'./boot-tests.ts'
],
Publishing the application

Combining the generated client-side assets and the published ASP.NET Core artifacts into a ready-to-deploy
package can be cumbersome. Thankfully, SpaServices orchestrates that entire publication process with a custom
MSBuild target named RunWebpack :
<Target Name="RunWebpack" AfterTargets="ComputeFilesToPublish">


<Exec Command="npm install" />
<Exec Command="node node_modules/webpack/bin/webpack.js --config webpack.config.vendor.js --env.prod" />
<Exec Command="node node_modules/webpack/bin/webpack.js --env.prod" />


<ItemGroup>
<DistFiles Include="wwwroot\dist\**; ClientApp\dist\**" />
<ResolvedFileToPublish Include="@(DistFiles->'%(FullPath)')" Exclude="@(ResolvedFileToPublish)">
<RelativePath>%(DistFiles.Identity)</RelativePath>
<CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
</ResolvedFileToPublish>
</ItemGroup>
</Target>
The MSBuild target has the following responsibilities:

1. Restore the npm packages
2. Create a production-grade build of the third-party, client-side assets
3. Create a production-grade build of the custom client-side assets
4. Copy the Webpack-generated assets to the publish folder
The MSBuild target is invoked when running:
dotnet publish -c Release
Angular Docs
Use the Single Page Application templates with
ASP.NET Core
NOTE
The released .NET Core 2.0.x SDK includes older project templates for Angular, React, and React with Redux. This
documentation isn't about those older project templates. This documentation is for the latest Angular, React, and React with
Redux templates, which can be installed manually into ASP.NET Core 2.0. The templates are included by default with ASP.NET
Core 2.1.
Prerequisites
Node.js, version 6 or later
Installation
The templates are already installed with ASP.NET Core 2.1.
If you have ASP.NET Core 2.0, run the following command to install the updated ASP.NET Core templates for
Angular, React, and React with Redux:
dotnet new --install Microsoft.DotNet.Web.Spa.ProjectTemplates::2.0.0
Use the templates

Use the Angular project template
Use the React project template
Use the React with Redux project template
Use the Angular project template with ASP.NET Core
NOTE
This documentation isn't about the Angular project template included in ASP.NET Core 2.0. It's about the newer Angular
template to which you can update manually. The template is included in ASP.NET Core 2.1 by default.
The updated Angular project template provides a convenient starting point for ASP.NET Core apps using Angular
and the Angular CLI to implement a rich, client-side user interface (UI).
The template is equivalent to creating an ASP.NET Core project to act as an API backend and an Angular CLI
project to act as a UI. The template offers the convenience of hosting both project types in a single app project.
Consequently, the app project can be built and published as a single unit.
Create a new app

If using ASP.NET Core 2.0, ensure you've installed the updated React project template.
If you have ASP.NET Core 2.1 installed, there's no need to install the Angular project template.
Create a new project from a command prompt using the command dotnet new angular in an empty directory. For
example, the following commands create the app in a my-new -app directory and switch to that directory:
dotnet new angular -o my-new-app

cd my-new-app
Run the app from either Visual Studio or the .NET Core CLI:
Visual Studio
.NET Core CLI
Open the generated .csproj file, and run the app as normal from there.
The build process restores npm dependencies on the first run, which can take several minutes. Subsequent builds
are much faster.
The project template creates an ASP.NET Core app and an Angular app. The ASP.NET Core app is intended to be
used for data access, authorization, and other server-side concerns. The Angular app, residing in the ClientApp
subdirectory, is intended to be used for all UI concerns.
Add pages, images, styles, modules, etc.

The ClientApp directory contains a standard Angular CLI app. See the official Angular documentation for more
information.
There are slight differences between the Angular app created by this template and the one created by Angular CLI
itself (via ng new ); however, the app's capabilities are unchanged. The app created by the template contains a
Bootstrap-based layout and a basic routing example.
Run ng commands
In a command prompt, switch to the ClientApp subdirectory:
cd ClientApp
If you have the ng tool installed globally, you can run any of its commands. For example, you can run ng lint ,
ng test , or any of the other Angular CLI commands. There's no need to run ng serve though, because your
ASP.NET Core app deals with serving both server-side and client-side parts of your app. Internally, it uses
ng serve in development.
If you don't have the ng tool installed, run npm run ng instead. For example, you can run npm run ng lint or
npm run ng test .
Install npm packages

To install third-party npm packages, use a command prompt in the ClientApp subdirectory. For example:
cd ClientApp
npm install --save <package_name>
Publish and deploy

In development, the app runs in a mode optimized for developer convenience. For example, JavaScript bundles
include source maps (so that when debugging, you can see your original TypeScript code). The app watches for
TypeScript, HTML, and CSS file changes on disk and automatically recompiles and reloads when it sees those files
change.
In production, serve a version of your app that's optimized for performance. This is configured to happen
automatically. When you publish, the build configuration emits a minified, ahead-of-time (AoT) compiled build of
your client-side code. Unlike the development build, the production build doesn't require Node.js to be installed
on the server (unless you have enabled server-side prerendering).
You can use standard ASP.NET Core hosting and deployment methods.
Run "ng serve" independently

The project is configured to start its own instance of the Angular CLI server in the background when the ASP.NET
Core app starts in development mode. This is convenient because you don't have to run a separate server
manually.
There's a drawback to this default setup. Each time you modify your C# code and your ASP.NET Core app needs
to restart, the Angular CLI server restarts. Around 10 seconds is required to start back up. If you're making
frequent C# code edits and don't want to wait for Angular CLI to restart, run the Angular CLI server externally,
independently of the ASP.NET Core process. To do so:
1. In a command prompt, switch to the ClientApp subdirectory, and launch the Angular CLI development
server:
cd ClientApp
npm start
IMPORTANT
Use npm start to launch the Angular CLI development server, not ng serve , so that the configuration in
package.json is respected. To pass additional parameters to the Angular CLI server, add them to the relevant
scripts line in your package.json file.
2. Modify your ASP.NET Core app to use the external Angular CLI instance instead of launching one of its
own. In your Startup class, replace the spa.UseAngularCliServer invocation with the following:
spa.UseProxyToSpaDevelopmentServer("http://localhost:4200");
When you start your ASP.NET Core app, it won't launch an Angular CLI server. The instance you started manually
is used instead. This enables it to start and restart faster. It's no longer waiting for Angular CLI to rebuild your
client app each time.
Server-side rendering
As a performance feature, you can choose to pre-render your Angular app on the server as well as running it on
the client. This means that browsers receive HTML markup representing your app's initial UI, so they display it
even before downloading and executing your JavaScript bundles. Most of the implementation of this comes from
an Angular feature called Angular Universal.
TIP
Enabling server-side rendering (SSR) introduces a number of extra complications both during development and deployment.
Read drawbacks of SSR to determine if SSR is a good fit for your requirements.
To enable SSR, you need to make a number of additions to your project.

In the Startup class, after the line that configures spa.Options.SourcePath , and before the call to
UseAngularCliServer or UseProxyToSpaDevelopmentServer , add the following:
app.UseSpa(spa =>
{
spa.Options.SourcePath = "ClientApp";
spa.UseSpaPrerendering(options =>
{
options.BootModulePath = $"{spa.Options.SourcePath}/dist-server/main.bundle.js";
options.BootModuleBuilder = env.IsDevelopment()
? new AngularCliBuilder(npmScript: "build:ssr")
: null;
options.ExcludeUrls = new[] { "/sockjs-node" };
});
{
spa.UseAngularCliServer(npmScript: "start");
}
});
In development mode, this code attempts to build the SSR bundle by running the script build:ssr , which is
defined in ClientApp\package.json. This builds an Angular app named ssr , which isn't yet defined.
At the end of the apps array in ClientApp/.angular-cli.json, define an extra app with name ssr . Use the following
options:
{
"name": "ssr",
"root": "src",
"outDir": "dist-server",
"assets": [
"assets"
],
"main": "main.server.ts",
"tsconfig": "tsconfig.server.json",
"prefix": "app",
"scripts": [],
"environmentSource": "environments/environment.ts",
"environments": {
"dev": "environments/environment.ts",
"prod": "environments/environment.prod.ts"
},
"platform": "server"
}
This new SSR -enabled app configuration requires two further files: tsconfig.server.json and main.server.ts. The
tsconfig.server.json file specifies TypeScript compilation options. The main.server.ts file serves as the code entry
point during SSR.
Add a new file called tsconfig.server.json inside ClientApp/src (alongside the existing tsconfig.app.json), containing
the following:
{
"extends": "../tsconfig.json",
"baseUrl": "./",
"module": "commonjs"
},
"angularCompilerOptions": {
"entryModule": "app/app.server.module#AppServerModule"
}
}
This file configures Angular's AoT compiler to look for a module called app.server.module . Add this by creating a
new file at ClientApp/src/app/app.server.module.ts (alongside the existing app.module.ts) containing the following:
import { NgModule } from '@angular/core';

import { ServerModule } from '@angular/platform-server';
import { ModuleMapLoaderModule } from '@nguniversal/module-map-ngfactory-loader';
import { AppComponent } from './app.component';
import { AppModule } from './app.module';
@NgModule({
imports: [AppModule, ServerModule, ModuleMapLoaderModule],
bootstrap: [AppComponent]
})
export class AppServerModule { }
This module inherits from your client-side app.module and defines which extra Angular modules are available
during SSR.
Recall that the new ssr entry in .angular-cli.json referenced an entry point file called main.server.ts. You haven't
yet added that file, and now is time to do so. Create a new file at ClientApp/src/main.server.ts (alongside the
existing main.ts), containing the following:
import 'zone.js/dist/zone-node';
import 'reflect-metadata';
import { renderModule, renderModuleFactory } from '@angular/platform-server';
import { APP_BASE_HREF } from '@angular/common';
import { enableProdMode } from '@angular/core';
import { provideModuleMap } from '@nguniversal/module-map-ngfactory-loader';
import { createServerRenderer } from 'aspnet-prerendering';
export { AppServerModule } from './app/app.server.module';
enableProdMode();

const { AppServerModule, AppServerModuleNgFactory, LAZY_MODULE_MAP } = (module as any).exports;
const options = {
document: params.data.originalHtml,
url: params.url,
extraProviders: [
provideModuleMap(LAZY_MODULE_MAP),
{ provide: APP_BASE_HREF, useValue: params.baseUrl },
{ provide: 'BASE_URL', useValue: params.origin + params.baseUrl }
]
};
const renderPromise = AppServerModuleNgFactory

? /* AoT */ renderModuleFactory(AppServerModuleNgFactory, options)
: /* dev */ renderModule(AppServerModule, options);
return renderPromise.then(html => ({ html }));

});
This file's code is what ASP.NET Core executes for each request when it runs the UseSpaPrerendering middleware
that you added to the Startup class. It deals with receiving params from the .NET code (such as the URL being
requested), and making calls to Angular SSR APIs to get the resulting HTML.
Strictly-speaking, this is sufficient to enable SSR in development mode. It's essential to make one final change so
that your app works correctly when published. In your app's main .csproj file, set the BuildServerSideRenderer
property value to true :


<BuildServerSideRenderer>true</BuildServerSideRenderer>
This configures the build process to run build:ssr during publishing and deploy the SSR files to the server. If you
don't enable this, SSR fails in production.
When your app runs in either development or production mode, the Angular code pre-renders as HTML on the
server. The client-side code executes as normal.
Pass data from .NET code into TypeScript code
During SSR, you might want to pass per-request data from your ASP.NET Core app into your Angular app. For
example, you could pass cookie information or something read from a database. To do this, edit your Startup class.
In the callback for UseSpaPrerendering , set a value for options.SupplyData such as the following:
options.SupplyData = (context, data) =>

{
// Creates a new value called isHttpsRequest that's passed to TypeScript code
data["isHttpsRequest"] = context.Request.IsHttps;
};
The SupplyData callback lets you pass arbitrary, per-request, JSON -serializable data (for example, strings,
booleans, or numbers). Your main.server.ts code receives this as params.data . For example, the preceding code
sample passes a boolean value as params.data.isHttpsRequest into the createServerRenderer callback. You can
pass this to other parts of your app in any way supported by Angular. For example, see how main.server.ts passes
the BASE_URL value to any component whose constructor is declared to receive it.
Drawbacks of SSR
Not all apps benefit from SSR. The primary benefit is perceived performance. Visitors reaching your app over a
slow network connection or on slow mobile devices see the initial UI quickly, even if it takes a while to fetch or
parse the JavaScript bundles. However, many SPAs are mainly used over fast, internal company networks on fast
computers where the app appears almost instantly.
At the same time, there are significant drawbacks to enabling SSR. It adds complexity to your development
process. Your code must run in two different environments: client-side and server-side (in a Node.js environment
invoked from ASP.NET Core). Here are some things to bear in mind:
SSR requires a Node.js installation on your production servers. This is automatically the case for some
deployment scenarios, such as Azure App Services, but not for others, such as Azure Service Fabric.
Enabling the BuildServerSideRenderer build flag causes your node_modules directory to publish. This
folder contains 20,000+ files, which increases deployment time.
To run your code in a Node.js environment, it can't rely on the existence of browser-specific JavaScript APIs
such as window or localStorage . If your code (or some third-party library you reference) tries to use these
APIs, you'll get an error during SSR. For example, don't use jQuery because it references browser-specific
APIs in many places. To prevent errors, you must either avoid SSR or avoid browser-specific APIs or
libraries. You can wrap any calls to such APIs in checks to ensure they aren't invoked during SSR. For
example, use a check such as the following in JavaScript or TypeScript code:
if (typeof window !== 'undefined') {

// Call browser-specific APIs here
}
Use the React project template with ASP.NET Core
NOTE
This documentation isn't about the React project template included in ASP.NET Core 2.0. It's about the newer React template
to which you can update manually. The template is included in ASP.NET Core 2.1 by default.
The updated React project template provides a convenient starting point for ASP.NET Core apps using React and
create-react-app (CRA) conventions to implement a rich, client-side user interface (UI).
The template is equivalent to creating both an ASP.NET Core project to act as an API backend, and a standard
CRA React project to act as a UI, but with the convenience of hosting both in a single app project that can be built
and published as a single unit.
Create a new app

If using ASP.NET Core 2.0, ensure you've installed the updated React project template.
If you have ASP.NET Core 2.1 installed, there's no need to install the React project template.
Create a new project from a command prompt using the command dotnet new react in an empty directory. For
example, the following commands create the app in a my-new -app directory and switch to that directory:
dotnet new react -o my-new-app

cd my-new-app
Run the app from either Visual Studio or the .NET Core CLI:
Visual Studio
.NET Core CLI
Open the generated .csproj file, and run the app as normal from there.
The build process restores npm dependencies on the first run, which can take several minutes. Subsequent builds
are much faster.
The project template creates an ASP.NET Core app and a React app. The ASP.NET Core app is intended to be
used for data access, authorization, and other server-side concerns. The React app, residing in the ClientApp
subdirectory, is intended to be used for all UI concerns.
Add pages, images, styles, modules, etc.

The ClientApp directory is a standard CRA React app. See the official CRA documentation for more information.
There are slight differences between the React app created by this template and the one created by CRA itself;
however, the app's capabilities are unchanged. The app created by the template contains a Bootstrap-based layout
and a basic routing example.
Install npm packages

To install third-party npm packages, use a command prompt in the ClientApp subdirectory. For example:
cd ClientApp
npm install --save <package_name>
Publish and deploy

In development, the app runs in a mode optimized for developer convenience. For example, JavaScript bundles
include source maps (so that when debugging, you can see your original source code). The app watches
JavaScript, HTML, and CSS file changes on disk and automatically recompiles and reloads when it sees those files
change.
In production, serve a version of your app that's optimized for performance. This is configured to happen
automatically. When you publish, the build configuration emits a minified, transpiled build of your client-side code.
Unlike the development build, the production build doesn't require Node.js to be installed on the server.
You can use standard ASP.NET Core hosting and deployment methods.
Run the CRA server independently

The project is configured to start its own instance of the CRA development server in the background when the
ASP.NET Core app starts in development mode. This is convenient because it means you don't have to run a
separate server manually.
There's a drawback to this default setup. Each time you modify your C# code and your ASP.NET Core app needs
to restart, the CRA server restarts. A few seconds are required to start back up. If you're making frequent C# code
edits and don't want to wait for the CRA server to restart, run the CRA server externally, independently of the
ASP.NET Core process. To do so:
1. In a command prompt, switch to the ClientApp subdirectory, and launch the CRA development server:
cd ClientApp
npm start
2. Modify your ASP.NET Core app to use the external CRA server instance instead of launching one of its
own. In your Startup class, replace the spa.UseReactDevelopmentServer invocation with the following:
spa.UseProxyToSpaDevelopmentServer("http://localhost:3000");
When you start your ASP.NET Core app, it won't launch a CRA server. The instance you started manually is used
instead. This enables it to start and restart faster. It's no longer waiting for your React app to rebuild each time.
Use the React-with-Redux project template with
ASP.NET Core
NOTE
This documentation isn't about the React-with-Redux project template included in ASP.NET Core 2.0. It's about the newer
React-with-Redux template to which you can update manually. The template is included in ASP.NET Core 2.1 by default.
The updated React-with-Redux project template provides a convenient starting point for ASP.NET Core apps
using React, Redux, and create-react-app (CRA) conventions to implement a rich, client-side user interface (UI).
With the exception of the project creation command, all information about the React-with-Redux template is the
same as the React template. To create this project type, run dotnet new reactredux instead of dotnet new react .
For more information about the functionality common to both React-based templates, see React template
documentation.
Mobile development with ASP.NET Core

ASP.NET Core
By Steve Smith

Features
well (5000). In order to test that your services work with a device, ensure you don't have an active firewall
blocking access to this port.




.UseKestrel()
.Build();
NOTE
Studio toolbar.
{
{
[Required]
[Required]
[Required]

}
}
{
{
}
}
using System.Linq;
{
{
{
InitializeData();
}

{
}

{
}

{
}

{
}

{
}

{
}

{

{
Done = true
};

{
ID = "b94afb54-a1cb-4313-8af3-b7511551b33b",
Done = false
};

{
Done = false,
};
}
}
}

{
services.AddMvc();
}
TIP

using System;
{
{

{
}
Reading Items
[HttpGet]
{
}
Creating Items
[HttpPost] attribute applied to it, and accepts a ToDoItem instance. Since the item argument will be passed in
the body of the POST, this parameter is decorated with the [FromBody] attribute.
added using the repository. Checking ModelState.IsValid performs model validation, and should be done in
every API method that accepts user input.
[HttpPost]
{
try
{
{
}
if (itemExists)
{
}
}
catch (Exception)
{
}
return Ok(item);
}

{
TodoItemIDInUse,
RecordNotFound,
CouldNotCreateItem,
CouldNotUpdateItem,
CouldNotDeleteItem
}
Updating Items
Modifying records is done using HTTP PUT requests. Other than this change, the Edit method is almost
identical to Create . Note that if the record isn't found, the Edit action will return a NotFound (404) response.
[HttpPut]
{
try
{
{
}
{
}
}
catch (Exception)
{
}
return NoContent();
}
Deleting Items
{
try
{
if (item == null)
{
}
}
catch (Exception)
{
}
return NoContent();
}

As you develop the backend services for your app, you will want to come up with a consistent set of conventions
or policies for handling cross-cutting concerns. For example, in the service shown above, requests for specific
records that weren't found received a NotFound response, rather than a BadRequest response. Similarly,
commands made to this service that passed in model bound types always checked ModelState.IsValid and
returned a BadRequest for invalid model types.
Host and deploy ASP.NET Core
In general, to deploy an ASP.NET Core app to a hosting environment:

Publish the app to a folder on the hosting server.
Set up a process manager that starts the app when requests arrive and restarts the app after it crashes or the
server reboots.
If configuration of a reverse proxy is desired, set up a reverse proxy that forwards requests to the app.
Publish to a folder
The dotnet publish CLI command compiles app code and copies the files needed to run the app into a publish
folder. When deploying from Visual Studio, the dotnet publish step happens automatically before the files are
copied to the deployment destination.
Folder contents
The publish folder contains .exe and .dll files for the app, its dependencies, and optionally the .NET runtime.
A .NET Core app can be published as self-contained or framework-dependent app. If the app is self-contained,
the .dll files that contain the .NET runtime are included in the publish folder. If the app is framework-dependent,
the .NET runtime files aren't included because the app has a reference to a version of .NET that's installed on the
server. The default deployment model is framework-dependent. For more information, see .NET Core
application deployment.
In addition to .exe and .dll files, the publish folder for an ASP.NET Core app typically contains configuration files,
static assets, and MVC views. For more information, see Directory structure.
Set up a process manager

An ASP.NET Core app is a console app that must be started when a server boots and restarted if it crashes. To
automate starts and restarts, a process manager is required. The most common process managers for ASP.NET
Core are:
Linux
Nginx
Apache
Windows
IIS
Windows Service
Set up a reverse proxy

ASP.NET Core 2.x
ASP.NET Core 1.x
If the app uses the Kestrel web server, Nginx, Apache, or IIS can be used as a reverse proxy server. A reverse
proxy server receives HTTP requests from the Internet and forwards them to Kestrel after some preliminary
handling.
Either configuration—with or without a reverse proxy server—is a valid and supported hosting configuration for
ASP.NET Core 2.0 or later apps. For more information, see When to use Kestrel with a reverse proxy.

Additional configuration might be required for apps hosted behind proxy servers and load balancers. Without
additional configuration, an app might not have access to the scheme (HTTP/HTTPS ) and the remote IP address
where a request originated. For more information, see Configure ASP.NET Core to work with proxy servers and
load balancers.
Using Visual Studio and MSBuild to automate deployment

Deployment often requires additional tasks besides copying the output from dotnet publish to a server. For
example, extra files might be required or excluded from the publish folder. Visual Studio uses MSBuild for web
deployment, and MSBuild can be customized to do many other tasks during deployment. For more information,
see Publish profiles in Visual Studio and the Using MSBuild and Team Foundation Build book.
By using the Publish Web feature or built-in Git support, apps can be deployed directly from Visual Studio to the
Azure App Service. Azure DevOps Services supports continuous deployment to Azure App Service.
Publishing to Azure
See Publish an ASP.NET Core web app to Azure App Service using Visual Studio for instructions on how to
publish an app to Azure using Visual Studio. The app can also be published to Azure from the command line.
Host in a web farm

For information on configuration for hosting ASP.NET Core apps in a web farm environment (for example,
deployment of multiple instances of your app for scalability), see Host ASP.NET Core in a web farm.
For information on using Docker as a hosting environment, see Host ASP.NET Core apps in Docker.
Azure App Service is a Microsoft cloud computing platform service for hosting web apps, including ASP.NET
Core.
Useful resources
The Azure Web Apps Documentation is the home for Azure Apps documentation, tutorials, samples, how -to
guides, and other resources. Two notable tutorials that pertain to hosting ASP.NET Core apps are:
Quickstart: Create an ASP.NET Core web app in Azure
Use Visual Studio to create and deploy an ASP.NET Core web app to Azure App Service on Windows.
Quickstart: Create a .NET Core web app in App Service on Linux
Use the command line to create and deploy an ASP.NET Core web app to Azure App Service on Linux.
The following articles are available in ASP.NET Core documentation:
Publish to Azure with Visual Studio
Learn how to publish an ASP.NET Core app to Azure App Service using Visual Studio.
Publish to Azure with CLI tools
Learn how to publish an ASP.NET Core app to Azure App Service using the Git command-line client.
Continuous deployment to Azure with Visual Studio and Git
Learn how to create an ASP.NET Core web app using Visual Studio and deploy it to Azure App Service using Git
for continuous deployment.
Set up a CI build for an ASP.NET Core app, then create a continuous deployment release to Azure App Service.
Azure Web App sandbox
Discover Azure App Service runtime execution limitations enforced by the Azure Apps platform.
Application configuration
In ASP.NET Core 2.0 or later, the following NuGet packages provide automatic logging features for apps deployed
to Azure App Service:
Microsoft.AspNetCore.AzureAppServices.HostingStartup uses IHostingStartup to provide ASP.NET Core
light-up integration with Azure App Service. The added logging features are provided by the
Microsoft.AspNetCore.AzureAppServicesIntegration package.
Microsoft.AspNetCore.AzureAppServicesIntegration executes AddAzureWebAppDiagnostics to add Azure
App Service diagnostics logging providers in the Microsoft.Extensions.Logging.AzureAppServices package.
Microsoft.Extensions.Logging.AzureAppServices provides logger implementations to support Azure App
Service diagnostics logs and log streaming features.
If targeting .NET Core and referencing the Microsoft.AspNetCore.All metapackage, the packages are already
included. The packages are absent from the newer Microsoft.AspNetCore.App metapackage. If targeting .NET
Framework or referencing the Microsoft.AspNetCore.App metapackage, reference the individual logging packages.
Override app configuration using the Azure Portal
The App Settings area of the Application settings blade permits you to set environment variables for the app.
Environment variables can be consumed by the Environment Variables Configuration Provider.
When an app uses the Web Host and builds the host using WebHost.CreateDefaultBuilder, environment variables
that configure the host use the ASPNETCORE_ prefix. For more information, see ASP.NET Core Web Host and the
Environment Variables Configuration Provider.
When an app uses the Generic Host, environment variables aren't loaded into an app's configuration by default
and the configuration provider must be added by the developer. The developer determines the environment
variable prefix when the configuration provider is added. For more information, see .NET Generic Host and the
Environment Variables Configuration Provider.

The IIS Integration Middleware, which configures Forwarded Headers Middleware, and the ASP.NET Core
Module are configured to forward the scheme (HTTP/HTTPS ) and the remote IP address where the request
originated. Additional configuration might be required for apps hosted behind additional proxy servers and load
balancers. For more information, see Configure ASP.NET Core to work with proxy servers and load balancers.
Monitoring and logging

For monitoring, logging, and troubleshooting information, see the following articles:
How to: Monitor Apps in Azure App Service
Learn how to review quotas and metrics for apps and App Service plans.
Enable diagnostics logging for web apps in Azure App Service
Discover how to enable and access diagnostic logging for HTTP status codes, failed requests, and web server
activity.
Introduction to Error Handling in ASP.NET Core
Understand common approaches to handling errors in ASP.NET Core apps.
Learn how to diagnose issues with Azure App Service deployments with ASP.NET Core apps.
See the common deployment configuration errors for apps hosted by Azure App Service/IIS with troubleshooting
advice.
Data Protection key ring and deployment slots

Data Protection keys are persisted to the %HOME%\ASP.NET\DataProtection-Keys folder. This folder is backed by
network storage and is synchronized across all machines hosting the app. Keys aren't protected at rest. This folder
supplies the key ring to all instances of an app in a single deployment slot. Separate deployment slots, such as
Staging and Production, don't share a key ring.
When swapping between deployment slots, any system using data protection won't be able to decrypt stored data
using the key ring inside the previous slot. ASP.NET Cookie Middleware uses data protection to protect its
cookies. This leads to users being signed out of an app that uses the standard ASP.NET Cookie Middleware. For a
slot-independent key ring solution, use an external key ring provider, such as:
Azure Blob Storage
Azure Key Vault
SQL store
Redis cache
For more information, see Key storage providers.
Deploy ASP.NET Core preview release to Azure App Service

ASP.NET Core preview apps can be deployed to Azure App Service with the following approaches:
Install the preview site extension
Use Docker with Web Apps for containers
Install the preview site extension
If a problem occurs using the preview site extension, open an issue on GitHub.
1. From the Azure portal, navigate to the App Service blade.
2. Select the web app.
3. Type "ex" in the search box or scroll down the list of management sections to DEVELOPMENT TOOLS.
4. Select DEVELOPMENT TOOLS > Extensions.
5. Select Add.
6. Select the ASP.NET Core <x.y> (x86) Runtime extension from the list, where <x.y> is the ASP.NET Core
preview version (for example, ASP.NET Core 2.2 (x86) Runtime). The x86 runtime is appropriate for
framework-dependent deployments that rely on out-of-process hosting by the ASP.NET Core Module.
7. Select OK to accept the legal terms.
8. Select OK to install the extension.
When the operation completes, the latest .NET Core preview is installed. Verify the installation:
1. Select Advanced Tools under DEVELOPMENT TOOLS.
2. Select Go on the Advanced Tools blade.
3. Select the Debug console > PowerShell menu item.
4. At the PowerShell prompt, execute the following command. Substitute the ASP.NET Core runtime version
for <x.y> in the command:
Test-Path D:\home\SiteExtensions\AspNetCoreRuntime.<x.y>.x86\
If the installed preview runtime is for ASP.NET Core 2.2, the command is:
Test-Path D:\home\SiteExtensions\AspNetCoreRuntime.2.2.x86\
The command returns True when the x64 preview runtime is installed.
NOTE
The platform architecture (x86/x64) of an App Services app is set in the Application Settings blade under General Settings
for apps that are hosted on an A-series compute or better hosting tier. If the app is run in in-process mode and the platform
architecture is configured for 64-bit (x64), the ASP.NET Core Module uses the 64-bit preview runtime, if present. Install the
ASP.NET Core <x.y> (x64) Runtime extension (for example, ASP.NET Core 2.2 (x64) Runtime).
After installing the x64 preview runtime, run the following command in the Kudu PowerShell command window to verify the
installation. Substitute the ASP.NET Core runtime version for <x.y> in the command:
Test-Path D:\home\SiteExtensions\AspNetCoreRuntime.<x.y>.x64\
If the installed preview runtime is for ASP.NET Core 2.2, the command is:
Test-Path D:\home\SiteExtensions\AspNetCoreRuntime.2.2.x64\
The command returns True when the x64 preview runtime is installed.
NOTE
ASP.NET Core Extensions enables additional functionality for ASP.NET Core on Azure App Services, such as enabling Azure
logging. The extension is installed automatically when deploying from Visual Studio. If the extension isn't installed, install it
for the app.
Use the preview site extension with an ARM template

If an ARM template is used to create and deploy apps, the siteextensions resource type can be used to add the
site extension to a web app. For example:
{
"type": "siteextensions",
"name": "AspNetCoreRuntime",
"apiVersion": "2015-04-01",
"location": "[resourceGroup().location]",
"properties": {
"version": "[parameters('aspnetcoreVersion')]"
},
"dependsOn": [
"[resourceId('Microsoft.Web/Sites', parameters('siteName'))]"
]
}
Use Docker with Web Apps for containers

The Docker Hub contains the latest preview Docker images. The images can be used as a base image. Use the
image and deploy to Web Apps for Containers normally.
Web Apps overview (5-minute overview video)
Azure App Service: The Best Place to Host your .NET Apps (55-minute overview video)
Azure Friday: Azure App Service Diagnostic and Troubleshooting Experience (12-minute video)
Azure App Service diagnostics overview
Azure App Service on Windows Server uses Internet Information Services (IIS ). The following topics pertain to
the underlying IIS technology:
ASP.NET Core Module
IIS modules with ASP.NET Core
Microsoft TechNet Library: Windows Server
Publish an ASP.NET Core app to Azure with Visual
Studio
By Rick Anderson, Cesar Blum Silveira, and Rachel Appel
IMPORTANT
ASP.NET Core preview releases with Azure App Service
ASP.NET Core preview releases aren't deployed to Azure App Service by default. To host an app that uses an ASP.NET Core
preview release, see Deploy ASP.NET Core preview release to Azure App Service.
See Publish to Azure from Visual Studio for Mac if you are working on macOS.
To troubleshoot an App Service deployment issue, see Troubleshoot ASP.NET Core on Azure App Service.
Set up
Open a free Azure account if you don't have one.
Create a web app

In the Visual Studio Start Page, select File > New > Project...

In the left pane, select .NET Core.
In the center pane, select ASP.NET Core Web Application.
Select OK.
In the New ASP.NET Core Web Application dialog:

Select Web Application.
Select Change Authentication.
The Change Authentication dialog appears.

Select Individual User Accounts.
Select OK to return to the New ASP.NET Core Web Application, then select OK again.
Visual Studio creates the solution.
Run the app

Press CTRL+F5 to run the project.
Test the About and Contact links.
Register a user
Select Register and register a new user. You can use a fictitious email address. When you submit, the page
displays the following error:
"Internal Server Error: A database operation failed while processing the request. SQL exception: Cannot
open the database. Applying existing migrations for Application DB context may resolve this issue."
Select Apply Migrations and, once the page updates, refresh the page.
The app displays the email used to register the new user and a Log out link.
Deploy the app to Azure
Right-click on the project in Solution Explorer and select Publish....
In the Publish dialog:
Select Microsoft Azure App Service.
Select the gear icon and then select Create Profile.
Select Create Profile.
Create Azure resources
The Create App Service dialog appears:
Enter your subscription.
The App Name, Resource Group, and App Service Plan entry fields are populated. You can keep these
names or change them.
Select the Services tab to create a new database.
Select the green + icon to create a new SQL Database
Select New... on the Configure SQL Database dialog to create a new database.
The Configure SQL Server dialog appears.

Enter an administrator user name and password, and then select OK. You can keep the default Server Name.
NOTE
"admin" isn't allowed as the administrator user name.
Select OK.
Visual Studio returns to the Create App Service dialog.
Select Create on the Create App Service dialog.
Visual Studio creates the Web app and SQL Server on Azure. This step can take a few minutes. For information
on the resources created, see Additonal resources.
When deployment completes, select Settings:
On the Settings page of the Publish dialog:

Expand Databases and check Use this connection string at runtime.
Expand Entity Framework Migrations and check Apply this migration on publish.
Select Save. Visual Studio returns to the Publish dialog.
Click Publish. Visual Studio publishs your app to Azure. When the deployment completes, the app is opened in a
browser.
Test your app in Azure
Test the About and Contact links
Register a new user
Update the app
Edit the Pages/About.cshtml Razor page and change its contents. For example, you can modify the
paragraph to say "Hello ASP.NET Core!":
@page
@model AboutModel
@{
}
<p>Hello ASP.NET Core!</p>
Right-click on the project and select Publish... again.

After the app is published, verify the changes you made are available on Azure.
Clean up
When you have finished testing the app, go to the Azure portal and delete the app.
Select Resource groups, then select the resource group you created.
In the Resource groups page, select Delete.

Enter the name of the resource group and select Delete. Your app and all other resources created in this
tutorial are now deleted from Azure.
Next steps
Continuous Deployment to Azure with Visual Studio and Git
Additonal resources
Azure App Service
Azure resource groups
Azure SQL Database
Publish an ASP.NET Core app to Azure with
command line tools
By Cam Soper
IMPORTANT
This tutorial will show you how to build and deploy an ASP.NET Core app to Microsoft Azure App Service using
command line tools. When finished, you'll have a Razor Pages web app built in ASP.NET Core hosted as an Azure
App Service Web App. This tutorial is written using Windows command line tools, but can be applied to macOS
and Linux environments, as well.
Create an Azure App Service website using Azure CLI
Deploy an ASP.NET Core app to Azure App Service using the Git command line tool
Prerequisites
To complete this tutorial, you'll need:
A Microsoft Azure subscription
Git command line client
Create a web app

Create a new directory for the web app, create a new ASP.NET Core Razor Pages app, and then run the website
locally.
Windows
Other
REM Create a new ASP.NET Core Razor Pages app

dotnet new webapp -o MyApplication
REM Change to the new directory that was just created

cd MyApplication
REM Run the app

dotnet run
REM Create a new ASP.NET Core Razor Pages app
dotnet new razor -o MyApplication
REM Change to the new directory that was just created

cd MyApplication
REM Run the app

dotnet run
Test the app by browsing to http://localhost:5000 .

Create the Azure App Service instance
Using the Azure Cloud Shell, create a resource group, App Service plan, and an App Service web app.
# Generate a unique Web App name

let randomNum=$RANDOM*$RANDOM
webappname=tutorialApp$randomNum
# Create the DotNetAzureTutorial resource group

az group create --name DotNetAzureTutorial --location EastUS
# Create an App Service plan.

az appservice plan create --name $webappname --resource-group DotNetAzureTutorial --sku FREE
# Create the Web App

az webapp create --name $webappname --resource-group DotNetAzureTutorial --plan $webappname
Before deployment, set the account-level deployment credentials using the following command:
az webapp deployment user set --user-name <desired user name> --password <desired password>
A deployment URL is needed to deploy the app using Git. Retrieve the URL like this.
az webapp deployment source config-local-git -n $webappname -g DotNetAzureTutorial --query [url] -o tsv

Note the displayed URL ending in .git . It's used in the next step.
Deploy the app using Git

You're ready to deploy from your local machine using Git.
NOTE
It's safe to ignore any warnings from Git about line endings.
Windows
Other
REM Initialize the local Git repository

git init
REM Add the contents of the working directory to the repo

git add --all
REM Commit the changes to the local repo

git commit -a -m "Initial commit"
REM Add the URL as a Git remote repository

git remote add azure <THE GIT URL YOU NOTED EARLIER>
REM Push the local repository to the remote

git push azure master
Git prompts for the deployment credentials that were set earlier. After authenticating, the app will be pushed to
the remote location, built, and deployed.
Test the app

Test the app by browsing to https://<web app name>.azurewebsites.net . To display the address in the Cloud Shell
(or Azure CLI), use the following:
az webapp show -n $webappname -g DotNetAzureTutorial --query defaultHostName -o tsv
Clean up
When finished testing the app and inspecting the code and resources, delete the web app and plan by deleting the
resource group.
az group delete -n DotNetAzureTutorial
Next steps
In this tutorial, you learned how to:
Create an Azure App Service website using Azure CLI
Deploy an ASP.NET Core app to Azure App Service using the Git command line tool
Next, learn to use the command line to deploy an existing web app that uses CosmosDB.
Deploy to Azure from the command line with .NET Core
Continuous deployment to Azure with Visual Studio
and Git with ASP.NET Core
By Erik Reitan
IMPORTANT
This tutorial shows how to create an ASP.NET Core web app using Visual Studio and deploy it from Visual Studio
to Azure App Service using continuous deployment.
See also Create your first pipeline with Azure Pipelines, which shows how to configure a continuous delivery (CD )
workflow for Azure App Service using Azure DevOps Services. Azure Pipelines (an Azure DevOps Services
service) simplifies setting up a robust deployment pipeline to publish updates for apps hosted in Azure App
Service. The pipeline can be configured from the Azure portal to build, run tests, deploy to a staging slot, and then
deploy to production.
NOTE
To complete this tutorial, a Microsoft Azure account is required. To obtain an account, activate MSDN subscriber benefits or
sign up for a free trial.
Prerequisites
This tutorial assumes the following software is installed:
Visual Studio
Git for Windows
Create an ASP.NET Core web app

1. Start Visual Studio.
2. From the File menu, select New > Project.
3. Select the ASP.NET Core Web Application project template. It appears under Installed > Templates >
Visual C# > .NET Core. Name the project SampleWebAppDemo . Select the Create new Git repository
option and click OK.
4. In the New ASP.NET Core Project dialog, select the ASP.NET Core Empty template, then click OK.
NOTE
The most recent release of .NET Core is 2.0.
Running the web app locally

1. Once Visual Studio finishes creating the app, run the app by selecting Debug > Start Debugging. As an
alternative, press F5.
It may take time to initialize Visual Studio and the new app. Once it's complete, the browser shows the
running app.
2. After reviewing the running Web app, close the browser and select the "Stop Debugging" icon in the
toolbar of Visual Studio to stop the app.
Create a web app in the Azure Portal

The following steps create a web app in the Azure Portal:
1. Log in to the Azure Portal.
2. Select NEW at the top left of the portal interface.
3. Select Web + Mobile > Web App.
4. In the Web App blade, enter a unique value for the App Service Name.
NOTE
The App Service Name name must be unique. The portal enforces this rule when the name is provided. If
providing a different value, substitute that value for each occurrence of SampleWebAppDemo in this tutorial.
Also in the Web App blade, select an existing App Service Plan/Location or create a new one. If creating
a new plan, select the pricing tier, location, and other options. For more information on App Service plans,
see Azure App Service plans in-depth overview.
5. Select Create. Azure will provision and start the web app.
Enable Git publishing for the new web app
Git is a distributed version control system that can be used to deploy an Azure App Service web app. Web app
code is stored in a local Git repository, and the code is deployed to Azure by pushing to a remote repository.
1. Log into the Azure Portal.
2. Select App Services to view a list of the app services associated with the Azure subscription.
3. Select the web app created in the previous section of this tutorial.
4. In the Deployment blade, select Deployment options > Choose Source > Local Git Repository.
5. Select OK.
6. If deployment credentials for publishing a web app or other App Service app haven't previously been set
up, set them up now:
Select Settings > Deployment credentials. The Set deployment credentials blade is displayed.
Create a user name and password. Save the password for later use when setting up Git.
Select Save.
7. In the Web App blade, select Settings > Properties. The URL of the remote Git repository to deploy to is
shown under GIT URL.
8. Copy the GIT URL value for later use in the tutorial.
Publish the web app to Azure App Service

In this section, create a local Git repository using Visual Studio and push from that repository to Azure to deploy
the web app. The steps involved include the following:
Add the remote repository setting using the GIT URL value, so the local repository can be deployed to Azure.
Commit project changes.
Push project changes from the local repository to the remote repository on Azure.
1. In Solution Explorer right-click Solution 'SampleWebAppDemo' and select Commit. The Team
Explorer is displayed.
2. In Team Explorer, select the Home (home icon) > Settings > Repository Settings.
3. In the Remotes section of the Repository Settings, select Add. The Add Remote dialog box is displayed.
4. Set the Name of the remote to Azure-SampleApp.
5. Set the value for Fetch to the Git URL that copied from Azure earlier in this tutorial. Note that this is the
URL that ends with .git.
NOTE
As an alternative, specify the remote repository from the Command Window by opening the Command Window,
changing to the project directory, and entering the command. Example:
git remote add Azure-SampleApp https://[email protected]:443/SampleApp.git
6. Select the Home (home icon) > Settings > Global Settings. Confirm that the name and email address
are set. Select Update if required.
7. Select Home > Changes to return to the Changes view.
8. Enter a commit message, such as Initial Push #1 and select Commit. This action creates a commit locally.
NOTE
As an alternative, commit changes from the Command Window by opening the Command Window, changing to
the project directory, and entering the git commands. Example:
git add .
git commit -am "Initial Push #1"
9. Select Home > Sync > Actions > Open Command Prompt. The command prompt opens to the project
directory.
10. Enter the following command in the command window:
git push -u Azure-SampleApp master
11. Enter the Azure deployment credentials password created earlier in Azure.
This command starts the process of pushing the local project files to Azure. The output from the above
command ends with a message that the deployment was successful.
remote: Finished successfully.

remote: Running post deployment command(s)...
remote: Deployment successful.
To https://[email protected]:443/SampleWebAppDemo01.git
* [new branch] master -> master
Branch master set up to track remote branch master from Azure-SampleApp.
NOTE
If collaboration on the project is required, consider pushing to GitHub before pushing to Azure.
Verify the Active Deployment

Verify that the web app transfer from the local environment to Azure is successful.
In the Azure Portal, select the web app. Select Deployment > Deployment options.
Run the app in Azure
Now that the web app is deployed to Azure, run the app.
This can be accomplished in two ways:
In the Azure Portal, locate the web app blade for the web app. Select Browse to view the app in the default
browser.
Open a browser and enter the URL for the web app. Example: http://SampleWebAppDemo.azurewebsites.net
Update the web app and republish

After making changes to the local code, republish:
1. In Solution Explorer of Visual Studio, open the Startup.cs file.
2. In the Configure method, modify the Response.WriteAsync method so that it appears as follows:
await context.Response.WriteAsync("Hello World! Deploy to Azure.");
3. Save the changes to Startup.cs.

4. In Solution Explorer, right-click Solution 'SampleWebAppDemo' and select Commit. The Team
Explorer is displayed.
5. Enter a commit message, such as Update #2 .
6. Press the Commit button to commit the project changes.
7. Select Home > Sync > Actions > Push.
NOTE
As an alternative, push the changes from the Command Window by opening the Command Window, changing to the
project directory, and entering a git command. Example:
git push -u Azure-SampleApp master
View the updated web app in Azure
View the updated web app by selecting Browse from the web app blade in the Azure Portal or by opening a
browser and entering the URL for the web app. Example: http://SampleWebAppDemo.azurewebsites.net
Project Kudu
By Luke Latham
IMPORTANT
This article provides instructions on how to diagnose an ASP.NET Core app startup issue using Azure App
Service's diagnostic tools. For additional troubleshooting advice, see Azure App Service diagnostics overview
and How to: Monitor Apps in Azure App Service in the Azure documentation.
App startup errors

502.5 Process Failure
The worker process fails. The app doesn't start.
The ASP.NET Core Module attempts to start the worker process but it fails to start. Examining the Application
Event Log often helps troubleshoot this type of problem. Accessing the log is explained in the Application Event
Log section.
The 502.5 Process Failure error page is returned when a misconfigured app causes the worker process to fail:
500 Internal Server Error

The app starts, but an error prevents the server from fulfilling the request.
This error occurs within the app's code during startup or while creating a response. The response may contain no
content, or the response may appear as a 500 Internal Server Error in the browser. The Application Event Log
usually states that the app started normally. From the server's perspective, that's correct. The app did start, but it
can't generate a valid response. Run the app in the Kudu console or enable the ASP.NET Core Module stdout log
to troubleshoot the problem.
Connection reset
If an error occurs after the headers are sent, it's too late for the server to send a 500 Internal Server Error when
an error occurs. This often happens when an error occurs during the serialization of complex objects for a
response. This type of error appears as a connection reset error on the client. Application logging can help
troubleshoot these types of errors.
Default startup limits

The ASP.NET Core Module is configured with a default startupTimeLimit of 120 seconds. When left at the
default value, an app may take up to two minutes to start before the module logs a process failure. For
information on configuring the module, see Attributes of the aspNetCore element.
Troubleshoot app startup errors

Application Event Log
To access the Application Event Log, use the Diagnose and solve problems blade in the Azure portal :
1. In the Azure portal, open the app's blade in the App Services blade.
2. Select the Diagnose and solve problems blade.
3. Under SELECT PROBLEM CATEGORY, select the Web App Down button.
4. Under Suggested Solutions, open the pane for Open Application Event Logs. Select the Open
Application Event Logs button.
5. Examine the latest error provided by the IIS AspNetCoreModule in the Source column.
An alternative to using the Diagnose and solve problems blade is to examine the Application Event Log file
directly using Kudu:
1. Select the Advanced Tools blade in the DEVELOPMENT TOOLS area. Select the Go→ button. The Kudu
console opens in a new browser tab or window.
2. Using the navigation bar at the top of the page, open Debug console and select CMD.
3. Open the LogFiles folder.
4. Select the pencil icon next to the eventlog.xml file.
5. Examine the log. Scroll to the bottom of the log to see the most recent events.
Run the app in the Kudu console
Many startup errors don't produce useful information in the Application Event Log. You can run the app in the
Kudu Remote Execution Console to discover the error:
1. Select the Advanced Tools blade in the DEVELOPMENT TOOLS area. Select the Go→ button. The Kudu
console opens in a new browser tab or window.
3. Open the folders to the path site > wwwroot.
4. In the console, run the app by executing the app's assembly.
If the app is a framework-dependent deployment, run the app's assembly with dotnet.exe. In the
following command, substitute the name of the app's assembly for <assembly_name> :
dotnet .\<assembly_name>.dll
If the app is a self-contained deployment, run the app's executable. In the following command,
substitute the name of the app's assembly for <assembly_name> : <assembly_name>.exe
5. The console output from the app, showing any errors, is piped to the Kudu console.
ASP.NET Core Module stdout log
The ASP.NET Core Module stdout log often records useful error messages not found in the Application Event
Log. To enable and view stdout logs:
1. Navigate to the Diagnose and solve problems blade in the Azure portal.
2. Under SELECT PROBLEM CATEGORY, select the Web App Down button.
3. Under Suggested Solutions > Enable Stdout Log Redirection, select the button to Open Kudu Console
to edit Web.Config.
4. In the Kudu Diagnostic Console, open the folders to the path site > wwwroot. Scroll down to reveal the
web.config file at the bottom of the list.
5. Click the pencil icon next to the web.config file.
6. Set stdoutLogEnabled to true and change the stdoutLogFile path to: \\?\%home%\LogFiles\stdout .
7. Select Save to save the updated web.config file.
8. Make a request to the app.
9. Return to the Azure portal. Select the Advanced Tools blade in the DEVELOPMENT TOOLS area. Select
the Go→ button. The Kudu console opens in a new browser tab or window.
11. Select the LogFiles folder.
12. Inspect the Modified column and select the pencil icon to edit the stdout log with the latest modification date.
13. When the log file opens, the error is displayed.
Important! Disable stdout logging when troubleshooting is complete.
1. In the Kudu Diagnostic Console, return to the path site > wwwroot to reveal the web.config file. Open the
web.config file again by selecting the pencil icon.
2. Set stdoutLogEnabled to false .
3. Select Save to save the file.
WARNING
Failure to disable the stdout log can lead to app or server failure. There's no limit on log file size or the number of log files
created. Only use stdout logging to troubleshoot app startup problems.
For general logging in an ASP.NET Core app after startup, use a logging library that limits log file size and rotates logs. For
more information, see third-party logging providers.
Common startup errors

See the ASP.NET Core common errors reference. Most of the common problems that prevent app startup are
covered in the reference topic.
Slow or hanging app

When an app responds slowly or hangs on a request, see Troubleshoot slow web app performance issues in
Azure App Service for debugging guidance.
Remote debugging
See the following topics:
Remote debugging web apps section of Troubleshoot a web app in Azure App Service using Visual Studio
(Azure documentation)
Remote Debug ASP.NET Core on IIS in Azure in Visual Studio 2017 (Visual Studio documentation)
Application Insights
Application Insights provides telemetry from apps hosted in the Azure App Service, including error logging and
reporting features. Application Insights can only report on errors that occur after the app starts when the app's
logging features become available. For more information, see Application Insights for ASP.NET Core.
Monitoring blades
Monitoring blades provide an alternative troubleshooting experience to the methods described earlier in the
topic. These blades can be used to diagnose 500-series errors.
Confirm that the ASP.NET Core Extensions are installed. If the extensions aren't installed, install them manually:
1. In the DEVELOPMENT TOOLS blade section, select the Extensions blade.
2. The ASP.NET Core Extensions should appear in the list.
3. If the extensions aren't installed, select the Add button.
4. Choose the ASP.NET Core Extensions from the list.
5. Select OK to accept the legal terms.
6. Select OK on the Add extension blade.
7. An informational pop-up message indicates when the extensions are successfully installed.
If stdout logging isn't enabled, follow these steps:
1. In the Azure portal, select the Advanced Tools blade in the DEVELOPMENT TOOLS area. Select the Go→
button. The Kudu console opens in a new browser tab or window.
3. Open the folders to the path site > wwwroot and scroll down to reveal the web.config file at the bottom of
the list.
4. Click the pencil icon next to the web.config file.
5. Set stdoutLogEnabled to true and change the stdoutLogFile path to: \\?\%home%\LogFiles\stdout .
6. Select Save to save the updated web.config file.
Proceed to activate diagnostic logging:
1. In the Azure portal, select the Diagnostics logs blade.
2. Select the On switch for Application Logging (Filesystem ) and Detailed error messages. Select the Save
button at the top of the blade.
3. To include failed request tracing, also known as Failed Request Event Buffering (FREB ) logging, select the On
switch for Failed request tracing.
4. Select the Log stream blade, which is listed immediately under the Diagnostics logs blade in the portal.
6. Within the log stream data, the cause of the error is indicated.
Important! Be sure to disable stdout logging when troubleshooting is complete. See the instructions in the
ASP.NET Core Module stdout log section.
To view the failed request tracing logs (FREB logs):
1. Navigate to the Diagnose and solve problems blade in the Azure portal.
2. Select Failed Request Tracing Logs from the SUPPORT TOOLS area of the sidebar.
See Failed request traces section of the Enable diagnostics logging for web apps in Azure App Service topic and
the Application performance FAQs for Web Apps in Azure: How do I turn on failed request tracing? for more
information.
For more information, see Enable diagnostics logging for web apps in Azure App Service.
WARNING
created.
For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. For more
information, see third-party logging providers.
Troubleshoot a web app in Azure App Service using Visual Studio
Troubleshoot HTTP errors of "502 bad gateway" and "503 service unavailable" in your Azure web apps
Troubleshoot slow web app performance issues in Azure App Service
Application performance FAQs for Web Apps in Azure
Azure Web App sandbox (App Service runtime execution limitations)
Azure Friday: Azure App Service Diagnostic and Troubleshooting Experience (12-minute video)
By Luke Latham
Supported operating systems

The following operating systems are supported:
Windows 7 or later
HTTP.sys server (formerly called WebListener) doesn't work in a reverse proxy configuration with IIS. Use the
Kestrel server.
For information on hosting in Azure, see Host ASP.NET Core on Azure App Service.
HTTP/2 support
HTTP/2 is supported with ASP.NET Core in the following IIS deployment scenarios:
In-process
Out-of-process
Edge connections use HTTP/2, but the reverse proxy connection to the Kestrel server uses HTTP/1.1.
Target framework: Not applicable to out-of-process deployments, since the HTTP/2 connection is
handled entirely by IIS.
For an in-process deployment when an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/2 .
For an out-of-process deployment when an HTTP/2 connection is established, HttpRequest.Protocol reports
HTTP/1.1 .
HTTP/2 is supported for out-of-process deployments that meet the following base requirements:
Edge connections use HTTP/2, but the reverse proxy connection to the Kestrel server uses HTTP/1.1.
Target framework: Not applicable to out-of-process deployments, since the HTTP/2 connection is handled
entirely by IIS.
If an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/1.1 .
HTTP/2 is enabled by default. Connections fall back to HTTP/1.1 if an HTTP/2 connection isn't established. For
more information on HTTP/2 configuration with IIS deployments, see HTTP/2 on IIS.
Application configuration
Enable the IISIntegration components
A typical Program.cs calls CreateDefaultBuilder to begin setting up a host. CreateDefaultBuilder configures
Kestrel as the web server and enables IIS integration by configuring the base path and port for the ASP.NET
Core Module:

...
The ASP.NET Core Module generates a dynamic port to assign to the back-end process. CreateDefaultBuilder
calls the UseIISIntegration method, which picks up the dynamic port and configures Kestrel to listen on
http://localhost:{dynamicPort}/ . This overrides other URL configurations, such as calls to UseUrls or Kestrel's
Listen API. Therefore, calls to UseUrls or Kestrel's Listen API aren't required when using the module. If
UseUrls or Listen is called, Kestrel listens on the port specified when running the app without IIS.
Include a dependency on the Microsoft.AspNetCore.Server.IISIntegration package in the app's dependencies.

Use IIS Integration middleware by adding the UseIISIntegration extension method to WebHostBuilder:

.UseKestrel()
...
Both UseKestrel and UseIISIntegration are required. Code calling UseIISIntegration doesn't affect code
portability. If the app isn't run behind IIS (for example, the app is run directly on Kestrel), UseIISIntegration
doesn't operate.
The ASP.NET Core Module generates a dynamic port to assign to the back-end process. The UseIISIntegration
method picks up the dynamic port and configures Kestrel to listen on http://locahost:{dynamicPort}/ . This
overrides other URL configurations, such as calls to UseUrls . Therefore, a call to UseUrls isn't required when
using the module. If UseUrls is called, Kestrel listens on the port specified when running the app without IIS.
If UseUrls is called in an ASP.NET Core 1.0 app, call it before calling UseIISIntegration so that the module-
configured port isn't overwritten. This calling order isn't required with ASP.NET Core 1.1 because the module
setting overrides UseUrls .
For more information on hosting, see Host in ASP.NET Core.
IIS options
To configure IIS options, include a service configuration for IISOptions in ConfigureServices. In the following
example, forwarding client certificates to the app to populate HttpContext.Connection.ClientCertificate is
disabled:
services.Configure<IISOptions>(options =>
{
options.ForwardClientCertificate = false;
});
OPTION DEFAULT SETTING

OPTION DEFAULT SETTING
AutomaticAuthentication true If true , IIS Integration Middleware

sets the HttpContext.User
authenticated by Windows
Authentication. If false , the
middleware only provides an identity
for HttpContext.User and responds
to challenges when explicitly requested
by the AuthenticationScheme .
Windows Authentication must be
enabled in IIS for
AutomaticAuthentication to
function. For more information, see the
Windows Authentication topic.
AuthenticationDisplayName null Sets the display name shown to users

on login pages.
ForwardClientCertificate true If true and the

MS-ASPNETCORE-CLIENTCERT request
header is present, the
HttpContext.Connection.ClientCertificate
is populated.

The IIS Integration Middleware, which configures Forwarded Headers Middleware, and the ASP.NET Core
Module are configured to forward the scheme (HTTP/HTTPS ) and the remote IP address where the request
originated. Additional configuration might be required for apps hosted behind additional proxy servers and load
balancers. For more information, see Configure ASP.NET Core to work with proxy servers and load balancers.
web.config file
The web.config file configures the ASP.NET Core Module. Creating, transforming, and publishing the web.config
file is handled by an MSBuild target ( _TransformWebConfig ) when the project is published. This target is present
in the Web SDK targets ( Microsoft.NET.Sdk.Web ). The SDK is set at the top of the project file:
If a web.config file isn't present in the project, the file is created with the correct processPath and arguments to
configure the ASP.NET Core Module and moved to published output.
If a web.config file is present in the project, the file is transformed with the correct processPath and arguments to
configure the ASP.NET Core Module and moved to published output. The transformation doesn't modify IIS
configuration settings in the file.
The web.config file may provide additional IIS configuration settings that control active IIS modules. For
information on IIS modules that are capable of processing requests with ASP.NET Core apps, see the IIS
modules topic.
To prevent the Web SDK from transforming the web.config file, use the <IsTransformWebConfigDisabled>
property in the project file:
<PropertyGroup>
<IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
</PropertyGroup>
When disabling the Web SDK from transforming the file, the processPath and arguments should be manually
set by the developer. For more information, see the ASP.NET Core Module configuration reference.
web.config file location
In order to create the reverse proxy between IIS and the Kestrel server, the web.config file must be present at the
content root path (typically the app base path) of the deployed app. This is the same location as the website
physical path provided to IIS. The web.config file is required at the root of the app to enable the publishing of
multiple apps using Web Deploy.
Sensitive files exist on the app's physical path, such as <assembly>.runtimeconfig.json, <assembly>.xml (XML
Documentation comments), and <assembly>.deps.json. When the web.config file is present and and the site
starts normally, IIS doesn't serve these sensitive files if they're requested. If the web.config file is missing,
incorrectly named, or unable to configure the site for normal startup, IIS may serve sensitive files publicly.
The web.config file must be present in the deployment at all times, correctly named, and able to
configure the site for normal start up. Never remove the web.config file from a production
deployment.
IIS configuration
Windows Server operating systems
Enable the Web Server (IIS ) server role and establish role services.
1. Use the Add Roles and Features wizard from the Manage menu or the link in Server Manager. On
the Server Roles step, check the box for Web Server (IIS ).
2. After the Features step, the Role services step loads for Web Server (IIS ). Select the IIS role services
desired or accept the default role services provided.
Windows Authentication (Optional)
To enable Windows Authentication, expand the following nodes: Web Server > Security. Select the
Windows Authentication feature. For more information, see Windows Authentication
<windowsAuthentication> and Configure Windows authentication.
WebSockets (Optional)
WebSockets is supported with ASP.NET Core 1.1 or later. To enable WebSockets, expand the following
nodes: Web Server > Application Development. Select the WebSocket Protocol feature. For more
information, see WebSockets.
3. Proceed through the Confirmation step to install the web server role and services. A server/IIS restart
isn't required after installing the Web Server (IIS ) role.
Windows desktop operating systems
Enable the IIS Management Console and World Wide Web Services.
1. Navigate to Control Panel > Programs > Programs and Features > Turn Windows features on or
off (left side of the screen).
2. Open the Internet Information Services node. Open the Web Management Tools node.
3. Check the box for IIS Management Console.
4. Check the box for World Wide Web Services.
5. Accept the default features for World Wide Web Services or customize the IIS features.
Windows Authentication (Optional)
To enable Windows Authentication, expand the following nodes: World Wide Web Services > Security.
Select the Windows Authentication feature. For more information, see Windows Authentication
<windowsAuthentication> and Configure Windows authentication.
WebSockets (Optional)
WebSockets is supported with ASP.NET Core 1.1 or later. To enable WebSockets, expand the following
nodes: World Wide Web Services > Application Development Features. Select the WebSocket
Protocol feature. For more information, see WebSockets.
6. If the IIS installation requires a restart, restart the system.
Install the .NET Core Hosting Bundle

1. Install the .NET Core Hosting Bundle on the hosting system. The bundle installs the .NET Core Runtime,
.NET Core Library, and the ASP.NET Core Module. The module creates the reverse proxy between IIS
and the Kestrel server. If the system doesn't have an Internet connection, obtain and install the Microsoft
Visual C++ 2015 Redistributable before installing the .NET Core Hosting Bundle.
a. Navigate to the .NET downloads page.
b. Under .NET Core, select the Download .NET Core Runtime button next to the Run Apps label. The
installer's executable contains the word "hosting" in the file name (for example, dotnet-hosting -2.1.2 -
win.exe).
c. Run the installer on the server.
Important! If the Hosting Bundle is installed before IIS, the bundle installation must be repaired. Run the
Hosting Bundle installer again after installing IIS.
To prevent the installer from installing x86 packages on an x64 OS, run the installer from an administrator
command prompt with the switch OPT_NO_X86=1 .
2. Restart the system or execute net stop was /y followed by net start w3svc from a command prompt.
Restarting IIS picks up a change to the system PATH, which is an environment variable, made by the
installer.
If the Windows Hosting Bundle installer detects that IIS requires a reset in order to complete installation,
the installer resets IIS. If the installer triggers an IIS reset, all of the IIS app pools and websites are
restarted.
NOTE
For information on IIS Shared Configuration, see ASP.NET Core Module with IIS Shared Configuration.
Install Web Deploy when publishing with Visual Studio

When deploying apps to servers with Web Deploy, install the latest version of Web Deploy on the server. To
install Web Deploy, use the Web Platform Installer (WebPI) or obtain an installer directly from the Microsoft
Download Center. The preferred method is to use WebPI. WebPI offers a standalone setup and a configuration
for hosting providers.
Create the IIS site

1. On the hosting system, create a folder to contain the app's published folders and files. An app's
deployment layout is described in the Directory Structure topic.
2. Within the new folder, create a logs folder to hold ASP.NET Core Module stdout logs when stdout
logging is enabled. If the app is deployed with a logs folder in the payload, skip this step. For instructions
on how to enable MSBuild to create the logs folder automatically when the project is built locally, see the
Directory structure topic.
IMPORTANT
Only use the stdout log to troubleshoot app startup failures. Never use stdout logging for routine app logging.
There's no limit on log file size or the number of log files created. The app pool must have write access to the
location where the logs are written. All of the folders on the path to the log location must exist. For more
information on the stdout log, see Log creation and redirection. For information on logging in an ASP.NET Core
app, see the Logging topic.
3. In IIS Manager, open the server's node in the Connections panel. Right-click the Sites folder. Select
Add Website from the contextual menu.
4. Provide a Site name and set the Physical path to the app's deployment folder. Provide the Binding
configuration and create the website by selecting OK:
WARNING
Top-level wildcard bindings ( http://*:80/ and http://+:80 ) should not be used. Top-level wildcard bindings
can open up your app to security vulnerabilities. This applies to both strong and weak wildcards. Use explicit host
names rather than wildcards. Subdomain wildcard binding (for example, *.mysub.com ) doesn't have this security
risk if you control the entire parent domain (as opposed to *.com , which is vulnerable). See rfc7230 section-5.4
5. Under the server's node, select Application Pools.

6. Right-click the site's app pool and select Basic Settings from the contextual menu.
7. In the Edit Application Pool window, set the .NET CLR version to No Managed Code:
ASP.NET Core runs in a separate process and manages the runtime. ASP.NET Core doesn't rely on
loading the desktop CLR. Setting the .NET CLR version to No Managed Code is optional.
8. Confirm the process model identity has the proper permissions.
If the default identity of the app pool (Process Model > Identity) is changed from
ApplicationPoolIdentity to another identity, verify that the new identity has the required permissions to
access the app's folder, database, and other required resources. For example, the app pool requires read
and write access to folders where the app reads and writes files.
Windows Authentication configuration (Optional)
For more information, see Configure Windows authentication.
Deploy the app

Deploy the app to the folder created on the hosting system. Web Deploy is the recommended mechanism for
deployment.
Web Deploy with Visual Studio
See the Visual Studio publish profiles for ASP.NET Core app deployment topic to learn how to create a publish
profile for use with Web Deploy. If the hosting provider provides a Publish Profile or support for creating one,
download their profile and import it using the Visual Studio Publish dialog.
Web Deploy outside of Visual Studio

Web Deploy can also be used outside of Visual Studio from the command line. For more information, see Web
Deployment Tool.
Alternatives to Web Deploy
Use any of several methods to move the app to the hosting system, such as manual copy, Xcopy, Robocopy, or
PowerShell.
For more information on ASP.NET Core deployment to IIS, see the Deployment resources for IIS administrators
section.
Browse the website

Locked deployment files
Files in the deployment folder are locked when the app is running. Locked files can't be overwritten during
deployment. To release locked files in a deployment, stop the app pool using one of the following approaches:
Use Web Deploy and reference Microsoft.NET.Sdk.Web in the project file. An app_offline.htm file is placed
at the root of the web app directory. When the file is present, the ASP.NET Core Module gracefully shuts
down the app and serves the app_offline.htm file during the deployment. For more information, see the
ASP.NET Core Module configuration reference.
Manually stop the app pool in the IIS Manager on the server.
Use PowerShell to stop and restart the app pool (requires PowerShell 5 or later):
$webAppPoolName = 'APP_POOL_NAME'
# Stop the AppPool

if((Get-WebAppPoolState $webAppPoolName).Value -ne 'Stopped') {
Stop-WebAppPool -Name $webAppPoolName
while((Get-WebAppPoolState $webAppPoolName).Value -ne 'Stopped') {
Start-Sleep -s 1
}
Write-Host `-AppPool Stopped
}
# Provide script commands here to deploy the app
# Restart the AppPool

if((Get-WebAppPoolState $webAppPoolName).Value -ne 'Started') {
Start-WebAppPool -Name $webAppPoolName
while((Get-WebAppPoolState $webAppPoolName).Value -ne 'Started') {
Start-Sleep -s 1
}
Write-Host `-AppPool Started
}
Data protection
The ASP.NET Core Data Protection stack is used by several ASP.NET Core middlewares, including middleware
used in authentication. Even if Data Protection APIs aren't called by user code, data protection should be
configured with a deployment script or in user code to create a persistent cryptographic key store. If data
protection isn't configured, the keys are held in memory and discarded when the app restarts.
If the key ring is stored in memory when the app restarts:
All cookie-based authentication tokens are invalidated.
Users are required to sign in again on their next request.
Any data protected with the key ring can no longer be decrypted. This may include CSRF tokens and
ASP.NET Core MVC TempData cookies.
To configure data protection under IIS to persist the key ring, use one of the following approaches:
Create Data Protection Registry Keys
Data protection keys used by ASP.NET Core apps are stored in the registry external to the apps. To
persist the keys for a given app, create registry keys for the app pool.
For standalone, non-webfarm IIS installations, the Data Protection Provision-AutoGenKeys.ps1
PowerShell script (ASP.NET Core 2.2) can be used for each app pool used with an ASP.NET Core app.
This script creates a registry key in the HKLM registry that's accessible only to the worker process
account of the app's app pool. Keys are encrypted at rest using DPAPI with a machine-wide key.
In web farm scenarios, an app can be configured to use a UNC path to store its data protection key ring.
By default, the data protection keys aren't encrypted. Ensure that the file permissions for the network
share are limited to the Windows account the app runs under. An X509 certificate can be used to protect
keys at rest. Consider a mechanism to allow users to upload certificates: Place certificates into the user's
trusted certificate store and ensure they're available on all machines where the user's app runs. See
Configure ASP.NET Core Data Protection for details.
Configure the IIS Application Pool to load the user profile
This setting is in the Process Model section under the Advanced Settings for the app pool. Set Load
User Profile to True . This stores keys under the user profile directory and protects them using DPAPI
with a key specific to the user account used by the app pool.
Use the file system as a key ring store
Adjust the app code to use the file system as a key ring store. Use an X509 certificate to protect the key
ring and ensure the certificate is a trusted certificate. If the certificate is self-signed, place the certificate in
the Trusted Root store.
When using IIS in a web farm:
Use a file share that all machines can access.
Deploy an X509 certificate to each machine. Configure data protection in code.
Set a machine-wide policy for data protection
The data protection system has limited support for setting a default machine-wide policy for all apps that
consume the Data Protection APIs. See the data protection documentation for details.
Sub-application configuration
Sub-apps added under the root app shouldn't include the ASP.NET Core Module as a handler. If the module is
added as a handler in a sub-app's web.config file, a 500.19 Internal Server Error referencing the faulty config file
is received when attempting to browse the sub-app.
The following example shows a published web.config file for an ASP.NET Core sub-app:
<?xml version="1.0" encoding="utf-8"?>

<configuration>
<system.webServer>
<aspNetCore processPath="dotnet"
arguments=".\<assembly_name>.dll"
stdoutLogEnabled="false"
stdoutLogFile=".\logs\stdout" />
</system.webServer>
</configuration>
When hosting a non-ASP.NET Core sub-app underneath an ASP.NET Core app, explicitly remove the inherited
handler in the sub-app web.config file:

<configuration>
<system.webServer>
<handlers>
<remove name="aspNetCore" />
</handlers>
arguments=".\<assembly_name>.dll"
</system.webServer>
</configuration>
For more information on configuring the ASP.NET Core Module, see the Introduction to ASP.NET Core Module
topic and the ASP.NET Core Module configuration reference.
Configuration of IIS with web.config

IIS configuration is influenced by the <system.webServer> section of web.config for those IIS features that
apply to a reverse proxy configuration. If IIS is configured at the server level to use dynamic compression, the
<urlCompression> element in the app's web.config file can disable it.
For more information, see the configuration reference for <system.webServer>, ASP.NET Core Module
Configuration Reference, and IIS Modules with ASP.NET Core. To set environment variables for individual apps
running in isolated app pools (supported for IIS 10.0 or later), see the AppCmd.exe command section of the
Environment Variables <environmentVariables> topic in the IIS reference documentation.
Configuration sections of web.config

Configuration sections of ASP.NET 4.x apps in web.config aren't used by ASP.NET Core apps for configuration:
<system.web>
<appSettings>
<connectionStrings>
<location>
ASP.NET Core apps are configured using other configuration providers. For more information, see
Configuration.
Application Pools
When hosting multiple websites on a server, we recommend isolating the apps from each other by running each
app in its own app pool. The IIS Add Website dialog defaults to this configuration. When Site name is
provided, the text is automatically transferred to the Application pool textbox. A new app pool is created using
the site name when the site is added.
Application Pool Identity

An app pool identity account allows an app to run under a unique account without having to create and manage
domains or local accounts. On IIS 8.0 or later, the IIS Admin Worker Process (WAS ) creates a virtual account
with the name of the new app pool and runs the app pool's worker processes under this account by default. In
the IIS Management Console under Advanced Settings for the app pool, ensure that the Identity is set to use
ApplicationPoolIdentity:
The IIS management process creates a secure identifier with the name of the app pool in the Windows Security
System. Resources can be secured using this identity. However, this identity isn't a real user account and doesn't
show up in the Windows User Management Console.
If the IIS worker process requires elevated access to the app, modify the Access Control List (ACL ) for the
directory containing the app:
1. Open Windows Explorer and navigate to the directory.
2. Right-click on the directory and select Properties.
3. Under the Security tab, select the Edit button and then the Add button.
4. Select the Locations button and make sure the system is selected.
5. Enter IIS AppPool\<app_pool_name> in Enter the object names to select area. Select the Check
Names button. For the DefaultAppPool check the names using IIS AppPool\DefaultAppPool. When
the Check Names button is selected, a value of DefaultAppPool is indicated in the object names area. It
isn't possible to enter the app pool name directly into the object names area. Use the IIS AppPool\
<app_pool_name> format when checking for the object name.
6. Select OK.
7. Read & execute permissions should be granted by default. Provide additional permissions as needed.
Access can also be granted at a command prompt using the ICACLS tool. Using the DefaultAppPool as an
example, the following command is used:
ICACLS C:\sites\MyWebApp /grant "IIS AppPool\DefaultAppPool":F
For more information, see the icacls topic.
Deployment resources for IIS administrators

Learn about IIS in-depth in the IIS documentation.
IIS documentation
Learn about .NET Core app deployment models.
.NET Core application deployment
Learn how the ASP.NET Core Module allows the Kestrel web server to use IIS or IIS Express as a reverse proxy
server.
ASP.NET Core Module
Learn how to configure the ASP.NET Core Module for hosting ASP.NET Core apps.
Learn about the directory structure of published ASP.NET Core apps.
Directory structure
Discover active and inactive IIS modules for ASP.NET Core apps and how to manage IIS modules.
IIS modules
Learn how to diagnose problems with IIS deployments of ASP.NET Core apps.
Troubleshoot
Distinguish common errors when hosting ASP.NET Core apps on IIS.
Common errors reference for Azure App Service and IIS
The Official Microsoft IIS Site
Windows Server technical content library
HTTP/2 on IIS
By Luke Latham
This article provides instructions on how to diagnose an ASP.NET Core app startup issue when hosting with
Internet Information Services (IIS ). The information in this article applies to hosting in IIS on Windows Server
and Windows Desktop.
In Visual Studio, an ASP.NET Core project defaults to IIS Express hosting during debugging. A 502.5 Process
Failure that occurs when debugging locally can be troubleshooted using the advice in this topic.
Additional troubleshooting topics:
Although App Service uses the ASP.NET Core Module and IIS to host apps, see the dedicated topic for
instructions specific to App Service.
Handle errors
Discover how to handle errors in ASP.NET Core apps during development on a local system.
Learn to debug using Visual Studio
This topic introduces the features of the Visual Studio debugger.
Debugging with Visual Studio Code
Learn about the debugging support built into Visual Studio Code.
App startup errors

502.5 Process Failure
The worker process fails. The app doesn't start.
The ASP.NET Core Module attempts to start the worker process but it fails to start. The cause of a process
startup failure can usually be determined from entries in the Application Event Log and the ASP.NET Core
Module stdout log.
The 502.5 Process Failure error page is returned when a hosting or app misconfiguration causes the worker
process to fail:
500 Internal Server Error
The app starts, but an error prevents the server from fulfilling the request.
This error occurs within the app's code during startup or while creating a response. The response may contain no
content, or the response may appear as a 500 Internal Server Error in the browser. The Application Event Log
usually states that the app started normally. From the server's perspective, that's correct. The app did start, but it
can't generate a valid response. Run the app at a command prompt on the server or enable the ASP.NET Core
Module stdout log to troubleshoot the problem.
Connection reset
If an error occurs after the headers are sent, it's too late for the server to send a 500 Internal Server Error when
an error occurs. This often happens when an error occurs during the serialization of complex objects for a
response. This type of error appears as a connection reset error on the client. Application logging can help
troubleshoot these types of errors.
Default startup limits

The ASP.NET Core Module is configured with a default startupTimeLimit of 120 seconds. When left at the
default value, an app may take up to two minutes to start before the module logs a process failure. For
information on configuring the module, see Attributes of the aspNetCore element.
Troubleshoot app startup errors

Application Event Log
Access the Application Event Log:
1. Open the Start menu, search for Event Viewer, and then select the Event Viewer app.
2. In Event Viewer, open the Windows Logs node.
3. Select Application to open the Application Event Log.
4. Search for errors associated with the failing app. Errors have a value of IIS AspNetCore Module or IIS Express
AspNetCore Module in the Source column.
Run the app at a command prompt
Many startup errors don't produce useful information in the Application Event Log. You can find the cause of
some errors by running the app at a command prompt on the hosting system.
Framework-dependent deployment
If the app is a framework-dependent deployment:
1. At a command prompt, navigate to the deployment folder and run the app by executing the app's assembly
with dotnet.exe. In the following command, substitute the name of the app's assembly for <assembly_name>:
dotnet .\<assembly_name>.dll .
2. The console output from the app, showing any errors, is written to the console window.
3. If the errors occur when making a request to the app, make a request to the host and port where Kestrel
listens. Using the default host and post, make a request to http://localhost:5000/ . If the app responds
normally at the Kestrel endpoint address, the problem is more likely related to the reverse proxy configuration
and less likely within the app.
Self-contained deployment
If the app is a self-contained deployment:
1. At a command prompt, navigate to the deployment folder and run the app's executable. In the following
command, substitute the name of the app's assembly for <assembly_name>: <assembly_name>.exe .
2. The console output from the app, showing any errors, is written to the console window.
3. If the errors occur when making a request to the app, make a request to the host and port where Kestrel
listens. Using the default host and post, make a request to http://localhost:5000/ . If the app responds
normally at the Kestrel endpoint address, the problem is more likely related to the reverse proxy configuration
and less likely within the app.
ASP.NET Core Module stdout log
To enable and view stdout logs:
1. Navigate to the site's deployment folder on the hosting system.
2. If the logs folder isn't present, create the folder. For instructions on how to enable MSBuild to create the logs
folder in the deployment automatically, see the Directory structure topic.
3. Edit the web.config file. Set stdoutLogEnabled to true and change the stdoutLogFile path to point to the
logs folder (for example, .\logs\stdout ). stdout in the path is the log file name prefix. A timestamp, process
id, and file extension are added automatically when the log is created. Using stdout as the file name prefix, a
typical log file is named stdout_20180205184032_5412.log.
4. Ensure your application pool's identity has write permissions to the logs folder.
5. Save the updated web.config file.
7. Navigate to the logs folder. Find and open the most recent stdout log.
8. Study the log for errors.
Important! Disable stdout logging when troubleshooting is complete.
1. Edit the web.config file.
2. Set stdoutLogEnabled to false .
3. Save the file.
WARNING
created.
For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. For more
information, see third-party logging providers.
Enabling the Developer Exception Page

The ASPNETCORE_ENVIRONMENT environment variable can be added to web.config to run the app in the
Development environment. As long as the environment isn't overridden in app startup by UseEnvironment on the
host builder, setting the environment variable allows the Developer Exception Page to appear when the app is
run.
arguments=".\MyApp.dll"
stdoutLogFile=".\logs\stdout">
<environmentVariables>
<environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
</environmentVariables>
</aspNetCore>
Setting the environment variable for ASPNETCORE_ENVIRONMENT is only recommended for use on staging and
testing servers that aren't exposed to the Internet. Remove the environment variable from the web.config file
after troubleshooting. For information on setting environment variables in web.config, see environmentVariables
child element of aspNetCore.
Common startup errors

See the ASP.NET Core common errors reference. Most of the common problems that prevent app startup are
covered in the reference topic.
Slow or hanging app

When an app responds slowly or hangs on a request, obtain and analyze a dump file. Dump files can be obtained
using any of the following tools:
ProcDump
DebugDiag
WinDbg: Download Debugging tools for Windows, Debugging Using WinDbg
Remote debugging
See Remote Debug ASP.NET Core on a Remote IIS Computer in Visual Studio 2017 in the Visual Studio
documentation.
Application Insights
Application Insights provides telemetry from apps hosted by IIS, including error logging and reporting features.
Application Insights can only report on errors that occur after the app starts when the app's logging features
become available. For more information, see Application Insights for ASP.NET Core.
Additional troubleshooting advice

Sometimes a functioning app fails immediately after upgrading either the .NET Core SDK on the development
machine or package versions within the app. In some cases, incoherent packages may break an app when
performing major upgrades. Most of these issues can be fixed by following these instructions:
1. Delete the bin and obj folders.
2. Clear the package caches at %UserProfile%\.nuget\packages and %LocalAppData%\Nuget\v3 -cache.
3. Restore and rebuild the project.
4. Confirm that the prior deployment on the server has been completely deleted prior to redeploying the app.
TIP
A convenient way to clear package caches is to execute dotnet nuget locals all --clear from a command prompt.
Clearing package caches can also be accomplished by using the nuget.exe tool and executing the command
nuget locals all -clear . nuget.exe isn't a bundled install with the Windows desktop operating system and must be
obtained separately from the NuGet website.
By Luke Latham, Rick Anderson, and Sourabh Shirhatti

This document provides instructions on how to configure the ASP.NET Core Module for hosting ASP.NET Core
apps. For an introduction to the ASP.NET Core Module and installation instructions, see the ASP.NET Core
Module overview.
Configuration with web.config

The ASP.NET Core Module is configured with the aspNetCore section of the system.webServer node in the site's
web.config file.
The following web.config file is published for a framework-dependent deployment and configures the ASP.NET
Core Module to handle site requests:

<configuration>
<system.webServer>
<handlers>
<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
</handlers>
</system.webServer>
</configuration>
The following web.config is published for a self-contained deployment:

<configuration>
<system.webServer>
<handlers>
<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
</handlers>
<aspNetCore processPath=".\MyApp.exe"
</system.webServer>
</configuration>
When an app is deployed to Azure App Service, the stdoutLogFile path is set to \\?\%home%\LogFiles\stdout .
The path saves stdout logs to the LogFiles folder, which is a location automatically created by the service.
See Sub-application configuration for an important note pertaining to the configuration of web.config files in
sub-apps.
Attributes of the aspNetCore element
ATTRIBUTE DESCRIPTION DEFAULT
arguments Optional string attribute.

Arguments to the executable
specified in processPath.
disableStartUpErrorPage true or false. false
If true, the 502.5 - Process

Failure page is suppressed, and
the 502 status code page
configured in the web.config takes
precedence.
forwardWindowsAuthToken true or false. true
If true, the token is forwarded to

the child process listening on
%ASPNETCORE_PORT% as a
header 'MS-ASPNETCORE-
WINAUTHTOKEN' per request. It's
the responsibility of that process
to call CloseHandle on this token
per request.
processPath Required string attribute.

Path to the executable that
launches a process listening for
HTTP requests. Relative paths are
supported. If the path begins with
. , the path is considered to be
relative to the site root.
rapidFailsPerMinute Optional integer attribute. 10
Specifies the number of times the

process specified in processPath is
allowed to crash per minute. If this
limit is exceeded, the module stops
launching the process for the
remainder of the minute.
requestTimeout Optional timespan attribute. 00:02:00
Specifies the duration for which the

ASP.NET Core Module waits for a
response from the process
listening on
%ASPNETCORE_PORT%.
In versions of the ASP.NET Core
Module that shipped with the
release of ASP.NET Core 2.0 or
earlier, the requestTimeout must
be specified in whole minutes only,
otherwise it defaults to 2 minutes.
shutdownTimeLimit Optional integer attribute. 10
Duration in seconds that the

module waits for the executable to
gracefully shutdown when the
app_offline.htm file is detected.
startupTimeLimit Optional integer attribute. 120

start a process listening on the
port. If this time limit is exceeded,
the module kills the process. The
module attempts to relaunch the
process when it receives a new
request and continues to attempt
to restart the process on
subsequent incoming requests
unless the app fails to start
rapidFailsPerMinute number of
times in the last rolling minute.
stdoutLogEnabled Optional Boolean attribute. false
If true, stdout and stderr for the

process specified in processPath
are redirected to the file specified
in stdoutLogFile.
stdoutLogFile Optional string attribute. aspnetcore-stdout
Specifies the relative or absolute

file path for which stdout and
stderr from the process specified
in processPath are logged.
Relative paths are relative to the
root of the site. Any path starting
with . are relative to the site
root and all other paths are
treated as absolute paths. Any
folders provided in the path must
exist in order for the module to
create the log file. Using
underscore delimiters, a
timestamp, process ID, and file
extension (.log) are added to the
last segment of the stdoutLogFile
path. If .\logs\stdout is
supplied as a value, an example
stdout log is saved as
stdout_20180205194132_1934.lo
g in the logs folder when saved on
2/5/2018 at 19:41:32 with a
process ID of 1934.
arguments Optional string attribute.

Arguments to the executable
specified in processPath.
disableStartUpErrorPage true or false. false
If true, the 502.5 - Process

Failure page is suppressed, and
the 502 status code page
configured in the web.config takes
precedence.
forwardWindowsAuthToken true or false. true
If true, the token is forwarded to

the child process listening on
%ASPNETCORE_PORT% as a
header 'MS-ASPNETCORE-
WINAUTHTOKEN' per request. It's
the responsibility of that process
to call CloseHandle on this token
per request.
processPath Required string attribute.

Path to the executable that
launches a process listening for
HTTP requests. Relative paths are
supported. If the path begins with
. , the path is considered to be
relative to the site root.
rapidFailsPerMinute Optional integer attribute. 10
Specifies the number of times the

process specified in processPath is
allowed to crash per minute. If this
limit is exceeded, the module stops
launching the process for the
remainder of the minute.
requestTimeout Optional timespan attribute. 00:02:00
Specifies the duration for which the

ASP.NET Core Module waits for a
response from the process
listening on
%ASPNETCORE_PORT%.
In versions of the ASP.NET Core
Module that shipped with the
release of ASP.NET Core 2.1 or
later, the requestTimeout is
specified in hours, minutes, and
seconds.
shutdownTimeLimit Optional integer attribute. 10

gracefully shutdown when the
app_offline.htm file is detected.
startupTimeLimit Optional integer attribute. 120

start a process listening on the
port. If this time limit is exceeded,
the module kills the process. The
module attempts to relaunch the
process when it receives a new
request and continues to attempt
to restart the process on
subsequent incoming requests
unless the app fails to start
rapidFailsPerMinute number of
times in the last rolling minute.
stdoutLogEnabled Optional Boolean attribute. false
If true, stdout and stderr for the

process specified in processPath
are redirected to the file specified
in stdoutLogFile.
stdoutLogFile Optional string attribute. aspnetcore-stdout
Specifies the relative or absolute

file path for which stdout and
stderr from the process specified
in processPath are logged.
Relative paths are relative to the
root of the site. Any path starting
with . are relative to the site
root and all other paths are
treated as absolute paths. Any
folders provided in the path must
exist in order for the module to
create the log file. Using
underscore delimiters, a
timestamp, process ID, and file
extension (.log) are added to the
last segment of the stdoutLogFile
path. If .\logs\stdout is
supplied as a value, an example
stdout log is saved as
stdout_20180205194132_1934.lo
g in the logs folder when saved on
2/5/2018 at 19:41:32 with a
process ID of 1934.
Setting environment variables

Environment variables can be specified for the process in the processPath attribute. Specify an environment
variable with the environmentVariable child element of an environmentVariables collection element.
Environment variables set in this section take precedence over system environment variables.
The following example sets two environment variables. ASPNETCORE_ENVIRONMENT configures the app's
environment to Development . A developer may temporarily set this value in the web.config file in order to force
the Developer Exception Page to load when debugging an app exception. CONFIG_DIR is an example of a user-
defined environment variable, where the developer has written code that reads the value on startup to form a
path for loading the app's configuration file.
stdoutLogFile="\\?\%home%\LogFiles\stdout">
<environmentVariables>
<environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
<environmentVariable name="CONFIG_DIR" value="f:\application_config" />
</environmentVariables>
</aspNetCore>
WARNING
Only set the ASPNETCORE_ENVIRONMENT envirnonment variable to Development on staging and testing servers that
aren't accessible to untrusted networks, such as the Internet.
app_offline.htm
If a file with the name app_offline.htm is detected in the root directory of an app, the ASP.NET Core Module
attempts to gracefully shutdown the app and stop processing incoming requests. If the app is still running after
the number of seconds defined in shutdownTimeLimit , the ASP.NET Core Module kills the running process.
While the app_offline.htm file is present, the ASP.NET Core Module responds to requests by sending back the
contents of the app_offline.htm file. When the app_offline.htm file is removed, the next request starts the app.
Start-up error page

If the ASP.NET Core Module fails to launch the backend process or the backend process starts but fails to listen
on the configured port, a 502.5 Process Failure status code page appears. To suppress this page and revert to the
default IIS 502 status code page, use the disableStartUpErrorPage attribute. For more information on
configuring custom error messages, see HTTP Errors <httpErrors> .
Log creation and redirection
The ASP.NET Core Module redirects stdout and stderr console output to disk if the stdoutLogEnabled and
stdoutLogFile attributes of the aspNetCore element are set. Any folders in the stdoutLogFile path must exist in
order for the module to create the log file. The app pool must have write access to the location where the logs
are written (use IIS AppPool\<app_pool_name> to provide write permission).
Logs aren't rotated, unless process recycling/restart occurs. It's the responsibility of the hoster to limit the disk
space the logs consume.
Using the stdout log is only recommended for troubleshooting app startup issues. Don't use the stdout log for
general app logging purposes. For routine logging in an ASP.NET Core app, use a logging library that limits log
file size and rotates logs. For more information, see third-party logging providers.
A timestamp and file extension are added automatically when the log file is created. The log file name is
composed by appending the timestamp, process ID, and file extension (.log) to the last segment of the
stdoutLogFile path (typically stdout) delimited by underscores. If the stdoutLogFile path ends with stdout, a log
for an app with a PID of 1934 created on 2/5/2018 at 19:42:32 has the file name
stdout_20180205194132_1934.log.
The following sample aspNetCore element configures stdout logging for an app hosted in Azure App Service. A
local path or network share path is acceptable for local logging. Confirm that the AppPool user identity has
permission to write to the path provided.
stdoutLogEnabled="true"
stdoutLogFile="\\?\%home%\LogFiles\stdout">
</aspNetCore>
See Configuration with web.config for an example of the aspNetCore element in the web.config file.
Proxy configuration uses HTTP protocol and a pairing token

The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. Using HTTP is a
performance optimization, where the traffic between the module and Kestrel takes place on a loopback address
off of the network interface. There's no risk of eavesdropping the traffic between the module and Kestrel from a
location off of the server.
A pairing token is used to guarantee that the requests received by Kestrel were proxied by IIS and didn't come
from some other source. The pairing token is created and set into an environment variable ( ASPNETCORE_TOKEN )
by the module. The pairing token is also set into a header ( MSAspNetCoreToken ) on every proxied request. IIS
Middleware checks each request it receives to confirm that the pairing token header value matches the
environment variable value. If the token values are mismatched, the request is logged and rejected. The pairing
token environment variable and the traffic between the module and Kestrel aren't accessible from a location off
of the server. Without knowing the pairing token value, an attacker can't submit requests that bypass the check in
the IIS Middleware.
ASP.NET Core Module with an IIS Shared Configuration

The ASP.NET Core Module installer runs with the privileges of the SYSTEM account. Because the local system
account doesn't have modify permission for the share path used by the IIS Shared Configuration, the installer
hits an access denied error when attempting to configure the module settings in applicationHost.config on the
share. When using an IIS Shared Configuration, follow these steps:
1. Disable the IIS Shared Configuration.
2. Run the installer.
3. Export the updated applicationHost.config file to the share.
4. Re-enable the IIS Shared Configuration.
Module version and Hosting Bundle installer logs

To determine the version of the installed ASP.NET Core Module:
1. On the hosting system, navigate to %windir%\System32\inetsrv.
2. Locate the aspnetcore.dll file.
3. Right-click the file and select Properties from the contextual menu.
4. Select the Details tab. The File version and Product version represent the installed version of the module.
The Hosting Bundle installer logs for the module are found at C:\Users\%UserName%\AppData\Local\Temp.
The file is named dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.
Module, schema, and configuration file locations

Module
IIS (x86/amd64):
%windir%\System32\inetsrv\aspnetcore.dll
%windir%\SysWOW64\inetsrv\aspnetcore.dll
IIS Express (x86/amd64):
%ProgramFiles%\IIS Express\aspnetcore.dll
%ProgramFiles(x86)%\IIS Express\aspnetcore.dll
Schema
IIS
%windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml
IIS Express
%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml
Configuration
IIS
%windir%\System32\inetsrv\config\applicationHost.config
IIS Express
.vs\config\applicationHost.config
The files can be found by searching for aspnetcore.dll in the applicationHost.config file. For IIS Express, the
applicationHost.config file won't exist by default. The file is created at <application_root>\.vs\config when
starting any web app project in the Visual Studio solution.
Development-time IIS support in Visual Studio for
ASP.NET Core
By Sourabh Shirhatti and Luke Latham

This article describes Visual Studio support for debugging ASP.NET Core apps running behind IIS on Windows
Server. This topic walks through enabling this feature and setting up a project.
Prerequisites
Visual Studio for Windows
X.509 security certificate
Enable IIS
1. Navigate to Control Panel > Programs > Programs and Features > Turn Windows features on or off (left
side of the screen).
2. Select the Internet Information Services check box.
The IIS installation may require a system restart.
Configure IIS
IIS must have a website configured with the following:
A host name that matches the app's launch profile URL host name.
Binding for port 443 with an assigned certificate.
For example, the Host name for an added website is set to "localhost" (the launch profile will also use "localhost"
later in this topic). The port is set to "443" (HTTPS ). The IIS Express Development Certificate is assigned to the
website, but any valid certificate works:
If the IIS installation already has a Default Web Site with a host name that matches the app's launch profile URL
host name:
Add a port binding for port 443 (HTTPS ).
Assign a valid certificate to the website.
Enable development-time IIS support in Visual Studio

1. Launch the Visual Studio installer.
2. Select the Development time IIS support component. The component is listed as optional in the Summary
panel for the ASP.NET and web development workload. The component installs the ASP.NET Core Module,
which is a native IIS module required to run ASP.NET Core apps behind IIS in a reverse proxy configuration.
Configure the project
HTTPS redirection
For a new project, select the check box to Configure for HTTPS in the New ASP.NET Core Web Application
window:
In an existing project, use HTTPS Redirection Middleware in Startup.Configure by calling the UseHttpsRedirection
extension method:
{
{
}
else
{
app.UseHsts();
}
app.UseMvc();
}
IIS launch profile

Create a new launch profile to add development-time IIS support:
1. For Profile, select the New button. Name the profile "IIS" in the popup window. Select OK to create the profile.
2. For the Launch setting, select IIS from the list.
3. Select the check box for Launch browser and provide the endpoint URL. Use the HTTPS protocol. This
example uses https://localhost/WebApplication1 .
4. In the Environment variables section, select the Add button. Provide an environment variable with a key of
ASPNETCORE_ENVIRONMENT and a value of Development .
5. In the Web Server Settings area, set the App URL. This example uses https://localhost/WebApplication1 .
6. Save the profile.
Alternatively, manually add a launch profile to the launchSettings.json file in the app:
{
"iisSettings": {
"windowsAuthentication": false,
"anonymousAuthentication": true,
"iis": {
"applicationUrl": "https://localhost/WebApplication1",
"sslPort": 0
}
},
"profiles": {
"IIS": {
"commandName": "IIS",
"launchUrl": "https://localhost/WebApplication1",
}
}
}
}
Run the project

In the VS UI, set the Run button to the IIS profile and select the button to start the app:
Visual Studio may prompt a restart if not running as an administrator. If prompted, restart Visual Studio.
If an untrusted development certificate is used, the browser may require you to create an exception for the
untrusted certificate.
Introduction to ASP.NET Core Module
Enforce HTTPS
IIS modules with ASP.NET Core
By Luke Latham
ASP.NET Core apps are hosted by IIS in a reverse proxy configuration. Some of the native IIS modules and all of
the IIS managed modules aren't available to process requests for ASP.NET Core apps. In many cases, ASP.NET
Core offers an alternative to the features of IIS native and managed modules.
Native modules
The table indicates native IIS modules that are functional on reverse proxy requests to ASP.NET Core apps.
MODULE FUNCTIONAL WITH ASP.NET CORE APPS ASP.NET CORE OPTION
Anonymous Authentication Yes

AnonymousAuthenticationModule
Basic Authentication Yes

BasicAuthenticationModule
Client Certification Mapping Yes

Authentication
CertificateMappingAuthenticationModule
CGI No
CgiModule
Configuration Validation Yes

ConfigurationValidationModule
HTTP Errors No Status Code Pages Middleware

CustomErrorModule
Custom Logging Yes

CustomLoggingModule
Default Document No Default Files Middleware

DefaultDocumentModule
Digest Authentication Yes

DigestAuthenticationModule
Directory Browsing No Directory Browsing Middleware

DirectoryListingModule
Dynamic Compression Yes Response Compression Middleware

DynamicCompressionModule
Tracing Yes ASP.NET Core Logging

FailedRequestsTracingModule
File Caching No Response Caching Middleware

FileCacheModule
HTTP Caching No Response Caching Middleware

HttpCacheModule
HTTP Logging Yes ASP.NET Core Logging

HttpLoggingModule Implementations: elmah.io, Loggr,
NLog, Serilog
HTTP Redirection Yes URL Rewriting Middleware

HttpRedirectionModule
IIS Client Certificate Mapping Yes

Authentication
IISCertificateMappingAuthenticationModule
IP and Domain Restrictions Yes

IpRestrictionModule
ISAPI Filters Yes Middleware

IsapiFilterModule
ISAPI Yes Middleware

IsapiModule
Protocol Support Yes

ProtocolSupportModule
Request Filtering Yes URL Rewriting Middleware IRule

RequestFilteringModule
Request Monitor Yes

RequestMonitorModule
URL Rewriting Yes† URL Rewriting Middleware

RewriteModule
Server-Side Includes No
ServerSideIncludeModule
Static Compression No Response Compression Middleware

StaticCompressionModule
Static Content No Static File Middleware

StaticFileModule
Token Caching Yes

TokenCacheModule
URI Caching Yes

UriCacheModule
URL Authorization Yes ASP.NET Core Identity

UrlAuthorizationModule
Windows Authentication Yes

WindowsAuthenticationModule
†The URL Rewrite Module's isFile and isDirectory match types don't work with ASP.NET Core apps due to
the changes in directory structure.
Managed modules
Managed modules are not functional with hosted ASP.NET Core apps when the app pool's .NET CLR version is
set to No Managed Code. ASP.NET Core offers middleware alternatives in several cases.
MODULE ASP.NET CORE OPTION
AnonymousIdentification
DefaultAuthentication
FileAuthorization
FormsAuthentication Cookie Authentication Middleware
OutputCache Response Caching Middleware
Profile
RoleManager
ScriptModule-4.0
Session Session Middleware
UrlAuthorization
UrlMappingsModule URL Rewriting Middleware
UrlRoutingModule-4.0 ASP.NET Core Identity
WindowsAuthentication
IIS Manager application changes

When using IIS Manager to configure settings, the web.config file of the app is changed. If deploying an app and
including web.config, any changes made with IIS Manager are overwritten by the deployed web.config file. If
changes are made to the server's web.config file, copy the updated web.config file on the server to the local
project immediately.
Disabling IIS modules

If an IIS module is configured at the server level that must be disabled for an app, an addition to the app's
web.config file can disable the module. Either leave the module in place and deactivate it using a configuration
setting (if available) or remove the module from the app.
Module deactivation
Many modules offer a configuration setting that allows them to be disabled without removing the module from
the app. This is the simplest and quickest way to deactivate a module. For example, the HTTP Redirection Module
can be disabled with the <httpRedirect> element in web.config:
<configuration>
<system.webServer>
<httpRedirect enabled="false" />
</system.webServer>
</configuration>
For more information on disabling modules with configuration settings, follow the links in the Child Elements
section of IIS <system.webServer>.
Module removal
If opting to remove a module with a setting in web.config, unlock the module and unlock the <modules> section
of web.config first:
1. Unlock the module at the server level. Select the IIS server in the IIS Manager Connections sidebar. Open
the Modules in the IIS area. Select the module in the list. In the Actions sidebar on the right, select
Unlock. Unlock as many modules as you plan to remove from web.config later.
2. Deploy the app without a <modules> section in web.config. If an app is deployed with a web.config
containing the <modules> section without having unlocked the section first in the IIS Manager, the
Configuration Manager throws an exception when attempting to unlock the section. Therefore, deploy the
app without a <modules> section.
3. Unlock the <modules> section of web.config. In the Connections sidebar, select the website in Sites. In
the Management area, open the Configuration Editor. Use the navigation controls to select the
system.webServer/modules section. In the Actions sidebar on the right, select to Unlock the section.
4. At this point, a <modules> section can be added to the web.config file with a <remove> element to
remove the module from the app. Multiple <remove> elements can be added to remove multiple
modules. If web.config changes are made on the server, immediately make the same changes to the
project's web.config file locally. Removing a module this way won't affect the use of the module with other
apps on the server.
<configuration>
<system.webServer>
<modules>
<remove name="MODULE_NAME" />
</modules>
</system.webServer>
</configuration>
An IIS module can also be removed with Appcmd.exe. Provide the MODULE_NAME and APPLICATION_NAME in the
command:
Appcmd.exe delete module MODULE_NAME /app.name:APPLICATION_NAME
For example, remove the DynamicCompressionModule from the Default Web Site:
%windir%\system32\inetsrv\appcmd.exe delete module DynamicCompressionModule /app.name:"Default Web Site"
Minimum module configuration

The only modules required to run an ASP.NET Core app are the Anonymous Authentication Module and the
ASP.NET Core Module.
The URI Caching Module ( UriCacheModule ) allows IIS to cache website configuration at the URL level. Without
this module, IIS must read and parse configuration on every request, even when the same URL is repeatedly
requested. Parsing the configuration every request results in a significant performance penalty. Although the URI
Caching Module isn't strictly required for a hosted ASP.NET Core app to run, we recommend that the URI
Caching Module be enabled for all ASP.NET Core deployments.
The HTTP Caching Module ( HttpCacheModule ) implements the IIS output cache and also the logic for caching
items in the HTTP.sys cache. Without this module, content is no longer cached in kernel mode, and cache profiles
are ignored. Removing the HTTP Caching Module usually has adverse effects on performance and resource
usage. Although the HTTP Caching Module isn't strictly required for a hosted ASP.NET Core app to run, we
recommend that the HTTP Caching Module be enabled for all ASP.NET Core deployments.
Introduction to IIS Architectures: Modules in IIS
IIS Modules Overview
Customizing IIS 7.0 Roles and Modules
IIS <system.webServer>
Host ASP.NET Core in a Windows Service
By Luke Latham and Tom Dykstra

An ASP.NET Core app can be hosted on Windows without using IIS as a Windows Service. When hosted as a
Windows Service, the app can automatically start after reboots and crashes without requiring human intervention.
Convert a project into a Windows Service

The following minimum changes are required to set up an existing ASP.NET Core project to run as a service:
1. In the project file:
Confirm the presence of a Windows Runtime Identifier (RID ) or add it to the <PropertyGroup> that
contains the target framework:
<PropertyGroup>
<RuntimeIdentifier>win7-x64</RuntimeIdentifier>
</PropertyGroup>
<PropertyGroup>
</PropertyGroup>
<PropertyGroup>
</PropertyGroup>
To publish for multiple RIDs:

Provide the RIDs in a semicolon-delimited list.
Use the property name <RuntimeIdentifiers> (plural).
For more information, see .NET Core RID Catalog.
Add a package reference for Microsoft.AspNetCore.Hosting.WindowsServices.
2. Make the following changes in Program.Main :
Call host.RunAsService instead of host.Run .
Call UseContentRoot and use a path to the app's published location instead of
Directory.GetCurrentDirectory() .
{
CreateWebHostBuilder(args).Build().RunAsService();
}

{
var pathToExe = Process.GetCurrentProcess().MainModule.FileName;
var pathToContentRoot = Path.GetDirectoryName(pathToExe);
.ConfigureAppConfiguration((context, config) =>
{
// Configure the app here.
})
.UseContentRoot(pathToContentRoot)
}

{

.UseKestrel()
.Build();
host.RunAsService();
}
3. Publish the app. Use dotnet publish or a Visual Studio publish profile. When using a Visual Studio, select
the FolderProfile.
To publish the sample app using command-line interface (CLI) tools, run the dotnet publish command at a
command prompt from the project folder. The RID must be specified in the <RuntimeIdenfifier> (or
<RuntimeIdentifiers> ) property of the project file. In the following example, the app is published in Release
configuration for the win7-x64 runtime:
dotnet publish --configuration Release --runtime win7-x64
4. Use the sc.exe command-line tool to create the service. The binPath value is the path to the app's
executable, which includes the executable file name. The space between the equal sign and the quote
character at the start of the path is required.
sc create <SERVICE_NAME> binPath= "<PATH_TO_SERVICE_EXECUTABLE>"
For a service published in the project folder, use the path to the publish folder to create the service. In the
following example:
The project resides in the c:\my_services\AspNetCoreService folder.
The project is published in Release configuration.
The Target Framework Moniker (TFM ) is netcoreapp2.1 .
The Runtime Identifer (RID ) is win7-x64 .
The app executable is named AspNetCoreService.exe.
The service is named MyService.
Example:
sc create MyService binPath= "c:\my_services\AspNetCoreService\bin\Release\netcoreapp2.1\win7-

x64\publish\AspNetCoreService.exe"
IMPORTANT
Make sure the space is present between the binPath= argument and its value.
To publish and start the service from a different folder:

Use the --output <OUTPUT_DIRECTORY> option on the dotnet publish command. If using Visual
Studio, configure the Target Location in the FolderProfile publish property page before selecting the
Publish button.
Create the service with the sc.exe command using the output folder path. Include the name of the
service's executable in the path provided to binPath .
5. Start the service with the sc start <SERVICE_NAME> command.
To start the sample app service, use the following command:
sc start MyService
The command takes a few seconds to start the service.

6. To check the status of the service, use the sc query <SERVICE_NAME> command. The status is reported as one
of the following values:
START_PENDING
RUNNING
STOP_PENDING
STOPPED
Use the following command to check the status of the sample app service:
sc query MyService
7. When the service is in the RUNNING state and if the service is a web app, browse the app at its path (by
default, http://localhost:5000 , which redirects to https://localhost:5001 when using HTTPS Redirection
Middleware).
For the sample app service, browse the app at http://localhost:5000 .
8. Stop the service with the sc stop <SERVICE_NAME> command.
The following command stops the sample app service:
sc stop MyService
9. After a short delay to stop a service, uninstall the service with the sc delete <SERVICE_NAME> command.
Check the status of the sample app service:
sc query MyService
When the sample app service is in the STOPPED state, use the following command to uninstall the sample
app service:
sc delete MyService
Run the app outside of a service

It's easier to test and debug when running outside of a service, so it's customary to add code that calls
RunAsService only under certain conditions. For example, the app can run as a console app with a --console
command-line argument or if the debugger is attached:

{
var isService = !(Debugger.IsAttached || args.Contains("--console"));
var builder = CreateWebHostBuilder(args.Where(arg => arg != "--console").ToArray());
if (isService)
{
builder.UseContentRoot(pathToContentRoot);
}
if (isService)
{
}
else
{
host.Run();
}
}

{
})
Because ASP.NET Core configuration requires name-value pairs for command-line arguments, the --console
switch is removed before the arguments are passed to CreateDefaultBuilder.
NOTE
isService isn't passed from Main into CreateWebHostBuilder because the signature of CreateWebHostBuilder must
be CreateWebHostBuilder(string[]) in order for integration testing to work properly.
{
var isService = true;
if (Debugger.IsAttached || args.Contains("--console"))
{
isService = false;
}
var pathToContentRoot = Directory.GetCurrentDirectory();
if (isService)
{
pathToContentRoot = Path.GetDirectoryName(pathToExe);
}

.UseKestrel()
.Build();
if (isService)
{
}
else
{
host.Run();
}
}
Handle stopping and starting events

To handle OnStarting, OnStarted, and OnStopping events, make the following additional changes:
1. Create a class that derives from WebHostService:
internal class CustomWebHostService : WebHostService

{
public CustomWebHostService(IWebHost host) : base(host)
{
}
protected override void OnStarting(string[] args)

{
base.OnStarting(args);
}
protected override void OnStarted()

{
base.OnStarted();
}
protected override void OnStopping()

{
base.OnStopping();
}
}
2. Create an extension method for IWebHost that passes the custom WebHostService to ServiceBase.Run:
public static class WebHostServiceExtensions
{
public static void RunAsCustomService(this IWebHost host)
{
var webHostService = new CustomWebHostService(host);
ServiceBase.Run(webHostService);
}
}
3. In Program.Main , call the new extension method, RunAsCustomService , instead of RunAsService:

{
var isService = !(Debugger.IsAttached || args.Contains("--console"));
var builder = CreateWebHostBuilder(args.Where(arg => arg != "--console").ToArray());
if (isService)
{
builder.UseContentRoot(pathToContentRoot);
}
if (isService)
{
host.RunAsCustomService();
}
else
{
host.Run();
}
}

{
})
NOTE
isService isn't passed from Main into CreateWebHostBuilder because the signature of
CreateWebHostBuilder must be CreateWebHostBuilder(string[]) in order for integration testing to work
properly.
{
var isService = true;
if (Debugger.IsAttached || args.Contains("--console"))
{
isService = false;
}
var pathToContentRoot = Directory.GetCurrentDirectory();
if (isService)
{
pathToContentRoot = Path.GetDirectoryName(pathToExe);
}

.UseKestrel()
.Build();
if (isService)
{
host.RunAsCustomService();
}
else
{
host.Run();
}
}
If the custom WebHostService code requires a service from dependency injection (such as a logger), obtain it from
the IWebHost.Services property:
internal class CustomWebHostService : WebHostService
{
private ILogger _logger;
public CustomWebHostService(IWebHost host) : base(host)

{
_logger = host.Services
.GetRequiredService<ILogger<CustomWebHostService>>();
}
protected override void OnStarting(string[] args)

{
_logger.LogDebug("OnStarting method called.");
base.OnStarting(args);
}
protected override void OnStarted()

{
_logger.LogDebug("OnStarted method called.");
base.OnStarted();
}
protected override void OnStopping()

{
_logger.LogDebug("OnStopping method called.");
base.OnStopping();
}
}

Services that interact with requests from the Internet or a corporate network and are behind a proxy or load
balancer might require additional configuration. For more information, see Configure ASP.NET Core to work with
proxy servers and load balancers.
Configure HTTPS
Specify a Kestrel server HTTPS endpoint configuration.
Current directory and content root

The current working directory returned by calling Directory.GetCurrentDirectory() for a Windows Service is the
C:\WINDOWS\system32 folder. The system32 folder isn't a suitable location to store a service's files (for example,
settings files). Use one of the following approaches to maintain and access a service's assets and settings files with
FileConfigurationExtensions.SetBasePath when using an IConfigurationBuilder:
Use the content root path. The IHostingEnvironment.ContentRootPath is the same path provided to the binPath
argument when the service is created. Instead of using Directory.GetCurrentDirectory() to create paths to
settings files, use the content root path and maintain the files in the app's content root.
Store the files in a suitable location on disk. Specify an absolute path with SetBasePath to the folder containing
the files.
Kestrel endpoint configuration (includes HTTPS configuration and SNI support)
ASP.NET Core Web Host
By Sourabh Shirhatti
This guide explains setting up a production-ready ASP.NET Core environment on an Ubuntu 16.04 server. These
instructions likely work with newer versions of Ubuntu, but the instructions haven't been tested with newer
versions.
For information on other Linux distributions supported by ASP.NET Core, see Prerequisites for .NET Core on
Linux.
NOTE
For Ubuntu 14.04, supervisord is recommended as a solution for monitoring the Kestrel process. systemd isn't available on
Ubuntu 14.04. For Ubuntu 14.04 instructions, see the previous version of this topic.
This guide:
Places an existing ASP.NET Core app behind a reverse proxy server.
Sets up the reverse proxy server to forward requests to the Kestrel web server.
Ensures the web app runs on startup as a daemon.
Configures a process management tool to help restart the web app.
Prerequisites
1. Access to an Ubuntu 16.04 server with a standard user account with sudo privilege.
2. Install the .NET Core runtime on the server.
a. Visit the .NET Core All Downloads page.
b. Select the latest non-preview runtime from the list under Runtime.
c. Select and follow the instructions for Ubuntu that match the Ubuntu version of the server.
3. An existing ASP.NET Core app.
Publish and copy over the app

Configure the app for a framework-dependent deployment.
Run dotnet publish from the development environment to package an app into a directory (for example,
bin/Release/<target_framework_moniker>/publish) that can run on the server:
dotnet publish --configuration Release
The app can also be published as a self-contained deployment if you prefer not to maintain the .NET Core
runtime on the server.
Copy the ASP.NET Core app to the server using a tool that integrates into the organization's workflow (for
example, SCP, SFTP ). It's common to locate web apps under the var directory (for example,
var/aspnetcore/hellomvc).
NOTE
Under a production deployment scenario, a continuous integration workflow does the work of publishing the app and
copying the assets to the server.
Test the app:

1. From the command line, run the app: dotnet <app_assembly>.dll .
2. In a browser, navigate to http://<serveraddress>:<port> to verify the app works on Linux locally.
Configure a reverse proxy server

A reverse proxy is a common setup for serving dynamic web apps. A reverse proxy terminates the HTTP request
and forwards it to the ASP.NET Core app.
NOTE
Either configuration—with or without a reverse proxy server—is a valid and supported hosting configuration for ASP.NET
Core 2.0 or later apps. For more information, see When to use Kestrel with a reverse proxy.
Use a reverse proxy server

Kestrel is great for serving dynamic content from ASP.NET Core. However, the web serving capabilities aren't as
feature rich as servers such as IIS, Apache, or Nginx. A reverse proxy server can offload work such as serving
static content, caching requests, compressing requests, and SSL termination from the HTTP server. A reverse
proxy server may reside on a dedicated machine or may be deployed alongside an HTTP server.
For the purposes of this guide, a single instance of Nginx is used. It runs on the same server, alongside the HTTP
server. Based on requirements, a different setup may be chosen.
Because requests are forwarded by reverse proxy, use the Forwarded Headers Middleware from the
Microsoft.AspNetCore.HttpOverrides package. The middleware updates the Request.Scheme , using the
X-Forwarded-Proto header, so that redirect URIs and other security policies work correctly.
Any component that depends on the scheme, such as authentication, link generation, redirects, and geolocation,
must be placed after invoking the Forwarded Headers Middleware. As a general rule, Forwarded Headers
Middleware should run before other middleware except diagnostics and error handling middleware. This
ordering ensures that the middleware relying on forwarded headers information can consume the header values
for processing.
ASP.NET Core 2.x
ASP.NET Core 1.x
Invoke the UseForwardedHeaders method in Startup.Configure before calling UseAuthentication or similar
authentication scheme middleware. Configure the middleware to forward the X-Forwarded-For and
X-Forwarded-Proto headers:
app.UseForwardedHeaders(new ForwardedHeadersOptions
{
ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto
});
If no ForwardedHeadersOptions are specified to the middleware, the default headers to forward are None .
Only proxies running on localhost (127.0.0.1, [::1]) are trusted by default. If other trusted proxies or networks
within the organization handle requests between the Internet and the web server, add them to the list of
KnownProxies or KnownNetworks with ForwardedHeadersOptions. The following example adds a trusted proxy
server at IP address 10.0.0.100 to the Forwarded Headers Middleware KnownProxies in
services.Configure<ForwardedHeadersOptions>(options =>
{
options.KnownProxies.Add(IPAddress.Parse("10.0.0.100"));
});
For more information, see Configure ASP.NET Core to work with proxy servers and load balancers.
Install Nginx
Use apt-get to install Nginx. The installer creates a systemd init script that runs Nginx as daemon on system
startup. Follow the installation instructions for Ubuntu at Nginx: Official Debian/Ubuntu packages.
NOTE
If optional Nginx modules are required, building Nginx from source might be required.
Since Nginx was installed for the first time, explicitly start it by running:
sudo service nginx start
Verify a browser displays the default landing page for Nginx. The landing page is reachable at
http://<server_IP_address>/index.nginx-debian.html .
Configure Nginx
To configure Nginx as a reverse proxy to forward requests to your ASP.NET Core app, modify /etc/nginx/sites-
available/default. Open it in a text editor, and replace the contents with the following:
server {
listen 80;
server_name example.com *.example.com;
location / {
proxy_pass http://localhost:5000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection keep-alive;
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
When no server_name matches, Nginx uses the default server. If no default server is defined, the first server in
the configuration file is the default server. As a best practice, add a specific default server which returns a status
code of 444 in your configuration file. A default server configuration example is:
server {
listen 80 default_server;
# listen [::]:80 default_server deferred;
return 444;
}
With the preceding configuration file and default server, Nginx accepts public traffic on port 80 with host header
example.com or *.example.com . Requests not matching these hosts won't get forwarded to Kestrel. Nginx
forwards the matching requests to Kestrel at http://localhost:5000 . See How nginx processes a request for
more information. To change Kestrel's IP/port, see Kestrel: Endpoint configuration.
WARNING
Failure to specify a proper server_name directive exposes your app to security vulnerabilities. Subdomain wildcard binding
(for example, *.example.com ) doesn't pose this security risk if you control the entire parent domain (as opposed to
*.com , which is vulnerable). See rfc7230 section-5.4 for more information.
Once the Nginx configuration is established, run sudo nginx -t to verify the syntax of the configuration files. If
the configuration file test is successful, force Nginx to pick up the changes by running sudo nginx -s reload .
To directly run the app on the server:
1. Navigate to the app's directory.
2. Run the app's executable: ./<app_executable> .
If a permissions error occurs, change the permissions:
chmod u+x <app_executable>
If the app runs on the server but fails to respond over the Internet, check the server's firewall and confirm that
port 80 is open. If using an Azure Ubuntu VM, add a Network Security Group (NSG ) rule that enables inbound
port 80 traffic. There's no need to enable an outbound port 80 rule, as the outbound traffic is automatically
granted when the inbound rule is enabled.
When done testing the app, shut the app down with Ctrl+C at the command prompt.
Monitoring the app

The server is setup to forward requests made to http://<serveraddress>:80 on to the ASP.NET Core app
running on Kestrel at http://127.0.0.1:5000 . However, Nginx isn't set up to manage the Kestrel process. systemd
can be used to create a service file to start and monitor the underlying web app. systemd is an init system that
provides many powerful features for starting, stopping, and managing processes.
Create the service file
Create the service definition file:
sudo nano /etc/systemd/system/kestrel-hellomvc.service
The following is an example service file for the app:

[Unit]
Description=Example .NET Web API App running on Ubuntu
[Service]
WorkingDirectory=/var/aspnetcore/hellomvc
ExecStart=/usr/bin/dotnet /var/aspnetcore/hellomvc/hellomvc.dll
Restart=always
# Restart service after 10 seconds if the dotnet service crashes:
RestartSec=10
KillSignal=SIGINT
SyslogIdentifier=dotnet-example
User=www-data
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false
[Install]
WantedBy=multi-user.target
If the user www -data isn't used by the configuration, the user defined here must be created first and given proper
ownership for files.
Use TimeoutStopSec to configure the duration of time to wait for the app to shut down after it receives the initial
interrupt signal. If the app doesn't shut down in this period, SIGKILL is issued to terminate the app. Provide the
value as unitless seconds (for example, 150 ), a time span value (for example, 2min 30s ), or infinity to disable
the timeout. TimeoutStopSec defaults to the value of DefaultTimeoutStopSec in the manager configuration file
(systemd -system.conf, system.conf.d, systemd -user.conf, user.conf.d). The default timeout for most distributions is
90 seconds.
# The default value is 90 seconds for most distributions.

TimeoutStopSec=90
Linux has a case-sensitive file system. Setting ASPNETCORE_ENVIRONMENT to "Production" results in

searching for the configuration file appsettings.Production.json, not appsettings.production.json.
Some values (for example, SQL connection strings) must be escaped for the configuration providers to read the
environment variables. Use the following command to generate a properly escaped value for use in the
configuration file:
systemd-escape "<value-to-escape>"
Save the file and enable the service.
sudo systemctl enable kestrel-hellomvc.service
Start the service and verify that it's running.
sudo systemctl start kestrel-hellomvc.service

sudo systemctl status kestrel-hellomvc.service
● kestrel-hellomvc.service - Example .NET Web API App running on Ubuntu

Loaded: loaded (/etc/systemd/system/kestrel-hellomvc.service; enabled)
Active: active (running) since Thu 2016-10-18 04:09:35 NZDT; 35s ago
Main PID: 9021 (dotnet)
CGroup: /system.slice/kestrel-hellomvc.service
└─9021 /usr/local/bin/dotnet /var/aspnetcore/hellomvc/hellomvc.dll
With the reverse proxy configured and Kestrel managed through systemd, the web app is fully configured and
can be accessed from a browser on the local machine at http://localhost . It's also accessible from a remote
machine, barring any firewall that might be blocking. Inspecting the response headers, the Server header shows
the ASP.NET Core app being served by Kestrel.
HTTP/1.1 200 OK
Date: Tue, 11 Oct 2016 16:22:23 GMT
Server: Kestrel
Keep-Alive: timeout=5, max=98
Connection: Keep-Alive
Transfer-Encoding: chunked
Viewing logs
Since the web app using Kestrel is managed using systemd , all events and processes are logged to a centralized
journal. However, this journal includes all entries for all services and processes managed by systemd . To view the
kestrel-hellomvc.service -specific items, use the following command:
sudo journalctl -fu kestrel-hellomvc.service
For further filtering, time options such as --since today , --until 1 hour ago or a combination of these can
reduce the amount of entries returned.
sudo journalctl -fu kestrel-hellomvc.service --since "2016-10-18" --until "2016-10-18 04:00"
Data protection
The ASP.NET Core Data Protection stack is used by several ASP.NET Core middlewares, including
authentication middleware (for example, cookie middleware) and cross-site request forgery (CSRF ) protections.
Even if Data Protection APIs aren't called by user code, data protection should be configured to create a
persistent cryptographic key store. If data protection isn't configured, the keys are held in memory and discarded
when the app restarts.
To configure data protection to persist and encrypt the key ring, see:
Key storage providers in ASP.NET Core
Key encryption At rest in ASP.NET Core
Securing the app

Enable AppArmor
Linux Security Modules (LSM ) is a framework that's part of the Linux kernel since Linux 2.6. LSM supports
different implementations of security modules. AppArmor is a LSM that implements a Mandatory Access
Control system which allows confining the program to a limited set of resources. Ensure AppArmor is enabled
and properly configured.
Configuring the firewall
Close off all external ports that are not in use. Uncomplicated firewall (ufw ) provides a front end for iptables by
providing a command line interface for configuring the firewall.
WARNING
A firewall will prevent access to the whole system if not configured correctly. Failure to specify the correct SSH port will
effectively lock you out of the system if you are using SSH to connect to it. The default port is 22. For more information,
see the introduction to ufw and the manual.
Install ufw and configure it to allow traffic on any ports needed.
sudo apt-get install ufw
sudo ufw allow 22/tcp

sudo ufw enable
Securing Nginx
Change the Nginx response name
Edit src/http/ngx_http_header_filter_module.c:
static char ngx_http_server_string[] = "Server: Web Server" CRLF;

static char ngx_http_server_full_string[] = "Server: Web Server" CRLF;
Configure options
Configure the server with additional required modules. Consider using a web app firewall, such as ModSecurity,
to harden the app.
Configure SSL
Configure the server to listen to HTTPS traffic on port 443 by specifying a valid certificate issued by a
trusted Certificate Authority (CA).
Harden the security by employing some of the practices depicted in the following /etc/nginx/nginx.conf
file. Examples include choosing a stronger cipher and redirecting all traffic over HTTP to HTTPS.
Adding an HTTP Strict-Transport-Security (HSTS ) header ensures all subsequent requests made by the
client are over HTTPS only.
Don't add the Strict-Transport-Security header or chose an appropriate max-age if SSL will be disabled in
the future.
Add the /etc/nginx/proxy.conf configuration file:
proxy_redirect off;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
client_max_body_size 10m;
client_body_buffer_size 128k;
proxy_connect_timeout 90;
proxy_send_timeout 90;
proxy_read_timeout 90;
proxy_buffers 32 4k;
Edit the /etc/nginx/nginx.conf configuration file. The example contains both http and server sections in one
configuration file.
http {
include /etc/nginx/proxy.conf;
limit_req_zone $binary_remote_addr zone=one:10m rate=5r/s;
server_tokens off;
sendfile on;
keepalive_timeout 29; # Adjust to the lowest possible value that makes sense for your use case.
client_body_timeout 10; client_header_timeout 10; send_timeout 10;
upstream hellomvc{
server localhost:5000;
}
server {
listen *:80;
add_header Strict-Transport-Security max-age=15768000;
return 301 https://$host$request_uri;
}
server {
listen *:443 ssl;
server_name example.com;
ssl_certificate /etc/ssl/certs/testCert.crt;
ssl_certificate_key /etc/ssl/certs/testCert.key;
ssl_protocols TLSv1.1 TLSv1.2;
ssl_prefer_server_ciphers on;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
ssl_ecdh_curve secp384r1;
ssl_session_cache shared:SSL:10m;
ssl_session_tickets off;
ssl_stapling on; #ensure your cert is capable
ssl_stapling_verify on; #ensure your cert is capable
add_header Strict-Transport-Security "max-age=63072000; includeSubdomains; preload";

add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
#Redirects all traffic

location / {
proxy_pass http://hellomvc;
limit_req zone=one burst=10 nodelay;
}
}
}
Secure Nginx from clickjacking

Clickjacking is a malicious technique to collect an infected user's clicks. Clickjacking tricks the victim (visitor) into
clicking on an infected site. Use X-FRAME -OPTIONS to secure the site.
Edit the nginx.conf file:
sudo nano /etc/nginx/nginx.conf
Add the line add_header X-Frame-Options "SAMEORIGIN"; and save the file, then restart Nginx.
MIME-type sniffing
This header prevents most browsers from MIME -sniffing a response away from the declared content type, as the
header instructs the browser not to override the response content type. With the nosniff option, if the server
says the content is "text/html", the browser renders it as "text/html".
Edit the nginx.conf file:
sudo nano /etc/nginx/nginx.conf
Add the line add_header X-Content-Type-Options "nosniff"; and save the file, then restart Nginx.
Prerequisites for .NET Core on Linux
Nginx: Binary Releases: Official Debian/Ubuntu packages
NGINX: Using the Forwarded header
By Shayne Boyer
Using this guide, learn how to set up Apache as a reverse proxy server on CentOS 7 to redirect HTTP traffic to an
ASP.NET Core web app running on Kestrel. The mod_proxy extension and related modules create the server's
reverse proxy.
Prerequisites
1. Server running CentOS 7 with a standard user account with sudo privilege.
2. Install the .NET Core runtime on the server.
a. Visit the .NET Core All Downloads page.
b. Select the latest non-preview runtime from the list under Runtime.
c. Select and follow the instructions for CentOS/Oracle.
3. An existing ASP.NET Core app.
Publish and copy over the app

Configure the app for a framework-dependent deployment.
Run dotnet publish from the development environment to package an app into a directory (for example,
bin/Release/<target_framework_moniker>/publish) that can run on the server:
dotnet publish --configuration Release
The app can also be published as a self-contained deployment if you prefer not to maintain the .NET Core
runtime on the server.
Copy the ASP.NET Core app to the server using a tool that integrates into the organization's workflow (for
example, SCP, SFTP ). It's common to locate web apps under the var directory (for example,
var/aspnetcore/hellomvc).
NOTE
Under a production deployment scenario, a continuous integration workflow does the work of publishing the app and
copying the assets to the server.
Configure a proxy server

A reverse proxy is a common setup for serving dynamic web apps. The reverse proxy terminates the HTTP
request and forwards it to the ASP.NET app.
A proxy server is one which forwards client requests to another server instead of fulfilling requests itself. A
reverse proxy forwards to a fixed destination, typically on behalf of arbitrary clients. In this guide, Apache is
configured as the reverse proxy running on the same server that Kestrel is serving the ASP.NET Core app.
Because requests are forwarded by reverse proxy, use the Forwarded Headers Middleware from the
Microsoft.AspNetCore.HttpOverrides package. The middleware updates the Request.Scheme , using the
X-Forwarded-Proto header, so that redirect URIs and other security policies work correctly.
Any component that depends on the scheme, such as authentication, link generation, redirects, and geolocation,
must be placed after invoking the Forwarded Headers Middleware. As a general rule, Forwarded Headers
Middleware should run before other middleware except diagnostics and error handling middleware. This
ordering ensures that the middleware relying on forwarded headers information can consume the header values
for processing.
NOTE
Either configuration—with or without a reverse proxy server—is a valid and supported hosting configuration for ASP.NET
Core 2.0 or later apps. For more information, see When to use Kestrel with a reverse proxy.
ASP.NET Core 2.x

ASP.NET Core 1.x
Invoke the UseForwardedHeaders method in Startup.Configure before calling UseAuthentication or similar
authentication scheme middleware. Configure the middleware to forward the X-Forwarded-For and
X-Forwarded-Proto headers:
app.UseForwardedHeaders(new ForwardedHeadersOptions
{
ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto
});
If no ForwardedHeadersOptions are specified to the middleware, the default headers to forward are None .
Only proxies running on localhost (127.0.0.1, [::1]) are trusted by default. If other trusted proxies or networks
within the organization handle requests between the Internet and the web server, add them to the list of
KnownProxies or KnownNetworks with ForwardedHeadersOptions. The following example adds a trusted proxy
server at IP address 10.0.0.100 to the Forwarded Headers Middleware KnownProxies in
{
});
For more information, see Configure ASP.NET Core to work with proxy servers and load balancers.
Install Apache
Update CentOS packages to their latest stable versions:
sudo yum update -y
Install the Apache web server on CentOS with a single yum command:
sudo yum -y install httpd mod_ssl
Sample output after running the command:

Downloading packages:
httpd-2.4.6-40.el7.centos.4.x86_64.rpm | 2.7 MB 00:00:01
Running transaction check
Running transaction test
Transaction test succeeded
Running transaction
Installing : httpd-2.4.6-40.el7.centos.4.x86_64 1/1
Verifying : httpd-2.4.6-40.el7.centos.4.x86_64 1/1
Installed:
httpd.x86_64 0:2.4.6-40.el7.centos.4
Complete!
NOTE
In this example, the output reflects httpd.86_64 since the CentOS 7 version is 64 bit. To verify where Apache is installed,
run whereis httpd from a command prompt.
Configure Apache
Configuration files for Apache are located within the /etc/httpd/conf.d/ directory. Any file with the .conf
extension is processed in alphabetical order in addition to the module configuration files in
/etc/httpd/conf.modules.d/ , which contains any configuration files necessary to load modules.
Create a configuration file, named hellomvc.conf, for the app:
<VirtualHost *:*>
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
<VirtualHost *:80>
ProxyPreserveHost On
ProxyPass / http://127.0.0.1:5000/
ProxyPassReverse / http://127.0.0.1:5000/
ServerName www.example.com
ServerAlias *.example.com
ErrorLog ${APACHE_LOG_DIR}hellomvc-error.log
CustomLog ${APACHE_LOG_DIR}hellomvc-access.log common
</VirtualHost>
The VirtualHost block can appear multiple times, in one or more files on a server. In the preceding configuration
file, Apache accepts public traffic on port 80. The domain www.example.com is being served, and the
*.example.com alias resolves to the same website. See Name-based virtual host support for more information.
Requests are proxied at the root to port 5000 of the server at 127.0.0.1. For bi-directional communication,
ProxyPass and ProxyPassReverse are required. To change Kestrel's IP/port, see Kestrel: Endpoint configuration.
WARNING
Failure to specify a proper ServerName directive in the VirtualHost block exposes your app to security vulnerabilities.
Subdomain wildcard binding (for example, *.example.com ) doesn't pose this security risk if you control the entire parent
domain (as opposed to *.com , which is vulnerable). See rfc7230 section-5.4 for more information.
Logging can be configured per VirtualHost using ErrorLog and CustomLog directives. ErrorLog is the location
where the server logs errors, and CustomLog sets the filename and format of log file. In this case, this is where
request information is logged. There's one line for each request.
Save the file and test the configuration. If everything passes, the response should be Syntax [OK] .
sudo service httpd configtest
Restart Apache:
sudo systemctl restart httpd

sudo systemctl enable httpd
Monitoring the app

Apache is now setup to forward requests made to http://localhost:80 to the ASP.NET Core app running on
Kestrel at http://127.0.0.1:5000 . However, Apache isn't set up to manage the Kestrel process. Use systemd and
create a service file to start and monitor the underlying web app. systemd is an init system that provides many
powerful features for starting, stopping, and managing processes.
Create the service file
Create the service definition file:
sudo nano /etc/systemd/system/kestrel-hellomvc.service
An example service file for the app:
[Unit]
Description=Example .NET Web API App running on CentOS 7
[Service]
WorkingDirectory=/var/aspnetcore/hellomvc
ExecStart=/usr/local/bin/dotnet /var/aspnetcore/hellomvc/hellomvc.dll
Restart=always
# Restart service after 10 seconds if the dotnet service crashes:
RestartSec=10
KillSignal=SIGINT
SyslogIdentifier=dotnet-example
User=apache
Environment=ASPNETCORE_ENVIRONMENT=Production
[Install]
WantedBy=multi-user.target
If the user apache isn't used by the configuration, the user must be created first and given proper ownership of
files.
Use TimeoutStopSec to configure the duration of time to wait for the app to shut down after it receives the initial
interrupt signal. If the app doesn't shut down in this period, SIGKILL is issued to terminate the app. Provide the
value as unitless seconds (for example, 150 ), a time span value (for example, 2min 30s ), or infinity to disable
the timeout. TimeoutStopSec defaults to the value of DefaultTimeoutStopSec in the manager configuration file
(systemd -system.conf, system.conf.d, systemd -user.conf, user.conf.d). The default timeout for most distributions is
90 seconds.
# The default value is 90 seconds for most distributions.

TimeoutStopSec=90
Some values (for example, SQL connection strings) must be escaped for the configuration providers to read the
environment variables. Use the following command to generate a properly escaped value for use in the
configuration file:
systemd-escape "<value-to-escape>"
Save the file and enable the service:
sudo systemctl enable kestrel-hellomvc.service
Start the service and verify that it's running:
sudo systemctl start kestrel-hellomvc.service

sudo systemctl status kestrel-hellomvc.service
● kestrel-hellomvc.service - Example .NET Web API App running on CentOS 7

Loaded: loaded (/etc/systemd/system/kestrel-hellomvc.service; enabled)
Active: active (running) since Thu 2016-10-18 04:09:35 NZDT; 35s ago
Main PID: 9021 (dotnet)
CGroup: /system.slice/kestrel-hellomvc.service
└─9021 /usr/local/bin/dotnet /var/aspnetcore/hellomvc/hellomvc.dll
With the reverse proxy configured and Kestrel managed through systemd, the web app is fully configured and
can be accessed from a browser on the local machine at http://localhost . Inspecting the response headers, the
Server header indicates that the ASP.NET Core app is served by Kestrel:
HTTP/1.1 200 OK
Date: Tue, 11 Oct 2016 16:22:23 GMT
Server: Kestrel
Keep-Alive: timeout=5, max=98
Connection: Keep-Alive
Transfer-Encoding: chunked
Viewing logs
Since the web app using Kestrel is managed using systemd, events and processes are logged to a centralized
journal. However, this journal includes entries for all of the services and processes managed by systemd. To view
the kestrel-hellomvc.service -specific items, use the following command:
sudo journalctl -fu kestrel-hellomvc.service
For time filtering, specify time options with the command. For example, use --since today to filter for the
current day or --until 1 hour ago to see the previous hour's entries. For more information, see the man page for
journalctl.
sudo journalctl -fu kestrel-hellomvc.service --since "2016-10-18" --until "2016-10-18 04:00"
Data protection
The ASP.NET Core Data Protection stack is used by several ASP.NET Core middlewares, including
authentication middleware (for example, cookie middleware) and cross-site request forgery (CSRF ) protections.
Even if Data Protection APIs aren't called by user code, data protection should be configured to create a
persistent cryptographic key store. If data protection isn't configured, the keys are held in memory and discarded
when the app restarts.
To configure data protection to persist and encrypt the key ring, see:
Securing the app

Configure firewall
Firewalld is a dynamic daemon to manage the firewall with support for network zones. Ports and packet filtering
can still be managed by iptables. Firewalld should be installed by default. yum can be used to install the package
or verify it's installed.
sudo yum install firewalld -y
Use firewalld to open only the ports needed for the app. In this case, port 80 and 443 are used. The following
commands permanently set ports 80 and 443 to open:
sudo firewall-cmd --add-port=80/tcp --permanent

sudo firewall-cmd --add-port=443/tcp --permanent
Reload the firewall settings. Check the available services and ports in the default zone. Options are available by
inspecting firewall-cmd -h .
sudo firewall-cmd --reload

sudo firewall-cmd --list-all
public (default, active)

interfaces: eth0
sources:
services: dhcpv6-client
ports: 443/tcp 80/tcp
masquerade: no
forward-ports:
icmp-blocks:
rich rules:
SSL configuration
To configure Apache for SSL, the mod_ssl module is used. When the httpd module was installed, the mod_ssl
module was also installed. If it wasn't installed, use yum to add it to the configuration.
sudo yum install mod_ssl
To enforce SSL, install the mod_rewrite module to enable URL rewriting:

sudo yum install mod_rewrite
Modify the hellomvc.conf file to enable URL rewriting and secure communication on port 443:
<VirtualHost *:*>
</VirtualHost>
<VirtualHost *:80>
RewriteEngine On
RewriteCond %{HTTPS} !=on
RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]
</VirtualHost>
<VirtualHost *:443>
ProxyPreserveHost On
ProxyPass / http://127.0.0.1:5000/
ErrorLog /var/log/httpd/hellomvc-error.log
CustomLog /var/log/httpd/hellomvc-access.log common
SSLEngine on
SSLProtocol all -SSLv2
SSLCipherSuite ALL:!ADH:!EXPORT:!SSLv2:!RC4+RSA:+HIGH:+MEDIUM:!LOW:!RC4
SSLCertificateFile /etc/pki/tls/certs/localhost.crt
SSLCertificateKeyFile /etc/pki/tls/private/localhost.key
</VirtualHost>
NOTE
This example is using a locally-generated certificate. SSLCertificateFile should be the primary certificate file for the domain
name. SSLCertificateKeyFile should be the key file generated when CSR is created. SSLCertificateChainFile should be
the intermediate certificate file (if any) that was supplied by the certificate authority.
Save the file and test the configuration:
sudo service httpd configtest
Restart Apache:
sudo systemctl restart httpd
Additional Apache suggestions

Additional headers
In order to secure against malicious attacks, there are a few headers that should either be modified or added.
Ensure that the mod_headers module is installed:
sudo yum install mod_headers
Secure Apache from clickjacking attacks

Clickjacking, also known as a UI redress attack, is a malicious attack where a website visitor is tricked into clicking
a link or button on a different page than they're currently visiting. Use X-FRAME-OPTIONS to secure the site.
Edit the httpd.conf file:
sudo nano /etc/httpd/conf/httpd.conf
Add the line Header append X-FRAME-OPTIONS "SAMEORIGIN" . Save the file. Restart Apache.
MIME-type sniffing
The X-Content-Type-Options header prevents Internet Explorer from MIME -sniffing (determining a file's
Content-Type from the file's content). If the server sets the Content-Type header to text/html with the nosniff
option set, Internet Explorer renders the content as text/html regardless of the file's content.
Edit the httpd.conf file:
sudo nano /etc/httpd/conf/httpd.conf
Add the line Header set X-Content-Type-Options "nosniff" . Save the file. Restart Apache.
Load Balancing
This example shows how to setup and configure Apache on CentOS 7 and Kestrel on the same instance machine.
In order to not have a single point of failure; using mod_proxy_balancer and modifying the VirtualHost would
allow for managing multiple instances of the web apps behind the Apache proxy server.
sudo yum install mod_proxy_balancer
In the configuration file shown below, an additional instance of the hellomvc app is setup to run on port 5001.
The Proxy section is set with a balancer configuration with two members to load balance byrequests.
<VirtualHost *:*>
</VirtualHost>
<VirtualHost *:80>
RewriteEngine On
RewriteCond %{HTTPS} !=on
RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]
</VirtualHost>
<VirtualHost *:443>
ProxyPass / balancer://mycluster/
<Proxy balancer://mycluster>
BalancerMember http://127.0.0.1:5000
BalancerMember http://127.0.0.1:5001
ProxySet lbmethod=byrequests
</Proxy>
<Location />
SetHandler balancer
</Location>
ErrorLog /var/log/httpd/hellomvc-error.log
CustomLog /var/log/httpd/hellomvc-access.log common
SSLEngine on
SSLProtocol all -SSLv2
SSLCipherSuite ALL:!ADH:!EXPORT:!SSLv2:!RC4+RSA:+HIGH:+MEDIUM:!LOW:!RC4
SSLCertificateFile /etc/pki/tls/certs/localhost.crt
SSLCertificateKeyFile /etc/pki/tls/private/localhost.key
</VirtualHost>
Rate Limits
Using mod_ratelimit, which is included in the httpd module, the bandwidth of clients can be limited:
sudo nano /etc/httpd/conf.d/ratelimit.conf
The example file limits bandwidth as 600 KB/sec under the root location:
<IfModule mod_ratelimit.c>
<Location />
SetOutputFilter RATE_LIMIT
SetEnv rate-limit 600
</Location>
</IfModule>
Host ASP.NET Core in Docker containers
The following articles are available for learning about hosting ASP.NET Core apps in Docker:
Introduction to Containers and Docker
See how containerization is an approach to software development in which an application or service, its
dependencies, and its configuration are packaged together as a container image. The image can be tested and then
deployed to a host.
What is Docker
Discover how Docker is an open-source project for automating the deployment of apps as portable, self-sufficient
containers that can run on the cloud or on-premises.
Docker Terminology
Learn terms and definitions for Docker technology.
Docker containers, images, and registries
Find out how Docker container images are stored in an image registry for consistent deployment across
environments.
Build Docker Images for .NET Core Applications
Learn how to build and dockerize an ASP.NET Core app. Explore Docker images maintained by Microsoft and
examine use cases.
Visual Studio Tools for Docker
Discover how Visual Studio 2017 supports building, debugging, and running ASP.NET Core apps targeting either
.NET Framework or .NET Core on Docker for Windows. Both Windows and Linux containers are supported.
Publish to a Docker Image
Find out how to use the Visual Studio Tools for Docker extension to deploy an ASP.NET Core app to a Docker host
on Azure using PowerShell.
Additional configuration might be required for apps hosted behind proxy servers and load balancers. Passing
requests through a proxy often obscures information about the original request, such as the scheme and client IP.
It might be necessary to forwarded some information about the request manually to the app.
Visual Studio Tools for Docker with ASP.NET Core
Visual Studio 2017 supports building, debugging, and running containerized ASP.NET Core apps targeting .NET
Core. Both Windows and Linux containers are supported.
Prerequisites
Docker for Windows
Visual Studio 2017 with the .NET Core cross-platform development workload
Installation and setup

For Docker installation, first review the information at Docker for Windows: What to know before you install. Next,
install Docker For Windows.
Shared Drives in Docker for Windows must be configured to support volume mapping and debugging. Right-
click the System Tray's Docker icon, select Settings, and select Shared Drives. Select the drive where Docker
stores files. Click Apply.
TIP
Visual Studio 2017 versions 15.6 and later prompt when Shared Drives aren't configured.
Add a project to a Docker container

To containerize an ASP.NET Core project, the project must target .NET Core. Both Linux and Windows containers
are supported.
When adding Docker support to a project, choose either a Windows or a Linux container. The Docker host must be
running the same container type. To change the container type in the running Docker instance, right-click the
System Tray's Docker icon and choose Switch to Windows containers... or Switch to Linux containers....
New app
When creating a new app with the ASP.NET Core Web Application project templates, select the Enable Docker
Support check box:
If the target framework is .NET Core, the OS drop-down allows for the selection of a container type.
Existing app
For ASP.NET Core projects targeting .NET Core, there are two options for adding Docker support via the tooling.
Open the project in Visual Studio, and choose one of the following options:
Select Docker Support from the Project menu.
Right-click the project in Solution Explorer and select Add > Docker Support.
The Visual Studio Tools for Docker don't support adding Docker to an existing ASP.NET Core project targeting
.NET Framework.
Dockerfile overview
A Dockerfile, the recipe for creating a final Docker image, is added to the project root. Refer to Dockerfile reference
for an understanding of the commands within it. This particular Dockerfile uses a multi-stage build with four
distinct, named build stages:
FROM microsoft/dotnet:2.1-aspnetcore-runtime AS base

WORKDIR /app
EXPOSE 59518
EXPOSE 44364
FROM microsoft/dotnet:2.1-sdk AS build

WORKDIR /src
COPY HelloDockerTools/HelloDockerTools.csproj HelloDockerTools/
RUN dotnet restore HelloDockerTools/HelloDockerTools.csproj
COPY . .
WORKDIR /src/HelloDockerTools
RUN dotnet build HelloDockerTools.csproj -c Release -o /app
FROM build AS publish

RUN dotnet publish HelloDockerTools.csproj -c Release -o /app
FROM base AS final

WORKDIR /app
COPY --from=publish /app .
ENTRYPOINT ["dotnet", "HelloDockerTools.dll"]
The preceding Dockerfile is based on the microsoft/dotnet image. This base image includes the ASP.NET Core
runtime and NuGet packages. The packages are just-in-time (JIT) compiled to improve startup performance.
When the new project dialog's Configure for HTTPS check box is checked, the Dockerfile exposes two ports. One
port is used for HTTP traffic; the other port is used for HTTPS. If the check box isn't checked, a single port (80) is
exposed for HTTP traffic.
FROM microsoft/aspnetcore:2.0 AS base

WORKDIR /app
EXPOSE 80
FROM microsoft/aspnetcore-build:2.0 AS build

WORKDIR /src
COPY HelloDockerTools/HelloDockerTools.csproj HelloDockerTools/
RUN dotnet restore HelloDockerTools/HelloDockerTools.csproj
COPY . .
WORKDIR /src/HelloDockerTools
RUN dotnet build HelloDockerTools.csproj -c Release -o /app
FROM build AS publish

RUN dotnet publish HelloDockerTools.csproj -c Release -o /app
FROM base AS final

WORKDIR /app
COPY --from=publish /app .
The preceding Dockerfile is based on the microsoft/aspnetcore image. This base image includes the ASP.NET Core
NuGet packages, which are just-in-time (JIT) compiled to improve startup performance.
Add container orchestrator support to an app

Visual Studio 2017 versions 15.7 or earlier support Docker Compose as the sole container orchestration solution.
The Docker Compose artifacts are added via Add > Docker Support.
Visual Studio 2017 versions 15.8 or later add an orchestration solution only when instructed. Right-click the
project in Solution Explorer and select Add > Container Orchestrator Support. Two different choices are
offered: Docker Compose and Service Fabric.
Docker Compose
The Visual Studio Tools for Docker add a docker-compose project to the solution with the following files:
docker-compose.dcproj – The file representing the project. Includes a <DockerTargetOS> element specifying the
OS to be used.
.dockerignore – Lists the file and directory patterns to exclude when generating a build context.
docker-compose.yml – The base Docker Compose file used to define the collection of images built and run with
docker-compose build and docker-compose run , respectively.
docker-compose.override.yml – An optional file, read by Docker Compose, with configuration overrides for
services. Visual Studio executes docker-compose -f "docker-compose.yml" -f "docker-compose.override.yml" to
merge these files.
The docker-compose.yml file references the name of the image that's created when the project runs:
version: '3.4'
services:
hellodockertools:
image: ${DOCKER_REGISTRY}hellodockertools
build:
context: .
dockerfile: HelloDockerTools/Dockerfile
In the preceding example, image: hellodockertools generates the image hellodockertools:dev when the app runs
in Debug mode. The hellodockertools:latest image is generated when the app runs in Release mode.
Prefix the image name with the Docker Hub username (for example, dockerhubusername/hellodockertools ) if the
image is pushed to the registry. Alternatively, change the image name to include the private registry URL (for
example, privateregistry.domain.com/hellodockertools ) depending on the configuration.
If you want different behavior based on the build configuration (for example, Debug or Release), add
configuration-specific docker-compose files. The files should be named according to the build configuration (for
example, docker-compose.vs.debug.yml and docker-compose.vs.release.yml) and placed in the same location as the
docker-compose-override.yml file.
Using the configuration-specific override files, you can specify different configuration settings (such as
environment variables or entry points) for Debug and Release build configurations.
Service Fabric
In addition to the base Prerequisites, the Service Fabric orchestration solution demands the following
prerequisites:
Microsoft Azure Service Fabric SDK version 2.6 or later
Visual Studio 2017's Azure Development workload
Service Fabric doesn't support running Linux containers in the local development cluster on Windows. If the
project is already using a Linux container, Visual Studio prompts to switch to Windows containers.
The Visual Studio Tools for Docker do the following tasks:
Adds a <project_name>Application Service Fabric Application project to the solution.
Adds a Dockerfile and a .dockerignore file to the ASP.NET Core project. If a Dockerfile already exists in the
ASP.NET Core project, it's renamed to Dockerfile.original. A new Dockerfile, similar to the following, is
created:
# See https://aka.ms/containerimagehelp for information on how to use Windows Server 1709 containers
with Service Fabric.
# FROM microsoft/aspnetcore:2.0-nanoserver-1709
FROM microsoft/aspnetcore:2.0-nanoserver-sac2016
ARG source
WORKDIR /app
COPY ${source:-obj/Docker/publish} .
Adds an <IsServiceFabricServiceProject> element to the ASP.NET Core project's .csproj file:
<IsServiceFabricServiceProject>True</IsServiceFabricServiceProject>
Adds a PackageRoot folder to the ASP.NET Core project. The folder includes the service manifest and
settings for the new service.
For more information, see Deploy a .NET app in a Windows container to Azure Service Fabric.
Debug
Select Docker from the debug drop-down in the toolbar, and start debugging the app. The Docker view of the
Output window shows the following actions taking place:
The 2.1 -aspnetcore-runtime tag of the microsoft/dotnet runtime image is acquired (if not already in the cache).
The image installs the ASP.NET Core and .NET Core runtimes and associated libraries. It's optimized for
running ASP.NET Core apps in production.
The ASPNETCORE_ENVIRONMENT environment variable is set to Development within the container.
Two dynamically assigned ports are exposed: one for HTTP and one for HTTPS. The port assigned to localhost
can be queried with the docker ps command.
The app is copied to the container.
The default browser is launched with the debugger attached to the container using the dynamically assigned
port.
The resulting Docker image of the app is tagged as dev. The image is based on the 2.1 -aspnetcore-runtime tag of
the microsoft/dotnet base image. Run the docker images command in the Package Manager Console (PMC )
window. The images on the machine are displayed:
REPOSITORY TAG IMAGE ID CREATED SIZE

hellodockertools dev d72ce0f1dfe7 30 seconds ago 255MB
microsoft/dotnet 2.1-aspnetcore-runtime fcc3887985bb 6 days ago 255MB
The microsoft/aspnetcore runtime image is acquired (if not already in the cache).
The ASPNETCORE_ENVIRONMENT environment variable is set to Development within the container.
Port 80 is exposed and mapped to a dynamically assigned port for localhost. The port is determined by the
Docker host and can be queried with the docker ps command.
The app is copied to the container.
The default browser is launched with the debugger attached to the container using the dynamically assigned
port.
The resulting Docker image of the app is tagged as dev. The image is based on the microsoft/aspnetcore base
image. Run the docker images command in the Package Manager Console (PMC ) window. The images on the
machine are displayed:

hellodockertools dev 5fafe5d1ad5b 4 minutes ago 347MB
microsoft/aspnetcore 2.0 c69d39472da9 13 days ago 347MB
NOTE
The dev image lacks the app contents, as Debug configurations use volume mounting to provide the iterative experience. To
push an image, use the Release configuration.
Run the docker ps command in PMC. Notice the app is running using the container:
CONTAINER ID IMAGE COMMAND CREATED STATUS

PORTS NAMES
baf9a678c88d hellodockertools:dev "C:\\remote_debugge..." 21 seconds ago Up 19 seconds
0.0.0.0:37630->80/tcp dockercompose4642749010770307127_hellodockertools_1
Edit and continue

Changes to static files and Razor views are automatically updated without the need for a compilation step. Make
the change, save, and refresh the browser to view the update.
Code file modifications require compilation and a restart of Kestrel within the container. After making the change,
use CTRL+F5 to perform the process and start the app within the container. The Docker container isn't rebuilt or
stopped. Run the docker ps command in PMC. Notice the original container is still running as of 10 minutes ago:
CONTAINER ID IMAGE COMMAND CREATED STATUS

PORTS NAMES
baf9a678c88d hellodockertools:dev "C:\\remote_debugge..." 10 minutes ago Up 10 minutes
0.0.0.0:37630->80/tcp dockercompose4642749010770307127_hellodockertools_1
Publish Docker images

Once the develop and debug cycle of the app is completed, the Visual Studio Tools for Docker assist in creating the
production image of the app. Change the configuration drop-down to Release and build the app. The tooling
acquires the compile/publish image from Docker Hub (if not already in the cache). An image is produced with the
latest tag, which can be pushed to the private registry or Docker Hub.
Run the docker images command in PMC to see the list of images. Output similar to the following is displayed:

hellodockertools latest e3984a64230c About a minute ago 258MB
hellodockertools dev d72ce0f1dfe7 4 minutes ago 255MB
microsoft/dotnet 2.1-sdk 9e243db15f91 6 days ago 1.7GB
microsoft/dotnet 2.1-aspnetcore-runtime fcc3887985bb 6 days ago 255MB

hellodockertools latest cd28f0d4abbd 12 seconds ago 349MB
hellodockertools dev 5fafe5d1ad5b 23 minutes ago 347MB
microsoft/aspnetcore-build 2.0 7fed40fbb647 13 days ago 2.02GB
microsoft/aspnetcore 2.0 c69d39472da9 13 days ago 347MB
The microsoft/aspnetcore-build and microsoft/aspnetcore images listed in the preceding output are replaced with
microsoft/dotnet images as of .NET Core 2.1. For more information, see the Docker repositories migration
announcement.
NOTE
The docker images command returns intermediary images with repository names and tags identified as <none> (not
listed above). These unnamed images are produced by the multi-stage build Dockerfile. They improve the efficiency of
building the final image—only the necessary layers are rebuilt when changes occur. When the intermediary images are no
longer needed, delete them using the docker rmi command.
There may be an expectation for the production or release image to be smaller in size by comparison to the dev
image. Because of the volume mapping, the debugger and app were running from the local machine and not
within the container. The latest image has packaged the necessary app code to run the app on a host machine.
Therefore, the delta is the size of the app code.
Container development with Visual Studio
Azure Service Fabric: Prepare your development environment
Deploy a .NET app in a Windows container to Azure Service Fabric
Troubleshoot Visual Studio 2017 development with Docker
Visual Studio Tools for Docker GitHub repository
Configure ASP.NET Core to work with proxy servers
and load balancers
By Luke Latham and Chris Ross

In the recommended configuration for ASP.NET Core, the app is hosted using IIS/ASP.NET Core Module,
Nginx, or Apache. Proxy servers, load balancers, and other network appliances often obscure information
about the request before it reaches the app:
When HTTPS requests are proxied over HTTP, the original scheme (HTTPS ) is lost and must be forwarded
in a header.
Because an app receives a request from the proxy and not its true source on the Internet or corporate
network, the originating client IP address must also be forwarded in a header.
This information may be important in request processing, for example in redirects, authentication, link
generation, policy evaluation, and client geolocation.
Forwarded headers
By convention, proxies forward information in HTTP headers.
HEADER DESCRIPTION
X-Forwarded-For Holds information about the client that initiated the request
and subsequent proxies in a chain of proxies. This parameter
may contain IP addresses (and, optionally, port numbers). In
a chain of proxy servers, the first parameter indicates the
client where the request was first made. Subsequent proxy
identifiers follow. The last proxy in the chain isn't in the list of
parameters. The last proxy's IP address, and optionally a
port number, are available as the remote IP address at the
transport layer.
X-Forwarded-Proto The value of the originating scheme (HTTP/HTTPS). The

value may also be a list of schemes if the request has
traversed multiple proxies.
X-Forwarded-Host The original value of the Host header field. Usually, proxies
don't modify the Host header. See Microsoft Security
Advisory CVE-2018-0787 for information on an elevation-
of-privileges vulnerability that affects systems where the
proxy doesn't validate or restict Host headers to known
good values.
The Forwarded Headers Middleware, from the Microsoft.AspNetCore.HttpOverrides package, reads these
headers and fills in the associated fields on HttpContext.
The middleware updates:
HttpContext.Connection.RemoteIpAddress – Set using the X-Forwarded-For header value. Additional
settings influence how the middleware sets RemoteIpAddress . For details, see the Forwarded Headers
Middleware options.
HttpContext.Request.Scheme – Set using the X-Forwarded-Proto header value.
HttpContext.Request.Host – Set using the X-Forwarded-Host header value.
Forwarded Headers Middleware default settings can be configured. The default settings are:
There is only one proxy between the app and the source of the requests.
Only loopback addresses are configured for known proxies and known networks.
The forwarded headers are named X-Forwarded-For and X-Forwarded-Proto .
Not all network appliances add the X-Forwarded-For and X-Forwarded-Proto headers without additional
configuration. Consult your appliance manufacturer's guidance if proxied requests don't contain these headers
when they reach the app. If the appliance uses different header names than X-Forwarded-For and
X-Forwarded-Proto , set the ForwardedForHeaderName and ForwardedProtoHeaderName options to match
the header names used by the appliance. For more information, see Forwarded Headers Middleware options
and Configuration for a proxy that uses different header names.
IIS/IIS Express and ASP.NET Core Module

Forwarded Headers Middleware is enabled by default by IIS Integration Middleware when the app is run
behind IIS and the ASP.NET Core Module. Forwarded Headers Middleware is activated to run first in the
middleware pipeline with a restricted configuration specific to the ASP.NET Core Module due to trust concerns
with forwarded headers (for example, IP spoofing). The middleware is configured to forward the
X-Forwarded-For and X-Forwarded-Proto headers and is restricted to a single localhost proxy. If additional
configuration is required, see the Forwarded Headers Middleware options.
Other proxy server and load balancer scenarios

Outside of using IIS Integration Middleware, Forwarded Headers Middleware isn't enabled by default.
Forwarded Headers Middleware must be enabled for an app to process forwarded headers with
UseForwardedHeaders. After enabling the middleware if no ForwardedHeadersOptions are specified to the
middleware, the default ForwardedHeadersOptions.ForwardedHeaders are ForwardedHeaders.None.
Configure the middleware with ForwardedHeadersOptions to forward the X-Forwarded-For and
X-Forwarded-Proto headers in Startup.ConfigureServices . Invoke the UseForwardedHeaders method in
Startup.Configure before calling other middleware:
{
services.AddMvc();
{
options.ForwardedHeaders =
ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
});
}

{
app.UseForwardedHeaders();
{
}
else
{
}
// In ASP.NET Core 1.x, replace the following line with: app.UseIdentity();
app.UseMvc();
}
NOTE
If no ForwardedHeadersOptions are specified in Startup.ConfigureServices or directly to the extension method with
UseForwardedHeaders(IApplicationBuilder, ForwardedHeadersOptions), the default headers to forward are
ForwardedHeaders.None. The ForwardedHeadersOptions.ForwardedHeaders property must be configured with the
headers to forward.
Nginx configuration
To forward the X-Forwarded-For and X-Forwarded-Proto headers, see Host ASP.NET Core on Linux with Nginx.
For more information, see NGINX: Using the Forwarded header.
Apache configuration
X-Forwarded-For is added automatically (see Apache Module mod_proxy: Reverse Proxy Request Headers). For
information on how to forward the X-Forwarded-Proto header, see Host ASP.NET Core on Linux with Apache.
Forwarded Headers Middleware options

ForwardedHeadersOptions control the behavior of the Forwarded Headers Middleware. The following
example changes the default values:
Limit the number of entries in the forwarded headers to 2 .
Add a known proxy address of 127.0.10.1 .
Change the forwarded header name from the default X-Forwarded-For to
X-Forwarded-For-My-Custom-Header-Name .
{
options.ForwardLimit = 2;
options.ForwardedForHeaderName = "X-Forwarded-For-My-Custom-Header-Name";
});
OPTION DESCRIPTION
AllowedHosts Restricts hosts by the X-Forwarded-Host header to the

values provided.
Values are compared using ordinal-ignore-case.
Port numbers must be excluded.
If the list is empty, all hosts are allowed.
A top-level wildcard * allows all non-empty hosts.
Subdomain wildcards are permitted but don't match
the root domain. For example, *.contoso.com
matches the subdomain foo.contoso.com but not
the root domain contoso.com .
Unicode host names are allowed but are converted
to Punycode for matching.
IPv6 addresses must include bounding brackets and
be in conventional form (for example,
[ABCD:EF01:2345:6789:ABCD:EF01:2345:6789] ).
IPv6 addresses aren't special-cased to check for
logical equality between different formats, and no
canonicalization is performed.
Failure to restrict the allowed hosts may allow an
attacker to spoof links generated by the service.
The default value is an empty IList<string>.
ForwardedForHeaderName Use the header specified by this property instead of the one
specified by
ForwardedHeadersDefaults.XForwardedForHeaderName.
This option is used when the proxy/forwarder doesn't use
the X-Forwarded-For header but uses some other header
to forward the information.
The default is X-Forwarded-For .
ForwardedHeaders Identifies which forwarders should be processed. See the

ForwardedHeaders Enum for the list of fields that apply.
Typical values assigned to this property are
ForwardedHeaders.XForwardedFor |
ForwardedHeaders.XForwardedProto
.
The default value is ForwardedHeaders.None.
ForwardedHostHeaderName Use the header specified by this property instead of the one
specified by
ForwardedHeadersDefaults.XForwardedHostHeaderName.
the X-Forwarded-Host header but uses some other
header to forward the information.
The default is X-Forwarded-Host .

OPTION DESCRIPTION
ForwardedProtoHeaderName Use the header specified by this property instead of the one
specified by
ForwardedHeadersDefaults.XForwardedProtoHeaderName.
the X-Forwarded-Proto header but uses some other
The default is X-Forwarded-Proto .
ForwardLimit Limits the number of entries in the headers that are

processed. Set to null to disable the limit, but this should
only be done if KnownProxies or KnownNetworks are
configured.
The default is 1.
KnownNetworks Address ranges of known networks to accept forwarded

headers from. Provide IP ranges using Classless Interdomain
Routing (CIDR) notation.
If the server is using dual-mode sockets, IPv4 addresses are

supplied in an IPv6 format (for example, 10.0.0.1 in IPv4
represented in IPv6 as ::ffff:10.0.0.1 ). See
IPAddress.MapToIPv6. Determine if this format is required
by looking at the
HttpContext.Connection.RemoteIpAddress. For more
information, see the Configuration for an IPv4 address
represented as an IPv6 address section.
The default is an IList<IPNetwork> containing a single entry

for IPAddress.Loopback .
KnownProxies Addresses of known proxies to accept forwarded headers

from. Use KnownProxies to specify exact IP address
matches.

by looking at the
The default is an IList<IPAddress> containing a single entry

for IPAddress.IPv6Loopback .
OriginalForHeaderName Use the header specified by this property instead of the one
specified by
ForwardedHeadersDefaults.XOriginalForHeaderName.
The default is X-Original-For .

OPTION DESCRIPTION
OriginalHostHeaderName Use the header specified by this property instead of the one
specified by
ForwardedHeadersDefaults.XOriginalHostHeaderName.
The default is X-Original-Host .
OriginalProtoHeaderName Use the header specified by this property instead of the one
specified by
ForwardedHeadersDefaults.XOriginalProtoHeaderName.
The default is X-Original-Proto .
RequireHeaderSymmetry Require the number of header values to be in sync between

the ForwardedHeadersOptions.ForwardedHeaders being
processed.
The default in ASP.NET Core 1.x is true . The default in

ASP.NET Core 2.0 or later is false .
OPTION DESCRIPTION
ForwardedForHeaderName Use the header specified by this property instead of the one
specified by
ForwardedHeadersDefaults.XForwardedForHeaderName.
the X-Forwarded-For header but uses some other header
to forward the information.
The default is X-Forwarded-For .
ForwardedHeaders Identifies which forwarders should be processed. See the

ForwardedHeaders Enum for the list of fields that apply.
Typical values assigned to this property are
ForwardedHeaders.XForwardedFor |
ForwardedHeaders.XForwardedProto
.
The default value is ForwardedHeaders.None.
ForwardedHostHeaderName Use the header specified by this property instead of the one
specified by
ForwardedHeadersDefaults.XForwardedHostHeaderName.
the X-Forwarded-Host header but uses some other
The default is X-Forwarded-Host .
ForwardedProtoHeaderName Use the header specified by this property instead of the one
specified by
ForwardedHeadersDefaults.XForwardedProtoHeaderName.
the X-Forwarded-Proto header but uses some other
The default is X-Forwarded-Proto .

OPTION DESCRIPTION
ForwardLimit Limits the number of entries in the headers that are

processed. Set to null to disable the limit, but this should
only be done if KnownProxies or KnownNetworks are
configured.
The default is 1.
KnownNetworks Address ranges of known networks to accept forwarded

headers from. Provide IP ranges using Classless Interdomain
Routing (CIDR) notation.

by looking at the
The default is an IList<IPNetwork> containing a single entry

for IPAddress.Loopback .
KnownProxies Addresses of known proxies to accept forwarded headers

from. Use KnownProxies to specify exact IP address
matches.

by looking at the
The default is an IList<IPAddress> containing a single entry

for IPAddress.IPv6Loopback .
OriginalForHeaderName Use the header specified by this property instead of the one
specified by
ForwardedHeadersDefaults.XOriginalForHeaderName.
The default is X-Original-For .
OriginalHostHeaderName Use the header specified by this property instead of the one
specified by
ForwardedHeadersDefaults.XOriginalHostHeaderName.
The default is X-Original-Host .
OriginalProtoHeaderName Use the header specified by this property instead of the one
specified by
ForwardedHeadersDefaults.XOriginalProtoHeaderName.
The default is X-Original-Proto .

OPTION DESCRIPTION
RequireHeaderSymmetry Require the number of header values to be in sync between

the ForwardedHeadersOptions.ForwardedHeaders being
processed.
The default in ASP.NET Core 1.x is true . The default in

ASP.NET Core 2.0 or later is false .
Scenarios and use cases

When it isn't possible to add forwarded headers and all requests are secure
In some cases, it might not be possible to add forwarded headers to the requests proxied to the app. If the
proxy is enforcing that all public external requests are HTTPS, the scheme can be manually set in
Startup.Configure before using any type of middleware:

{
context.Request.Scheme = "https";
return next();
});
This code can be disabled with an environment variable or other configuration setting in a development or
staging environment.
Deal with path base and proxies that change the request path
Some proxies pass the path intact but with an app base path that should be removed so that routing works
properly. UsePathBaseExtensions.UsePathBase middleware splits the path into HttpRequest.Path and the app
base path into HttpRequest.PathBase.
If /foo is the app base path for a proxy path passed as /foo/api/1 , the middleware sets Request.PathBase to
/foo and Request.Path to /api/1 with the following command:
app.UsePathBase("/foo");
The original path and path base are reapplied when the middleware is called again in reverse. For more
information on middleware order processing, see ASP.NET Core Middleware.
If the proxy trims the path (for example, forwarding /foo/api/1 to /api/1 ), fix redirects and links by setting
the request's PathBase property:

{
context.Request.PathBase = new PathString("/foo");
return next();
});
If the proxy is adding path data, discard part of the path to fix redirects and links by using
StartsWithSegments(PathString, PathString) and assigning to the Path property:
{
if (context.Request.Path.StartsWithSegments("/foo", out var remainder))
{
context.Request.Path = remainder;
}
return next();
});
Configuration for a proxy that uses different header names

If the proxy doesn't use headers named X-Forwarded-For and X-Forwarded-Proto to forward the proxy
address/port and originating scheme information, set the ForwardedForHeaderName and
ForwardedProtoHeaderName options to match the header names used by the proxy:
{
options.ForwardedForHeaderName = "Header_Name_Used_By_Proxy_For_X-Forwarded-For_Header";
options.ForwardedProtoHeaderName = "Header_Name_Used_By_Proxy_For_X-Forwarded-Proto_Header";
});
Configuration for an IPv4 address represented as an IPv6 address

If the server is using dual-mode sockets, IPv4 addresses are supplied in an IPv6 format (for example, 10.0.0.1
in IPv4 represented in IPv6 as ::ffff:10.0.0.1 or ::ffff:a00:1 ). See IPAddress.MapToIPv6. Determine if this
format is required by looking at the HttpContext.Connection.RemoteIpAddress.
In the following example, a network address that supplies forwarded headers is added to the KnownNetworks
list in IPv6 format.
IPv4 address: 10.11.12.1/8
Converted IPv6 address: ::ffff:10.11.12.1

Converted prefix length: 104
You can also supply the address in hexadecimal format ( 10.11.12.1 represented in IPv6 as ::ffff:0a0b:0c01 ).
When converting an IPv4 address to IPv6, add 96 to the CIDR Prefix Length ( 8 in the example) to account for
the additional ::ffff: IPv6 prefix (8 + 96 = 104).
// To access IPNetwork and IPAddress, add the following namespaces:

// using using System.Net;
// using Microsoft.AspNetCore.HttpOverrides;
{
options.ForwardedHeaders =
ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
options.KnownNetworks.Add(new IPNetwork(
IPAddress.Parse("::ffff:10.11.12.1"), 104));
});
Troubleshoot
When headers aren't forwarded as expected, enable logging. If the logs don't provide sufficient information to
troubleshoot the problem, enumerate the request headers received by the server. Use inline middleware to
write request headers to an app response or log the headers. Place either of the following code examples
immediately after the call to UseForwardedHeaders in Startup.Configure .
To write the headers to the app's response, use the following terminal inline middleware:

{
context.Response.ContentType = "text/plain";
// Request method, scheme, and path

$"Request Method: {context.Request.Method}{Environment.NewLine}");
$"Request Scheme: {context.Request.Scheme}{Environment.NewLine}");
$"Request Path: {context.Request.Path}{Environment.NewLine}");
// Headers
await context.Response.WriteAsync($"Request Headers:{Environment.NewLine}");
foreach (var header in context.Request.Headers)

{
await context.Response.WriteAsync($"{header.Key}: " +
$"{header.Value}{Environment.NewLine}");
}
await context.Response.WriteAsync(Environment.NewLine);
// Connection: RemoteIp
$"Request RemoteIp: {context.Connection.RemoteIpAddress}");
});
You can also write to logs instead of the response body by using the following inline middleware. This allows
the site to function normally while debugging.
var logger = _loggerFactory.CreateLogger<Startup>();

{
// Request method, scheme, and path
logger.LogDebug("Request Method: {METHOD}", context.Request.Method);
logger.LogDebug("Request Scheme: {SCHEME}", context.Request.Scheme);
logger.LogDebug("Request Path: {PATH}", context.Request.Path);
// Headers
foreach (var header in context.Request.Headers)
{
logger.LogDebug("Header: {KEY}: {VALUE}", header.Key, header.Value);
}
// Connection: RemoteIp
logger.LogDebug("Request RemoteIp: {REMOTE_IP_ADDRESS}",
context.Connection.RemoteIpAddress);
await next();
});
When processed, X-Forwarded-{For|Proto|Host} values are moved to X-Original-{For|Proto|Host} . If there are

multiple values in a given header, note Forwarded Headers Middleware processes headers in reverse order
from right to left. The default ForwardLimit is 1 (one), so only the rightmost value from the headers is
processed unless the value of ForwardLimit is increased.
The request's original remote IP must match an entry in the KnownProxies or KnownNetworks lists before
forwarded headers are processed. This limits header spoofing by not accepting forwarders from untrusted
proxies. When an unknown proxy is detected, logging indicates the address of the proxy:
September 20th 2018, 15:49:44.168 Unknown proxy: 10.0.0.100:54321
In the preceding example, 10.0.0.100 is a proxy server. If the server is a trusted proxy, add the server's IP
address to KnownProxies (or add a trusted network to KnownNetworks ) in Startup.ConfigureServices . For more
information, see the Forwarded Headers Middleware options section.
{
});
IMPORTANT
Only allow trusted proxies and networks to forward headers. Otherwise, IP spoofing attacks are possible.
Microsoft Security Advisory CVE -2018-0787: ASP.NET Core Elevation Of Privilege Vulnerability
By Luke Latham and Chris Ross

A web farm is a group of two or more web servers (or nodes) that host multiple instances of an app. When
requests from users arrive to a web farm, a load balancer distributes the requests to the web farm's nodes. Web
farms improve:
Reliability/availability – When one or more nodes fail, the load balancer can route requests to other
functioning nodes to continue processing requests.
Capacity/performance – Multiple nodes can process more requests than a single server. The load balancer
balances the workload by distributing requests to the nodes.
Scalability – When more or less capacity is required, the number of active nodes can be increased or
decreased to match the workload. Web farm platform technologies, such as Azure App Service, can
automatically add or remove nodes at the request of the system administrator or automatically without
human intervention.
Maintainability – Nodes of a web farm can rely on a set of shared services, which results in easier system
management. For example, the nodes of a web farm can rely upon a single database server and a common
network location for static resources, such as images and downloadable files.
This topic describes configuration and dependencies for ASP.NET core apps hosted in a web farm that rely upon
shared resources.
General configuration
Host and deploy ASP.NET Core
Learn how to set up hosting environments and deploy ASP.NET Core apps. Configure a process manager on
each node of the web farm to automate app starts and restarts. Each node requires the ASP.NET Core runtime.
For more information, see the topics in the Host and deploy area of the documentation.
Learn about configuration for apps hosted behind proxy servers and load balancers, which often obscure
important request information.
Azure App Service is a Microsoft cloud computing platform service for hosting web apps, including ASP.NET
Core. App Service is a fully managed platform that provides automatic scaling, load balancing, patching, and
continuous deployment.
App data
When an app is scaled to multiple instances, there might be app state that requires sharing across nodes. If the
state is transient, consider sharing an IDistributedCache. If the shared state requires persistence, consider storing
the shared state in a database.
Required configuration
Data Protection and Caching require configuration for apps deployed to a web farm.
Data Protection
The ASP.NET Core Data Protection system is used by apps to protect data. Data Protection relies upon a set of
cryptographic keys stored in a key ring. When the Data Protection system is initialized, it applies default settings
that store the key ring locally. Under the default configuration, a unique key ring is stored on each node of the
web farm. Consequently, each web farm node can't decrypt data that's encrypted by an app on any other node.
The default configuration isn't generally appropriate for hosting apps in a web farm. An alternative to
implementing a shared key ring is to always route user requests to the same node. For more information on
Data Protection system configuration for web farm deployments, see Configure ASP.NET Core Data Protection.
Caching
In a web farm environment, the caching mechanism must share cached items across the web farm's nodes.
Caching must either rely upon a common Redis cache, a shared SQL Server database, or a custom caching
implementation that shares cached items across the web farm. For more information, see Work with a
distributed cache in ASP.NET Core.
Dependent components
The following scenarios don't require additional configuration, but they depend on technologies that require
configuration for web farms.
SCENARIO DEPENDS ON …
Authentication Data Protection (see Configure ASP.NET Core Data

Protection).
For more information, see Use cookie authentication without

ASP.NET Core Identity and Share cookies among apps with
ASP.NET and ASP.NET Core.
Identity Authentication and database configuration.
For more information, see Introduction to Identity on

ASP.NET Core.
Session Data Protection (encrypted cookies) (see Configure ASP.NET

Core Data Protection) and Caching (see Work with a
distributed cache in ASP.NET Core).
For more information, see Session and app state: Session

state.
TempData Data Protection (encrypted cookies) (see Configure ASP.NET

Core Data Protection) or Session (see Session and app state:
Session state).
For more information, see Session and app state: TempData.
Anti-forgery Data Protection (see Configure ASP.NET Core Data

Protection).
For more information, see Prevent Cross-Site Request

Forgery (XSRF/CSRF) attacks in ASP.NET Core.
Troubleshoot
When Data Protection or Caching isn't configured for a web farm environment, intermittent errors occur when
requests are processed. This occurs because nodes don't share the same resources and user requests aren't
always routed back to the same node.
Consider a user who signs into the app using cookie authentication. The user signs into the app on one web farm
node. If their next request arrives at the same node where they signed in, the app is able to decrypt the
authentication cookie and allows access to the app's resource. If their next request arrives at a different node, the
app can't decrypt the authentication cookie from the node where the user signed in, and authorization for the
requested resource fails.
When any of the following symptoms occur intermittently, the problem is usually traced to improper Data
Protection or Caching configuration for a web farm environment:
Authentication breaks – The authentication cookie is misconfigured or can't be decrypted. OAuth (Facebook,
Microsoft, Twitter) or OpenIdConnect logins fail with the error "Correlation failed."
Authorization breaks – Identity is lost.
Session state loses data.
Cached items disappear.
TempData fails.
POSTs fail – The anti-forgery check fails.
For more information on Data Protection configuration for web farm deployments, see Configure ASP.NET Core
Data Protection. For more information on Caching configuration for web farm deployments, see Work with a
distributed cache in ASP.NET Core.
Visual Studio publish profiles for ASP.NET Core app
deployment
By Sayed Ibrahim Hashimi and Rick Anderson

This document focuses on using Visual Studio 2017 to create and use publish profiles. The publish profiles created
with Visual Studio can be run from MSBuild and Visual Studio 2017. See Publish an ASP.NET Core web app to
Azure App Service using Visual Studio for instructions on publishing to Azure.
The following project file was created with the command dotnet new mvc :
ASP.NET Core 2.x
ASP.NET Core 1.x
<PropertyGroup>
</PropertyGroup>
<ItemGroup>
</ItemGroup>
<ItemGroup>
</ItemGroup>
</Project>
The <Project> element's Sdk attribute accomplishes the following tasks:

Imports the properties file from $ (MSBuildSDKsPath)\Microsoft.NET.Sdk.Web\Sdk\Sdk.Props at the beginning.
Imports the targets file from $ (MSBuildSDKsPath)\Microsoft.NET.Sdk.Web\Sdk\Sdk.targets at the end.
The default location for MSBuildSDKsPath (with Visual Studio 2017 Enterprise) is the
%programfiles(x86 )%\Microsoft Visual Studio\2017\Enterprise\MSBuild\Sdks folder.
The Microsoft.NET.Sdk.Web SDK depends on:
Microsoft.NET.Sdk.Web.ProjectSystem
Microsoft.NET.Sdk.Publish
Which causes the following properties and targets to be imported:
$ (MSBuildSDKsPath)\Microsoft.NET.Sdk.Web.ProjectSystem\Sdk\Sdk.Props
$ (MSBuildSDKsPath)\Microsoft.NET.Sdk.Web.ProjectSystem\Sdk\Sdk.targets
$ (MSBuildSDKsPath)\Microsoft.NET.Sdk.Publish\Sdk\Sdk.Props
$ (MSBuildSDKsPath)\Microsoft.NET.Sdk.Publish\Sdk\Sdk.targets
Publish targets import the right set of targets based on the publish method used.
When MSBuild or Visual Studio loads a project, the following high-level actions occur:
Build project
Compute files to publish
Publish files to destination
Compute project items

When the project is loaded, the project items (files) are computed. The item type attribute determines how the
file is processed. By default, .cs files are included in the Compile item list. Files in the Compile item list are
compiled.
The Content item list contains files that are published in addition to the build outputs. By default, files matching
the pattern wwwroot/** are included in the Content item. The wwwroot/\*\* globbing pattern matches all files in
the wwwroot folder and subfolders. To explicitly add a file to the publish list, add the file directly in the .csproj file
as shown in Include Files.
When selecting the Publish button in Visual Studio or when publishing from the command line:
The properties/items are computed (the files that are needed to build).
Visual Studio only: NuGet packages are restored. (Restore needs to be explicit by the user on the CLI.)
The project builds.
The publish items are computed (the files that are needed to publish).
The project is published (the computed files are copied to the publish destination).
When an ASP.NET Core project references Microsoft.NET.Sdk.Web in the project file, an app_offline.htm file is
placed at the root of the web app directory. When the file is present, the ASP.NET Core Module gracefully shuts
down the app and serves the app_offline.htm file during the deployment. For more information, see the ASP.NET
Core Module configuration reference.
Basic command-line publishing

Command-line publishing works on all .NET Core-supported platforms and doesn't require Visual Studio. In the
samples below, the dotnet publish command is run from the project directory (which contains the .csproj file). If
not in the project folder, explicitly pass in the project file path. For example:
dotnet publish C:\Webs\Web1
Run the following commands to create and publish a web app:

ASP.NET Core 2.x
ASP.NET Core 1.x
dotnet new mvc

dotnet publish
The dotnet publish command produces output similar to the following:
C:\Webs\Web1>dotnet publish
Microsoft (R) Build Engine version 15.3.409.57025 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.
Web1 -> C:\Webs\Web1\bin\Debug\netcoreapp2.0\Web1.dll

Web1 -> C:\Webs\Web1\bin\Debug\netcoreapp2.0\publish\
The default publish folder is bin\$(Configuration)\netcoreapp<version>\publish . The default for $(Configuration)
is Debug. In the preceding sample, the <TargetFramework> is netcoreapp2.0 .
dotnet publish -h displays help information for publish.
The following command specifies a Release build and the publishing directory:
dotnet publish -c Release -o C:\MyWebs\test
The dotnet publish command calls MSBuild, which invokes the Publish target. Any parameters passed to
dotnet publish are passed to MSBuild. The -c parameter maps to the Configuration MSBuild property. The
-o parameter maps to OutputPath .
MSBuild properties can be passed using either of the following formats:

p:<NAME>=<VALUE>
/p:<NAME>=<VALUE>
The following command publishes a Release build to a network share:

dotnet publish -c Release /p:PublishDir=//r8/release/AdminWeb
The network share is specified with forward slashes ( //r8/) and works on all .NET Core supported platforms.
Confirm that the published app for deployment isn't running. Files in the publish folder are locked when the app is
running. Deployment can't occur because locked files can't be copied.
Publish profiles
This section uses Visual Studio 2017 to create a publishing profile. Once created, publishing from Visual Studio or
the command line is available.
Publish profiles can simplify the publishing process, and any number of profiles can exist. Create a publish profile
in Visual Studio by choosing one of the following paths:
Right-click the project in Solution Explorer and select Publish.
Select Publish <project_name> from the Build menu.
The Publish tab of the app capacities page is displayed. If the project lacks a publish profile, the following page is
displayed:
When Folder is selected, specify a folder path to store the published assets. The default folder is
bin\Release\PublishOutput. Click the Create Profile button to finish.
Once a publish profile is created, the Publish tab changes. The newly created profile appears in a drop-down list.
Click Create new profile to create another new profile.
The Publish wizard supports the following publish targets:
Azure App Service
Azure Virtual Machines
IIS, FTP, etc. (for any web server)
Folder
Import Profile
For more information, see What publishing options are right for me.
When creating a publish profile with Visual Studio, a Properties/PublishProfiles/<profile_name>.pubxml MSBuild
file is created. The .pubxml file is a MSBuild file and contains publish configuration settings. This file can be
changed to customize the build and publish process. This file is read by the publishing process.
<LastUsedBuildConfiguration> is special because it's a global property and shouldn't be in any file that's imported
in the build. See MSBuild: how to set the configuration property for more information.
When publishing to an Azure target, the .pubxml file contains your Azure subscription identifier. With that target
type, adding this file to source control is discouraged. When publishing to a non-Azure target, it's safe to check in
the .pubxml file.
Sensitive information (like the publish password) is encrypted on a per user/machine level. It's stored in the
Properties/PublishProfiles/<profile_name>.pubxml.user file. Because this file can store sensitive information, it
shouldn't be checked into source control.
For an overview of how to publish a web app on ASP.NET Core, see Host and deploy. The MSBuild tasks and
targets necessary to publish an ASP.NET Core app are open-source at https://github.com/aspnet/websdk.
dotnet publish can use folder, MSDeploy, and Kudu publish profiles:
Folder (works cross-platform):
dotnet publish WebApplication.csproj /p:PublishProfile=<FolderProfileName>
MSDeploy (currently this only works in Windows since MSDeploy isn't cross-platform):
dotnet publish WebApplication.csproj /p:PublishProfile=<MsDeployProfileName> /p:Password=<DeploymentPassword>
MSDeploy package (currently this only works in Windows since MSDeploy isn't cross-platform):
dotnet publish WebApplication.csproj /p:PublishProfile=<MsDeployPackageProfileName>
In the preceding samples, don't pass deployonbuild to dotnet publish .

For more information, see Microsoft.NET.Sdk.Publish.
dotnet publish supports Kudu APIs to publish to Azure from any platform. Visual Studio publish supports the
Kudu APIs, but it's supported by WebSDK for cross-platform publish to Azure.
Add a publish profile to the Properties/PublishProfiles folder with the following content:
<Project>
<PropertyGroup>
<PublishProtocol>Kudu</PublishProtocol>
<PublishSiteName>nodewebapp</PublishSiteName>
<UserName>username</UserName>
<Password>password</Password>
</PropertyGroup>
</Project>
Run the following command to zip up the publish contents and publish it to Azure using the Kudu APIs:
dotnet publish /p:PublishProfile=Azure /p:Configuration=Release
Set the following MSBuild properties when using a publish profile:

DeployOnBuild=true
PublishProfile=<Publish profile name>
When publishing with a profile named FolderProfile, either of the commands below can be executed:
dotnet build /p:DeployOnBuild=true /p:PublishProfile=FolderProfile
msbuild /p:DeployOnBuild=true /p:PublishProfile=FolderProfile
When invoking dotnet build, it calls msbuild to run the build and publish process. Calling either dotnet build or
msbuild is equivalent when passing in a folder profile. When calling MSBuild directly on Windows, the .NET
Framework version of MSBuild is used. MSDeploy is currently limited to Windows machines for publishing.
Calling dotnet build on a non-folder profile invokes MSBuild, and MSBuild uses MSDeploy on non-folder
profiles. Calling dotnet build on a non-folder profile invokes MSBuild (using MSDeploy) and results in a failure
(even when running on a Windows platform). To publish with a non-folder profile, call MSBuild directly.
The following folder publish profile was created with Visual Studio and publishes to a network share:

<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<WebPublishMethod>FileSystem</WebPublishMethod>
<PublishProvider>FileSystem</PublishProvider>
<LastUsedBuildConfiguration>Release</LastUsedBuildConfiguration>
<LastUsedPlatform>Any CPU</LastUsedPlatform>
<SiteUrlToLaunchAfterPublish />
<LaunchSiteAfterPublish>True</LaunchSiteAfterPublish>
<ExcludeApp_Data>False</ExcludeApp_Data>
<PublishFramework>netcoreapp1.1</PublishFramework>
<ProjectGuid>c30c453c-312e-40c4-aec9-394a145dee0b</ProjectGuid>
<publishUrl>\\r8\Release\AdminWeb</publishUrl>
<DeleteExistingFiles>False</DeleteExistingFiles>
</PropertyGroup>
</Project>
Note <LastUsedBuildConfiguration> is set to Release . When publishing from Visual Studio, the
<LastUsedBuildConfiguration> configuration property value is set using the value when the publish process is
started. The <LastUsedBuildConfiguration> configuration property is special and shouldn't be overridden in an
imported MSBuild file. This property can be overridden from the command line.
Using the .NET Core CLI:
dotnet build -c Release /p:DeployOnBuild=true /p:PublishProfile=FolderProfile
Using MSBuild:
msbuild /p:Configuration=Release /p:DeployOnBuild=true /p:PublishProfile=FolderProfile
Publish to an MSDeploy endpoint from the command line

Publishing can be accomplished using the .NET Core CLI or MSBuild. dotnet publish runs in the context of .NET
Core. The msbuild command requires .NET Framework, which limits it to Windows environments.
The easiest way to publish with MSDeploy is to first create a publish profile in Visual Studio 2017 and use the
profile from the command line.
In the following sample, an ASP.NET Core web app is created (using dotnet new mvc ), and an Azure publish
profile is added with Visual Studio.
Run msbuild from a Developer Command Prompt for VS 2017. The Developer Command Prompt has the
correct msbuild.exe in its path with some MSBuild variables set.
MSBuild uses the following syntax:
msbuild <path-to-project-file> /p:DeployOnBuild=true /p:PublishProfile=<Publish Profile> /p:Username=

<USERNAME> /p:Password=<PASSWORD>
Get the Password from the <Publish name>.PublishSettings file. Download the .PublishSettings file from either:
Solution Explorer: Right-click on the Web App and select Download Publish Profile.
Azure portal: Click Get publish profile on the Web App's Overview panel.
Username can be found in the publish profile.
The following sample uses the Web11112 - Web Deploy publish profile:
msbuild "C:\Webs\Web1\Web1.csproj" /p:DeployOnBuild=true

/p:PublishProfile="Web11112 - Web Deploy" /p:Username="$Web11112"
/p:Password="<password removed>"
Exclude files
When publishing ASP.NET Core web apps, the build artifacts and contents of the wwwroot folder are included.
msbuild supports globbing patterns. For example, the following <Content> element excludes all text (.txt) files
from the wwwroot/content folder and all its subfolders.
<ItemGroup>
<Content Update="wwwroot/content/**/*.txt" CopyToPublishDirectory="Never" />
</ItemGroup>
The preceding markup can be added to a publish profile or the .csproj file. When added to the .csproj file, the rule
is added to all publish profiles in the project.
The following <MsDeploySkipRules> element excludes all files from the wwwroot/content folder:
<ItemGroup>
<MsDeploySkipRules Include="CustomSkipFolder">
<ObjectName>dirPath</ObjectName>
<AbsolutePath>wwwroot\\content</AbsolutePath>
</MsDeploySkipRules>
</ItemGroup>
<MsDeploySkipRules> won't delete the skip targets from the deployment site. <Content> targeted files and folders
are deleted from the deployment site. For example, suppose a deployed web app had the following files:
Views/Home/About1.cshtml
If the following <MsDeploySkipRules> elements are added, those files wouldn't be deleted on the deployment site.
<ItemGroup>
<MsDeploySkipRules Include="CustomSkipFile">
<ObjectName>filePath</ObjectName>
<AbsolutePath>Views\\Home\\About1.cshtml</AbsolutePath>
</ItemGroup>
The preceding <MsDeploySkipRules> elements prevent the skipped files from being deployed. It won't delete those
files once they're deployed.
The following <Content> element deletes the targeted files at the deployment site:
<ItemGroup>
<Content Update="Views/Home/About?.cshtml" CopyToPublishDirectory="Never" />
</ItemGroup>
Using command-line deployment with the preceding <Content> element yields the following output:
MSDeployPublish:
Starting Web deployment task from source:
manifest(C:\Webs\Web1\obj\Release\netcoreapp1.1\PubTmp\Web1.SourceManifest.
xml) to Destination: auto().
Deleting file (Web11112\Views\Home\About1.cshtml).
Updating file (Web11112\web.config).
Updating file (Web11112\Web1.deps.json).
Updating file (Web11112\Web1.dll).
Updating file (Web11112\Web1.pdb).
Updating file (Web11112\Web1.runtimeconfig.json).
Successfully executed Web deployment task.
Publish Succeeded.
Done Building Project "C:\Webs\Web1\Web1.csproj" (default targets).
Include files
The following markup includes an images folder outside the project directory to the wwwroot/images folder of
the publish site:
<ItemGroup>
<_CustomFiles Include="$(MSBuildProjectDirectory)/../images/**/*" />
<DotnetPublishFiles Include="@(_CustomFiles)">
<DestinationRelativePath>wwwroot/images/%(RecursiveDir)%(Filename)%(Extension)</DestinationRelativePath>
</DotnetPublishFiles>
</ItemGroup>
The markup can be added to the .csproj file or the publish profile. If it's added to the .csproj file, it's included in
each publish profile in the project.
The following highlighted markup shows how to:
Copy a file from outside the project into the wwwroot folder.
Exclude the wwwroot\Content folder.
Exclude Views\Home\About2.cshtml.

<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<WebPublishMethod>FileSystem</WebPublishMethod>
<PublishProvider>FileSystem</PublishProvider>
<LastUsedBuildConfiguration>Release</LastUsedBuildConfiguration>
<LastUsedPlatform>Any CPU</LastUsedPlatform>
<SiteUrlToLaunchAfterPublish />
<LaunchSiteAfterPublish>True</LaunchSiteAfterPublish>
<ExcludeApp_Data>False</ExcludeApp_Data>
<PublishFramework />
<ProjectGuid>afa9f185-7ce0-4935-9da1-ab676229d68a</ProjectGuid>
<publishUrl>bin\Release\PublishOutput</publishUrl>
<DeleteExistingFiles>False</DeleteExistingFiles>
</PropertyGroup>
<ItemGroup>
<ResolvedFileToPublish Include="..\ReadMe2.MD">
<RelativePath>wwwroot\ReadMe2.MD</RelativePath>
</ResolvedFileToPublish>
<Content Update="wwwroot\Content\**\*" CopyToPublishDirectory="Never" />

<Content Update="Views\Home\About2.cshtml" CopyToPublishDirectory="Never" />
</ItemGroup>
</Project>
See the WebSDK Readme for more deployment samples.
Run a target before or after publishing

The built-in BeforePublish and AfterPublish targets execute a target before or after the publish target. Add the
following elements to the publish profile to log console messages both before and after publishing:
<Target Name="CustomActionsBeforePublish" BeforeTargets="BeforePublish">

<Message Text="Inside BeforePublish" Importance="high" />
</Target>
<Target Name="CustomActionsAfterPublish" AfterTargets="AfterPublish">
<Message Text="Inside AfterPublish" Importance="high" />
</Target>
Publish to a server using an untrusted certificate

Add the <AllowUntrustedCertificate> property with a value of True to the publish profile:
<PropertyGroup>
<AllowUntrustedCertificate>True</AllowUntrustedCertificate>
</PropertyGroup>
The Kudu service

To view the files in an Azure App Service web app deployment, use the Kudu service. Append the scm token to
the web app name. For example:
URL RESULT
http://mysite.azurewebsites.net/ Web App
http://mysite.scm.azurewebsites.net/ Kudu service
Select the Debug Console menu item to view, edit, delete, or add files.
Web Deploy (MSDeploy) simplifies deployment of web apps and websites to IIS servers.
https://github.com/aspnet/websdk: File issues and request features for deployment.
Publish an ASP.NET Web App to an Azure VM from Visual Studio
ASP.NET Core directory structure
By Luke Latham
In ASP.NET Core, the published application directory, publish, is comprised of application files, config files, static
assets, packages, and the runtime (for self-contained deployments).
APP TYPE DIRECTORY STRUCTURE
Framework-dependent Deployment publish†

Logs† (optional unless required to receive
stdout logs)
Views† (MVC apps; if views aren't precompiled)
Pages† (MVC or Razor Pages apps; if pages
aren't precompiled)
wwwroot†
*.dll files
<assembly-name>.deps.json
<assembly-name>.dll
<assembly-name>.pdb
<assembly-name>.PrecompiledViews.dll
<assembly-name>.PrecompiledViews.pdb
<assembly-name>.runtimeconfig.json
web.config (IIS deployments)
Self-contained Deployment publish†

Logs† (optional unless required to receive
stdout logs)
refs†
Views† (MVC apps; if views aren't precompiled)
Pages† (MVC or Razor Pages apps; if pages
aren't precompiled)
wwwroot†
*.dll files
<assembly-name>.deps.json
<assembly-name>.exe
<assembly-name>.pdb
<assembly-name>.PrecompiledViews.dll
<assembly-name>.PrecompiledViews.pdb
<assembly-name>.runtimeconfig.json
web.config (IIS deployments)
†Indicates a directory
The publish directory represents the content root path, also called the application base path, of the deployment.
Whatever name is given to the publish directory of the deployed app on the server, its location serves as the
server's physical path to the hosted app.
The wwwroot directory, if present, only contains static assets.
The stdout Logs directory can be created for the deployment using one of the following two approaches:
Add the following <Target> element to the project file:
<Target Name="CreateLogsFolder" AfterTargets="Publish">

<MakeDir Directories="$(PublishDir)Logs"
Condition="!Exists('$(PublishDir)Logs')" />
<WriteLinesToFile File="$(PublishDir)Logs\.log"
Lines="Generated file"
Overwrite="True"
Condition="!Exists('$(PublishDir)Logs\.log')" />
</Target>
The <MakeDir> element creates an empty Logs folder in the published output. The element uses the
PublishDir property to determine the target location for creating the folder. Several deployment
methods, such as Web Deploy, skip empty folders during deployment. The <WriteLinesToFile> element
generates a file in the Logs folder, which guarantees deployment of the folder to the server. Note that
folder creation may still fail if the worker process doesn't have write access to the target folder.
Physically create the Logs directory on the server in the deployment.
The deployment directory requires Read/Execute permissions. The Logs directory requires Read/Write
permissions. Additional directories where files are written require Read/Write permissions.
Common errors reference for Azure App Service
and IIS with ASP.NET Core
By Luke Latham
The following isn't a complete list of errors. If you encounter an error not listed here, open a new issue with
detailed instructions to reproduce the error.
Collect the following information:
Browser behavior
Application Event Log entries
ASP.NET Core Module stdout log entries
Compare the information to the following common errors. If a match is found, follow the troubleshooting advice.
IMPORTANT
Installer unable to obtain VC++ Redistributable

Installer Exception: 0x80072efd or 0x80072f76 - Unspecified error
Installer Log Exception†: Error 0x80072efd or 0x80072f76: Failed to execute EXE package
†The log is located at C:\Users\
{USER }\AppData\Local\Temp\dd_DotNetCoreWinSvrHosting__{timestamp}.log.
Troubleshooting:
If the system doesn't have Internet access while installing the Hosting Bundle, this exception occurs when the
installer is prevented from obtaining the Microsoft Visual C++ 2015 Redistributable. Obtain an installer from
the Microsoft Download Center. If the installer fails, the server may not receive the .NET Core runtime
required to host a framework-dependent deployment (FDD ). If hosting an FDD, confirm that the runtime is
installed in Programs & Features. If needed, obtain a runtime installer from .NET All Downloads. After
installing the runtime, restart the system or restart IIS by executing net stop was /y followed by net start
w3svc from a command prompt.
OS upgrade removed the 32-bit ASP.NET Core Module

Application Log: The Module DLL C:\WINDOWS\system32\inetsrv\aspnetcore.dll failed to load. The
data is the error.
Troubleshooting:
Non-OS files in the C:\Windows\SysWOW64\inetsrv directory aren't preserved during an OS upgrade. If
the ASP.NET Core Module is installed prior to an OS upgrade and then any AppPool is run in 32-bit mode
after an OS upgrade, this issue is encountered. After an OS upgrade, repair the ASP.NET Core Module. See
Install the .NET Core Hosting bundle. Select Repair when the installer is run.
Platform conflicts with RID

Browser: HTTP Error 502.5 - Process Failure
Application Log: Application 'MACHINE/WEBROOT/APPHOST/{ASSEMBLY }' with physical root 'C:
{PATH}' failed to start process with commandline '"C:\{PATH}{assembly}.{exe|dll}" ', ErrorCode =
'0x80004005 : ff.
ASP.NET Core Module Log: Unhandled Exception: System.BadImageFormatException: Could not load
file or assembly '{assembly}.dll'. An attempt was made to load a program with an incorrect format.
Troubleshooting:
Confirm that the app runs locally on Kestrel. A process failure might be the result of a problem within the
app. For more information, see Troubleshooting.
Confirm that the <PlatformTarget>in the .csproj doesn't conflict with the RID. For example, don't specify a
<PlatformTarget> of x86 and publish with an RID of win10-x64 , either by using dotnet publish -c Release
-r win10 -x64 or by setting the <RuntimeIdentifiers> in the .csproj to win10-x64 . The project publishes
without warning or error but fails with the above logged exceptions on the system.
If this exception occurs for an Azure Apps deployment when upgrading an app and deploying newer
assemblies, manually delete all files from the prior deployment. Lingering incompatible assemblies can
result in a System.BadImageFormatException exception when deploying an upgraded app.
URI endpoint wrong or stopped website

Browser: ERR_CONNECTION_REFUSED
Application Log: No entry
ASP.NET Core Module Log: Log file not created
Troubleshooting:
Confirm the correct URI endpoint for the app is being used. Check the bindings.
Confirm that the IIS website isn't in the Stopped state.
CoreWebEngine or W3SVC server features disabled

OS Exception: The IIS 7.0 CoreWebEngine and W3SVC features must be installed to use the ASP.NET Core
Module.
Troubleshooting:
Confirm that the proper role and features are enabled. See IIS Configuration.
Incorrect website physical path or app missing

Browser: 403 Forbidden - Access is denied --OR-- 403.14 Forbidden - The Web server is configured to
not list the contents of this directory.
Troubleshooting:
Check the IIS website Basic Settings and the physical app folder. Confirm that the app is in the folder at the
IIS website Physical path.
Incorrect role, module not installed, or incorrect permissions

Browser: 500.19 Internal Server Error - The requested page cannot be accessed because the related
configuration data for the page is invalid.
Troubleshooting:
Confirm that the proper role is enabled. See IIS Configuration.
Check Programs & Features and confirm that the Microsoft ASP.NET Core Module has been
installed. If the Microsoft ASP.NET Core Module isn't present in the list of installed programs, install
the module. See Install the .NET Core Hosting Bundle.
Make sure that the Application Pool > Process Model > Identity is set to ApplicationPoolIdentity
or the custom identity has the correct permissions to access the app's deployment folder.
Incorrect processPath, missing PATH variable, Hosting Bundle not

installed, system/IIS not restarted, VC++ Redistributable not installed,
or dotnet.exe access violation
Application Log: Application 'MACHINE/WEBROOT/APPHOST/{ASSEMBLY }' with physical root 'C:\
{PATH}' failed to start process with commandline '".{assembly}.exe" ', ErrorCode = '0x80070002 : 0.
ASP.NET Core Module Log: Log file created but empty
Troubleshooting:
Check the processPath attribute on the <aspNetCore> element in web.config to confirm that it's dotnet for
a framework-dependent deployment (FDD ) or .{assembly }.exe for a self-contained deployment (SCD ).
For an FDD, dotnet.exe might not be accessible via the PATH settings. Confirm that *C:\Program
Files\dotnet* exists in the System PATH settings.
For an FDD, dotnet.exe might not be accessible for the user identity of the Application Pool. Confirm that
the AppPool user identity has access to the C:\Program Files\dotnet directory. Confirm that there are no
deny rules configured for the AppPool user identity on the C:\Program Files\dotnet and app directories.
An FDD may have been deployed and .NET Core installed without restarting IIS. Either restart the server
or restart IIS by executing net stop was /y followed by net start w3svc from a command prompt.
An FDD may have been deployed without installing the .NET Core runtime on the hosting system. If the
.NET Core runtime hasn't been installed, run the .NET Core Hosting Bundle installer on the system.
See Install the .NET Core Hosting Bundle. If attempting to install the .NET Core runtime on a system
without an Internet connection, obtain the runtime from .NET All Downloads and run the Hosting Bundle
installer to install the ASP.NET Core Module. Complete the installation by restarting the system or
restarting IIS by executing net stop was /y followed by net start w3svc from a command prompt.
An FDD may have been deployed and the Microsoft Visual C++ 2015 Redistributable (x64 ) isn't installed
on the system. Obtain an installer from the Microsoft Download Center.
Incorrect arguments of <aspNetCore> element

{PATH}' failed to start process with commandline '"dotnet" .{assembly}.dll', ErrorCode = '0x80004005 :
80008081.
ASP.NET Core Module Log: The application to execute does not exist: 'PATH{assembly}.dll'
Troubleshooting:
Examine the arguments attribute on the <aspNetCore> element in web.config to confirm that it's either (a) .
{assembly }.dll for a framework-dependent deployment (FDD ); or (b) not present, an empty string
(arguments=""), or a list of the app's arguments (arguments="arg1, arg2, ...") for a self-contained
deployment (SCD ).
Missing .NET Framework version

Browser: 502.3 Bad Gateway - There was a connection error while trying to route the request.
Application Log: ErrorCode = Application 'MACHINE/WEBROOT/APPHOST/{ASSEMBLY }' with
physical root 'C:\{PATH}' failed to start process with commandline '"dotnet" .{assembly}.dll', ErrorCode =
'0x80004005 : 80008081.
ASP.NET Core Module Log: Missing method, file, or assembly exception. The method, file, or assembly
specified in the exception is a .NET Framework method, file, or assembly.
Troubleshooting:
Install the .NET Framework version missing from the system.
For a framework-dependent deployment (FDD ), confirm that the correct runtime installed on the system.
If the project is upgraded from 1.1 to 2.0, deployed to the hosting system, and this exception results,
ensure that the 2.0 framework is on the hosting system.
Stopped Application Pool

Browser: 503 Service Unavailable
Troubleshooting
Confirm that the Application Pool isn't in the Stopped state.
IIS Integration middleware not implemented

{PATH}' created process with commandline '"C:\{PATH}{assembly}.{exe|dll}" ' but either crashed or did not
reponse or did not listen on the given port '{PORT}', ErrorCode = '0x800705b4'
ASP.NET Core Module Log: Log file created and shows normal operation.
Troubleshooting
Confirm that either:
The IIS Integration middleware is referencedby calling the UseIISIntegration method on the app's
WebHostBuilder ( ASP.NET Core 1.x)
The apps uses the CreateDefaultBuilder method (ASP.NET Core 2.x).
See Host in ASP.NET Core for details.
Sub-application includes a <handlers> section

Browser: HTTP Error 500.19 - Internal Server Error
ASP.NET Core Module Log: Log file created and shows normal operation for the root app. Log file not
created for the sub-app.
Troubleshooting
Confirm that the sub-app's web.config file doesn't include a <handlers> section.
stdout log path incorrect

Browser: The app responds normally.
Application Log: Warning: Could not create stdoutLogFile \?
\C:_apps\app_folder\bin\Release\netcoreapp2.0\win10-
x64\publish\logs\path_doesnt_exist\stdout_8748_201831835937.log, ErrorCode = -2147024893.
Troubleshooting
The stdoutLogFile path specified in the <aspNetCore> element of web.config doesn't exist. For more
information, see the Log creation and redirection section of the ASP.NET Core Module configuration
reference topic.
Application configuration general issue

{PATH}' created process with commandline '"C:\{PATH}{assembly}.{exe|dll}" ' but either crashed or did not
reponse or did not listen on the given port '{PORT}', ErrorCode = '0x800705b4'
ASP.NET Core Module Log: Log file created but empty
Troubleshooting
This general exception indicates that the process failed to start, most likely due to an app configuration issue.
Referring to Directory Structure, confirm that the app's deployed files and folders are appropriate and that the
app's configuration files are present and contain the correct settings for the app and environment. For more
information, see Troubleshooting.
Overview of ASP.NET Core Security
ASP.NET Core enables developers to easily configure and manage security for their apps. ASP.NET Core contains
features for managing authentication, authorization, data protection, SSL enforcement, app secrets, anti-request
forgery protection, and CORS management. These security features allow you to build robust yet secure ASP.NET
Core apps.
ASP.NET Core security features

ASP.NET Core provides many tools and libraries to secure your apps including built-in Identity providers but you
can use 3rd party identity services such as Facebook, Twitter, or LinkedIn. With ASP.NET Core, you can easily
manage app secrets, which are a way to store and use confidential information without having to expose it in the
code.
Authentication vs. Authorization

Authentication is a process in which a user provides credentials that are then compared to those stored in an
operating system, database, app or resource. If they match, users authenticate successfully, and can then perform
actions that they're authorized for, during an authorization process. The authorization refers to the process that
determines what a user is allowed to do.
Another way to think of authentication is to consider it as a way to enter a space, such as a server, database, app or
resource, while authorization is which actions the user can perform to which objects inside that space (server,
database, or app).
Common Vulnerabilities in software

ASP.NET Core and EF contain features that help you secure your apps and prevent security breaches. The
following list of links takes you to documentation detailing techniques to avoid the most common security
vulnerabilities in web apps:
Cross-site scripting attacks
SQL injection attacks
Cross-Site Request Forgery (CSRF )
Open redirect attacks
There are more vulnerabilities that you should be aware of. For more information, see the section in this document
on ASP.NET Core Security Documentation.
ASP.NET Core Security Documentation

Authentication
Enable authentication with WS -Federation
Use cookie authentication without Identity
Integrate Azure AD into an ASP.NET Core web app
Call an ASP.NET Core Web API from a WPF app using Azure AD
An ASP.NET Core web app with Azure AD B2C
Authorization
Introduction
View -based authorization
Limit identity by scheme
Data protection
Consumer APIs
Consumer APIs Overview
Purpose strings
Hash passwords
Configuration
Configure data protection
Default settings
Machine-wide policy
Non DI-aware scenarios
Extensibility APIs
Miscellaneous APIs
Implementation
Context headers
Key management
Key storage format
Compatibility
Replace in ASP.NET
Safe storage of app secrets in development
Enforce SSL
Prevent open redirect attacks
Prevent Cross-Site Scripting
Enable Cross-Origin Requests (CORS )
Share cookies among apps
IP safelist
Authentication in ASP.NET Core
Community OSS authentication options

Enable authentication with WS -Federation
Enable QR code generation in Identity
Use cookie authentication without Identity
Integrate Azure AD into an ASP.NET Core web app
Integrate Azure AD B2C into a customer-facing ASP.NET Core web app
Integrate Azure AD B2C into an ASP.NET Core web API
Call an ASP.NET Core Web API from a WPF app using Azure AD
Secure ASP.NET Core apps with Azure App Service Authentication (Easy Auth)
Articles based on projects created with individual user accounts
Introduction to Identity on ASP.NET Core
By Rick Anderson
ASP.NET Core Identity is a membership system that adds login functionality to ASP.NET Core apps. Users
can create an account with the login information stored in Identity or they can use an external login provider.
Supported external login providers include Facebook, Google, Microsoft Account, and Twitter.
Identity can be configured using a SQL Server database to store user names, passwords, and profile data.
Alternatively, another persistent store can be used, for example, Azure Table Storage.
View or download the sample code. (How to download)
In this topic, you learn how to use Identity to register, log in, and log out a user. For more detailed instructions
about creating apps that use Identity, see the Next Steps section at the end of this article.
AddDefaultIdentity and AddIdentity

AddDefaultIdentity was introduced in ASP.Core 2.1. Calling AddDefaultIdentity is similar to calling the
following:
AddIdentity
AddDefaultUI
AddDefaultTokenProviders
See AddDefaultIdentity source for more information.
Create a Web app with authentication

Create an ASP.NET Core Web Application project with Individual User Accounts.
Visual Studio
.NET Core CLI
Select File > New > Project.
Select ASP.NET Core Web Application. Name the project WebApp1 to have the same namespace as
the project download. Click OK.
Select an ASP.NET Core Web Application for ASP.NET Core 2.1, then select Change Authentication.
Select Individual User Accounts and click OK.
The generated project provides ASP.NET Core Identity as a Razor Class Library.
Test Register and Login
Run the app and register a user. Depending on your screen size, you might need to select the navigation toggle
button to see the Register and Login links.
View the Identity database
Visual Studio
.NET Core CLI
From the View menu, select SQL Server Object Explorer (SSOX).
Navigate to (localdb)MSSQLLocalDB (SQL Server 13). Right-click on dbo.AspNetUsers > View Data:
Configure Identity services

Services are added in ConfigureServices . The typical pattern is to call all the Add{Service} methods, and then
call all the services.Configure{Service} methods. The following code doesn't include the template generated
CookiePolicyOptions :

{
options.UseSqlServer(
Configuration.GetConnectionString("DefaultConnection")));
services.AddDefaultIdentity<IdentityUser>()
.AddEntityFrameworkStores<ApplicationDbContext>();
services.Configure<IdentityOptions>(options =>
{
// Password settings.
options.Password.RequireDigit = true;
options.Password.RequireLowercase = true;
options.Password.RequireNonAlphanumeric = true;
options.Password.RequireUppercase = true;
options.Password.RequiredLength = 6;
options.Password.RequiredUniqueChars = 1;
// Lockout settings.
options.Lockout.DefaultLockoutTimeSpan = TimeSpan.FromMinutes(5);
options.Lockout.MaxFailedAccessAttempts = 5;
options.Lockout.AllowedForNewUsers = true;
// User settings.
options.User.AllowedUserNameCharacters =
"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._@+";
options.User.RequireUniqueEmail = false;
});
services.ConfigureApplicationCookie(options =>
{
// Cookie settings
options.ExpireTimeSpan = TimeSpan.FromMinutes(5);
options.LoginPath = "/Identity/Account/Login";
options.AccessDeniedPath = "/Identity/Account/AccessDenied";
options.SlidingExpiration = true;
});
}
The preceding code configures Identity with default option values. Services are made available to the app
through dependency injection.
Identity is enabled by calling UseAuthentication. UseAuthentication adds authentication middleware to the
request pipeline.
{
{
}
else
{
app.UseHsts();
}
app.UseMvc();
}
{
{
// Password settings
options.Password.RequireNonAlphanumeric = false;
options.Password.RequireLowercase = false;
// Lockout settings
// User settings
options.User.RequireUniqueEmail = true;
});
{
// Cookie settings
// If the LoginPath isn't set, ASP.NET Core defaults
// the path to /Account/Login.
options.LoginPath = "/Account/Login";
// If the AccessDeniedPath isn't set, ASP.NET Core defaults
// the path to /Account/AccessDenied.
options.AccessDeniedPath = "/Account/AccessDenied";
});

services.AddTransient<IEmailSender, EmailSender>();
services.AddMvc();
}
Services are made available to the application through dependency injection.

Identity is enabled for the application by calling UseAuthentication in the Configure method.
UseAuthentication adds authentication middleware to the request pipeline.
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
{
{
}
else
{
}
{
routes.MapRoute(
name: "default",
});
}

{
services.AddMvc();
// Configure Identity
{
// Lockout settings
// Cookie settings
options.Cookies.ApplicationCookie.ExpireTimeSpan = TimeSpan.FromDays(150);
options.Cookies.ApplicationCookie.LoginPath = "/Account/Login";
// User settings
});

}
These services are made available to the application through dependency injection.
Identity is enabled for the application by calling UseIdentity in the Configure method. UseIdentity adds
cookie-based authentication middleware to the request pipeline.

{
{
}
else
{
}
app.UseIdentity();
// Add external authentication middleware below. To configure them please see

https://go.microsoft.com/fwlink/?LinkID=532715
{
routes.MapRoute(
name: "default",
});
}
For more information, see the IdentityOptions Class and Application Startup.
Scaffold Register, Login, and LogOut

Follow the Scaffold identity into a Razor project with authorization instructions.
Visual Studio
.NET Core CLI
Add the Register, Login, and LogOut files.
Examine Register
When a user clicks the Register link, the RegisterModel.OnPostAsync action is invoked. The user is created by
CreateAsync on the _userManager object. _userManager is provided by dependency injection):
public async Task<IActionResult> OnPostAsync(string returnUrl = null)
{
returnUrl = returnUrl ?? Url.Content("~/");
{
var user = new IdentityUser { UserName = Input.Email, Email = Input.Email };
var result = await _userManager.CreateAsync(user, Input.Password);
if (result.Succeeded)
{
_logger.LogInformation("User created a new account with password.");
var code = await _userManager.GenerateEmailConfirmationTokenAsync(user);

var callbackUrl = Url.Page(
"/Account/ConfirmEmail",
pageHandler: null,
values: new { userId = user.Id, code = code },
protocol: Request.Scheme);
await _emailSender.SendEmailAsync(Input.Email, "Confirm your email",

$"Please confirm your account by <a
href='{HtmlEncoder.Default.Encode(callbackUrl)}'>clicking here</a>.");
await _signInManager.SignInAsync(user, isPersistent: false);

}
foreach (var error in result.Errors)
{
ModelState.AddModelError(string.Empty, error.Description);
}
}
// If we got this far, something failed, redisplay form

return Page();
}
When a user clicks the Register link, the Register action is invoked on AccountController . The Register
action creates the user by calling CreateAsync on the _userManager object (provided to AccountController by
dependency injection):
//
// POST: /Account/Register
[HttpPost]
[AllowAnonymous]
public async Task<IActionResult> Register(RegisterViewModel model)
{
{
var user = new ApplicationUser { UserName = model.Email, Email = model.Email };
var result = await _userManager.CreateAsync(user, model.Password);
{
// For more information on how to enable account confirmation and password reset please visit
http://go.microsoft.com/fwlink/?LinkID=532713
// Send an email with this link
//var code = await _userManager.GenerateEmailConfirmationTokenAsync(user);
//var callbackUrl = Url.Action("ConfirmEmail", "Account", new { userId = user.Id, code = code
}, protocol: HttpContext.Request.Scheme);
//await _emailSender.SendEmailAsync(model.Email, "Confirm your account",
// "Please confirm your account by clicking this link: <a href=\"" + callbackUrl +
"\">link</a>");
_logger.LogInformation(3, "User created a new account with password.");
return RedirectToAction(nameof(HomeController.Index), "Home");
}
AddErrors(result);
}

return View(model);
}
If the user was created successfully, the user is logged in by the call to _signInManager.SignInAsync .
Note: See account confirmation for steps to prevent immediate login at registration.
Log in
The Login form is displayed when:
The Log in link is selected.
When a user accesses a page where they are not authenticated or authorized, they are redirected to the
Login page.
When the form on the Login page is submitted, the OnPostAsync action is called. PasswordSignInAsync is called
on the _signInManager object (provided by dependency injection).
{
{
// This doesn't count login failures towards account lockout
// To enable password failures to trigger account lockout,
// set lockoutOnFailure: true
var result = await _signInManager.PasswordSignInAsync(Input.Email,
Input.Password, Input.RememberMe, lockoutOnFailure: true);
{
_logger.LogInformation("User logged in.");
}
if (result.RequiresTwoFactor)
{
return RedirectToPage("./LoginWith2fa", new { ReturnUrl = returnUrl,
RememberMe = Input.RememberMe });
}
if (result.IsLockedOut)
{
_logger.LogWarning("User account locked out.");
return RedirectToPage("./Lockout");
}
else
{
ModelState.AddModelError(string.Empty, "Invalid login attempt.");
return Page();
}
}

return Page();
}
The base Controller class exposes a User property that you can access from controller methods. For
instance, you can enumerate User.Claims and make authorization decisions. For more information, see
Authorization.
The Login form is displayed when users select the Log in link or are redirected when accessing a page that
requires authentication. When the user submits the form on the Login page, the AccountController Login
action is called.
The Login action calls PasswordSignInAsync on the _signInManager object (provided to AccountController by
dependency injection).
//
// POST: /Account/Login
[HttpPost]
[AllowAnonymous]
public async Task<IActionResult> Login(LoginViewModel model, string returnUrl = null)
{
ViewData["ReturnUrl"] = returnUrl;
{
// This doesn't count login failures towards account lockout
// To enable password failures to trigger account lockout, set lockoutOnFailure: true
var result = await _signInManager.PasswordSignInAsync(model.Email,
model.Password, model.RememberMe, lockoutOnFailure: false);
{
_logger.LogInformation(1, "User logged in.");
return RedirectToLocal(returnUrl);
}
{
return RedirectToAction(nameof(SendCode), new { ReturnUrl = returnUrl, RememberMe =
model.RememberMe });
}
{
_logger.LogWarning(2, "User account locked out.");
return View("Lockout");
}
else
{
return View(model);
}
}

return View(model);
}
The base ( Controller or PageModel ) class exposes a User property. For example, User.Claims can be
enumerated to make authorization decisions.
Log out
The Log out link invokes the LogoutModel.OnPost action.
using System;
using System.Linq;
using Microsoft.AspNetCore.Identity;
namespace WebApp1.Areas.Identity.Pages.Account
{
[AllowAnonymous]
public class LogoutModel : PageModel
{
private readonly SignInManager<IdentityUser> _signInManager;
private readonly ILogger<LogoutModel> _logger;
public LogoutModel(SignInManager<IdentityUser> signInManager, ILogger<LogoutModel> logger)

{
_signInManager = signInManager;
_logger = logger;
}
public void OnGet()

{
}
public async Task<IActionResult> OnPost(string returnUrl = null)

{
await _signInManager.SignOutAsync();
_logger.LogInformation("User logged out.");
if (returnUrl != null)
{
}
else
{
return Page();
}
}
}
}
SignOutAsync clears the user's claims stored in a cookie. Don't redirect after calling SignOutAsync or the user
will not be signed out.
Post is specified in the Pages/Shared/_LoginPartial.cshtml:
@inject SignInManager<IdentityUser> SignInManager

@inject UserManager<IdentityUser> UserManager
@if (SignInManager.IsSignedIn(User))
{
<form asp-area="Identity" asp-page="/Account/Logout"
asp-route-returnUrl="@Url.Page("/Index", new { area = "" })"
method="post"
id="logoutForm" class="navbar-right">
<ul class="nav navbar-nav navbar-right">
<li>
<a asp-area="Identity" asp-page="/Account/Manage/Index" title="Manage">
Hello @UserManager.GetUserName(User)!</a>
</li>
<li>
<button type="submit" class="btn btn-link navbar-btn navbar-link">Logout</button>
</li>
</ul>
</form>
}
else
{
<li><a asp-area="Identity" asp-page="/Account/Register">Register</a></li>
<li><a asp-area="Identity" asp-page="/Account/Login">Login</a></li>
</ul>
}
Clicking the Log out link calls the LogOut action.
//
// POST: /Account/LogOut
[HttpPost]
public async Task<IActionResult> LogOut()
{
await _signInManager.SignOutAsync();
_logger.LogInformation(4, "User logged out.");
}
The preceding code calls the _signInManager.SignOutAsync method. The SignOutAsync method clears the user's
claims stored in a cookie.
Test Identity
The default web project templates allow anonymous access to the home pages. To test Identity, add
[Authorize] to the About page.
namespace WebApp1.Pages
{
[Authorize]
{
public void OnGet()

{
Message = "Your application description page.";
}
}
}
If you are signed in, sign out. Run the app and select the About link. You are redirected to the login page.
Explore Identity
To explore Identity in more detail:
Create full identity UI source
Examine the source of each page and step through the debugger.
Identity Components
All the Identity dependent NuGet packages are included in the Microsoft.AspNetCore.App metapackage.
The primary package for Identity is Microsoft.AspNetCore.Identity. This package contains the core set of
interfaces for ASP.NET Core Identity, and is included by Microsoft.AspNetCore.Identity.EntityFrameworkCore .
Migrating to ASP.NET Core Identity

For more information and guidance on migrating your existing Identity store, see Migrate Authentication and
Identity.
Setting password strength

See Configuration for a sample that sets the minimum password requirements.
Next Steps
Configure Identity
Create an ASP.NET Core app with user data protected by authorization
Add, download, and delete custom user data to Identity in an ASP.NET Core project
Enable QR Code generation for TOTP authenticator apps in ASP.NET Core
Configure Identity primary keys data type.
Migrate Authentication and Identity to ASP.NET Core
Two-factor authentication with SMS in ASP.NET Core
Scaffold Identity in ASP.NET Core projects
By Rick Anderson
ASP.NET Core 2.1 and later provides ASP.NET Core Identity as a Razor Class Library. Applications that include
Identity can apply the scaffolder to selectively add the source code contained in the Identity Razor Class Library
(RCL ). You might want to generate source code so you can modify the code and change the behavior. For
example, you could instruct the scaffolder to generate the code used in registration. Generated code takes
precedence over the same code in the Identity RCL. To gain full control of the UI and not use the default RCL, see
the section Create full identity UI source.
Applications that do not include authentication can apply the scaffolder to add the RCL Identity package. You
have the option of selecting Identity code to be generated.
Although the scaffolder generates most of the necessary code, you'll have to update your project to complete the
process. This document explains the steps needed to complete an Identity scaffolding update.
When the Identity scaffolder is run, a ScaffoldingReadme.txt file is created in the project directory. The
ScaffoldingReadme.txt file contains general instructions on what's needed to complete the Identity scaffolding
update. This document contains more complete instructions than the ScaffoldingReadme.txt file.
We recommend using a source control system that shows file differences and allows you to back out of changes.
Inspect the changes after running the Identity scaffolder.
NOTE
Services are required when using Two Factor Authentication, Account confirmation and password recovery, and other
security features with Identity. Services or service stubs aren't generated when scaffolding Identity. Services to enable these
features must be added manually. For example, see Require Email Confirmation.
Scaffold identity into an empty project

Run the Identity scaffolder:
Visual Studio
.NET Core CLI
From Solution Explorer, right-click on the project > Add > New Scaffolded Item.
From the left pane of the Add Scaffold dialog, select Identity > ADD.
In the ADD Identity dialog, select the options you want.
Select your existing layout page, or your layout file will be overwritten with incorrect markup. For
example ~/Pages/Shared/_Layout.cshtml for Razor Pages ~/Views/Shared/_Layout.cshtml for MVC
projects
Select the + button to create a new Data context class.
Select ADD.
Add the following highlighted calls to the Startup class:
{
{
services.AddMvc();
}
{
{
}
else
{
app.UseHsts();
}
app.UseMvc();
}
}
UseHsts is recommended but not required. See HTTP Strict Transport Security Protocol for more information.
The generated Identity database code requires Entity Framework Core Migrations. Create a migration and update
the database. For example, run the following commands:
Visual Studio
.NET Core CLI
In the Visual Studio Package Manager Console:
Add-Migration CreateIdentitySchema
Update-Database
The "CreateIdentitySchema" name parameter for the Add-Migration command is arbitrary.

"CreateIdentitySchema" describes the migration.
Scaffold identity into a Razor project without existing authorization

Visual Studio
.NET Core CLI
projects
Select ADD.
Identity is configured in Areas/Identity/IdentityHostingStartup.cs. for more information, see IHostingStartup.
Migrations, UseAuthentication, and layout
Visual Studio
.NET Core CLI
Update-Database

Enable authentication
In the Configure method of the Startup class, call UseAuthentication after UseStaticFiles :

{
{
}

{
services.AddMvc();
}

{
{
}
else
{
app.UseHsts();
}
app.UseMvc();
}
}
Layout changes
Optional: Add the login partial ( _LoginPartial ) to the layout file:
<!DOCTYPE html>
<html>
<html>
<head>
<title>@ViewData["Title"] - RazorNoAuth8</title>
</environment>
value="absolute" />
</environment>
</head>
<body>
collapse">
</button>
<a asp-page="/Index" class="navbar-brand">RazorNoAuth8</a>
</div>
<li><a asp-page="/Contact">Contact</a></li>
</ul>
<partial name="_LoginPartial" />
</div>
</div>
</nav>

@RenderBody()
<hr />
<footer>
<p>© 2018 - RazorNoAuth8</p>
</footer>
</div>
</environment>
</script>
</script>
</script>
</environment>

</body>
</html>
Scaffold identity into a Razor project with authorization

Visual Studio
.NET Core CLI
Select your existing layout page, or your layout file will be overwritten with incorrect markup. When an
existing _Layout.cshtml file is selected, it is not overwritten.
For example ~/Pages/Shared/_Layout.cshtml for Razor Pages ~/Views/Shared/_Layout.cshtml for MVC projects
To use your existing data context, select at least one file to override. You must select at least one file to add
your data context.
Select your data context class.
Select ADD.
To create a new user context and possibly create a custom user class for Identity:
Select ADD.
Note: If you're creating a new user context, you don't have to select a file to override.
Some Identity options are configured in Areas/Identity/IdentityHostingStartup.cs. For more information, see
IHostingStartup.
Scaffold identity into an MVC project without existing authorization

Visual Studio
.NET Core CLI
projects
Select ADD.
Optional: Add the login partial ( _LoginPartial ) to the Views/Shared/_Layout.cshtml file:
<!DOCTYPE html>
<html>
<html>
<head>
<title>@ViewData["Title"] - MvcNoAuth3</title>
</environment>
value="absolute" />
</environment>
</head>
<body>
collapse">
</button>
<a asp-area="" asp-controller="Home" asp-action="Index" class="navbar-brand">MvcNoAuth3</a>
</div>
</ul>
<partial name="_LoginPartial" />
</div>
</div>
</nav>

@RenderBody()
<hr />
<footer>
<p>© 2018 - MvcNoAuth3</p>
</footer>
</div>
</environment>
</script>
</script>
</script>
</environment>

</body>
</html>
Move the Pages/Shared/_LoginPartial.cshtml file to Views/Shared/_LoginPartial.cshtml

Identity is configured in Areas/Identity/IdentityHostingStartup.cs. For more information, see IHostingStartup.
Visual Studio
.NET Core CLI
Update-Database

Call UseAuthentication after UseStaticFiles :

{

{
services.AddMvc();
}

{
{
}
else
{
app.UseHsts();
}
}
}
Scaffold identity into an MVC project with authorization

Visual Studio
.NET Core CLI
Select your existing layout page, or your layout file will be overwritten with incorrect markup. When an
existing _Layout.cshtml file is selected, it is not overwritten.
For example ~/Pages/Shared/_Layout.cshtml for Razor Pages ~/Views/Shared/_Layout.cshtml for MVC projects
To use your existing data context, select at least one file to override. You must select at least one file to add
your data context.
Select your data context class.
Select ADD.
To create a new user context and possibly create a custom user class for Identity:
Select ADD.
Note: If you're creating a new user context, you don't have to select a file to override.
Delete the Pages/Shared folder and the files in that folder.
Create full identity UI source

To maintain full control of the Identity UI, run the Identity scaffolder and select Override all files.
The following highlighted code shows the changes to replace the default Identity UI with Identity in an ASP.NET
Core 2.1 web app. You might want to do this to have full control of the Identity UI.
{
{
});
services.AddIdentity<IdentityUser, IdentityRole>()
// services.AddDefaultIdentity<IdentityUser>()
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1)
{
options.AllowAreas = true;
options.Conventions.AuthorizeAreaFolder("Identity", "/Account/Manage");
options.Conventions.AuthorizeAreaPage("Identity", "/Account/Logout");
});
{
options.LoginPath = $"/Identity/Account/Login";
options.LogoutPath = $"/Identity/Account/Logout";
options.AccessDeniedPath = $"/Identity/Account/AccessDenied";
});
// using Microsoft.AspNetCore.Identity.UI.Services;
services.AddSingleton<IEmailSender, EmailSender>();
}
The default Identity is replaced in the following code:
services.AddIdentity<IdentityUser, IdentityRole>()
// services.AddDefaultIdentity<IdentityUser>()
The following the code sets the LoginPath, LogoutPath, and AccessDeniedPath:
{
options.LoginPath = $"/Identity/Account/Login";
options.LogoutPath = $"/Identity/Account/Logout";
options.AccessDeniedPath = $"/Identity/Account/AccessDenied";
});
Register an IEmailSender implementation, for example:
public class EmailSender : IEmailSender
{
public Task SendEmailAsync(string email, string subject, string message)
{
}
}
Changes to authentication code to ASP.NET Core 2.1 and later
Add, download, and delete custom user data to
Identity in an ASP.NET Core project
By Rick Anderson
This article shows how to:
Add custom user data to an ASP.NET Core web app.
Decorate the custom user data model with the PersonalData attribute so it's automatically available for
download and deletion. Making the data able to be downloaded and deleted helps meet GDPR requirements.
The project sample is created from a Razor Pages web app, but the instructions are similar for a ASP.NET Core
MVC web app.
Prerequisites

Visual Studio
.NET Core CLI
From the Visual Studio File menu, select New > Project. Name the project WebApp1 if you want to it match
the namespace of the download sample code.
Select ASP.NET Core Web Application > OK
Select ASP.NET Core 2.1 in the dropdown
Select Web Application > OK
Build and run the project.
Run the Identity scaffolder

Visual Studio
.NET Core CLI
In the ADD Identity dialog, the following options:
Select the existing layout file ~/Pages/Shared/_Layout.cshtml
Select the following files to override:
Account/Register
Account/Manage/Index
Select the + button to create a new Data context class. Accept the type
(WebApp1.Models.WebApp1Context if the project is named WebApp1).
Select the + button to create a new User class. Accept the type (WebApp1User if the project is named
WebApp1) > Add.
Select ADD.
Follow the instruction in Migrations, UseAuthentication, and layout to perform the following steps:
Create a migration and update the database.
Add UseAuthentication to Startup.Configure .
Add <partial name="_LoginPartial" /> to the layout file.
Test the app:
Register a user
Select the new user name (next to the Logout link). You might need to expand the window or select the
navigation bar icon to show the user name and other links.
Select the Personal Data tab.
Select the Download button and examined the PersonalData.json file.
Test the Delete button, which deletes the logged on user.
Add custom user data to the Identity DB

Update the IdentityUser derived class with custom properties. If you named the project WebApp1, the file is
named Areas/Identity/Data/WebApp1User.cs. Update the file with the following code:
using System;
namespace WebApp1.Areas.Identity.Data
{
public class WebApp1User : IdentityUser
{
[PersonalData]
[PersonalData]
public DateTime DOB { get; set; }
}
}
Properties decorated with the PersonalData attribute are:

Deleted when the Areas/Identity/Pages/Account/Manage/DeletePersonalData.cshtml Razor Page calls
UserManager.Delete .
Included in the downloaded data by the
Areas/Identity/Pages/Account/Manage/DownloadPersonalData.cshtml Razor Page.
Update the Account/Manage/Index.cshtml page
Update the InputModel in Areas/Identity/Pages/Account/Manage/Index.cshtml.cs with the following highlighted
code:
public partial class IndexModel : PageModel

{
private readonly UserManager<WebApp1User> _userManager;
private readonly SignInManager<WebApp1User> _signInManager;
private readonly IEmailSender _emailSender;
public IndexModel(
UserManager<WebApp1User> userManager,
SignInManager<WebApp1User> signInManager,
IEmailSender emailSender)
{
_userManager = userManager;
_emailSender = emailSender;
}
public string Username { get; set; }
public bool IsEmailConfirmed { get; set; }
[TempData]
public string StatusMessage { get; set; }
[BindProperty]
public InputModel Input { get; set; }
public class InputModel

{
[Required]
[DataType(DataType.Text)]
[Display(Name = "Full name")]
[Required]
[Display(Name = "Birth Date")]
[Required]
[EmailAddress]
[Phone]
[Display(Name = "Phone number")]
public string PhoneNumber { get; set; }
}
public async Task<IActionResult> OnGetAsync()

{
var user = await _userManager.GetUserAsync(User);
if (user == null)
{
return NotFound($"Unable to load user with ID '{_userManager.GetUserId(User)}'.");
}
var userName = await _userManager.GetUserNameAsync(user);

var email = await _userManager.GetEmailAsync(user);
var phoneNumber = await _userManager.GetPhoneNumberAsync(user);
Username = userName;
Input = new InputModel

{
Name = user.Name,
DOB = user.DOB,
Email = email,
PhoneNumber = phoneNumber
};
IsEmailConfirmed = await _userManager.IsEmailConfirmedAsync(user);
return Page();
}

{
{
return Page();
}

if (user == null)
{
}
if (Input.Name != user.Name)
{
user.Name = Input.Name;
}
if (Input.DOB != user.DOB)
{
user.DOB = Input.DOB;
}

if (Input.Email != email)
{
var setEmailResult = await _userManager.SetEmailAsync(user, Input.Email);
if (!setEmailResult.Succeeded)
{
var userId = await _userManager.GetUserIdAsync(user);
throw new InvalidOperationException($"Unexpected error occurred setting email for user with ID
'{userId}'.");
}
}
var phoneNumber = await _userManager.GetPhoneNumberAsync(user);

if (Input.PhoneNumber != phoneNumber)
{
var setPhoneResult = await _userManager.SetPhoneNumberAsync(user, Input.PhoneNumber);
if (!setPhoneResult.Succeeded)
{
throw new InvalidOperationException($"Unexpected error occurred setting phone number for user
with ID '{userId}'.");
}
}
await _userManager.UpdateAsync(user);
await _signInManager.RefreshSignInAsync(user);
StatusMessage = "Your profile has been updated";
}
public async Task<IActionResult> OnPostSendVerificationEmailAsync()

{
{
return Page();
}

if (user == null)
{
}

pageHandler: null,
values: new { userId = userId, code = code },
await _emailSender.SendEmailAsync(
await _emailSender.SendEmailAsync(
email,
"Confirm your email",
$"Please confirm your account by <a href='{HtmlEncoder.Default.Encode(callbackUrl)}'>clicking
here</a>.");
StatusMessage = "Verification email sent. Please check your email.";

}
}
Update the Areas/Identity/Pages/Account/Manage/Index.cshtml with the following highlighted markup:

@page
@model IndexModel
@{
ViewData["Title"] = "Profile";
}
@Html.Partial("_StatusMessage", Model.StatusMessage)
<div class="row">
<form id="profile-form" method="post">
<div asp-validation-summary="All" class="text-danger"></div>
<label asp-for="Username"></label>
<input asp-for="Username" class="form-control" disabled />
</div>
<label asp-for="Input.Email"></label>
@if (Model.IsEmailConfirmed)
{
<div class="input-group">
<input asp-for="Input.Email" class="form-control" />
<span class="input-group-addon" aria-hidden="true"><span class="glyphicon glyphicon-ok
text-success"></span></span>
</div>
}
else
{
<button id="email-verification" type="submit" asp-page-handler="SendVerificationEmail"
class="btn btn-link">Send verification email</button>
}
<span asp-validation-for="Input.Email" class="text-danger"></span>
</div>
<label asp-for="Input.Name"></label>
<input asp-for="Input.Name" class="form-control" />
</div>
<label asp-for="Input.DOB"></label>
<input asp-for="Input.DOB" class="form-control" />
</div>
<label asp-for="Input.PhoneNumber"></label>
<input asp-for="Input.PhoneNumber" class="form-control" />
<span asp-validation-for="Input.PhoneNumber" class="text-danger"></span>
</div>
<button type="submit" class="btn btn-default">Save</button>
</form>
</div>
</div>
@section Scripts {
<partial name="_ValidationScriptsPartial" />
}
Update the Account/Register.cshtml page

Update the InputModel in Areas/Identity/Pages/Account/Register.cshtml.cs with the following highlighted code:
[BindProperty]
public InputModel Input { get; set; }
public string ReturnUrl { get; set; }
public class InputModel

{
{
[Required]
[DataType(DataType.Text)]
[Display(Name = "Full name")]
[Required]
[Display(Name = "Birth Date")]
[Required]
[EmailAddress]
[Display(Name = "Email")]
[Required]
[StringLength(100, ErrorMessage = "The {0} must be at least {2} and at max {1} characters long.",
MinimumLength = 6)]
[Display(Name = "Password")]
[Display(Name = "Confirm password")]
[Compare("Password", ErrorMessage = "The password and confirmation password do not match.")]
public string ConfirmPassword { get; set; }
}

{
{
var user = new WebApp1User {
UserName = Input.Email,
Email = Input.Email,
Name = Input.Name,
DOB = Input.DOB
};
{

pageHandler: null,

here</a>.");

}
{
}
}

return Page();
}
Update the Areas/Identity/Pages/Account/Register.cshtml with the following highlighted markup:
@page
@model RegisterModel
@{
ViewData["Title"] = "Register";
}
<div class="row">
<form asp-route-returnUrl="@Model.ReturnUrl" method="post">
<h4>Create a new account.</h4>
<hr />
<div asp-validation-summary="All" class="text-danger"></div>
<label asp-for="Input.Name"></label>
<input asp-for="Input.Name" class="form-control" />
<span asp-validation-for="Input.Name" class="text-danger"></span>
</div>
<label asp-for="Input.DOB"></label>
<input asp-for="Input.DOB" class="form-control" />
<span asp-validation-for="Input.DOB" class="text-danger"></span>
</div>
<label asp-for="Input.Email"></label>
<span asp-validation-for="Input.Email" class="text-danger"></span>
</div>
<label asp-for="Input.Password"></label>
<input asp-for="Input.Password" class="form-control" />
<span asp-validation-for="Input.Password" class="text-danger"></span>
</div>
<label asp-for="Input.ConfirmPassword"></label>
<input asp-for="Input.ConfirmPassword" class="form-control" />
<span asp-validation-for="Input.ConfirmPassword" class="text-danger"></span>
</div>
<button type="submit" class="btn btn-default">Register</button>
</form>
</div>
</div>
@section Scripts {
<partial name="_ValidationScriptsPartial" />
}
Build the project.

Add a migration for the custom user data
Visual Studio
.NET Core CLI
Add-Migration CustomUserData
Update-Database
Test create, view, download, delete custom user data
Test the app:
Register a new user.
View the custom user data on the /Identity/Account/Manage page.
Download and view the users personal data from the /Identity/Account/Manage/PersonalData page.
Identity model customization in ASP.NET Core
By Arthur Vickers
ASP.NET Core Identity provides a framework for managing and storing user accounts in ASP.NET Core apps.
Identity is added to your project when Individual User Accounts is selected as the authentication mechanism. By
default, Identity makes use of an Entity Framework (EF ) Core data model. This article describes how to customize
the Identity model.
Identity and EF Core Migrations

Before examining the model, it's useful to understand how Identity works with EF Core Migrations to create and
update a database. At the top level, the process is:
1. Define or update a data model in code.
2. Add a Migration to translate this model into changes that can be applied to the database.
3. Check that the Migration correctly represents your intentions.
4. Apply the Migration to update the database to be in sync with the model.
5. Repeat steps 1 through 4 to further refine the model and keep the database in sync.
Use one of the following approaches to add and apply Migrations:
The Package Manager Console (PMC ) window if using Visual Studio. For more information, see EF Core
PMC tools.
The .NET Core CLI if using the command line. For more information, see EF Core .NET command line tools.
Clicking the Apply Migrations button on the error page when the app is run.
ASP.NET Core has a development-time error page handler. The handler can apply migrations when the app is run.
For production apps, it's often more appropriate to generate SQL scripts from the migrations and deploy database
changes as part of a controlled app and database deployment.
When a new app using Identity is created, steps 1 and 2 above have already been completed. That is, the initial data
model already exists, and the initial migration has been added to the project. The initial migration still needs to be
applied to the database. The initial migration can be applied via one of the following approaches:
Run Update-Database in PMC.
Run dotnet ef database update in a command shell.
Click the Apply Migrations button on the error page when the app is run.
Repeat the preceding steps as changes are made to the model.
The Identity model

Entity types
The Identity model consists of the following entity types.
ENTITY TYPE DESCRIPTION
User Represents the user.

ENTITY TYPE DESCRIPTION
Role Represents a role.
UserClaim Represents a claim that a user possesses.
UserToken Represents an authentication token for a user.
UserLogin Associates a user with a login.
RoleClaim Represents a claim that's granted to all users within a role.
UserRole A join entity that associates users and roles.
Entity type relationships

The entity types are related to each other in the following ways:
Each User can have many UserClaims .
Each User can have many UserLogins .
Each User can have many UserTokens .
Each Role can have many associated RoleClaims .
Each User can have many associated Roles , and each Role can be associated with many Users . This is a
many-to-many relationship that requires a join table in the database. The join table is represented by the
UserRole entity.
Default model configuration

Identity defines many context classes that inherit from DbContext to configure and use the model. This
configuration is done using the EF Core Code First Fluent API in the OnModelCreating method of the context
class. The default configuration is:
builder.Entity<TUser>(b =>
{
// Primary key
b.HasKey(u => u.Id);
// Indexes for "normalized" username and email, to allow efficient lookups

b.HasIndex(u => u.NormalizedUserName).HasName("UserNameIndex").IsUnique();
b.HasIndex(u => u.NormalizedEmail).HasName("EmailIndex");
// Maps to the AspNetUsers table

b.ToTable("AspNetUsers");
// A concurrency token for use with the optimistic concurrency checking

b.Property(u => u.ConcurrencyStamp).IsConcurrencyToken();
// Limit the size of columns to use efficient database types

b.Property(u => u.UserName).HasMaxLength(256);
b.Property(u => u.NormalizedUserName).HasMaxLength(256);
b.Property(u => u.Email).HasMaxLength(256);
b.Property(u => u.NormalizedEmail).HasMaxLength(256);
// The relationships between User and other entity types

// Note that these relationships are configured with no navigation properties
// Each User can have many UserClaims

b.HasMany<TUserClaim>().WithOne().HasForeignKey(uc => uc.UserId).IsRequired();
// Each User can have many UserLogins

b.HasMany<TUserLogin>().WithOne().HasForeignKey(ul => ul.UserId).IsRequired();
// Each User can have many UserTokens

b.HasMany<TUserToken>().WithOne().HasForeignKey(ut => ut.UserId).IsRequired();
// Each User can have many entries in the UserRole join table
b.HasMany<TUserRole>().WithOne().HasForeignKey(ur => ur.UserId).IsRequired();
});
builder.Entity<TUserClaim>(b =>
{
// Primary key
b.HasKey(uc => uc.Id);
// Maps to the AspNetUserClaims table

b.ToTable("AspNetUserClaims");
});
builder.Entity<TUserLogin>(b =>
{
// Composite primary key consisting of the LoginProvider and the key to use
// with that provider
b.HasKey(l => new { l.LoginProvider, l.ProviderKey });
// Limit the size of the composite key columns due to common DB restrictions
b.Property(l => l.LoginProvider).HasMaxLength(128);
b.Property(l => l.ProviderKey).HasMaxLength(128);
// Maps to the AspNetUserLogins table

b.ToTable("AspNetUserLogins");
});
builder.Entity<TUserToken>(b =>
{
// Composite primary key consisting of the UserId, LoginProvider and Name
b.HasKey(t => new { t.UserId, t.LoginProvider, t.Name });
// Limit the size of the composite key columns due to common DB restrictions
b.Property(t => t.LoginProvider).HasMaxLength(maxKeyLength);
b.Property(t => t.Name).HasMaxLength(maxKeyLength);
// Maps to the AspNetUserTokens table

b.ToTable("AspNetUserTokens");
});
builder.Entity<TRole>(b =>
{
// Primary key
b.HasKey(r => r.Id);
// Index for "normalized" role name to allow efficient lookups

b.HasIndex(r => r.NormalizedName).HasName("RoleNameIndex").IsUnique();
// Maps to the AspNetRoles table

b.ToTable("AspNetRoles");
// A concurrency token for use with the optimistic concurrency checking

b.Property(r => r.ConcurrencyStamp).IsConcurrencyToken();
// Limit the size of columns to use efficient database types

b.Property(u => u.Name).HasMaxLength(256);
b.Property(u => u.NormalizedName).HasMaxLength(256);
// The relationships between Role and other entity types

// Note that these relationships are configured with no navigation properties
// Each Role can have many entries in the UserRole join table
b.HasMany<TUserRole>().WithOne().HasForeignKey(ur => ur.RoleId).IsRequired();
// Each Role can have many associated RoleClaims
b.HasMany<TRoleClaim>().WithOne().HasForeignKey(rc => rc.RoleId).IsRequired();
});
builder.Entity<TRoleClaim>(b =>
{
// Primary key
b.HasKey(rc => rc.Id);
// Maps to the AspNetRoleClaims table

b.ToTable("AspNetRoleClaims");
});
builder.Entity<TUserRole>(b =>
{
// Primary key
b.HasKey(r => new { r.UserId, r.RoleId });
// Maps to the AspNetUserRoles table

b.ToTable("AspNetUserRoles");
});
Model generic types

Identity defines default Common Language Runtime (CLR ) types for each of the entity types listed above. These
types are all prefixed with Identity:
IdentityUser
IdentityRole
IdentityUserClaim
IdentityUserToken
IdentityUserLogin
IdentityRoleClaim
IdentityUserRole
Rather than using these types directly, the types can be used as base classes for the app's own types. The
DbContext classes defined by Identity are generic, such that different CLR types can be used for one or more of the
entity types in the model. These generic types also allow the User primary key (PK) data type to be changed.
When using Identity with support for roles, an IdentityDbContext class should be used. For example:
// Uses all the built-in Identity types
// Uses `string` as the key type
public class IdentityDbContext
: IdentityDbContext<IdentityUser, IdentityRole, string>
{
}
// Uses the built-in Identity types except with a custom User type
public class IdentityDbContext<TUser>
: IdentityDbContext<TUser, IdentityRole, string>
where TUser : IdentityUser
{
}
// Uses the built-in Identity types except with custom User and Role types
// The key type is defined by TKey
public class IdentityDbContext<TUser, TRole, TKey> : IdentityDbContext<
TUser, TRole, TKey, IdentityUserClaim<TKey>, IdentityUserRole<TKey>,
IdentityUserLogin<TKey>, IdentityRoleClaim<TKey>, IdentityUserToken<TKey>>
where TUser : IdentityUser<TKey>
where TRole : IdentityRole<TKey>
where TKey : IEquatable<TKey>
{
}
// No built-in Identity types are used; all are specified by generic arguments
public abstract class IdentityDbContext<
TUser, TRole, TKey, TUserClaim, TUserRole, TUserLogin, TRoleClaim, TUserToken>
: IdentityUserContext<TUser, TKey, TUserClaim, TUserLogin, TUserToken>
where TRole : IdentityRole<TKey>
where TUserClaim : IdentityUserClaim<TKey>
where TUserRole : IdentityUserRole<TKey>
where TUserLogin : IdentityUserLogin<TKey>
where TRoleClaim : IdentityRoleClaim<TKey>
where TUserToken : IdentityUserToken<TKey>
It's also possible to use Identity without roles (only claims), in which case an IdentityUserContext<TUser> class
should be used:
// Uses the built-in non-role Identity types except with a custom User type
public class IdentityUserContext<TUser>
: IdentityUserContext<TUser, string>
where TUser : IdentityUser
{
}
// Uses the built-in non-role Identity types except with a custom User type
public class IdentityUserContext<TUser, TKey> : IdentityUserContext<
TUser, TKey, IdentityUserClaim<TKey>, IdentityUserLogin<TKey>,
IdentityUserToken<TKey>>
{
}
// No built-in Identity types are used; all are specified by generic arguments, with no roles
public abstract class IdentityUserContext<
TUser, TKey, TUserClaim, TUserLogin, TUserToken> : DbContext
where TUserClaim : IdentityUserClaim<TKey>
where TUserLogin : IdentityUserLogin<TKey>
where TUserToken : IdentityUserToken<TKey>
{
}
Customize the model

The starting point for model customization is to derive from the appropriate context type. See the Model generic
types section. This context type is customarily called ApplicationDbContext and is created by the ASP.NET Core
templates.
The context is used to configure the model in two ways:
Supplying entity and key types for the generic type parameters.
Overriding OnModelCreating to modify the mapping of these types.
When overriding OnModelCreating , base.OnModelCreating should be called first; the overriding configuration
should be called next. EF Core generally has a last-one-wins policy for configuration. For example, if the ToTable
method for an entity type is called first with one table name and then again later with a different table name, the
table name in the second call is used.
Custom user data
Custom user data is supported by inheriting from IdentityUser . It's customary to name this type ApplicationUser
:

{
public string CustomTag { get; set; }
}
Use the ApplicationUser type as a generic argument for the context:

public class ApplicationDbContext : IdentityDbContext<ApplicationUser>
{
public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
: base(options)
{
}
}
There's no need to override OnModelCreating in the ApplicationDbContext class. EF Core maps the CustomTag
property by convention. However, the database needs to be updated to create a new CustomTag column. To create
the column, add a migration, and then update the database as described in Identity and EF Core Migrations.
Update Startup.ConfigureServices to use the new ApplicationUser class:
services.AddDefaultIdentity<ApplicationUser>()
.AddDefaultUI();
In ASP.NET Core 2.1 or later, Identity is provided as a Razor Class Library. For more information, see Scaffold
Identity in ASP.NET Core projects. Consequently, the preceding code requires a call to AddDefaultUI. If the Identity
scaffolder was used to add Identity files to the project, remove the call to AddDefaultUI . For more information, see:
Scaffold Identity
Add, download, and delete custom user data to Identity
.AddEntityFrameworkStores<ApplicationDbContext, Guid>()
Change the primary key type

A change to the PK column's data type after the database has been created is problematic on many database
systems. Changing the PK typically involves dropping and re-creating the table. Therefore, key types should be
specified in the initial migration when the database is created.
Follow these steps to change the PK type:
1. If the database was created before the PK change, run Drop-Database (PMC ) or dotnet ef database drop
(.NET Core CLI) to delete it.
2. After confirming deletion of the database, remove the initial migration with Remove-Migration (PMC ) or
dotnet ef migrations remove (.NET Core CLI ).
3. Update the ApplicationDbContext class to derive from IdentityDbContext<TUser,TRole,TKey>. Specify the

new key type for TKey . For example, to use a Guid key type:
public class ApplicationDbContext
: IdentityDbContext<IdentityUser<Guid>, IdentityRole<Guid>, Guid>
{
: base(options)
{
}
}
In the preceding code, the generic classes IdentityUser<TKey> and IdentityRole<TKey> must be specified to
use the new key type.
In the preceding code, the generic classes IdentityUser<TKey> and IdentityRole<TKey> must be specified to
use the new key type.
Startup.ConfigureServices must be updated to use the generic user:
services.AddDefaultIdentity<IdentityUser<Guid>>()
services.AddIdentity<IdentityUser<Guid>, IdentityRole>()
services.AddIdentity<IdentityUser<Guid>, IdentityRole>()
4. If a custom ApplicationUser class is being used, update the class to inherit from IdentityUser . For example:
using System;
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
public class ApplicationUser : IdentityUser<Guid>

{
}
using System;
public class ApplicationUser : IdentityUser<Guid>

{
}
Update ApplicationDbContext to reference the custom ApplicationUser class:

: IdentityDbContext<ApplicationUser, IdentityRole<Guid>, Guid>
{
: base(options)
{
}
}
Register the custom database context class when adding the Identity service in Startup.ConfigureServices :
.AddDefaultUI()
The primary key's data type is inferred by analyzing the DbContext object.
In ASP.NET Core 2.1 or later, Identity is provided as a Razor Class Library. For more information, see
Scaffold Identity in ASP.NET Core projects. Consequently, the preceding code requires a call to
AddDefaultUI. If the Identity scaffolder was used to add Identity files to the project, remove the call to
AddDefaultUI .
The AddEntityFrameworkStores method accepts a TKey type indicating the primary key's data type.
5. If a custom ApplicationRole class is being used, update the class to inherit from IdentityRole<TKey> . For
example:
using System;
public class ApplicationRole : IdentityRole<Guid>

{
}
Update ApplicationDbContext to reference the custom ApplicationRole class. For example, the following
class references a custom ApplicationUser and a custom ApplicationRole :
using System;
public class ApplicationDbContext :

IdentityDbContext<ApplicationUser, ApplicationRole, Guid>
{
: base(options)
{
}
}

{
{
});
services.AddIdentity<ApplicationUser, ApplicationRole>()
.AddDefaultUI()
services.AddMvc()
}
In ASP.NET Core 2.1 or later, Identity is provided as a Razor Class Library. For more information, see
Scaffold Identity in ASP.NET Core projects. Consequently, the preceding code requires a call to
AddDefaultUI. If the Identity scaffolder was used to add Identity files to the project, remove the call to
AddDefaultUI .
using System;

{
: base(options)
{
}
}
{
services.AddMvc()
{
options.Conventions.AuthorizeFolder("/Account/Manage");
options.Conventions.AuthorizePage("/Account/Logout");
});
}
using System;

{
: base(options)
{
}
}

{
services.AddMvc();
}
The AddEntityFrameworkStores method accepts a TKey type indicating the primary key's data type.
Add navigation properties
Changing the model configuration for relationships can be more difficult than making other changes. Care must be
taken to replace the existing relationships rather than create new, additional relationships. In particular, the changed
relationship must specify the same foreign key (FK) property as the existing relationship. For example, the
relationship between Users and UserClaims is, by default, specified as follows:
builder.Entity<TUser>(b =>
{
b.HasMany<TUserClaim>()
.WithOne()
.HasForeignKey(uc => uc.UserId)
.IsRequired();
});
The FK for this relationship is specified as the UserClaim.UserId property. HasMany and WithOne are called without
arguments to create the relationship without navigation properties.
Add a navigation property to ApplicationUser that allows associated UserClaims to be referenced from the user:

{
public virtual ICollection<IdentityUserClaim<string>> Claims { get; set; }
}
The TKey for IdentityUserClaim<TKey> is the type specified for the PK of users. In this case, TKey is string
because the defaults are being used. It's not the PK type for the UserClaim entity type.
Now that the navigation property exists, it must be configured in OnModelCreating :

{
: base(options)
{
}

{
base.OnModelCreating(modelBuilder);
modelBuilder.Entity<ApplicationUser>(b =>
{
b.HasMany(e => e.Claims)
.WithOne()
.IsRequired();
});
}
}
Notice that relationship is configured exactly as it was before, only with a navigation property specified in the call
to HasMany .
The navigation properties only exist in the EF model, not the database. Because the FK for the relationship hasn't
changed, this kind of model change doesn't require the database to be updated. This can be checked by adding a
migration after making the change. The Up and Down methods are empty.
Add all User navigation properties
Using the section above as guidance, the following example configures unidirectional navigation properties for all
relationships on User:
{
public virtual ICollection<IdentityUserLogin<string>> Logins { get; set; }
public virtual ICollection<IdentityUserToken<string>> Tokens { get; set; }
public virtual ICollection<IdentityUserRole<string>> UserRoles { get; set; }
}

{
: base(options)
{
}

{
{
.WithOne()
.IsRequired();

b.HasMany(e => e.Logins)
.WithOne()
.HasForeignKey(ul => ul.UserId)
.IsRequired();

b.HasMany(e => e.Tokens)
.WithOne()
.HasForeignKey(ut => ut.UserId)
.IsRequired();
b.HasMany(e => e.UserRoles)
.WithOne()
.HasForeignKey(ur => ur.UserId)
.IsRequired();
});
}
}
Add User and Role navigation properties

Using the section above as guidance, the following example configures navigation properties for all relationships
on User and Role:
{
public virtual ICollection<IdentityUserLogin<string>> Logins { get; set; }
public virtual ICollection<IdentityUserToken<string>> Tokens { get; set; }
public virtual ICollection<ApplicationUserRole> UserRoles { get; set; }
}
public class ApplicationRole : IdentityRole

{
}
public class ApplicationUserRole : IdentityUserRole<string>

{
public virtual ApplicationUser User { get; set; }
public virtual ApplicationRole Role { get; set; }
}
: IdentityDbContext<
ApplicationUser, ApplicationRole, string,
IdentityUserClaim<string>, ApplicationUserRole, IdentityUserLogin<string>,
IdentityRoleClaim<string>, IdentityUserToken<string>>
{
: base(options)
{
}

{
{
.WithOne()
.IsRequired();

.WithOne()
.IsRequired();

.WithOne()
.IsRequired();
.WithOne(e => e.User)
.IsRequired();
});
modelBuilder.Entity<ApplicationRole>(b =>
{
.WithOne(e => e.Role)
.HasForeignKey(ur => ur.RoleId)
.IsRequired();
});
}
}
Notes:
This example also includes the UserRole join entity, which is needed to navigate the many-to-many relationship
from Users to Roles.
Remember to change the types of the navigation properties to reflect that ApplicationXxx types are now being
used instead of IdentityXxx types.
Remember to use the ApplicationXxx in the generic ApplicationContext definition.
Add all navigation properties
Using the section above as guidance, the following example configures navigation properties for all relationships
on all entity types:

{
public virtual ICollection<ApplicationUserClaim> Claims { get; set; }
public virtual ICollection<ApplicationUserLogin> Logins { get; set; }
public virtual ICollection<ApplicationUserToken> Tokens { get; set; }
}
public class ApplicationRole : IdentityRole

{
public virtual ICollection<ApplicationRoleClaim> RoleClaims { get; set; }
}
public class ApplicationUserRole : IdentityUserRole<string>

{
}
public class ApplicationUserClaim : IdentityUserClaim<string>

{
}
public class ApplicationUserLogin : IdentityUserLogin<string>

{
}
public class ApplicationRoleClaim : IdentityRoleClaim<string>

{
}
public class ApplicationUserToken : IdentityUserToken<string>

{
}
: IdentityDbContext<
ApplicationUser, ApplicationRole, string,
ApplicationUserClaim, ApplicationUserRole, ApplicationUserLogin,
ApplicationRoleClaim, ApplicationUserToken>
{
: base(options)
{
}

{
{
.IsRequired();

.IsRequired();

.IsRequired();
.IsRequired();
});
modelBuilder.Entity<ApplicationRole>(b =>
{
.HasForeignKey(ur => ur.RoleId)
.IsRequired();
// Each Role can have many associated RoleClaims

b.HasMany(e => e.RoleClaims)
.HasForeignKey(rc => rc.RoleId)
.IsRequired();
});
}
}
Use composite keys

The preceding sections demonstrated changing the type of key used in the Identity model. Changing the Identity
key model to use composite keys isn't supported or recommended. Using a composite key with Identity involves
changing how the Identity manager code interacts with the model. This customization is beyond the scope of this
document.
Change table/column names and facets
To change the names of tables and columns, call base.OnModelCreating . Then, add configuration to override any of
the defaults. For example, to change the name of all the Identity tables:

{
modelBuilder.Entity<IdentityUser>(b =>
{
b.ToTable("MyUsers");
});
modelBuilder.Entity<IdentityUserClaim<string>>(b =>
{
b.ToTable("MyUserClaims");
});
modelBuilder.Entity<IdentityUserLogin<string>>(b =>
{
b.ToTable("MyUserLogins");
});
modelBuilder.Entity<IdentityUserToken<string>>(b =>
{
b.ToTable("MyUserTokens");
});
modelBuilder.Entity<IdentityRole>(b =>
{
b.ToTable("MyRoles");
});
modelBuilder.Entity<IdentityRoleClaim<string>>(b =>
{
b.ToTable("MyRoleClaims");
});
modelBuilder.Entity<IdentityUserRole<string>>(b =>
{
b.ToTable("MyUserRoles");
});
}
These examples use the default Identity types. If using an app type such as ApplicationUser , configure that type
instead of the default type.
The following example changes some column names:
{
{
b.Property(e => e.Email).HasColumnName("EMail");
});
modelBuilder.Entity<IdentityUserClaim<string>>(b =>
{
b.Property(e => e.ClaimType).HasColumnName("CType");
b.Property(e => e.ClaimValue).HasColumnName("CValue");
});
}
Some types of database columns can be configured with certain facets (for example, the maximum string length
allowed). The following example sets column maximum lengths for several string properties in the model:

{
{
b.Property(u => u.UserName).HasMaxLength(128);
b.Property(u => u.NormalizedUserName).HasMaxLength(128);
b.Property(u => u.Email).HasMaxLength(128);
b.Property(u => u.NormalizedEmail).HasMaxLength(128);
});
modelBuilder.Entity<IdentityUserToken<string>>(b =>
{
b.Property(t => t.LoginProvider).HasMaxLength(128);
b.Property(t => t.Name).HasMaxLength(128);
});
}
Map to a different schema

Schemas can behave differently across database providers. For SQL Server, the default is to create all tables in the
dbo schema. The tables can be created in a different schema. For example:

{
modelBuilder.HasDefaultSchema("notdbo");
}
Lazy loading
In this section, support for lazy-loading proxies in the Identity model is added. Lazy-loading is useful since it allows
navigation properties to be used without first ensuring they're loaded.
Entity types can be made suitable for lazy-loading in several ways, as described in the EF Core documentation. For
simplicity, use lazy-loading proxies, which requires:
Installation of the Microsoft.EntityFrameworkCore.Proxies package.
A call to UseLazyLoadingProxies inside AddDbContext<TContext>.
Public entity types with public virtual navigation properties.
The following example demonstrates calling UseLazyLoadingProxies in Startup.ConfigureServices :
services
.AddDbContext<ApplicationDbContext>(
b => b.UseSqlServer(connectionString)
.UseLazyLoadingProxies())
.AddDefaultIdentity<ApplicationUser>()
Refer to the preceding examples for guidance on adding navigation properties to the entity types.
Scaffold Identity in ASP.NET Core projects
Community OSS authentication options for ASP.NET
Core
This page contains community-provided, open source authentication options for ASP.NET Core. This page is
periodically updated as new providers become available.
OSS authentication providers

The list below is sorted alphabetically.
NAME DESCRIPTION
AspNet.Security.OpenIdConnect.Server (ASOS) ASOS is a low-level, protocol-first OpenID Connect server

framework for ASP.NET Core and OWIN/Katana.
Cierge Cierge is an OpenID Connect server that handles user signup,

login, profiles, management, and social logins.
Gluu Server Enterprise ready, open source software for identity, access
management (IAM), and single sign-on (SSO). For more
information, see the Gluu Product Documentation.
IdentityServer IdentityServer is an OpenID Connect and OAuth 2.0

framework for ASP.NET Core, officially certified by the OpenID
Foundation and under governance of the .NET Foundation.
For more information, see Welcome to IdentityServer4
(Documentation).
OpenIddict OpenIddict is an easy-to-use OpenID Connect server for

ASP.NET Core.
To add a provider, edit this page.

Configure ASP.NET Core Identity
ASP.NET Core Identity uses default values for settings such as password policy, lockout, and cookie configuration.
These settings can be overridden in the Startup class.
Identity options
The IdentityOptions class represents the options that can be used to configure the Identity system.
IdentityOptions must be set after calling AddIdentity or AddDefaultIdentity .
Claims Identity
IdentityOptions.ClaimsIdentity specifies the ClaimsIdentityOptions with the properties shown in the following
table.
RoleClaimType Gets or sets the claim type used for a ClaimTypes.Role

role claim.
SecurityStampClaimType Gets or sets the claim type used for the AspNet.Identity.SecurityStamp
security stamp claim.
UserIdClaimType Gets or sets the claim type used for the ClaimTypes.NameIdentifier
user identifier claim.
UserNameClaimType Gets or sets the claim type used for the ClaimTypes.Name
user name claim.
Lockout
Lockout is set in the PasswordSignInAsync method:
{
{
var result = await _signInManager.PasswordSignInAsync(Input.Email,
Input.Password, Input.RememberMe,
lockoutOnFailure: false);
{
_logger.LogInformation("User logged in.");
}
{
return RedirectToPage("./LoginWith2fa", new { ReturnUrl = returnUrl,
Input.RememberMe });
}
{
_logger.LogWarning("User account locked out.");
}
else
{
return Page();
}
}

return Page();
}
The preceding code is based on the Login Identity template.

Lockout options are set in StartUp.ConfigureServices :
{
// Default Lockout settings.
});
The preceding code sets the IdentityOptions LockoutOptions with default values.
A successful authentication resets the failed access attempts count and resets the clock.
IdentityOptions.Lockout specifies the LockoutOptions with the properties shown in the table.
AllowedForNewUsers Determines if a new user can be locked true

out.
DefaultLockoutTimeSpan The amount of time a user is locked out 5 minutes

when a lockout occurs.
MaxFailedAccessAttempts The number of failed access attempts 5

until a user is locked out, if lockout is
enabled.
Password
By default, Identity requires that passwords contain an uppercase character, lowercase character, a digit, and a non-
alphanumeric character. Passwords must be at least six characters long. PasswordOptions can be set in
{
// Default Password settings.
});
services.AddIdentity<ApplicationUser, IdentityRole>(options =>

{
})
{
});
IdentityOptions.Password specifies the PasswordOptions with the properties shown in the table.
RequireDigit Requires a number between 0-9 in the true

password.
RequiredLength The minimum length of the password. 6
| RequiredUniqueChars | Only applies to ASP.NET Core 2.0 or later.
Requires the number of distinct characters in the password. | 1 |

| RequireLowercase | Requires a lowercase character in the password. | true | | RequireNonAlphanumeric |
Requires a non-alphanumeric character in the password. | true | | RequireUppercase | Requires an uppercase
character in the password. | true |
Sign-in
The following code sets SignIn settings (to default values):
{
// Default SignIn settings.
options.SignIn.RequireConfirmedEmail = true;
options.SignIn.RequireConfirmedPhoneNumber = false;
});
services.AddIdentity<ApplicationUser, IdentityRole>(options =>

{
// Signin settings
options.SignIn.RequireConfirmedEmail = true;
options.SignIn.RequireConfirmedPhoneNumber = false;
})
IdentityOptions.SignIn specifies the SignInOptions with the properties shown in the table.
RequireConfirmedEmail Requires a confirmed email to sign in. false
RequireConfirmedPhoneNumber Requires a confirmed phone number to false

sign in.
Tokens
IdentityOptions.Tokens specifies the TokenOptions with the properties shown in the table.
AuthenticatorTokenProvider Gets or sets the AuthenticatorTokenProvider used to

validate two-factor sign-ins with an authenticator.
ChangeEmailTokenProvider Gets or sets the ChangeEmailTokenProvider used to

generate tokens used in email change confirmation emails.
ChangePhoneNumberTokenProvider Gets or sets the ChangePhoneNumberTokenProvider used to

generate tokens used when changing phone numbers.
EmailConfirmationTokenProvider Gets or sets the token provider used to generate tokens used
in account confirmation emails.
PasswordResetTokenProvider Gets or sets the IUserTwoFactorTokenProvider used to

generate tokens used in password reset emails.
ProviderMap Used to construct a User Token Provider with the key used as
the provider's name.
User
{
// Default User settings.
options.User.AllowedUserNameCharacters =
"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._@+";
});
IdentityOptions.User specifies the UserOptions with the properties shown in the table.
AllowedUserNameCharacters Allowed characters in the username. abcdefghijklmnopqrstuvwxyz

ABCDEFGHIJKLMNOPQRSTUVWXYZ
0123456789
-._@+
RequireUniqueEmail Requires each user to have a unique false

email.
Cookie settings
Configure the app's cookie in Startup.ConfigureServices . ConfigureApplicationCookie must be called after calling
AddIdentity or AddDefaultIdentity .
{
options.AccessDeniedPath = "/Identity/Account/AccessDenied";
options.Cookie.Name = "YourAppCookieName";
options.LoginPath = "/Identity/Account/Login";
// ReturnUrlParameter requires
//using Microsoft.AspNetCore.Authentication.Cookies;
options.ReturnUrlParameter = CookieAuthenticationDefaults.ReturnUrlParameter;
});
{
options.AccessDeniedPath = "/Account/AccessDenied";
options.Cookie.Name = "YourAppCookieName";
options.LoginPath = "/Account/Login";
// ReturnUrlParameter requires ùsing Microsoft.AspNetCore.Authentication.Cookies;`
options.ReturnUrlParameter = CookieAuthenticationDefaults.ReturnUrlParameter;
});
{
// Cookie settings
options.Cookies.ApplicationCookie.CookieName = "YourAppCookieName";
options.Cookies.ApplicationCookie.ExpireTimeSpan = TimeSpan.FromDays(150);
options.Cookies.ApplicationCookie.LoginPath = "/Account/LogIn";
options.Cookies.ApplicationCookie.AccessDeniedPath = "/Account/AccessDenied";
options.Cookies.ApplicationCookie.AutomaticAuthenticate = true;
// Requires ùsing Microsoft.AspNetCore.Authentication.Cookies;`
options.Cookies.ApplicationCookie.AuthenticationScheme =
CookieAuthenticationDefaults.AuthenticationScheme;
options.Cookies.ApplicationCookie.ReturnUrlParameter = CookieAuthenticationDefaults.ReturnUrlParameter;
});
For more information, see CookieAuthenticationOptions.

Configure Windows Authentication in ASP.NET Core

Windows Authentication can be configured for ASP.NET Core apps hosted with IIS, HTTP.sys, or WebListener.
Windows Authentication relies on the operating system to authenticate users of ASP.NET Core apps. You can
use Windows Authentication when your server runs on a corporate network using Active Directory domain
identities or other Windows accounts to identify users. Windows Authentication is best suited to intranet
environments in which users, client applications, and web servers belong to the same Windows domain.
Learn more about Windows Authentication and installing it for IIS.
Enable Windows Authentication in an ASP.NET Core app

The Visual Studio Web Application template can be configured to support Windows Authentication.
Use the Windows Authentication app template
In Visual Studio:
1. Create a new ASP.NET Core Web Application.
2. Select Web Application from the list of templates.
3. Select the Change Authentication button and select Windows Authentication.
Run the app. The username appears in the top right of the app.
For development work using IIS Express, the template provides all the configuration necessary to use Windows
Authentication. The following section shows how to manually configure an ASP.NET Core app for Windows
Authentication.
Visual Studio settings for Windows and anonymous authentication
The Visual Studio project Properties page's Debug tab provides check boxes for Windows Authentication and
anonymous authentication.
Alternatively, these two properties can be configured in the launchSettings.json file:
{
"iisSettings": {
"windowsAuthentication": true,
"anonymousAuthentication": false,
"iisExpress": {
"applicationUrl": "http://localhost:52171/",
"sslPort": 0
}
} // additional options trimmed
}
Enable Windows Authentication with IIS

IIS uses the ASP.NET Core Module to host ASP.NET Core apps. Windows Authentication is configured in IIS,
not the app. The following sections show how to use IIS Manager to configure an ASP.NET Core app to use
Windows Authentication.
IIS configuration
Enable the IIS Role Service for Windows Authentication. For more information, see Enable Windows
Authentication in IIS Role Services (see Step 2).
IIS Integration Middleware is configured to automatically authenticate requests by default. For more
information, see Host ASP.NET Core on Windows with IIS: IIS options (AutomaticAuthentication).
The ASP.NET Core Module is configured to forward the Windows Authentication token to the app by default.
For more information, see ASP.NET Core Module configuration reference: Attributes of the aspNetCore
element.
Create a new IIS site
Specify a name and folder and allow it to create a new application pool.
Customize authentication
Open the Authentication features for the site.
Disable Anonymous Authentication and enable Windows Authentication.

Publish your project to the IIS site folder
Using Visual Studio or the .NET Core CLI, publish the app to the destination folder.
Learn more about publishing to IIS.

Launch the app to verify Windows Authentication is working.
Enable Windows Authentication with HTTP.sys

Although Kestrel doesn't support Windows Authentication, you can use HTTP.sys to support self-hosted
scenarios on Windows. The following example configures the app's web host to use HTTP.sys with Windows
Authentication:

{
public static void Main(string[] args) =>

{
options.Authentication.Schemes =
AuthenticationSchemes.NTLM | AuthenticationSchemes.Negotiate;
options.Authentication.AllowAnonymous = false;
})
.Build();
}
NOTE
HTTP.sys delegates to kernel mode authentication with the Kerberos authentication protocol. User mode authentication
isn't supported with Kerberos and HTTP.sys. The machine account must be used to decrypt the Kerberos token/ticket
that's obtained from Active Directory and forwarded by the client to the server to authenticate the user. Register the
Service Principal Name (SPN) for the host, not the user of the app.
Enable Windows Authentication with WebListener

Although Kestrel doesn't support Windows Authentication, you can use WebListener to support self-hosted
scenarios on Windows. The following example configures the app's web host to use WebListener with Windows
Authentication:

{
{
.UseWebListener(options =>
{
options.ListenerSettings.Authentication.Schemes =
AuthenticationSchemes.Negotiate | AuthenticationSchemes.NTLM;
options.ListenerSettings.Authentication.AllowAnonymous = false;
})
.Build();
host.Run();
}
}
NOTE
WebListener delegates to kernel mode authentication with the Kerberos authentication protocol. User mode
authentication isn't supported with Kerberos and WebListener. The machine account must be used to decrypt the
Kerberos token/ticket that's obtained from Active Directory and forwarded by the client to the server to authenticate the
user. Register the Service Principal Name (SPN) for the host, not the user of the app.
Work with Windows Authentication
The configuration state of anonymous access determines the way in which the [Authorize] and
[AllowAnonymous] attributes are used in the app. The following two sections explain how to handle the
disallowed and allowed configuration states of anonymous access.
Disallow anonymous access
When Windows Authentication is enabled and anonymous access is disabled, the [Authorize] and
[AllowAnonymous] attributes have no effect. If the IIS site (or HTTP.sys or WebListener server ) is configured to
disallow anonymous access, the request never reaches your app. For this reason, the [AllowAnonymous] attribute
isn't applicable.
Allow anonymous access
When both Windows Authentication and anonymous access are enabled, use the [Authorize] and
[AllowAnonymous] attributes. The [Authorize] attribute allows you to secure pieces of the app which truly do
require Windows Authentication. The [AllowAnonymous] attribute overrides [Authorize] attribute usage within
apps which allow anonymous access. See Simple Authorization for attribute usage details.
In ASP.NET Core 2.x, the [Authorize] attribute requires additional configuration in Startup.cs to challenge
anonymous requests for Windows Authentication. The recommended configuration varies slightly based on the
web server being used.
NOTE
By default, users who lack authorization to access a page are presented with an empty HTTP 403 response. The
StatusCodePages middleware can be configured to provide users with a better "Access Denied" experience.
IIS
If using IIS, add the following to the ConfigureServices method:
// IISDefaults requires the following import:

// using Microsoft.AspNetCore.Server.IISIntegration;
services.AddAuthentication(IISDefaults.AuthenticationScheme);
HTTP.sys
If using HTTP.sys, add the following to the ConfigureServices method:
// HttpSysDefaults requires the following import:

// using Microsoft.AspNetCore.Server.HttpSys;
services.AddAuthentication(HttpSysDefaults.AuthenticationScheme);
Impersonation
ASP.NET Core doesn't implement impersonation. Apps run with the application identity for all requests, using
app pool or process identity. If you need to explicitly perform an action on behalf of a user, use
WindowsIdentity.RunImpersonated . Run a single action in this context and then close the context.
{
try
{
var user = (WindowsIdentity)context.User.Identity;
.WriteAsync($"User: {user.Name}\tState: {user.ImpersonationLevel}\n");
WindowsIdentity.RunImpersonated(user.AccessToken, () =>
{
var impersonatedUser = WindowsIdentity.GetCurrent();
var message =
$"User: {impersonatedUser.Name}\tState: {impersonatedUser.ImpersonationLevel}";
var bytes = Encoding.UTF8.GetBytes(message);

context.Response.Body.Write(bytes, 0, bytes.Length);
});
}
catch (Exception e)
{
await context.Response.WriteAsync(e.ToString());
}
});
Note that RunImpersonated doesn't support asynchronous operations and shouldn't be used for complex
scenarios. For example, wrapping entire requests or middleware chains isn't supported or recommended.
Custom storage providers for ASP.NET Core Identity
By Steve Smith
ASP.NET Core Identity is an extensible system which enables you to create a custom storage provider and connect
it to your app. This topic describes how to create a customized storage provider for ASP.NET Core Identity. It
covers the important concepts for creating your own storage provider, but isn't a step-by-step walkthrough.
Introduction
By default, the ASP.NET Core Identity system stores user information in a SQL Server database using Entity
Framework Core. For many apps, this approach works well. However, you may prefer to use a different persistence
mechanism or data schema. For example:
You use Azure Table Storage or another data store.
Your database tables have a different structure.
You may wish to use a different data access approach, such as Dapper.
In each of these cases, you can write a customized provider for your storage mechanism and plug that provider
into your app.
ASP.NET Core Identity is included in project templates in Visual Studio with the "Individual User Accounts" option.
When using the .NET Core CLI, add -au Individual :
dotnet new mvc -au Individual

dotnet new webapi -au Individual
The ASP.NET Core Identity architecture

ASP.NET Core Identity consists of classes called managers and stores. Managers are high-level classes which an
app developer uses to perform operations, such as creating an Identity user. Stores are lower-level classes that
specify how entities, such as users and roles, are persisted. Stores follow the repository pattern and are closely
coupled with the persistence mechanism. Managers are decoupled from stores, which means you can replace the
persistence mechanism without changing your application code (except for configuration).
The following diagram shows how a web app interacts with the managers, while stores interact with the data
access layer.
To create a custom storage provider, create the data source, the data access layer, and the store classes that interact
with this data access layer (the green and grey boxes in the diagram above). You don't need to customize the
managers or your app code that interacts with them (the blue boxes above).
When creating a new instance of UserManager or RoleManager you provide the type of the user class and pass an
instance of the store class as an argument. This approach enables you to plug your customized classes into
ASP.NET Core.
Reconfigure app to use new storage provider shows how to instantiate UserManager and RoleManager with a
customized store.
ASP.NET Core Identity stores data types

ASP.NET Core Identity data types are detailed in the following sections:
Users
Registered users of your web site. The IdentityUser type may be extended or used as an example for your own
custom type. You don't need to inherit from a particular type to implement your own custom identity storage
solution.
User Claims
A set of statements (or Claims) about the user that represent the user's identity. Can enable greater expression of
the user's identity than can be achieved through roles.
User Logins
Information about the external authentication provider (like Facebook or a Microsoft account) to use when logging
in a user. Example
Roles
Authorization groups for your site. Includes the role Id and role name (like "Admin" or "Employee"). Example
The data access layer

This topic assumes you are familiar with the persistence mechanism that you are going to use and how to create
entities for that mechanism. This topic doesn't provide details about how to create the repositories or data access
classes; it provides some suggestions about design decisions when working with ASP.NET Core Identity.
You have a lot of freedom when designing the data access layer for a customized store provider. You only need to
create persistence mechanisms for features that you intend to use in your app. For example, if you are not using
roles in your app, you don't need to create storage for roles or user role associations. Your technology and existing
infrastructure may require a structure that's very different from the default implementation of ASP.NET Core
Identity. In your data access layer, you provide the logic to work with the structure of your storage implementation.
The data access layer provides the logic to save the data from ASP.NET Core Identity to a data source. The data
access layer for your customized storage provider might include the following classes to store user and role
information.
Context class
Encapsulates the information to connect to your persistence mechanism and execute queries. Several data classes
require an instance of this class, typically provided through dependency injection. Example.
User Storage
Stores and retrieves user information (such as user name and password hash). Example
Role Storage
Stores and retrieves role information (such as the role name). Example
UserClaims Storage
Stores and retrieves user claim information (such as the claim type and value). Example
UserLogins Storage
Stores and retrieves user login information (such as an external authentication provider). Example
UserRole Storage
Stores and retrieves which roles are assigned to which users. Example
TIP: Only implement the classes you intend to use in your app.
In the data access classes, provide code to perform data operations for your persistence mechanism. For example,
within a custom provider, you might have the following code to create a new user in the store class:
public async Task<IdentityResult> CreateAsync(ApplicationUser user,

CancellationToken cancellationToken = default(CancellationToken))
{
cancellationToken.ThrowIfCancellationRequested();
if (user == null) throw new ArgumentNullException(nameof(user));
return await _usersTable.CreateAsync(user);

}
The implementation logic for creating the user is in the _usersTable.CreateAsync method, shown below.
Customize the user class

When implementing a storage provider, create a user class which is equivalent to the IdentityUser class.
At a minimum, your user class must include an Id and a UserName property.
The IdentityUser class defines the properties that the UserManager calls when performing requested operations.
The default type of the Id property is a string, but you can inherit from
IdentityUser<TKey, TUserClaim, TUserRole, TUserLogin, TUserToken> and specify a different type. The framework
expects the storage implementation to handle data type conversions.
Customize the user store

Create a UserStore class that provides the methods for all data operations on the user. This class is equivalent to
the UserStore<TUser> class. In your UserStore class, implement IUserStore<TUser> and the optional interfaces
required. You select which optional interfaces to implement based on the functionality provided in your app.
Optional interfaces
IUserRoleStore
IUserClaimStore
IUserPasswordStore
IUserSecurityStampStore
IUserEmailStore
IPhoneNumberStore
IQueryableUserStore
IUserLoginStore
IUserTwoFactorStore
IUserLockoutStore
The optional interfaces inherit from IUserStore<TUser> . You can see a partially implemented sample user store in
the sample app.
Within the UserStore class, you use the data access classes that you created to perform operations. These are
passed in using dependency injection. For example, in the SQL Server with Dapper implementation, the UserStore
class has the CreateAsync method which uses an instance of DapperUsersTable to insert a new record:
public async Task<IdentityResult> CreateAsync(ApplicationUser user)

{
string sql = "INSERT INTO dbo.CustomUser " +
"VALUES (@id, @Email, @EmailConfirmed, @PasswordHash, @UserName)";
int rows = await _connection.ExecuteAsync(sql, new { user.Id, user.Email, user.EmailConfirmed,

user.PasswordHash, user.UserName });
if(rows > 0)
{
return IdentityResult.Success;
}
return IdentityResult.Failed(new IdentityError { Description = $"Could not insert user {user.Email}." });
}
Interfaces to implement when customizing user store

IUserStore
The IUserStore<TUser> interface is the only interface you must implement in the user store. It defines methods
for creating, updating, deleting, and retrieving users.
IUserClaimStore
The IUserClaimStore<TUser> interface defines the methods you implement to enable user claims. It contains
methods for adding, removing and retrieving user claims.
IUserLoginStore
The IUserLoginStore<TUser> defines the methods you implement to enable external authentication providers.
It contains methods for adding, removing and retrieving user logins, and a method for retrieving a user based
on the login information.
IUserRoleStore
The IUserRoleStore<TUser> interface defines the methods you implement to map a user to a role. It contains
methods to add, remove, and retrieve a user's roles, and a method to check if a user is assigned to a role.
IUserPasswordStore
The IUserPasswordStore<TUser> interface defines the methods you implement to persist hashed passwords. It
contains methods for getting and setting the hashed password, and a method that indicates whether the user
has set a password.
IUserSecurityStampStore
The IUserSecurityStampStore<TUser> interface defines the methods you implement to use a security stamp
for indicating whether the user's account information has changed. This stamp is updated when a user changes
the password, or adds or removes logins. It contains methods for getting and setting the security stamp.
IUserTwoFactorStore
The IUserTwoFactorStore<TUser> interface defines the methods you implement to support two factor
authentication. It contains methods for getting and setting whether two factor authentication is enabled for a
user.
IUserPhoneNumberStore
The IUserPhoneNumberStore<TUser> interface defines the methods you implement to store user phone
numbers. It contains methods for getting and setting the phone number and whether the phone number is
confirmed.
IUserEmailStore
The IUserEmailStore<TUser> interface defines the methods you implement to store user email addresses. It
contains methods for getting and setting the email address and whether the email is confirmed.
IUserLockoutStore
The IUserLockoutStore<TUser> interface defines the methods you implement to store information about
locking an account. It contains methods for tracking failed access attempts and lockouts.
IQueryableUserStore
The IQueryableUserStore<TUser> interface defines the members you implement to provide a queryable user
store.
You implement only the interfaces that are needed in your app. For example:
public class UserStore : IUserStore<IdentityUser>,

IUserClaimStore<IdentityUser>,
IUserLoginStore<IdentityUser>,
IUserRoleStore<IdentityUser>,
IUserPasswordStore<IdentityUser>,
IUserSecurityStampStore<IdentityUser>
{
// interface implementations not shown
}
IdentityUserClaim, IdentityUserLogin, and IdentityUserRole

The Microsoft.AspNet.Identity.EntityFramework namespace contains implementations of the IdentityUserClaim,
IdentityUserLogin, and IdentityUserRole classes. If you are using these features, you may want to create your own
versions of these classes and define the properties for your app. However, sometimes it's more efficient to not load
these entities into memory when performing basic operations (such as adding or removing a user's claim). Instead,
the backend store classes can execute these operations directly on the data source. For example, the
UserStore.GetClaimsAsync method can call the userClaimTable.FindByUserId(user.Id) method to execute a query
on that table directly and return a list of claims.
Customize the role class

When implementing a role storage provider, you can create a custom role type. It need not implement a particular
interface, but it must have an Id and typically it will have a Name property.
The following is an example role class:
using System;
namespace CustomIdentityProviderSample.CustomProvider
{
public class ApplicationRole
{
public Guid Id { get; set; } = Guid.NewGuid();
}
}
Customize the role store

You can create a RoleStore class that provides the methods for all data operations on roles. This class is equivalent
to the RoleStore<TRole> class. In the RoleStore class, you implement the IRoleStore<TRole> and optionally the
IQueryableRoleStore<TRole> interface.
IRoleStore<TRole>
The IRoleStore<TRole> interface defines the methods to implement in the role store class. It contains methods
for creating, updating, deleting, and retrieving roles.
RoleStore<TRole>
To customize RoleStore , create a class that implements the IRoleStore<TRole> interface.
Reconfigure app to use a new storage provider

Once you have implemented a storage provider, you configure your app to use it. If your app used the default
provider, replace it with your custom provider.
1. Remove the Microsoft.AspNetCore.EntityFramework.Identity NuGet package.
2. If the storage provider resides in a separate project or package, add a reference to it.
3. Replace all references to Microsoft.AspNetCore.EntityFramework.Identity with a using statement for the
namespace of your storage provider.
4. In the ConfigureServices method, change the AddIdentity method to use your custom types. You can create
your own extension methods for this purpose. See IdentityServiceCollectionExtensions for an example.
5. If you are using Roles, update the RoleManager to use your RoleStore class.
6. Update the connection string and credentials to your app's configuration.
Example:
{
// Add identity types
// Identity Services
services.AddTransient<IUserStore<ApplicationUser>, CustomUserStore>();
services.AddTransient<IRoleStore<ApplicationRole>, CustomRoleStore>();
string connectionString = Configuration.GetConnectionString("DefaultConnection");
services.AddTransient<SqlConnection>(e => new SqlConnection(connectionString));
services.AddTransient<DapperUsersTable>();
// additional configuration
}
References
Custom Storage Providers for ASP.NET 4.x Identity
ASP.NET Core Identity - This repository includes links to community maintained store providers.
Facebook, Google, and external provider
authentication in ASP.NET Core
By Valeriy Novytskyy and Rick Anderson

This tutorial demonstrates how to build an ASP.NET Core 2.x app that enables users to log in using OAuth 2.0
with credentials from external authentication providers.
Facebook, Twitter, Google, and Microsoft providers are covered in the following sections. Other providers are
available in third-party packages such as AspNet.Security.OAuth.Providers and
AspNet.Security.OpenId.Providers.
Enabling users to sign in with their existing credentials is convenient for the users and shifts many of the
complexities of managing the sign-in process onto a third party. For examples of how social logins can drive
traffic and customer conversions, see case studies by Facebook and Twitter.
Note: Packages presented here abstract a great deal of complexity of the OAuth authentication flow, but
understanding the details may become necessary when troubleshooting. Many resources are available; for
example, see Introduction to OAuth 2 or Understanding OAuth 2. Some issues can be resolved by looking at the
ASP.NET Core source code for the provider packages.
Create a New ASP.NET Core Project

In Visual Studio 2017, create a new project from the Start Page, or via File > New > Project.
Select the ASP.NET Core Web Application template available in Visual C# > .NET Core category:
Tap Web Application and verify Authentication is set to Individual User Accounts:
Note: This tutorial applies to ASP.NET Core 2.0 SDK version which can be selected at the top of the wizard.
Apply migrations
Run the app and select the Log in link.
Select the Register as a new user link.
Enter the email and password for the new account, and then select Register.
Follow the instructions to apply migrations.
Require SSL
OAuth 2.0 requires the use of SSL for authentication over the HTTPS protocol.
Note: Projects created using Web Application or Web API project templates for ASP.NET Core 2.x are
automatically configured to enable SSL and launch with https URL if the Individual User Accounts option was
selected on Change Authentication dialog in the project wizard as shown above.
Require SSL on your site by following the steps in Enforce SSL in an ASP.NET Core app topic.
Use SecretManager to store tokens assigned by login providers

Social login providers assign Application Id and Application Secret tokens during the registration process.
The exact token names vary by provider. These tokens represent the credentials your app uses to access their
API. The tokens constitute the "secrets" that can be linked to your app configuration with the help of Secret
Manager. Secret Manager is a more secure alternative to storing the tokens in a configuration file, such as
appsettings.json.
IMPORTANT
Secret Manager is for development purposes only. You can store and protect Azure test and production secrets with the
Azure Key Vault configuration provider.
Follow the steps in Safe storage of app secrets in development in ASP.NET Core topic to store tokens assigned
by each login provider below.
Setup login providers required by your application

Use the following topics to configure your application to use the respective providers:
Facebook instructions
Twitter instructions
Google instructions
Microsoft instructions
Other provider instructions
When the app requires multiple providers, chain the provider extension methods behind AddAuthentication:
services.AddAuthentication()
.AddMicrosoftAccount(microsoftOptions => { ... })
.AddGoogle(googleOptions => { ... })
.AddTwitter(twitterOptions => { ... })
.AddFacebook(facebookOptions => { ... });
Optionally set password

When you register with an external login provider, you don't have a password registered with the app. This
alleviates you from creating and remembering a password for the site, but it also makes you dependent on the
external login provider. If the external login provider is unavailable, you won't be able to log in to the web site.
To create a password and sign in using your email that you set during the sign in process with external providers:
Tap the Hello <email alias> link at the top right corner to navigate to the Manage view.
Tap Create
Set a valid password and you can use this to sign in with your email.
Next steps
This article introduced external authentication and explained the prerequisites required to add external
logins to your ASP.NET Core app.
Reference provider-specific pages to configure logins for the providers required by your app.
You may want to persist additional data about the user and their access and refresh tokens. For more
information, see Persist additional claims and tokens from external providers in ASP.NET Core.
Facebook external login setup in ASP.NET Core

This tutorial shows you how to enable your users to sign in with their Facebook account using a sample ASP.NET
Core 2.0 project created on the previous page. Facebook authentication requires the
Microsoft.AspNetCore.Authentication.Facebook NuGet package. We start by creating a Facebook App ID by
following the official steps.
Create the app in Facebook

Navigate to the Facebook Developers app page and sign in. If you don't already have a Facebook account,
use the Sign up for Facebook link on the login page to create one.
Tap the Add a New App button in the upper right corner to create a new App ID.
Fill out the form and tap the Create App ID button.
On the Select a product page, click Set Up on the Facebook Login card.
The Quickstart wizard will launch with Choose a Platform as the first page. Bypass the wizard for now by
clicking the Settings link in the menu on the left:
You are presented with the Client OAuth Settings page:

Enter your development URI with /signin-facebook appended into the Valid OAuth Redirect URIs field (for
example: https://localhost:44320/signin-facebook ). The Facebook authentication configured later in this
tutorial will automatically handle requests at /signin-facebook route to implement the OAuth flow.
NOTE
The URI /signin-facebook is set as the default callback of the Facebook authentication provider. You can change the default
callback URI while configuring the Facebook authentication middleware via the inherited
RemoteAuthenticationOptions.CallbackPath property of the FacebookOptions class.
Click Save Changes.

Click Settings > Basic link in the left navigation.
On this page, make a note of your App ID and your App Secret . You will add both into your ASP.NET
Core application in the next section:
When deploying the site you need to revisit the Facebook Login setup page and register a new public
URI.
Store Facebook App ID and App Secret

Link sensitive settings like Facebook App ID and App Secret to your application configuration using the Secret
Manager. For the purposes of this tutorial, name the tokens Authentication:Facebook:AppId and
Authentication:Facebook:AppSecret .
Execute the following commands to securely store App ID and App Secret using Secret Manager:
dotnet user-secrets set Authentication:Facebook:AppId <app-id>

dotnet user-secrets set Authentication:Facebook:AppSecret <app-secret>
Configure Facebook Authentication

ASP.NET Core 2.x
ASP.NET Core 1.x
Add the Facebook service in the ConfigureServices method in the Startup.cs file:
services.AddAuthentication().AddFacebook(facebookOptions =>
{
facebookOptions.AppId = Configuration["Authentication:Facebook:AppId"];
facebookOptions.AppSecret = Configuration["Authentication:Facebook:AppSecret"];
});
The call to AddIdentity configures the default scheme settings. The AddAuthentication(String) overload sets the
DefaultScheme property. The AddAuthentication(Action<AuthenticationOptions>) overload allows configuring
authentication options, which can be used to set up default authentication schemes for different purposes.
Subsequent calls to AddAuthentication override previously configured AuthenticationOptions properties.
AuthenticationBuilder extension methods that register an authentication handler may only be called once per
authentication scheme. Overloads exist that allow configuring the scheme properties, scheme name, and display
name.
See the FacebookOptions API reference for more information on configuration options supported by Facebook
authentication. Configuration options can be used to:
Request different information about the user.
Add query string arguments to customize the login experience.
Sign in with Facebook

Run your application and click Log in. You see an option to sign in with Facebook.
When you click on Facebook, you are redirected to Facebook for authentication:
Facebook authentication requests public profile and email address by default:

Once you enter your Facebook credentials you are redirected back to your site where you can set your email.
You are now logged in using your Facebook credentials:
Troubleshooting
ASP.NET Core 2.x only: If Identity isn't configured by calling services.AddIdentity in ConfigureServices ,
attempting to authenticate will result in ArgumentException: The 'SignInScheme' option must be provided. The
project template used in this tutorial ensures that this is done.
If the site database has not been created by applying the initial migration, you get A database operation failed
while processing the request error. Tap Apply Migrations to create the database and refresh to continue past
the error.
Next steps
This article showed how you can authenticate with Facebook. You can follow a similar approach to
authenticate with other providers listed on the previous page.
Once you publish your web site to Azure web app, you should reset the AppSecret in the Facebook
developer portal.
Set the Authentication:Facebook:AppId and Authentication:Facebook:AppSecret as application settings in
the Azure portal. The configuration system is set up to read keys from environment variables.
Twitter external login setup with ASP.NET Core

This tutorial shows you how to enable your users to sign in with their Twitter account using a sample ASP.NET
Core 2.0 project created on the previous page.
Create the app in Twitter

Navigate to https://apps.twitter.com/ and sign in. If you don't already have a Twitter account, use the Sign up
now link to create one. After signing in, the Application Management page is shown:
Tap Create New App and fill out the application Name, Description and public Website URI (this can be
temporary until you register the domain name):
Enter your development URI with /signin-twitter appended into the Valid OAuth Redirect URIs field (for
example: https://localhost:44320/signin-twitter ). The Twitter authentication scheme configured later in this
tutorial will automatically handle requests at /signin-twitter route to implement the OAuth flow.
NOTE
The URI segment /signin-twitter is set as the default callback of the Twitter authentication provider. You can change the
default callback URI while configuring the Twitter authentication middleware via the inherited
RemoteAuthenticationOptions.CallbackPath property of the TwitterOptions class.
Fill out the rest of the form and tap Create your Twitter application. New application details are displayed:
When deploying the site you'll need to revisit the Application Management page and register a new public
URI.
Storing Twitter ConsumerKey and ConsumerSecret

Link sensitive settings like Twitter Consumer Key and Consumer Secret to your application configuration using the
Secret Manager. For the purposes of this tutorial, name the tokens Authentication:Twitter:ConsumerKey and
Authentication:Twitter:ConsumerSecret .
These tokens can be found on the Keys and Access Tokens tab after creating your new Twitter application:
Configure Twitter Authentication
The project template used in this tutorial ensures that Microsoft.AspNetCore.Authentication.Twitter package is
already installed.
To install this package with Visual Studio 2017, right-click on the project and select Manage NuGet
Packages.
To install with .NET Core CLI, execute the following in your project directory:
dotnet add package Microsoft.AspNetCore.Authentication.Twitter
ASP.NET Core 2.x

ASP.NET Core 1.x
Add the Twitter service in the ConfigureServices method in Startup.cs file:
services.AddAuthentication().AddTwitter(twitterOptions =>
{
twitterOptions.ConsumerKey = Configuration["Authentication:Twitter:ConsumerKey"];
twitterOptions.ConsumerSecret = Configuration["Authentication:Twitter:ConsumerSecret"];
});
name.
See the TwitterOptions API reference for more information on configuration options supported by Twitter
authentication. This can be used to request different information about the user.
Sign in with Twitter

Run your application and click Log in. An option to sign in with Twitter appears:
Clicking on Twitter redirects to Twitter for authentication:

After entering your Twitter credentials, you are redirected back to the web site where you can set your email.
You are now logged in using your Twitter credentials:
Troubleshooting
If the site database has not been created by applying the initial migration, you will get A database operation
failed while processing the request error. Tap Apply Migrations to create the database and refresh to continue
past the error.
Next steps
This article showed how you can authenticate with Twitter. You can follow a similar approach to
Once you publish your web site to Azure web app, you should reset the ConsumerSecret in the Twitter
developer portal.
Set the Authentication:Twitter:ConsumerKey and Authentication:Twitter:ConsumerSecret as application
settings in the Azure portal. The configuration system is set up to read keys from environment variables.
Google external login setup in ASP.NET Core

This tutorial shows you how to enable your users to sign in with their Google+ account using a sample ASP.NET
Core 2.0 project created on the previous page. We start by following the official steps to create a new app in
Google API Console.
Create the app in Google API Console

Navigate to https://console.developers.google.com/projectselector/apis/library and sign in. If you don't already
have a Google account, use More options > Create account link to create one:
You are redirected to API Manager Library page:

Tap Create and enter your Project name:
After accepting the dialog, you are redirected back to the Library page allowing you to choose features for your
new app. Find Google+ API in the list and click on its link to add the API feature:
The page for the newly added API is displayed. Tap Enable to add Google+ sign in feature to your app:
After enabling the API, tap Create credentials to configure the secrets:
Choose:
Google+ API
Web server (e.g. node.js, Tomcat), and
User data:
Tap What credentials do I need? which takes you to the second step of app configuration, Create an OAuth
2.0 client ID:
Because we are creating a Google+ project with just one feature (sign in), we can enter the same Name for
the OAuth 2.0 client ID as the one we used for the project.
Enter your development URI with /signin-google appended into the Authorized redirect URIs field (for
example: https://localhost:44320/signin-google ). The Google authentication configured later in this
tutorial will automatically handle requests at /signin-google route to implement the OAuth flow.
NOTE
The URI segment /signin-google is set as the default callback of the Google authentication provider. You can change the
default callback URI while configuring the Google authentication middleware via the inherited
RemoteAuthenticationOptions.CallbackPath property of the GoogleOptions class.
Press TAB to add the Authorized redirect URIs entry.

Tap Create client ID, which takes you to the third step, Set up the OAuth 2.0 consent screen:
Enter your public facing Email address and the Product name shown for your app when Google+
prompts the user to sign in. Additional options are available under More customization options.
Tap Continue to proceed to the last step, Download credentials:
Tap Download to save a JSON file with application secrets, and Done to complete creation of the new
app.
When deploying the site you'll need to revisit the Google Console and register a new public url.
Store Google ClientID and ClientSecret

Link sensitive settings like Google Client ID and Client Secret to your application configuration using the
Secret Manager. For the purposes of this tutorial, name the tokens Authentication:Google:ClientId and
Authentication:Google:ClientSecret .
The values for these tokens can be found in the JSON file downloaded in the previous step under web.client_id
and web.client_secret .
Configure Google Authentication

ASP.NET Core 2.x
ASP.NET Core 1.x
Add the Google service in the ConfigureServices method in Startup.cs file:
services.AddAuthentication().AddGoogle(googleOptions =>
{
googleOptions.ClientId = Configuration["Authentication:Google:ClientId"];
googleOptions.ClientSecret = Configuration["Authentication:Google:ClientSecret"];
});
name.
See the GoogleOptions API reference for more information on configuration options supported by Google
authentication. This can be used to request different information about the user.
Sign in with Google

Run your application and click Log in. An option to sign in with Google appears:
When you click on Google, you are redirected to Google for authentication:
After entering your Google credentials, then you are redirected back to the web site where you can set your email.
You are now logged in using your Google credentials:
Troubleshooting
If you receive a 403 (Forbidden) error page from your own app when running in development mode (or break
into the debugger with the same error), ensure that Google+ API has been enabled in the API Manager
Library by following the steps listed earlier on this page. If the sign in doesn't work and you aren't getting any
errors, switch to development mode to make the issue easier to debug.
If the site database has not been created by applying the initial migration, you will get A database operation
failed while processing the request error. Tap Apply Migrations to create the database and refresh to continue
past the error.
Next steps
This article showed how you can authenticate with Google. You can follow a similar approach to
Once you publish your web site to Azure web app, you should reset the ClientSecret in the Google API
Console.
Set the Authentication:Google:ClientId and Authentication:Google:ClientSecret as application settings in
the Azure portal. The configuration system is set up to read keys from environment variables.
Microsoft Account external login setup with ASP.NET
Core

This tutorial shows you how to enable your users to sign in with their Microsoft account using a sample ASP.NET
Core 2.0 project created on the previous page.
Create the app in Microsoft Developer Portal

Navigate to https://apps.dev.microsoft.com and create or sign into a Microsoft account:
If you don't already have a Microsoft account, tap Create one! After signing in you are redirected to My
applications page:
Tap Add an app in the upper right corner and enter your Application Name and Contact Email:
For the purposes of this tutorial, clear the Guided Setup check box.
Tap Create to continue to the Registration page. Provide a Name and note the value of the Application
Id, which you use as ClientId later in the tutorial:
Tap Add Platform in the Platforms section and select the Web platform:
In the new Web platform section, enter your development URL with /signin-microsoft appended into the
Redirect URLs field (for example: https://localhost:44320/signin-microsoft ). The Microsoft authentication
scheme configured later in this tutorial will automatically handle requests at /signin-microsoft route to
implement the OAuth flow:
NOTE
The URI segment /signin-microsoft is set as the default callback of the Microsoft authentication provider. You can
change the default callback URI while configuring the Microsoft authentication middleware via the inherited
RemoteAuthenticationOptions.CallbackPath property of the MicrosoftAccountOptions class.
Tap Add URL to ensure the URL was added.

Fill out any other application settings if necessary and tap Save at the bottom of the page to save changes
to app configuration.
When deploying the site you'll need to revisit the Registration page and set a new public URL.
Store Microsoft Application Id and Password

Note the Application Id displayed on the Registration page.
Tap Generate New Password in the Application Secrets section. This displays a box where you can copy
the application password:
Link sensitive settings like Microsoft Application ID and Password to your application configuration using the
Secret Manager. For the purposes of this tutorial, name the tokens Authentication:Microsoft:ApplicationId and
Authentication:Microsoft:Password .
Configure Microsoft Account Authentication

The project template used in this tutorial ensures that Microsoft.AspNetCore.Authentication.MicrosoftAccount
package is already installed.
To install this package with Visual Studio 2017, right-click on the project and select Manage NuGet
Packages.
To install with .NET Core CLI, execute the following in your project directory:
dotnet add package Microsoft.AspNetCore.Authentication.MicrosoftAccount
ASP.NET Core 2.x

ASP.NET Core 1.x
Add the Microsoft Account service in the ConfigureServices method in Startup.cs file:
services.AddAuthentication().AddMicrosoftAccount(microsoftOptions =>
{
microsoftOptions.ClientId = Configuration["Authentication:Microsoft:ApplicationId"];
microsoftOptions.ClientSecret = Configuration["Authentication:Microsoft:Password"];
});
name.
Although the terminology used on Microsoft Developer Portal names these tokens ApplicationId and Password ,
they're exposed as ClientId and ClientSecret to the configuration API.
See the MicrosoftAccountOptions API reference for more information on configuration options supported by
Microsoft Account authentication. This can be used to request different information about the user.
Sign in with Microsoft Account

Run your application and click Log in. An option to sign in with Microsoft appears:
When you click on Microsoft, you are redirected to Microsoft for authentication. After signing in with your
Microsoft Account (if not already signed in) you will be prompted to let the app access your info:
Tap Yes and you will be redirected back to the web site where you can set your email.
You are now logged in using your Microsoft credentials:
Troubleshooting
If the Microsoft Account provider redirects you to a sign in error page, note the error title and description
query string parameters directly following the # (hashtag) in the Uri.
Although the error message seems to indicate a problem with Microsoft authentication, the most common
cause is your application Uri not matching any of the Redirect URIs specified for the Web platform.
attempting to authenticate will result in ArgumentException: The 'SignInScheme' option must be provided.
The project template used in this tutorial ensures that this is done.
If the site database has not been created by applying the initial migration, you will get A database
operation failed while processing the request error. Tap Apply Migrations to create the database and
refresh to continue past the error.
Next steps
This article showed how you can authenticate with Microsoft. You can follow a similar approach to
Once you publish your web site to Azure web app, you should create a new Password in the Microsoft
Developer Portal.
Set the Authentication:Microsoft:ApplicationId and Authentication:Microsoft:Password as application
settings in the Azure portal. The configuration system is set up to read keys from environment variables.
Short survey of other authentication providers
By Rick Anderson, Pranav Rastogi, and Valeriy Novytskyy

Here are set up instructions for some other common OAuth providers. Third-party NuGet packages such as the
ones maintained by aspnet-contrib can be used to complement authentication providers implemented by the
ASP.NET Core team.
Set up LinkedIn sign in: https://www.linkedin.com/developer/apps. See official steps.
Set up Instagram sign in: https://www.instagram.com/developer/register/. See official steps.
Set up Reddit sign in: https://www.reddit.com/login?
dest=https%3A%2F%2Ffanyv88.com%3A443%2Fhttps%2Fwww.reddit.com%2Fprefs%2Fapps. See official steps.
Set up Github sign in: https://github.com/login?
return_to=https%3A%2F%2Ffanyv88.com%3A443%2Fhttps%2Fgithub.com%2Fsettings%2Fapplications%2Fnew. See official steps.
Set up Yahoo sign in: https://login.yahoo.com/config/login?
src=devnet&.done=https%3A%2F%2Ffanyv88.com%3A443%2Fhttp%2Fdeveloper.yahoo.com%2Fapps%2Fcreate%2F. See official steps.
Set up Tumblr sign in: https://www.tumblr.com/oauth/apps. See official steps.
Set up Pinterest sign in: https://www.pinterest.com/login/?next=https%3A%2F%2Ffanyv88.com%3A443%2Fhttp%2Fdevsite%2Fapps%2F.
See official steps.
Set up Pocket sign in: https://getpocket.com/developer/apps/new. See official steps.
Set up Flickr sign in: https://www.flickr.com/services/apps/create. See official steps.
Set up Dribble sign in: https://dribbble.com/signup. See official steps.
Set up Vimeo sign in: https://vimeo.com/join. See official steps.
Set up SoundCloud sign in: https://soundcloud.com/you/apps/new. See official steps.
Set up VK sign in: https://vk.com/apps?act=manage. See official steps.
Multiple authentication providers

Persist additional claims and tokens from external
providers in ASP.NET Core
By Luke Latham
An ASP.NET Core app can establish additional claims and tokens from external authentication providers, such as
Facebook, Google, Microsoft, and Twitter. Each provider reveals different information about users on its platform,
but the pattern for receiving and transforming user data into additional claims is the same.
Prerequisite
Decide which external authentication providers to support in the app. For each provider, register the app and obtain
a client ID and client secret. For more information, see Facebook, Google, and external provider authentication in
ASP.NET Core. The sample app uses the Google authentication provider.
Authentication provider configuration

Set the client ID and client secret
The OAuth authentication provider establishes a trust relationship with an app using a client ID and client secret.
Client ID and client secret values are created for the app by the external authentication provider when the app is
registered with the provider. Each external provider that the app uses must be configured independently with the
provider's client ID and client secret. For more information, see the external authentication provider topics that apply
to your scenario:
Microsoft authentication
Other authentication providers
OpenIdConnect
The sample app configures the Google authentication provider with a client ID and client secret provided by Google:
services.AddAuthentication().AddGoogle(options =>
{
// Provide the Google Client ID
options.ClientId = "XXXXXXXXXXX.apps.googleusercontent.com";
// Provide the Google Secret
options.ClientSecret = "g4GZ2#...GD5Gg1x";
options.Scope.Add("https://www.googleapis.com/auth/plus.login");
options.ClaimActions.MapJsonKey(ClaimTypes.Gender, "gender");
options.SaveTokens = true;
options.Events.OnCreatingTicket = ctx =>
{
List<AuthenticationToken> tokens = ctx.Properties.GetTokens()
as List<AuthenticationToken>;
tokens.Add(new AuthenticationToken()
{
Name = "TicketCreated",
Value = DateTime.UtcNow.ToString()
});
ctx.Properties.StoreTokens(tokens);
};
});
Establish the authentication scope

Specify the list of permissions to retrieve from the provider by specifying the Scope. Authentication scopes for
common external providers appear in the following table.
PROVIDER SCOPE
Facebook https://www.facebook.com/dialog/oauth
Google https://www.googleapis.com/auth/plus.login
Microsoft https://login.microsoftonline.com/common/oauth2/v2.0/authorize
Twitter https://api.twitter.com/oauth/authenticate
The sample app adds the Google plus.login scope to request Google+ sign in permissions:
{
{
{
});
};
});
Map user data keys and create claims
In the provider's options, specify a MapJsonKey for each key in the external provider's JSON user data for the app
identity to read on sign in. For more information on claim types, see ClaimTypes.
The sample app creates a Gender claim from the gender key in Google user data:
{
{
{
});
};
});
In OnPostConfirmationAsync, an IdentityUser ( ApplicationUser ) is signed into the app with SignInAsync. During
the sign in process, the UserManager<TUser> can store an ApplicationUser claim for user data available from the
Principal.
In the sample app, OnPostConfirmationAsync (Account/ExternalLogin.cshtml.cs) establishes a Gender claim for the
signed in ApplicationUser :
public async Task<IActionResult> OnPostConfirmationAsync(
string returnUrl = null)
{
{
// Get the information about the user from the external login
// provider
var info = await _signInManager.GetExternalLoginInfoAsync();
if (info == null)
{
throw new ApplicationException(
"Error loading external login data during confirmation.");
}
var user = new ApplicationUser

{
Email = Input.Email
};
var result = await _userManager.CreateAsync(user);
{
result = await _userManager.AddLoginAsync(user, info);
{
// Copy over the gender claim
await _userManager.AddClaimAsync(user,
info.Principal.FindFirst(ClaimTypes.Gender));
// Include the access token in the properties

var props = new AuthenticationProperties();
props.StoreTokens(info.AuthenticationTokens);
await _signInManager.SignInAsync(user, props,

authenticationMethod: info.LoginProvider);
"User created an account using {Name} provider.",
info.LoginProvider);
return LocalRedirect(Url.GetLocalUrl(returnUrl));
}
}

{
}
}
ReturnUrl = returnUrl;
return Page();
}
Save the access token

SaveTokens defines whether access and refresh tokens should be stored in the AuthenticationProperties after a
successful authorization. SaveTokens is set to false by default to reduce the size of the final authentication cookie.
The sample app sets the value of SaveTokens to true in GoogleOptions:
{
{
{
});
};
});
When OnPostConfirmationAsync executes, store the access token (ExternalLoginInfo.AuthenticationTokens) from the
external provider in the ApplicationUser 's AuthenticationProperties .
The sample app saves the access token in:
OnPostConfirmationAsync – Executes for new user registration.
OnGetCallbackAsync – Executes when a previously registered user signs into the app.
Account/ExternalLogin.cshtml.cs:
public async Task<IActionResult> OnPostConfirmationAsync(
string returnUrl = null)
{
{
// Get the information about the user from the external login
// provider
if (info == null)
{
throw new ApplicationException(
"Error loading external login data during confirmation.");
}
var user = new ApplicationUser

{
Email = Input.Email
};
var result = await _userManager.CreateAsync(user);
{
result = await _userManager.AddLoginAsync(user, info);
{
// Copy over the gender claim
await _userManager.AddClaimAsync(user,
info.Principal.FindFirst(ClaimTypes.Gender));
// Include the access token in the properties

await _signInManager.SignInAsync(user, props,

authenticationMethod: info.LoginProvider);
"User created an account using {Name} provider.",
info.LoginProvider);
}
}

{
}
}
return Page();
}
public async Task<IActionResult> OnGetCallbackAsync(
string returnUrl = null, string remoteError = null)
{
if (remoteError != null)
{
ErrorMessage = $"Error from external provider: {remoteError}";
return RedirectToPage("./Login");
}
if (info == null)
{
return RedirectToPage("./Login");
}
// Sign in the user with this external login provider if the user
// already has a login
var result = await _signInManager.ExternalLoginSignInAsync(
info.LoginProvider, info.ProviderKey, isPersistent: false,
bypassTwoFactor : true);
{
// Store the access token and resign in so the token is included in
// in the cookie
var user = await _userManager.FindByLoginAsync(info.LoginProvider,
info.ProviderKey);

await _signInManager.SignInAsync(user, props, info.LoginProvider);
"{Name} logged in with {LoginProvider} provider.",
info.Principal.Identity.Name, info.LoginProvider);
}
{
}
else
{
// If the user does not have an account, then ask the user to
// create an account
LoginProvider = info.LoginProvider;
if (info.Principal.HasClaim(c => c.Type == ClaimTypes.Email))

{
Input = new InputModel
{
Email = info.Principal.FindFirstValue(ClaimTypes.Email)
};
}
return Page();
}
}
How to add additional custom tokens

To demonstrate how to add a custom token, which is stored as part of SaveTokens , the sample app adds an
AuthenticationToken with the current DateTime for an AuthenticationToken.Name of TicketCreated :
{
{
{
});
};
});
Sample app instructions

The sample app demonstrates how to:
Obtain the user's gender from Google and store a gender claim with the value.
Store the Google access token in the user's AuthenticationProperties .
To use the sample app:
1. Register the app and obtain a valid client ID and client secret for Google authentication. For more information,
see Google external login setup in ASP.NET Core.
2. Provide the client ID and client secret to the app in the GoogleOptions of Startup.ConfigureServices .
3. Run the app and request the My Claims page. When the user isn't signed in, the app redirects to Google. Sign in
with Google. Google redirects the user back to the app ( /Home/MyClaims ). The user is authenticated, and the My
Claims page is loaded. The gender claim is present under User Claims with the value obtained from Google. The
access token appears in the Authentication Properties.
User Claims
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
b36a7b09-9135-4810-b7a5-78697ff23e99
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
[email protected]
AspNet.Identity.SecurityStamp
29G2TB881ATCUQFJSRFG1S0QJ0OOAWVT
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/gender
female
http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod
Google
Authentication Properties
.Token.access_token
bv42.Dgw...GQMv9ArLPs
.Token.token_type
Bearer
.Token.expires_at
2018-08-27T19:08:00.0000000+00:00
.Token.TicketCreated
8/27/2018 6:08:00 PM
.TokenNames
access_token;token_type;expires_at;TicketCreated
.issued
Mon, 27 Aug 2018 18:08:05 GMT
.expires
Mon, 10 Sep 2018 18:08:05 GMT
Authenticate users with WS-Federation in ASP.NET
Core
This tutorial demonstrates how to enable users to sign in with a WS -Federation authentication provider like Active
Directory Federation Services (ADFS ) or Azure Active Directory (AAD ). It uses the ASP.NET Core 2.0 sample app
described in Facebook, Google, and external provider authentication.
For ASP.NET Core 2.0 apps, WS -Federation support is provided by
Microsoft.AspNetCore.Authentication.WsFederation. This component is ported from
Microsoft.Owin.Security.WsFederation and shares many of that component's mechanics. However, the
components differ in a couple of important ways.
By default, the new middleware:
Doesn't allow unsolicited logins. This feature of the WS -Federation protocol is vulnerable to XSRF attacks.
However, it can be enabled with the AllowUnsolicitedLogins option.
Doesn't check every form post for sign-in messages. Only requests to the CallbackPath are checked for sign-
ins. CallbackPath defaults to /signin-wsfed but can be changed via the inherited
RemoteAuthenticationOptions.CallbackPath property of the WsFederationOptions class. This path can be
shared with other authentication providers by enabling the SkipUnrecognizedRequests option.
Register the app with Active Directory

Active Directory Federation Services
Open the server's Add Relying Party Trust Wizard from the ADFS Management console:
Choose to enter data manually:

Enter a display name for the relying party. The name isn't important to the ASP.NET Core app.
Microsoft.AspNetCore.Authentication.WsFederation lacks support for token encryption, so don't configure
a token encryption certificate:
Enable support for WS -Federation Passive protocol, using the app's URL. Verify the port is correct for the app:
NOTE
This must be an HTTPS URL. IIS Express can provide a self-signed certificate when hosting the app during development.
Kestrel requires manual certificate configuration. See the Kestrel documentation for more details.
Click Next through the rest of the wizard and Close at the end.
ASP.NET Core Identity requires a Name ID claim. Add one from the Edit Claim Rules dialog:
In the Add Transform Claim Rule Wizard, leave the default Send LDAP Attributes as Claims template
selected, and click Next. Add a rule mapping the SAM -Account-Name LDAP attribute to the Name ID
outgoing claim:
Click Finish > OK in the Edit Claim Rules window.
Navigate to the AAD tenant's app registrations blade. Click New application registration:
Enter a name for the app registration. This isn't important to the ASP.NET Core app.
Enter the URL the app listens on as the Sign-on URL:
Click Endpoints and note the Federation Metadata Document URL. This is the WS -Federation
middleware's MetadataAddress :
Navigate to the new app registration. Click Settings > Properties and make note of the App ID URI. This is
the WS -Federation middleware's Wtrealm :
Add WS-Federation as an external login provider for ASP.NET Core
Identity
Add a dependency on Microsoft.AspNetCore.Authentication.WsFederation to the project.
Add WS -Federation to the Configure method in Startup.cs:
.AddWsFederation(options =>
{
// MetadataAddress represents the Active Directory instance used to authenticate users.
options.MetadataAddress = "https://<ADFS FQDN or AAD tenant>/FederationMetadata/2007-
06/FederationMetadata.xml";
// Wtrealm is the app's identifier in the Active Directory instance.

// For ADFS, use the relying party's identifier, its WS-Federation Passive protocol URL:
options.Wtrealm = "https://localhost:44307/";
// For AAD, use the App ID URI from the app registration's Properties blade:
options.Wtrealm = "https://wsfedsample.onmicrosoft.com/bf0e7e6d-056e-4e37-b9a6-2c36797b9f01";
});
services.AddMvc()
// ...
name.
Log in with WS -Federation
Browse to the app and click the Log in link in the nav header. There's an option to log in with WsFederation:
With ADFS as the provider, the button redirects to an ADFS sign-in page:
With Azure Active Directory as the provider, the button redirects to an AAD sign-in page:
A successful sign-in for a new user redirects to the app's user registration page:
Use WS-Federation without ASP.NET Core Identity

The WS -Federation middleware can be used without Identity. For example:
{
services.AddAuthentication(sharedOptions =>
{
sharedOptions.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
sharedOptions.DefaultSignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
sharedOptions.DefaultChallengeScheme = WsFederationDefaults.AuthenticationScheme;
})
.AddWsFederation(options =>
{
options.Wtrealm = Configuration["wsfed:realm"];
options.MetadataAddress = Configuration["wsfed:metadata"];
})
.AddCookie();
}

{
// …
}
See this PDF file for the ASP.NET Core 1.1 and 2.1 version.
Account confirmation and password recovery in ASP.NET

Core
This tutorial shows how to build an ASP.NET Core app with email confirmation and password reset. This tutorial
is not a beginning topic. You should be familiar with:
ASP.NET Core
Authentication
Entity Framework Core
Prerequisites
Create a web app and scaffold Identity

Visual Studio
.NET Core CLI
In Visual Studio, create a new Web Application project named WebPWrecover.
Select ASP.NET Core 2.1.
Keep the default Authentication set to No Authentication. Authentication is added in the next step.
In the next step:
Set the layout page to ~/Pages/Shared/_Layout.cshtml
Select Account/Register
Create a new Data context class
Follow the instructions in Enable authentication:
Add app.UseAuthentication(); to Startup.Configure
Add <partial name="_LoginPartial" /> to the layout file.
Test new user registration

Run the app, select the Register link, and register a user. At this point, the only validation on the email is with the
[EmailAddress] attribute. After submitting the registration, you are logged into the app. Later in the tutorial, the
code is updated so new users can't log in until their email is validated.
View the Identity database
Visual Studio
.NET Core CLI
From the View menu, select SQL Server Object Explorer (SSOX).
Navigate to (localdb)MSSQLLocalDB (SQL Server 13). Right-click on dbo.AspNetUsers > View Data:
Note the table's EmailConfirmed field is False .

You might want to use this email again in the next step when the app sends a confirmation email. Right-click on
the row and select Delete. Deleting the email alias makes it easier in the following steps.
Require email confirmation

It's a best practice to confirm the email of a new user registration. Email confirmation helps to verify they're not
impersonating someone else (that is, they haven't registered with someone else's email). Suppose you had a
discussion forum, and you wanted to prevent "[email protected]" from registering as "[email protected]".
Without email confirmation, "[email protected]" could receive unwanted email from your app. Suppose the
user accidentally registered as "[email protected]" and hadn't noticed the misspelling of "yli". They wouldn't be
able to use password recovery because the app doesn't have their correct email. Email confirmation provides
limited protection from bots. Email confirmation doesn't provide protection from malicious users with many
email accounts.
You generally want to prevent new users from posting any data to your web site before they have a confirmed
email.
Update Areas/Identity/IdentityHostingStartup.cs to require a confirmed email:
public class IdentityHostingStartup : IHostingStartup
{
{
builder.ConfigureServices((context, services) => {
services.AddDbContext<WebPWrecoverContext>(options =>
context.Configuration.GetConnectionString("WebPWrecoverContextConnection")));
services.AddDefaultIdentity<IdentityUser>(config =>
{
config.SignIn.RequireConfirmedEmail = true;
})
.AddEntityFrameworkStores<WebPWrecoverContext>();
});
}
}
config.SignIn.RequireConfirmedEmail = true; prevents registered users from logging in until their email is
confirmed.
Configure email provider
In this tutorial, SendGrid is used to send email. You need a SendGrid account and key to send email. You can use
other email providers. ASP.NET Core 2.x includes System.Net.Mail , which allows you to send email from your
app. We recommend you use SendGrid or another email service to send email. SMTP is difficult to secure and
set up correctly.
Create a class to fetch the secure email key. For this sample, create Services/AuthMessageSenderOptions.cs:
public class AuthMessageSenderOptions

{
public string SendGridUser { get; set; }
public string SendGridKey { get; set; }
}
Configure SendGrid user secrets

Add a unique <UserSecretsId> value to the <PropertyGroup> element of the project file:
<PropertyGroup>
<UserSecretsId>aspnet-WebPWrecover-1234</UserSecretsId>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="SendGrid" Version="9.9.0" />
</ItemGroup>
</Project>
Set the SendGridUser and SendGridKey with the secret-manager tool. For example:
C:/WebAppl>dotnet user-secrets set SendGridUser RickAndMSFT

info: Successfully saved SendGridUser = RickAndMSFT to the secret store.
On Windows, Secret Manager stores keys/value pairs in a secrets.json file in the

%APPDATA%/Microsoft/UserSecrets/<WebAppName-userSecretsId> directory.
The contents of the secrets.json file aren't encrypted. The secrets.json file is shown below (the SendGridKey value
has been removed.)
{
"SendGridUser": "RickAndMSFT",
"SendGridKey": "<key removed>"
}
For more information, see the Options pattern and configuration.

Install SendGrid
This tutorial shows how to add email notifications through SendGrid, but you can send email using SMTP and
other mechanisms.
Install the SendGrid NuGet package:
Visual Studio
.NET Core CLI
From the Package Manager Console, enter the following command:
Install-Package SendGrid
See Get Started with SendGrid for Free to register for a free SendGrid account.
Implement IEmailSender
To Implement IEmailSender , create Services/EmailSender.cs with code similar to the following:
using Microsoft.AspNetCore.Identity.UI.Services;
using Microsoft.Extensions.Options;
using SendGrid;
using SendGrid.Helpers.Mail;
namespace WebPWrecover.Services
{
public class EmailSender : IEmailSender
{
public EmailSender(IOptions<AuthMessageSenderOptions> optionsAccessor)
{
Options = optionsAccessor.Value;
}
public AuthMessageSenderOptions Options { get; } //set only via Secret Manager

{
return Execute(Options.SendGridKey, subject, message, email);
}
public Task Execute(string apiKey, string subject, string message, string email)
{
var client = new SendGridClient(apiKey);
var msg = new SendGridMessage()
{
From = new EmailAddress("[email protected]", "Joe Smith"),
Subject = subject,
PlainTextContent = message,
HtmlContent = message
};
msg.AddTo(new EmailAddress(email));
// Disable click tracking.

// See https://sendgrid.com/docs/User_Guide/Settings/tracking.html
msg.TrackingSettings = new TrackingSettings
{
ClickTracking = new ClickTracking { Enable = false }
};
return client.SendEmailAsync(msg);
}
}
}
Configure startup to support email

Add the following code to the ConfigureServices method in the Startup.cs file:
Add EmailSender as a singleton service.
Register the AuthMessageSenderOptions configuration instance.
{
{
});
// requires
// using WebPWrecover.Services;
services.Configure<AuthMessageSenderOptions>(Configuration);
}
Enable account confirmation and password recovery

The template has the code for account confirmation and password recovery. Find the OnPostAsync method in
Areas/Identity/Pages/Account/Register.cshtml.cs.
Prevent newly registered users from being automatically logged on by commenting out the following line:
The complete method is shown with the changed line highlighted:

{
{
var user = new IdentityUser { UserName = Input.Email, Email = Input.Email };
{

pageHandler: null,

here</a>.");
// await _signInManager.SignInAsync(user, isPersistent: false);

}
{
}
}

return Page();
}
Register, confirm email, and reset password

Run the web app, and test the account confirmation and password recovery flow.
Run the app and register a new user
Check your email for the account confirmation link. See Debug email if you don't get the email.
Click the link to confirm your email.
Log in with your email and password.
Log off.
View the manage page
Select your user name in the browser:
You might need to expand the navbar to see user name.

The manage page is displayed with the Profile tab selected. The Email shows a check box indicating the email
has been confirmed.
Test password reset
If you're logged in, select Logout.
Select the Log in link and select the Forgot your password? link.
Enter the email you used to register the account.
An email with a link to reset your password is sent. Check your email and click the link to reset your password.
After your password has been successfully reset, you can log in with your email and new password.
Debug email
If you can't get email working:
Set a breakpoint in EmailSender.Execute to verify SendGridClient.SendEmailAsync is called.
Create a console app to send email using similar code to EmailSender.Execute .
Review the Email Activity page.
Check your spam folder.
Try another email alias on a different email provider (Microsoft, Yahoo, Gmail, etc.)
Try sending to different email accounts.
A security best practice is to not use production secrets in test and development. If you publish the app to
Azure, you can set the SendGrid secrets as application settings in the Azure Web App portal. The configuration
system is set up to read keys from environment variables.
Combine social and local login accounts

To complete this section, you must first enable an external authentication provider. See Facebook, Google, and
external provider authentication.
You can combine local and social accounts by clicking on your email link. In the following sequence,
"[email protected]" is first created as a local login; however, you can create the account as a social login
first, then add a local login.
Click on the Manage link. Note the 0 external (social logins) associated with this account.
Click the link to another login service and accept the app requests. In the following image, Facebook is the
external authentication provider:
The two accounts have been combined. You are able to log on with either account. You might want your users to
add local accounts in case their social login authentication service is down, or more likely they've lost access to
their social account.
Enable account confirmation after a site has users

Enabling account confirmation on a site with users locks out all the existing users. Existing users are locked out
because their accounts aren't confirmed. To work around existing user lockout, use one of the following
approaches:
Update the database to mark all existing users as being confirmed.
Confirm exiting users. For example, batch-send emails with confirmation links.
Enable QR Code generation for TOTP authenticator
apps in ASP.NET Core
QR Codes requires ASP.NET Core 2.0 or later.

ASP.NET Core ships with support for authenticator applications for individual authentication. Two factor
authentication (2FA) authenticator apps, using a Time-based One-time Password Algorithm (TOTP ), are the
industry recommended approach for 2FA. 2FA using TOTP is preferred to SMS 2FA. An authenticator app
provides a 6 to 8 digit code which users must enter after confirming their username and password. Typically an
authenticator app is installed on a smart phone.
The ASP.NET Core web app templates support authenticators, but don't provide support for QRCode generation.
QRCode generators ease the setup of 2FA. This document will guide you through adding QR Code generation to
the 2FA configuration page.
Adding QR Codes to the 2FA configuration page

These instructions use qrcode.js from the https://davidshimjs.github.io/qrcodejs/ repo.
Download the qrcode.js javascript library to the wwwroot\lib folder in your project.
Follow the instructions in Scaffold Identity to generate
/Areas/Identity/Pages/Account/Manage/EnableAuthenticator.cshtml.
In /Areas/Identity/Pages/Account/Manage/EnableAuthenticator.cshtml, locate the Scripts section at the end
of the file:
In Pages/Account/Manage/EnableAuthenticator.cshtml (Razor Pages) or
Views/Manage/EnableAuthenticator.cshtml (MVC ), locate the Scripts section at the end of the file:
@section Scripts {
@await Html.PartialAsync("_ValidationScriptsPartial")
}
Update the Scripts section to add a reference to the qrcodejs library you added and a call to generate the
QR Code. It should look as follows:
@section Scripts {
@await Html.PartialAsync("_ValidationScriptsPartial")
<script type="text/javascript" src="~/lib/qrcode.js"></script>

<script type="text/javascript">
new QRCode(document.getElementById("qrCode"),
{
text: "@Html.Raw(Model.AuthenticatorUri)",
width: 150,
height: 150
});
</script>
}
Delete the paragraph which links you to these instructions.

Run your app and ensure that you can scan the QR code and validate the code the authenticator proves.
Change the site name in the QR Code

The site name in the QR Code is taken from the project name you choose when initially creating your project. You
can change it by looking for the GenerateQrCodeUri(string email, string unformattedKey) method in the
/Areas/Identity/Pages/Account/Manage/EnableAuthenticator.cshtml.
The site name in the QR Code is taken from the project name you choose when initially creating your project. You
can change it by looking for the GenerateQrCodeUri(string email, string unformattedKey) method in the
Pages/Account/Manage/EnableAuthenticator.cshtml.cs (Razor Pages) file or the Controllers/ManageController.cs
(MVC ) file.
The default code from the template looks as follows:
private string GenerateQrCodeUri(string email, string unformattedKey)

{
return string.Format(
AuthenicatorUriFormat,
_urlEncoder.Encode("Razor Pages"),
_urlEncoder.Encode(email),
unformattedKey);
}
The second parameter in the call to string.Format is your site name, taken from your solution name. It can be
changed to any value, but it must always be URL encoded.
Using a different QR Code library

You can replace the QR Code library with your preferred library. The HTML contains a qrCode element into
which you can place a QR Code by whatever mechanism your library provides.
The correctly formatted URL for the QR Code is available in the:
AuthenticatorUri property of the model.
data-url property in the qrCodeData element.
TOTP client and server time skew

TOTP (Time-based One-Time Password) authentication depends on both the server and authenticator device
having an accurate time. Tokens only last for 30 seconds. If TOTP 2FA logins are failing, check that the server time
is accurate, and preferably synchronized to an accurate NTP service.
Two-factor authentication with SMS in ASP.NET Core
By Rick Anderson and Swiss-Devs
WARNING
Two factor authentication (2FA) authenticator apps, using a Time-based One-time Password Algorithm (TOTP), are the
industry recommended approach for 2FA. 2FA using TOTP is preferred to SMS 2FA. For more information, see Enable QR
Code generation for TOTP authenticator apps in ASP.NET Core for ASP.NET Core 2.0 and later.
This tutorial shows how to set up two-factor authentication (2FA) using SMS. Instructions are given for twilio and
ASPSMS, but you can use any other SMS provider. We recommend you complete Account Confirmation and
Password Recovery before starting this tutorial.
View the completed sample. How to download.
Create a new ASP.NET Core project

Create a new ASP.NET Core web app named Web2FA with individual user accounts. Follow the instructions in
Enforce SSL in an ASP.NET Core app to set up and require SSL.
Create an SMS account
Create an SMS account, for example, from twilio or ASPSMS. Record the authentication credentials (for twilio:
accountSid and authToken, for ASPSMS: Userkey and Password).
Figuring out SMS Provider credentials
Twilio: From the Dashboard tab of your Twilio account, copy the Account SID and Auth token.
ASPSMS: From your account settings, navigate to Userkey and copy it together with your Password.
We will later store these values in with the secret-manager tool within the keys SMSAccountIdentification and
SMSAccountPassword .
Specifying SenderID / Originator

Twilio: From the Numbers tab, copy your Twilio phone number.
ASPSMS: Within the Unlock Originators Menu, unlock one or more Originators or choose an alphanumeric
Originator (Not supported by all networks).
We will later store this value with the secret-manager tool within the key SMSAccountFrom .
Provide credentials for the SMS service
We'll use the Options pattern to access the user account and key settings.
Create a class to fetch the secure SMS key. For this sample, the SMSoptions class is created in the
Services/SMSoptions.cs file.
namespace Web2FA.Services
{
public class SMSoptions
{
public string SMSAccountIdentification { get; set; }
public string SMSAccountPassword { get; set; }
public string SMSAccountFrom { get; set; }
}
}
Set the SMSAccountIdentification , SMSAccountPassword and SMSAccountFrom with the secret-manager tool. For
example:
C:/Web2FA/src/WebApp1>dotnet user-secrets set SMSAccountIdentification 12345

info: Successfully saved SMSAccountIdentification = 12345 to the secret store.
Add the NuGet package for the SMS provider. From the Package Manager Console (PMC ) run:
Twilio: Install-Package Twilio
ASPSMS: Install-Package ASPSMS
Add code in the Services/MessageServices.cs file to enable SMS. Use either the Twilio or the ASPSMS section:
Twilio:
using Twilio;
using Twilio.Rest.Api.V2010.Account;
using Twilio.Types;
{
// This class is used by the application to send Email and SMS
// when you turn on two-factor authentication in ASP.NET Identity.
// For more details see this link https://go.microsoft.com/fwlink/?LinkID=532713
public class AuthMessageSender : IEmailSender, ISmsSender
{
public AuthMessageSender(IOptions<SMSoptions> optionsAccessor)
{
}
public SMSoptions Options { get; } // set only via Secret Manager

{
// Plug in your email service here to send an email.
}
public Task SendSmsAsync(string number, string message)

{
// Plug in your SMS service here to send a text message.
// Your Account SID from twilio.com/console
var accountSid = Options.SMSAccountIdentification;
// Your Auth Token from twilio.com/console
var authToken = Options.SMSAccountPassword;
TwilioClient.Init(accountSid, authToken);
return MessageResource.CreateAsync(
to: new PhoneNumber(number),
from: new PhoneNumber(Options.SMSAccountFrom),
body: message);
}
}
}
ASPSMS:
{
// This class is used by the application to send Email and SMS
// when you turn on two-factor authentication in ASP.NET Identity.
// For more details see this link https://go.microsoft.com/fwlink/?LinkID=532713
public class AuthMessageSender : IEmailSender, ISmsSender
{
public AuthMessageSender(IOptions<SMSoptions> optionsAccessor)
{
}
public SMSoptions Options { get; } // set only via Secret Manager

{
// Plug in your email service here to send an email.
}
public Task SendSmsAsync(string number, string message)

{
ASPSMS.SMS SMSSender = new ASPSMS.SMS();
SMSSender.Userkey = Options.SMSAccountIdentification;
SMSSender.Password = Options.SMSAccountPassword;
SMSSender.Originator = Options.SMSAccountFrom;
SMSSender.AddRecipient(number);
SMSSender.MessageData = message;
SMSSender.SendTextSMS();
}
}
}
Configure startup to use SMSoptions
Add SMSoptions to the service container in the ConfigureServices method in the Startup.cs:

services.Configure<SMSoptions>(Configuration);
}
Enable two -factor authentication

Open the Views/Manage/Index.cshtml Razor view file and remove the comment characters (so no markup is
commnted out).
Log in with two-factor authentication

Run the app and register a new user
Tap on your user name, which activates the Index action method in Manage controller. Then tap the phone
number Add link.
Add a phone number that will receive the verification code, and tap Send verification code.
You will get a text message with the verification code. Enter it and tap Submit
If you don't get a text message, see twilio log page.

The Manage view shows your phone number was added successfully.
Tap Enable to enable two-factor authentication.
Test two -factor authentication

Log off.
Log in.
The user account has enabled two-factor authentication, so you have to provide the second factor of
authentication . In this tutorial you have enabled phone verification. The built in templates also allow you to
set up email as the second factor. You can set up additional second factors for authentication such as QR
codes. Tap Submit.
Enter the code you get in the SMS message.

Clicking on the Remember this browser check box will exempt you from needing to use 2FA to log on
when using the same device and browser. Enabling 2FA and clicking on Remember this browser will
provide you with strong 2FA protection from malicious users trying to access your account, as long as they
don't have access to your device. You can do this on any private device you regularly use. By setting
Remember this browser, you get the added security of 2FA from devices you don't regularly use, and you
get the convenience on not having to go through 2FA on your own devices.
Account lockout for protecting against brute force attacks
Account lockout is recommended with 2FA. Once a user signs in through a local account or social account, each
failed attempt at 2FA is stored. If the maximum failed access attempts is reached, the user is locked out (default: 5
minute lockout after 5 failed access attempts). A successful authentication resets the failed access attempts count
and resets the clock. The maximum failed access attempts and lockout time can be set with
MaxFailedAccessAttempts and DefaultLockoutTimeSpan. The following configures account lockout for 10
minutes after 10 failed access attempts:

{
services.AddMvc();
{
});

services.Configure<SMSoptions>(Configuration);
}
Confirm that PasswordSignInAsync sets lockoutOnFailure to true :
var result = await _signInManager.PasswordSignInAsync(

Input.Email, Input.Password, Input.RememberMe, lockoutOnFailure: true);
Use cookie authentication without ASP.NET Core
Identity
By Rick Anderson and Luke Latham

As you've seen in the earlier authentication topics, ASP.NET Core Identity is a complete, full-featured
authentication provider for creating and maintaining logins. However, you may want to use your own custom
authentication logic with cookie-based authentication at times. You can use cookie-based authentication as a
standalone authentication provider without ASP.NET Core Identity.
For demonstration purposes in the sample app, the user account for the hypothetical user, Maria Rodriguez, is
hardcoded into the app. Use the Email username "[email protected]" and any password to sign in
the user. The user is authenticated in the AuthenticateUser method in the Pages/Account/Login.cshtml.cs file. In a
real-world example, the user would be authenticated against a database.
For information on migrating cookie-based authentication from ASP.NET Core 1.x to 2.0, see Migrate
Authentication and Identity to ASP.NET Core 2.0 topic (Cookie-based Authentication).
To use ASP.NET Core Identity, see the Introduction to Identity topic.
Configuration
ASP.NET Core 2.x
ASP.NET Core 1.x
If the app doesn't use the Microsoft.AspNetCore.App metapackage, create a package reference in the project file
for the Microsoft.AspNetCore.Authentication.Cookies package (version 2.1.0 or later).
In the ConfigureServices method, create the Authentication Middleware service with the AddAuthentication and
AddCookie methods:
services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
.AddCookie();
AuthenticationScheme passed to AddAuthentication sets the default authentication scheme for the app.
AuthenticationScheme is useful when there are multiple instances of cookie authentication and you want to
authorize with a specific scheme. Setting the AuthenticationScheme to
CookieAuthenticationDefaults.AuthenticationScheme provides a value of "Cookies" for the scheme. You can supply
any string value that distinguishes the scheme.
The app's authentication scheme is different from the app's cookie authentication scheme. When a cookie
authentication scheme isn't provided to AddCookie, it uses CookieAuthenticationDefaults.AuthenticationScheme
("Cookies").
In the Configure method, use the UseAuthentication method to invoke the Authentication Middleware that sets
the HttpContext.User property. Call the UseAuthentication method before calling UseMvcWithDefaultRoute or
UseMvc :
AddCookie Options
The CookieAuthenticationOptions class is used to configure the authentication provider options.
OPTION DESCRIPTION
AccessDeniedPath Provides the path to supply with a 302 Found (URL redirect)
when triggered by HttpContext.ForbidAsync . The default
value is /Account/AccessDenied .
ClaimsIssuer The issuer to use for the Issuer property on any claims
created by the cookie authentication service.
Cookie.Domain The domain name where the cookie is served. By default, this
is the host name of the request. The browser only sends the
cookie in requests to a matching host name. You may wish to
adjust this to have cookies available to any host in your
domain. For example, setting the cookie domain to
.contoso.com makes it available to contoso.com ,
www.contoso.com , and staging.www.contoso.com .
Cookie.Expiration Gets or sets the lifespan of a cookie. Currently, this option

no-ops and will become obsolete in ASP.NET Core 2.1+. Use
the ExpireTimeSpan option to set cookie expiration. For
more information, see Clarify behavior of
CookieAuthenticationOptions.Cookie.Expiration.
Cookie.HttpOnly A flag indicating if the cookie should be accessible only to

servers. Changing this value to false permits client-side
scripts to access the cookie and may open your app to cookie
theft should your app have a Cross-site scripting (XSS)
vulnerability. The default value is true .
Cookie.Name Sets the name of the cookie.
Cookie.Path Used to isolate apps running on the same host name. If you
have an app running at /app1 and want to restrict cookies
to that app, set the CookiePath property to /app1 . By
doing so, the cookie is only available on requests to /app1
and any app underneath it.
Cookie.SameSite Indicates whether the browser should allow the cookie to be

attached to same-site requests only ( SameSiteMode.Strict )
or cross-site requests using safe HTTP methods and same-
site requests ( SameSiteMode.Lax ). When set to
SameSiteMode.None , the cookie header value isn't set. Note
that Cookie Policy Middleware might overwrite the value that
you provide. To support OAuth authentication, the default
value is SameSiteMode.Lax . For more information, see
OAuth authentication broken due to SameSite cookie policy.
OPTION DESCRIPTION
Cookie.SecurePolicy A flag indicating if the cookie created should be limited to

HTTPS ( CookieSecurePolicy.Always ), HTTP or HTTPS (
CookieSecurePolicy.None ), or the same protocol as the
request ( CookieSecurePolicy.SameAsRequest ). The default
value is CookieSecurePolicy.SameAsRequest .
DataProtectionProvider Sets the DataProtectionProvider that's used to create the

default TicketDataFormat . If the TicketDataFormat
property is set, the DataProtectionProvider option isn't
used. If not provided, the app's default data protection
provider is used.
Events The handler calls methods on the provider that give the app
control at certain processing points. If Events aren't
provided, a default instance is supplied that does nothing
when the methods are called.
EventsType Used as the service type to get the Events instance instead
of the property.
ExpireTimeSpan The TimeSpan after which the authentication ticket stored

inside the cookie expires. ExpireTimeSpan is added to the
current time to create the expiration time for the ticket. The
ExpiredTimeSpan value always goes into the encrypted
AuthTicket verified by the server. It may also go into the Set-
Cookie header, but only if IsPersistent is set. To set
IsPersistent to true , configure the
AuthenticationProperties passed to SignInAsync . The
default value of ExpireTimeSpan is 14 days.
LoginPath Provides the path to supply with a 302 Found (URL redirect)
when triggered by HttpContext.ChallengeAsync . The
current URL that generated the 401 is added to the
LoginPath as a query string parameter named by the
ReturnUrlParameter . Once a request to the LoginPath
grants a new sign-in identity, the ReturnUrlParameter value
is used to redirect the browser back to the URL that caused
the original unauthorized status code. The default value is
/Account/Login .
LogoutPath If the LogoutPath is provided to the handler, then a request

to that path redirects based on the value of the
ReturnUrlParameter . The default value is
/Account/Logout .
ReturnUrlParameter Determines the name of the query string parameter that's

appended by the handler for a 302 Found (URL redirect)
response. ReturnUrlParameter is used when a request
arrives on the LoginPath or LogoutPath to return the
browser to the original URL after the login or logout action is
performed. The default value is ReturnUrl .
OPTION DESCRIPTION
SessionStore An optional container used to store identity across requests.

When used, only a session identifier is sent to the client.
SessionStore can be used to mitigate potential problems
with large identities.
SlidingExpiration A flag indicating if a new cookie with an updated expiration

time should be issued dynamically. This can happen on any
request where the current cookie expiration period is more
than 50% expired. The new expiration date is moved forward
to be the current date plus the ExpireTimespan . An
absolute cookie expiration time can be set by using the
AuthenticationProperties class when calling
SignInAsync . An absolute expiration time can improve the
security of your app by limiting the amount of time that the
authentication cookie is valid. The default value is true .
TicketDataFormat The TicketDataFormat is used to protect and unprotect the

identity and other properties that are stored in the cookie
value. If not provided, a TicketDataFormat is created using
the DataProtectionProvider.
Validate Method that checks that the options are valid.
Set CookieAuthenticationOptions in the service configuration for authentication in the ConfigureServices method:
.AddCookie(options =>
{
...
});
Cookie Policy Middleware

Cookie Policy Middleware enables cookie policy capabilities in an app. Adding the middleware to the app
processing pipeline is order sensitive; it only affects components registered after it in the pipeline.
app.UseCookiePolicy(cookiePolicyOptions);
The CookiePolicyOptions provided to the Cookie Policy Middleware allow you to control global characteristics of
cookie processing and hook into cookie processing handlers when cookies are appended or deleted.
HttpOnly Affects whether cookies must be HttpOnly, which is a flag

indicating if the cookie should be accessible only to servers.
The default value is HttpOnlyPolicy.None .
MinimumSameSitePolicy Affects the cookie's same-site attribute (see below). The

default value is SameSiteMode.Lax . This option is available
for ASP.NET Core 2.0+.
OnAppendCookie Called when a cookie is appended.

OnDeleteCookie Called when a cookie is deleted.
Secure Affects whether cookies must be Secure. The default value is

CookieSecurePolicy.None .
MinimumSameSitePolicy (ASP.NET Core 2.0+ only)

The default MinimumSameSitePolicy value is SameSiteMode.Lax to permit OAuth2 authentication. To strictly enforce
a same-site policy of SameSiteMode.Strict , set the MinimumSameSitePolicy . Although this setting breaks OAuth2
and other cross-origin authentication schemes, it elevates the level of cookie security for other types of apps that
don't rely on cross-origin request processing.
var cookiePolicyOptions = new CookiePolicyOptions

{
MinimumSameSitePolicy = SameSiteMode.Strict,
};
The Cookie Policy Middleware setting for MinimumSameSitePolicy can affect your setting of Cookie.SameSite in
CookieAuthenticationOptions settings according to the matrix below.
MINIMUMSAMESITEPOLICY COOKIE.SAMESITE RESULTANT COOKIE.SAMESITE SETTING
SameSiteMode.None SameSiteMode.None SameSiteMode.None

SameSiteMode.Lax SameSiteMode.Lax
SameSiteMode.Strict SameSiteMode.Strict
SameSiteMode.Lax SameSiteMode.None SameSiteMode.Lax

SameSiteMode.Lax SameSiteMode.Lax
SameSiteMode.Strict SameSiteMode.None SameSiteMode.Strict

SameSiteMode.Lax SameSiteMode.Strict
Create an authentication cookie

To create a cookie holding user information, you must construct a ClaimsPrincipal. The user information is
serialized and stored in the cookie.
ASP.NET Core 2.x
ASP.NET Core 1.x
Create a ClaimsIdentity with any required Claims and call SignInAsync to sign in the user:
var claims = new List<Claim>
{
new Claim(ClaimTypes.Name, user.Email),
new Claim("FullName", user.FullName),
new Claim(ClaimTypes.Role, "Administrator"),
};
var claimsIdentity = new ClaimsIdentity(

claims, CookieAuthenticationDefaults.AuthenticationScheme);
var authProperties = new AuthenticationProperties

{
//AllowRefresh = <bool>,
// Refreshing the authentication session should be allowed.
//ExpiresUtc = DateTimeOffset.UtcNow.AddMinutes(10),
// The time at which the authentication ticket expires. A
// value set here overrides the ExpireTimeSpan option of
// CookieAuthenticationOptions set with AddCookie.
//IsPersistent = true,
// Whether the authentication session is persisted across
// multiple requests. Required when setting the
// ExpireTimeSpan option of CookieAuthenticationOptions
// set with AddCookie. Also required when setting
// ExpiresUtc.
//IssuedUtc = <DateTimeOffset>,
// The time at which the authentication ticket was issued.
//RedirectUri = <string>
// The full path or absolute URI to be used as an http
// redirect response value.
};
await HttpContext.SignInAsync(
CookieAuthenticationDefaults.AuthenticationScheme,
new ClaimsPrincipal(claimsIdentity),
authProperties);
SignInAsync creates an encrypted cookie and adds it to the current response. If you don't specify an
AuthenticationScheme , the default scheme is used.
Under the covers, the encryption used is ASP.NET Core's Data Protection system. If you're hosting app on
multiple machines, load balancing across apps, or using a web farm, then you must configure data protection to
use the same key ring and app identifier.
Sign out
ASP.NET Core 2.x
ASP.NET Core 1.x
To sign out the current user and delete their cookie, call SignOutAsync:
await HttpContext.SignOutAsync(
CookieAuthenticationDefaults.AuthenticationScheme);
If you aren't using CookieAuthenticationDefaults.AuthenticationScheme (or "Cookies") as the scheme (for example,
"ContosoCookie"), supply the scheme you used when configuring the authentication provider. Otherwise, the
default scheme is used.
React to back-end changes
Once a cookie is created, it becomes the single source of identity. Even if you disable a user in your back-end
systems, the cookie authentication system has no knowledge of this, and a user stays logged in as long as their
cookie is valid.
The ValidatePrincipal event in ASP.NET Core 2.x or the ValidateAsync method in ASP.NET Core 1.x can be used
to intercept and override validation of the cookie identity. This approach mitigates the risk of revoked users
accessing the app.
One approach to cookie validation is based on keeping track of when the user database has been changed. If the
database hasn't been changed since the user's cookie was issued, there's no need to re-authenticate the user if
their cookie is still valid. To implement this scenario, the database, which is implemented in IUserRepository for
this example, stores a LastChanged value. When any user is updated in the database, the LastChanged value is set
to the current time.
In order to invalidate a cookie when the database changes based on the LastChanged value, create the cookie with
a LastChanged claim containing the current LastChanged value from the database:
var claims = new List<Claim>

{
new Claim(ClaimTypes.Name, user.Email),
new Claim("LastChanged", {Database Value})
};
var claimsIdentity = new ClaimsIdentity(

claims,
new ClaimsPrincipal(claimsIdentity));
ASP.NET Core 2.x

ASP.NET Core 1.x
To implement an override for the ValidatePrincipal event, write a method with the following signature in a class
that you derive from CookieAuthenticationEvents:
ValidatePrincipal(CookieValidatePrincipalContext)
An example looks like the following:

using System.Linq;
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.Cookies;
public class CustomCookieAuthenticationEvents : CookieAuthenticationEvents

{
private readonly IUserRepository _userRepository;
public CustomCookieAuthenticationEvents(IUserRepository userRepository)

{
// Get the database from registered DI services.
_userRepository = userRepository;
}
public override async Task ValidatePrincipal(CookieValidatePrincipalContext context)

{
var userPrincipal = context.Principal;
// Look for the LastChanged claim.

var lastChanged = (from c in userPrincipal.Claims
where c.Type == "LastChanged"
select c.Value).FirstOrDefault();
if (string.IsNullOrEmpty(lastChanged) ||
!_userRepository.ValidateLastChanged(lastChanged))
{
context.RejectPrincipal();
await context.HttpContext.SignOutAsync(
}
}
}
Register the events instance during cookie service registration in the ConfigureServices method. Provide a
scoped service registration for your CustomCookieAuthenticationEvents class:
{
options.EventsType = typeof(CustomCookieAuthenticationEvents);
});
services.AddScoped<CustomCookieAuthenticationEvents>();
Consider a situation in which the user's name is updated — a decision that doesn't affect security in any way. If
you want to non-destructively update the user principal, call context.ReplacePrincipal and set the
context.ShouldRenew property to true .
WARNING
The approach described here is triggered on every request. This can result in a large performance penalty for the app.
Persistent cookies
You may want the cookie to persist across browser sessions. This persistence should only be enabled with explicit
user consent with a "Remember Me" checkbox on login or a similar mechanism.
The following code snippet creates an identity and corresponding cookie that survives through browser closures.
Any sliding expiration settings previously configured are honored. If the cookie expires while the browser is
closed, the browser clears the cookie once it's restarted.
ASP.NET Core 2.x
ASP.NET Core 1.x
new AuthenticationProperties
{
IsPersistent = true
});
The AuthenticationProperties class resides in the Microsoft.AspNetCore.Authentication namespace.
Absolute cookie expiration

You can set an absolute expiration time with ExpiresUtc . You must also set IsPersistent ; otherwise, ExpiresUtc
is ignored and a single-session cookie is created. When ExpiresUtc is set on SignInAsync , it overrides the value
of the ExpireTimeSpan option of CookieAuthenticationOptions , if set.
The following code snippet creates an identity and corresponding cookie that lasts for 20 minutes. This ignores
any sliding expiration settings previously configured.
ASP.NET Core 2.x
ASP.NET Core 1.x
new AuthenticationProperties
{
IsPersistent = true,
ExpiresUtc = DateTime.UtcNow.AddMinutes(20)
});
Auth 2.0 Changes / Migration Announcement
Authorize with a specific scheme in ASP.NET Core
Claims-based authorization in ASP.NET Core
Policy-based role checks
Azure Active Directory with ASP.NET Core
Azure AD V1 samples
The following samples show how to integrate Azure AD V1, enabling users to sign-in with a work and school
account:
Integrating Azure AD Into an ASP.NET Core Web App
Calling a ASP.NET Core Web API From a WPF Application Using Azure AD
Calling a Web API in an ASP.NET Core Web Application Using Azure AD
Azure AD V2 samples
The following samples show how to integrate Azure AD V2, enabling users to sign-in with a work and school
account or a Microsoft personal account (formely Live account):
Integrating Azure AD V2 into an ASP.NET Core 2.0 web app:
See this associated video
Calling a ASP.NET Core 2.0 Web API from a WPF application using Azure AD V2:
See this associated video
Azure AD B2C sample

This sample shows how to integrate Azure AD B2C, enabling users to sign-in with social identities (like Facebook,
Google, ...)
An ASP.NET Core web API with Azure AD B2C
Cloud authentication with Azure Active Directory
B2C in ASP.NET Core
By Cam Soper
Azure Active Directory B2C (Azure AD B2C ) is a cloud identity management solution for web and mobile apps.
The service provides authentication for apps hosted in the cloud and on-premises. Authentication types include
individual accounts, social network accounts, and federated enterprise accounts. Additionally, Azure AD B2C can
provide multi-factor authentication with minimal configuration.
TIP
Azure Active Directory (Azure AD) and Azure AD B2C are separate product offerings. An Azure AD tenant represents an
organization, while an Azure AD B2C tenant represents a collection of identities to be used with relying party applications. To
learn more, see Azure AD B2C: Frequently asked questions (FAQ).
In this tutorial, learn how to:

Create an Azure Active Directory B2C tenant
Register an app in Azure AD B2C
Use Visual Studio to create an ASP.NET Core web app configured to use the Azure AD B2C tenant for
authentication
Configure policies controlling the behavior of the Azure AD B2C tenant
Prerequisites
The following are required for this walkthrough:
Microsoft Azure subscription
Visual Studio 2017 (any edition)
Create the Azure Active Directory B2C tenant

Create an Azure Active Directory B2C tenant as described in the documentation. When prompted, associating the
tenant with an Azure subscription is optional for this tutorial.
Register the app in Azure AD B2C

In the newly created Azure AD B2C tenant, register your app using the steps in the documentation under the
Register a web app section. Stop at the Create a web app client secret section. A client secret isn't required for
this tutorial.
Use the following values:
SETTING VALUE NOTES
Name <app name> Enter a Name for the app that

describes your app to consumers.
SETTING VALUE NOTES
Include web app / web API Yes
Allow implicit flow Yes
Reply URL https://localhost:44300/signin- Reply URLs are endpoints where Azure

oidc AD B2C returns any tokens that your
app requests. Visual Studio provides the
Reply URL to use. For now, enter
https://localhost:44300/signin-
oidc
to complete the form.
App ID URI Leave blank Not required for this tutorial.
Include native client No
WARNING
If setting up a non-localhost Reply URL, be aware of the constraints on what is allowed in the Reply URL list.
After the app is registered, the list of apps in the tenant is displayed. Select the app that was just registered. Select
the Copy icon to the right of the Application ID field to copy it to the clipboard.
Nothing more can be configured in the Azure AD B2C tenant at this time, but leave the browser window open.
There is more configuration after the ASP.NET Core app is created.
Create an ASP.NET Core app in Visual Studio 2017

The Visual Studio Web Application template can be configured to use the Azure AD B2C tenant for authentication.
In Visual Studio:
2. Select Web Application from the list of templates.
3. Select the Change Authentication button.
4. In the Change Authentication dialog, select Individual User Accounts, and then select Connect to an
existing user store in the cloud in the dropdown.
5. Complete the form with the following values:
SETTING VALUE
Domain Name <the domain name of your B2C tenant>

SETTING VALUE
Application ID <paste the Application ID from the clipboard>
Callback Path <use the default value>
Sign-up or sign-in policy B2C_1_SiUpIn
Reset password policy B2C_1_SSPR
Edit profile policy <leave blank>
Select the Copy link next to Reply URI to copy the Reply URI to the clipboard. Select OK to close the
Change Authentication dialog. Select OK to create the web app.
Finish the B2C app registration

Return to the browser window with the B2C app properties still open. Change the temporary Reply URL specified
earlier to the value copied from Visual Studio. Select Save at the top of the window.
TIP
If you didn't copy the Reply URL, use the SSL address from the Debug tab in the web project properties, and append the
CallbackPath value from appsettings.json.
Configure policies
Use the steps in the Azure AD B2C documentation to create a sign-up or sign-in policy, and then create a
password reset policy. Use the example values provided in the documentation for Identity providers, Sign-up
attributes, and Application claims. Using the Run now button to test the policies as described in the
documentation is optional.
WARNING
Ensure the policy names are exactly as described in the documentation, as those policies were used in the Change
Authentication dialog in Visual Studio. The policy names can be verified in appsettings.json.
Run the app

In Visual Studio, press F5 to build and run the app. After the web app launches, select Accept to accept the use of
cookies (if prompted), and then select Sign in.
The browser redirects to the Azure AD B2C tenant. Sign in with an existing account (if one was created testing the
policies) or select Sign up now to create a new account. The Forgot your password? link is used to reset a
forgotten password.
After successfully signing in, the browser redirects to the web app.
Next steps
Create an Azure Active Directory B2C tenant
Register an app in Azure AD B2C
Use Visual Studio to create an ASP.NET Core Web Application configured to use the Azure AD B2C tenant for
authentication
Configure policies controlling the behavior of the Azure AD B2C tenant
Now that the ASP.NET Core app is configured to use Azure AD B2C for authentication, the Authorize attribute can
be used to secure your app. Continue developing your app by learning to:
Customize the Azure AD B2C user interface.
Configure password complexity requirements.
Enable multi-factor authentication.
Configure additional identity providers, such as Microsoft, Facebook, Google, Amazon, Twitter, and others.
Use the Azure AD Graph API to retrieve additional user information, such as group membership, from the
Azure AD B2C tenant.
Secure an ASP.NET Core web API using Azure AD B2C.
Call a .NET web API from a .NET web app using Azure AD B2C.
Cloud authentication in web APIs with Azure Active
Directory B2C in ASP.NET Core
By Cam Soper
Azure Active Directory B2C (Azure AD B2C ) is a cloud identity management solution for web and mobile apps.
The service provides authentication for apps hosted in the cloud and on-premises. Authentication types include
individual accounts, social network accounts, and federated enterprise accounts. Additionally, Azure AD B2C can
provide multi-factor authentication with minimal configuration.
TIP
Azure Active Directory (Azure AD) and Azure AD B2C are separate product offerings. An Azure AD tenant represents an
organization, while an Azure AD B2C tenant represents a collection of identities to be used with relying party applications. To
learn more, see Azure AD B2C: Frequently asked questions (FAQ).
Since web APIs have no user interface, they're unable to redirect the user to a secure token service like Azure AD
B2C. Instead, the API is passed a bearer token from the calling app, which has already authenticated the user with
Azure AD B2C. The API then validates the token without direct user interaction.
In this tutorial, learn how to:
Create an Azure Active Directory B2C tenant.
Register a Web API in Azure AD B2C.
Use Visual Studio to create a Web API configured to use the Azure AD B2C tenant for authentication.
Configure policies controlling the behavior of the Azure AD B2C tenant.
Use Postman to simulate a web app which presents a login dialog, retrieves a token, and uses it to make a
request against the web API.
Prerequisites
The following are required for this walkthrough:
Microsoft Azure subscription
Visual Studio 2017 (any edition)
Postman
Create the Azure Active Directory B2C tenant

Create an Azure AD B2C tenant as described in the documentation. When prompted, associating the tenant with
an Azure subscription is optional for this tutorial.
Configure a sign-up or sign-in policy

Use the steps in the Azure AD B2C documentation to create a sign-up or sign-in policy. Name the policy SiUpIn.
Use the example values provided in the documentation for Identity providers, Sign-up attributes, and
Application claims. Using the Run now button to test the policy as described in the documentation is optional.
Register the API in Azure AD B2C
In the newly created Azure AD B2C tenant, register your API using the steps in the documentation under the
Register a web API section.
SETTING VALUE NOTES
Name <API name> Enter a Name for the app that

describes your app to consumers.
Reply URL https://localhost Reply URLs are endpoints where Azure

AD B2C returns any tokens that your
app requests.
App ID URI api The URI doesn't need to resolve to a

physical address. It only needs to be
unique.
After the API is registered, the list of apps and APIs in the tenant is displayed. Select the API that was just
registered. Select the Copy icon to the right of the Application ID field to copy it to the clipboard. Select
Published scopes and verify the default user_impersonation scope is present.
Create an ASP.NET Core app in Visual Studio 2017

The Visual Studio Web Application template can be configured to use the Azure AD B2C tenant for authentication.
In Visual Studio:
2. Select Web API from the list of templates.
3. Select the Change Authentication button.
4. In the Change Authentication dialog, select Individual User Accounts, and then select Connect to an
existing user store in the cloud in the dropdown.
5. Complete the form with the following values:
SETTING VALUE
Domain Name <the domain name of your B2C tenant>
Application ID <paste the Application ID from the clipboard>
Sign-up or sign-in policy B2C_1_SiUpIn
Select OK to close the Change Authentication dialog. Select OK to create the web app.
Visual Studio creates the web API with a controller named ValuesController.cs that returns hard-coded values for
GET requests. The class is decorated with the Authorize attribute, so all requests require authentication.
Run the web API
In Visual Studio, run the API. Visual Studio launches a browser pointed at the API's root URL. Note the URL in the
address bar, and leave the API running in the background.
NOTE
Since there is no controller defined for the root URL, the browser may display a 404 (page not found) error. This is expected
behavior.
Use Postman to get a token and test the API

Postman is a tool for testing web APIs. For this tutorial, Postman simulates a web app that accesses the web API
on the user's behalf.
Register Postman as a web app
Since Postman simulates a web app that can obtain tokens from the Azure AD B2C tenant, it must be registered in
the tenant as a web app. Register Postman using the steps in the documentation under the Register a web app
section. Stop at the Create a web app client secret section. A client secret isn't required for this tutorial.
SETTING VALUE NOTES
Name Postman
Reply URL https://getpostman.com/postman
App ID URI <leave blank> Not required for this tutorial.
The newly registered web app needs permission to access the web API on the user's behalf.
1. Select Postman in the list of apps and then select API access from the menu on the left.
2. Select + Add.
3. In the Select API dropdown, select the name of the web API.
4. In the Select Scopes dropdown, ensure all scopes are selected.
5. Select Ok.
Note the Postman app's Application ID, as it's required to obtain a bearer token.
Create a Postman request
Launch Postman. By default, Postman displays the Create New dialog upon launching. If the dialog isn't
displayed, select the + New button in the upper left.
From the Create New dialog:
1. Select Request.
2. Enter Get Values in the Request name box.
3. Select + Create Collection to create a new collection for storing the request. Name the collection ASP.NET
Core tutorials and then select the checkmark.
4. Select the Save to ASP.NET Core tutorials button.
Test the web API without authentication
To verify that the web API requires authentication, first make a request without authentication.
1. In the Enter request URL box, enter the URL for ValuesController . The URL is the same as displayed in
the browser with api/values appended. An example would be https://localhost:44375/api/values .
2. Select the Send button.
3. Note the status of the response is 401 Unauthorized.
IMPORTANT
If you get a "Could not get any response" error, you may need to disable SSL certificate verification in the Postman settings.
Obtain a bearer token

To make an authenticated request to the web API, a bearer token is required. Postman makes it easy to sign in to
the Azure AD B2C tenant and obtain a token.
1. On the Authorization tab, in the TYPE dropdown, select OAuth 2.0. In the Add authorization data to
dropdown, select Request Headers. Select Get New Access Token.
2. Complete the GET NEW ACCESS TOKEN dialog as follows:
SETTING VALUE NOTES
Token Name <token name> Enter a descriptive name for the

token.
Grant Type Implicit
Callback URL https://getpostman.com/postman
Auth URL Replace <tenant domain name>

https://login.microsoftonline.com/tfp/<tenant
domain with the tenant's domain name.
name>/B2C_1_SiUpIn/oauth2/v2.0/authorize
Client ID <enter the Postman app's

Application ID>
Scope https://<tenant domain Replace <tenant domain name>

name>/<api>/user_impersonation with the tenant's domain name.
openid offline_access
Replace <api> with the App ID URI
you gave the web API when you first
registered it (in this case, api ). The
pattern for the URL is:
https:// {tenant }.onmicrosoft.com/ {ap
i-id-uri}/ {scope name}.
State <leave blank>
Client Authentication Send client credentials in body
3. Select the Request Token button.

4. Postman opens a new window containing the Azure AD B2C tenant's sign in dialog. Sign in with an existing
account (if one was created testing the policies) or select Sign up now to create a new account. The Forgot
your password? link is used to reset a forgotten password.
5. After successfully signing in, the window closes and the MANAGE ACCESS TOKENS dialog appears.
Scroll down to the bottom and select the Use Token button.
Test the web API with authentication

Select the Send button to send the request again. This time, the response status is 200 OK and the JSON payload
is visible on the response Body tab.
Next steps
Create an Azure Active Directory B2C tenant.
Register a Web API in Azure AD B2C.
Use Visual Studio to create a Web API configured to use the Azure AD B2C tenant for authentication.
Configure policies controlling the behavior of the Azure AD B2C tenant.
Use Postman to simulate a web app which presents a login dialog, retrieves a token, and uses it to make a
request against the web API.
Continue developing your API by learning to:
Secure an ASP.NET Core web app using Azure AD B2C.
Call a .NET web API from a .NET web app using Azure AD B2C.
Customize the Azure AD B2C user interface.
Configure password complexity requirements.
Enable multi-factor authentication.
Configure additional identity providers, such as Microsoft, Facebook, Google, Amazon, Twitter, and others.
Use the Azure AD Graph API to retrieve additional user information, such as group membership, from the
Azure AD B2C tenant.
Articles based on ASP.NET Core projects created with
individual user accounts
ASP.NET Core Identity is included in project templates in Visual Studio with the "Individual User Accounts" option.
The authentication templates are available in .NET Core CLI with -au Individual :

dotnet new webapp -au Individual

dotnet new razor -au Individual
No Authentication
Authentication is specified in the .NET Core CLI with the -au option. In Visual Studio, the Change
Authentication dialog is available for new web applications. The default for new web apps in Visual Studio is No
Authentication.
Projects created with no authentication:
Don't contain web pages and UI to sign in and sign out.
Don't contain authentication code.
Windows Authentication is specified for new web apps in the .NET Core CLI with the -au Windows option. In
Visual Studio, the Change Authentication dialog provides the Windows Authentication options.
If Windows Authentication is selected, the app is configured to use the Windows Authentication IIS module.
Windows Authentication is intended for Intranet web sites.
The following articles show how to use the code generated in ASP.NET Core templates that use individual user
accounts:
Create an ASP.NET Core app with user data protected by authorization
Authorization in ASP.NET Core
Introduction
Razor Pages authorization
Authorization policy providers
View -based authorization
Authorize with a specific scheme
Introduction to authorization in ASP.NET Core
Authorization refers to the process that determines what a user is able to do. For example, an administrative user
is allowed to create a document library, add documents, edit documents, and delete them. A non-administrative
user working with the library is only authorized to read the documents.
Authorization is orthogonal and independent from authentication. However, authorization requires an
authentication mechanism. Authentication is the process of ascertaining who a user is. Authentication may create
one or more identities for the current user.
Authorization types
ASP.NET Core authorization provides a simple, declarative role and a rich policy-based model. Authorization is
expressed in requirements, and handlers evaluate a user's claims against requirements. Imperative checks can be
based on simple policies or policies which evaluate both the user identity and properties of the resource that the
user is attempting to access.
Namespaces
Authorization components, including the AuthorizeAttribute and AllowAnonymousAttribute attributes, are found in
the Microsoft.AspNetCore.Authorization namespace.
Consult the documentation on simple authorization.
See this PDF for the ASP.NET Core MVC version. The ASP.NET Core 1.1 version of this tutorial is in this folder.
The 1.1 ASP.NET Core sample is in the samples.
See this pdf
Create an ASP.NET Core app with user data protected by

authorization
This tutorial shows how to create an ASP.NET Core web app with user data protected by authorization. It displays
a list of contacts that authenticated (registered) users have created. There are three security groups:
Registered users can view all the approved data and can edit/delete their own data.
Managers can approve or reject contact data. Only approved contacts are visible to users.
Administrators can approve/reject and edit/delete any data.
In the following image, user Rick ( [email protected] ) is signed in. Rick can only view approved contacts and
Edit/Delete/Create New links for his contacts. Only the last record, created by Rick, displays Edit and Delete
links. Other users won't see the last record until a manager or administrator changes the status to "Approved".
In the following image, [email protected] is signed in and in the managers role:

The following image shows the managers details view of a contact:
The Approve and Reject buttons are only displayed for managers and administrators.
In the following image, [email protected] is signed in and in the administrators role:
The administrator has all privileges. She can read/edit/delete any contact and change the status of contacts.
The app was created by scaffolding the following Contact model:
public class Contact

{
public int ContactId { get; set; }
public string Address { get; set; }
public string Zip { get; set; }
[DataType(DataType.EmailAddress)]
}
The sample contains the following authorization handlers:

ContactIsOwnerAuthorizationHandler : Ensures that a user can only edit their data.
ContactManagerAuthorizationHandler : Allows managers to approve or reject contacts.
ContactAdministratorsAuthorizationHandler : Allows administrators to approve or reject contacts and to
edit/delete contacts.
Prerequisites
This tutorial is advanced. You should be familiar with:
ASP.NET Core
Authentication
Account Confirmation and Password Recovery
Authorization
In ASP.NET Core 2.1, User.IsInRole fails when using AddDefaultIdentity . This tutorial uses AddDefaultIdentity
and therefore requires ASP.NET Core 2.2 preview 1 or later. See this GitHub issue for a work-around.
The starter and completed app

Download the completed app. Test the completed app so you become familiar with its security features.
The starter app
Download the starter app.
Run the app, tap the ContactManager link, and verify you can create, edit, and delete a contact.
Secure user data

The following sections have all the major steps to create the secure user data app. You may find it helpful to refer
to the completed project.
Tie the contact data to the user
Use the ASP.NET Identity user ID to ensure users can edit their data, but not other users data. Add OwnerID and
ContactStatus to the Contact model:
public class Contact

{
public int ContactId { get; set; }
// user ID from AspNetUser table.

public string OwnerID { get; set; }

public string Address { get; set; }
public string Zip { get; set; }
[DataType(DataType.EmailAddress)]
public ContactStatus Status { get; set; }

}
public enum ContactStatus

{
Submitted,
Approved,
Rejected
}
OwnerID is the user's ID from the AspNetUser table in the Identity database. The Status field determines if a
contact is viewable by general users.
Create a new migration and update the database:
dotnet ef migrations add userID_Status

Add Role services to Identity

Append AddRoles to add Role services:

{
{
});
services.AddDefaultIdentity<IdentityUser>().AddRoles<IdentityRole>()
Require authenticated users

Set the default authentication policy to require users to be authenticated:

{
{
});
services.AddMvc(config =>
{
// using Microsoft.AspNetCore.Mvc.Authorization;
// using Microsoft.AspNetCore.Authorization;
var policy = new AuthorizationPolicyBuilder()
.RequireAuthenticatedUser()
.Build();
config.Filters.Add(new AuthorizeFilter(policy));
})
You can opt out of authentication at the Razor Page, controller, or action method level with the [AllowAnonymous]
attribute. Setting the default authentication policy to require users to be authenticated protects newly added
Razor Pages and controllers. Having authentication required by default is more secure than relying on new
controllers and Razor Pages to include the [Authorize] attribute.
Add AllowAnonymous to the Index, About, and Contact pages so anonymous users can get information about the
site before they register.
namespace ContactManager.Pages
{
[AllowAnonymous]
{
public void OnGet()
{
}
}
}
Configure the test account

The SeedData class creates two accounts: administrator and manager. Use the Secret Manager tool to set a
password for these accounts. Set the password from the project directory (the directory containing Program.cs):
dotnet user-secrets set SeedUserPW <PW>
If a strong password is not specified, an exception is thrown when SeedData.Initialize is called.

Update Main to use the test password:

{
{

{
var context = services.GetRequiredService<ApplicationDbContext>();
// requires using Microsoft.Extensions.Configuration;

var config = host.Services.GetRequiredService<IConfiguration>();
// Set password with the Secret Manager tool.
// dotnet user-secrets set SeedUserPW <pw>
var testUserPw = config["SeedUserPW"];

try
{
SeedData.Initialize(services, testUserPw).Wait();
}
{
logger.LogError(ex.Message, "An error occurred seeding the DB.");
}
}
host.Run();
}

}
Create the test accounts and update the contacts
Update the Initialize method in the SeedData class to create the test accounts:
public static async Task Initialize(IServiceProvider serviceProvider, string testUserPw)

{
using (var context = new ApplicationDbContext(
serviceProvider.GetRequiredService<DbContextOptions<ApplicationDbContext>>()))
{
// For sample purposes seed both with the same password.
// Password is set with the following:
// dotnet user-secrets set SeedUserPW <pw>
// The admin user can do anything
var adminID = await EnsureUser(serviceProvider, testUserPw, "[email protected]");

await EnsureRole(serviceProvider, adminID, Constants.ContactAdministratorsRole);
// allowed user can create and edit contacts that they create
var managerID = await EnsureUser(serviceProvider, testUserPw, "[email protected]");
await EnsureRole(serviceProvider, managerID, Constants.ContactManagersRole);
SeedDB(context, adminID);
}
}
private static async Task<string> EnsureUser(IServiceProvider serviceProvider,

string testUserPw, string UserName)
{
var userManager = serviceProvider.GetService<UserManager<IdentityUser>>();
var user = await userManager.FindByNameAsync(UserName);

if (user == null)
{
user = new IdentityUser { UserName = UserName };
await userManager.CreateAsync(user, testUserPw);
}
return user.Id;
}
private static async Task<IdentityResult> EnsureRole(IServiceProvider serviceProvider,

string uid, string role)
{
IdentityResult IR = null;
var roleManager = serviceProvider.GetService<RoleManager<IdentityRole>>();
if (roleManager == null)
{
throw new Exception("roleManager null");
}
if (!await roleManager.RoleExistsAsync(role))
{
IR = await roleManager.CreateAsync(new IdentityRole(role));
}
var userManager = serviceProvider.GetService<UserManager<IdentityUser>>();
var user = await userManager.FindByIdAsync(uid);
IR = await userManager.AddToRoleAsync(user, role);
return IR;
}
Add the administrator user ID and ContactStatus to the contacts. Make one of the contacts "Submitted" and one
"Rejected". Add the user ID and status to all the contacts. Only one contact is shown:
public static void SeedDB(ApplicationDbContext context, string adminID)

{
if (context.Contact.Any())
{
}
context.Contact.AddRange(
new Contact
{
Name = "Debra Garcia",
Address = "1234 Main St",
City = "Redmond",
State = "WA",
Zip = "10999",
Email = "[email protected]",
Status = ContactStatus.Approved,
OwnerID = adminID
},
Create owner, manager, and administrator authorization handlers

Create a ContactIsOwnerAuthorizationHandler class in the Authorization folder. The
ContactIsOwnerAuthorizationHandler verifies that the user acting on a resource owns the resource.
using ContactManager.Data;
using ContactManager.Models;
using Microsoft.AspNetCore.Authorization.Infrastructure;
namespace ContactManager.Authorization
{
public class ContactIsOwnerAuthorizationHandler
: AuthorizationHandler<OperationAuthorizationRequirement, Contact>
{
UserManager<IdentityUser> _userManager;
public ContactIsOwnerAuthorizationHandler(UserManager<IdentityUser>
userManager)
{
}
protected override Task

HandleRequirementAsync(AuthorizationHandlerContext context,
OperationAuthorizationRequirement requirement,
Contact resource)
{
if (context.User == null || resource == null)
{
// Return Task.FromResult(0) if targeting a version of
// .NET Framework older than 4.6:
}
// If we're not asking for CRUD permission, return.
if (requirement.Name != Constants.CreateOperationName &&

requirement.Name != Constants.ReadOperationName &&
requirement.Name != Constants.UpdateOperationName &&
requirement.Name != Constants.DeleteOperationName )
{
}
if (resource.OwnerID == _userManager.GetUserId(context.User))
{
context.Succeed(requirement);
}
}
}
}
The ContactIsOwnerAuthorizationHandler calls context.Succeed if the current authenticated user is the contact
owner. Authorization handlers generally:
Return context.Succeed when the requirements are met.
Return Task.CompletedTask when requirements aren't met. Task.CompletedTask is neither success or failure—it
allows other authorization handlers to run.
If you need to explicitly fail, return context.Fail.
The app allows contact owners to edit/delete/create their own data. ContactIsOwnerAuthorizationHandler doesn't
need to check the operation passed in the requirement parameter.
Create a manager authorization handler
Create a ContactManagerAuthorizationHandler class in the Authorization folder. The
ContactManagerAuthorizationHandler verifies the user acting on the resource is a manager. Only managers can
approve or reject content changes (new or changed).
{
public class ContactManagerAuthorizationHandler :
AuthorizationHandler<OperationAuthorizationRequirement, Contact>
{
protected override Task
HandleRequirementAsync(AuthorizationHandlerContext context,
Contact resource)
{
if (context.User == null || resource == null)
{
}
// If not asking for approval/reject, return.

if (requirement.Name != Constants.ApproveOperationName &&
requirement.Name != Constants.RejectOperationName)
{
}
// Managers can approve or reject.

if (context.User.IsInRole(Constants.ContactManagersRole))
{
}
}
}
}
Create an administrator authorization handler

Create a ContactAdministratorsAuthorizationHandler class in the Authorization folder. The
ContactAdministratorsAuthorizationHandler verifies the user acting on the resource is an administrator.
Administrator can do all operations.
{
public class ContactAdministratorsAuthorizationHandler
: AuthorizationHandler<OperationAuthorizationRequirement, Contact>
{
protected override Task HandleRequirementAsync(
AuthorizationHandlerContext context,
Contact resource)
{
if (context.User == null)
{
}
// Administrators can do anything.

if (context.User.IsInRole(Constants.ContactAdministratorsRole))
{
}
}
}
}
Register the authorization handlers

Services using Entity Framework Core must be registered for dependency injection using AddScoped. The
ContactIsOwnerAuthorizationHandler uses ASP.NET Core Identity, which is built on Entity Framework Core.
Register the handlers with the service collection so they're available to the ContactsController through
dependency injection. Add the following code to the end of ConfigureServices :
{
{
});
services.AddMvc(config =>
{
// using Microsoft.AspNetCore.Mvc.Authorization;
// using Microsoft.AspNetCore.Authorization;
var policy = new AuthorizationPolicyBuilder()
.RequireAuthenticatedUser()
.Build();
config.Filters.Add(new AuthorizeFilter(policy));
})
// Authorization handlers.
services.AddScoped<IAuthorizationHandler,
ContactIsOwnerAuthorizationHandler>();
services.AddSingleton<IAuthorizationHandler,
ContactAdministratorsAuthorizationHandler>();
services.AddSingleton<IAuthorizationHandler,
ContactManagerAuthorizationHandler>();
}
ContactAdministratorsAuthorizationHandler and ContactManagerAuthorizationHandler are added as singletons.

They're singletons because they don't use EF and all the information needed is in the Context parameter of the
HandleRequirementAsync method.
Support authorization
In this section, you update the Razor Pages and add an operations requirements class.
Review the contact operations requirements class
Review the ContactOperations class. This class contains the requirements the app supports:
{
public static class ContactOperations
{
public static OperationAuthorizationRequirement Create =
new OperationAuthorizationRequirement {Name=Constants.CreateOperationName};
public static OperationAuthorizationRequirement Read =
new OperationAuthorizationRequirement {Name=Constants.ReadOperationName};
public static OperationAuthorizationRequirement Update =
new OperationAuthorizationRequirement {Name=Constants.UpdateOperationName};
public static OperationAuthorizationRequirement Delete =
new OperationAuthorizationRequirement {Name=Constants.DeleteOperationName};
public static OperationAuthorizationRequirement Approve =
new OperationAuthorizationRequirement {Name=Constants.ApproveOperationName};
public static OperationAuthorizationRequirement Reject =
new OperationAuthorizationRequirement {Name=Constants.RejectOperationName};
}
public class Constants

{
public static readonly string CreateOperationName = "Create";
public static readonly string ReadOperationName = "Read";
public static readonly string UpdateOperationName = "Update";
public static readonly string DeleteOperationName = "Delete";
public static readonly string ApproveOperationName = "Approve";
public static readonly string RejectOperationName = "Reject";
public static readonly string ContactAdministratorsRole =

"ContactAdministrators";
public static readonly string ContactManagersRole = "ContactManagers";
}
}
Create a base class for the Contacts Razor Pages

Create a base class that contains the services used in the contacts Razor Pages. The base class puts the
initialization code in one location:
using ContactManager.Data;
namespace ContactManager.Pages.Contacts
{
public class DI_BasePageModel : PageModel
{
protected ApplicationDbContext Context { get; }
protected IAuthorizationService AuthorizationService { get; }
protected UserManager<IdentityUser> UserManager { get; }
public DI_BasePageModel(
ApplicationDbContext context,
IAuthorizationService authorizationService,
UserManager<IdentityUser> userManager) : base()
{
Context = context;
UserManager = userManager;
AuthorizationService = authorizationService;
}
}
}
The preceding code:
Adds the IAuthorizationService service to access to the authorization handlers.
Adds the Identity UserManager service.
Add the ApplicationDbContext .
Update the CreateModel
Update the create page model constructor to use the DI_BasePageModel base class:
public class CreateModel : DI_BasePageModel

{
public CreateModel(
UserManager<IdentityUser> userManager)
: base(context, authorizationService, userManager)
{
}
Update the CreateModel.OnPostAsync method to:

Add the user ID to the Contact model.
Call the authorization handler to verify the user has permission to create contacts.

{
{
return Page();
}
Contact.OwnerID = UserManager.GetUserId(User);
// requires using ContactManager.Authorization;

var isAuthorized = await AuthorizationService.AuthorizeAsync(
User, Contact,
ContactOperations.Create);
if (!isAuthorized.Succeeded)
{
return new ChallengeResult();
}
Context.Contact.Add(Contact);
await Context.SaveChangesAsync();
}
Update the IndexModel

Update the OnGetAsync method so only approved contacts are shown to general users:
public class IndexModel : DI_BasePageModel
{
public IndexModel(
{
}
public IList<Contact> Contact { get; set; }

{
var contacts = from c in Context.Contact
select c;
var isAuthorized = User.IsInRole(Constants.ContactManagersRole) ||

User.IsInRole(Constants.ContactAdministratorsRole);
var currentUserId = UserManager.GetUserId(User);
// Only approved contacts are shown UNLESS you're authorized to see them
// or you are the owner.
if (!isAuthorized)
{
contacts = contacts.Where(c => c.Status == ContactStatus.Approved
|| c.OwnerID == currentUserId);
}
Contact = await contacts.ToListAsync();

}
}
Update the EditModel

Add an authorization handler to verify the user owns the contact. Because resource authorization is being
validated, the [Authorize] attribute is not enough. The app doesn't have access to the resource when attributes
are evaluated. Resource-based authorization must be imperative. Checks must be performed once the app has
access to the resource, either by loading it in the page model or by loading it within the handler itself. You
frequently access the resource by passing in the resource key.
public class EditModel : DI_BasePageModel

{
public EditModel(
{
}
[BindProperty]
public Contact Contact { get; set; }

{
Contact = await Context.Contact.FirstOrDefaultAsync(
m => m.ContactId == id);
if (Contact == null)
{
return NotFound();
}
User, Contact,
ContactOperations.Update);
{
}
return Page();
}

{
{
return Page();
}
// Fetch Contact from DB to get OwnerID.

var contact = await Context
.Contact.AsNoTracking()
.FirstOrDefaultAsync(m => m.ContactId == id);
if (contact == null)
{
return NotFound();
}

User, contact,
ContactOperations.Update);
{
}
Contact.OwnerID = contact.OwnerID;
Context.Attach(Contact).State = EntityState.Modified;
if (contact.Status == ContactStatus.Approved)
{
// If the contact is updated after approval,
// and the user cannot approve,
// set the status back to submitted so the update can be
// checked and approved.
var canApprove = await AuthorizationService.AuthorizeAsync(User,
contact,
ContactOperations.Approve);
if (!canApprove.Succeeded)
{
contact.Status = ContactStatus.Submitted;
}
}
}
private bool ContactExists(int id)

{
return Context.Contact.Any(e => e.ContactId == id);
}
}
Update the DeleteModel
Update the delete page model to use the authorization handler to verify the user has delete permission on the
contact.
public class DeleteModel : DI_BasePageModel

{
public DeleteModel(
{
}
[BindProperty]

{
Contact = await Context.Contact.FirstOrDefaultAsync(
{
return NotFound();
}

User, Contact,
ContactOperations.Delete);
{
}
return Page();
}

{
Contact = await Context.Contact.FindAsync(id);
var contact = await Context

.Contact.AsNoTracking()
.FirstOrDefaultAsync(m => m.ContactId == id);
{
return NotFound();
}

User, contact,
ContactOperations.Delete);
{
}
Context.Contact.Remove(Contact);
}
}
Inject the authorization service into the views
Currently, the UI shows edit and delete links for contacts the user can't modify.
Inject the authorization service in the Views/_ViewImports.cshtml file so it's available to all views:
@using ContactManager
@using ContactManager.Data
@namespace ContactManager.Pages
@using ContactManager.Authorization;
@using Microsoft.AspNetCore.Authorization
@using ContactManager.Models
@inject IAuthorizationService AuthorizationService
The preceding markup adds several using statements.

Update the Edit and Delete links in Pages/Contacts/Index.cshtml so they're only rendered for users with the
appropriate permissions:
@page
@model ContactManager.Pages.Contacts.IndexModel
@{
}
<h2>Index</h2>
<p>
</p>
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.Contact[0].Name)
</th>
<th>
@Html.DisplayNameFor(model => model.Contact[0].Address)
</th>
<th>
@Html.DisplayNameFor(model => model.Contact[0].City)
</th>
<th>
@Html.DisplayNameFor(model => model.Contact[0].State)
</th>
<th>
@Html.DisplayNameFor(model => model.Contact[0].Zip)
</th>
<th>
@Html.DisplayNameFor(model => model.Contact[0].Email)
</th>
<th>
@Html.DisplayNameFor(model => model.Contact[0].Status)
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Contact)
{
<tr>
<td>
</td>
<td>
@Html.DisplayFor(modelItem => item.Address)
</td>
<td>
@Html.DisplayFor(modelItem => item.City)
</td>
<td>
@Html.DisplayFor(modelItem => item.State)
</td>
<td>
@Html.DisplayFor(modelItem => item.Zip)
</td>
<td>
@Html.DisplayFor(modelItem => item.Email)
</td>
<td>
@Html.DisplayFor(modelItem => item.Status)
</td>
<td>
@if ((await AuthorizationService.AuthorizeAsync(
User, item,
ContactOperations.Update)).Succeeded)
{
<a asp-page="./Edit" asp-route-id="@item.ContactId">Edit</a>
<text> | </text>
}
<a asp-page="./Details" asp-route-id="@item.ContactId">Details</a>

User, item,
ContactOperations.Delete)).Succeeded)
{
<text> | </text>
<a asp-page="./Delete" asp-route-id="@item.ContactId">Delete</a>
}
</td>
</tr>
}
</tbody>
</table>
WARNING
Hiding links from users that don't have permission to change data doesn't secure the app. Hiding links makes the app more
user-friendly by displaying only valid links. Users can hack the generated URLs to invoke edit and delete operations on data
they don't own. The Razor Page or controller must enforce access checks to secure the data.
Update Details
Update the details view so managers can approve or reject contacts:
@*Precedng markup omitted for brevity.*@
<dt>
@Html.DisplayNameFor(model => model.Contact.Email)
</dt>
<dd>
@Html.DisplayFor(model => model.Contact.Email)
</dd>
<dt>
@Html.DisplayNameFor(model => model.Contact.Status)
</dt>
<dd>
@Html.DisplayFor(model => model.Contact.Status)
</dd>
</dl>
</div>
@if (Model.Contact.Status != ContactStatus.Approved)

{
User, Model.Contact, ContactOperations.Approve)).Succeeded)
{
<form style="display:inline;" method="post">
<input type="hidden" name="id" value="@Model.Contact.ContactId" />
<input type="hidden" name="status" value="@ContactStatus.Approved" />
<button type="submit" class="btn btn-xs btn-success">Approve</button>
</form>
}
}
@if (Model.Contact.Status != ContactStatus.Rejected)

{
User, Model.Contact, ContactOperations.Reject)).Succeeded)
{
<form style="display:inline;" method="post">
<input type="hidden" name="id" value="@Model.Contact.ContactId" />
<input type="hidden" name="status" value="@ContactStatus.Rejected" />
<button type="submit" class="btn btn-xs btn-success">Reject</button>
</form>
}
}
<div>
User, Model.Contact,
ContactOperations.Update)).Succeeded)
{
<a asp-page="./Edit" asp-route-id="@Model.Contact.ContactId">Edit</a>
<text> | </text>
}
</div>
Update the details page model:

public class DetailsModel : DI_BasePageModel
{
public DetailsModel(
{
}

{
Contact = await Context.Contact.FirstOrDefaultAsync(m => m.ContactId == id);
{
return NotFound();
}
var isAuthorized = User.IsInRole(Constants.ContactManagersRole) ||

User.IsInRole(Constants.ContactAdministratorsRole);
var currentUserId = UserManager.GetUserId(User);
if (!isAuthorized
&& currentUserId != Contact.OwnerID
&& Contact.Status != ContactStatus.Approved)
{
}
return Page();
}
public async Task<IActionResult> OnPostAsync(int id, ContactStatus status)

{
var contact = await Context.Contact.FirstOrDefaultAsync(
{
return NotFound();
}
var contactOperation = (status == ContactStatus.Approved)

? ContactOperations.Approve
: ContactOperations.Reject;
var isAuthorized = await AuthorizationService.AuthorizeAsync(User, contact,

contactOperation);
{
}
contact.Status = status;
Context.Contact.Update(contact);
}
}
Add or remove a user to a role

See this issue for information on:
Removing privileges from a user. For example muting a user in a chat app.
Adding privileges to a user.
Test the completed app

If the app has contacts:
Delete all the records in the Contact table.
Restart the app to seed the database.
Register a user for browsing the contacts.
An easy way to test the completed app is to launch three different browsers (or incognito/InPrivate versions). In
one browser, register a new user (for example, [email protected] ). Sign in to each browser with a different user.
Verify the following operations:
Registered users can view all the approved contact data.
Registered users can edit/delete their own data.
Managers can approve or reject contact data. The Details view shows Approve and Reject buttons.
Administrators can approve/reject and edit/delete any data.
USER OPTIONS
[email protected] Can edit/delete own data
[email protected] Can approve/reject and edit/delete own data
[email protected] Can edit/delete and approve/reject all data
Create a contact in the administrator's browser. Copy the URL for delete and edit from the administrator contact.
Paste these links into the test user's browser to verify the test user can't perform these operations.
Create the starter app

Create a Razor Pages app named "ContactManager"
Create the app with Individual User Accounts.
Name it "ContactManager" so the namespace matches the namespace used in the sample.
-uld specifies LocalDB instead of SQLite
dotnet new webapp -o ContactManager -au Individual -uld
Add Models\Contact.cs:
Scaffold the Contact model.

Create initial migration and update the database:
dotnet aspnet-codegenerator razorpage -m Contact -udl -dc ApplicationDbContext -outDir Pages\Contacts --
dotnet ef database drop -f
dotnet ef migrations add initial
Update the ContactManager anchor in the Pages/_Layout.cshtml file:
<a asp-page="/Contacts/Index" class="navbar-brand">ContactManager</a>
Test the app by creating, editing, and deleting a contact

Seed the database
Add the SeedData class to the Data folder.
Call SeedData.Initialize from Main :

{
{

{
try
{
var context = services.GetRequiredService<ApplicationDbContext>();
SeedData.Initialize(services, "not used");
}
{
}
}
host.Run();
}

}
Test that the app seeded the database. If there are any rows in the contact DB, the seed method doesn't run.
ASP.NET Core Authorization Lab. This lab goes into more detail on the security features introduced in this
tutorial.
Authorization in ASP.NET Core: Simple, role, claims-based, and custom
Custom policy-based authorization
Razor Pages authorization conventions in ASP.NET
Core
By Luke Latham
One way to control access in your Razor Pages app is to use authorization conventions at startup. These
conventions allow you to authorize users and allow anonymous users to access individual pages or folders of
pages. The conventions described in this topic automatically apply authorization filters to control access.
The sample app uses Cookie authentication without ASP.NET Core Identity. The user account for the hypothetical
user, Maria Rodriguez, is hardcoded into the app. Use the Email username "[email protected]" and
any password to sign in the user. The user is authenticated in the AuthenticateUser method in the
Pages/Account/Login.cshtml.cs file. In a real-world example, the user would be authenticated against a database.
To use ASP.NET Core Identity, follow the guidance in the Introduction to Identity on ASP.NET Core topic. The
concepts and examples shown in this topic apply equally to apps that use ASP.NET Core Identity.
Require authorization to access a page

Use the AuthorizePage convention via AddRazorPagesOptions to add an AuthorizeFilter to the page at the
specified path:
services.AddMvc()
{
options.Conventions.AuthorizePage("/Contact");
options.Conventions.AuthorizeFolder("/Private");
options.Conventions.AllowAnonymousToPage("/Private/PublicPage");
options.Conventions.AllowAnonymousToFolder("/Private/PublicPages");
})
The specified path is the View Engine path, which is the Razor Pages root relative path without an extension and
containing only forward slashes.
An AuthorizePage overload is available if you need to specify an authorization policy.
NOTE
An AuthorizeFilter can be applied to a page model class with the [Authorize] filter attribute. For more information,
see Authorize filter attribute.
Require authorization to access a folder of pages

Use the AuthorizeFolder convention via AddRazorPagesOptions to add an AuthorizeFilter to all of the pages in a
folder at the specified path:
services.AddMvc()
{
})
The specified path is the View Engine path, which is the Razor Pages root relative path.
An AuthorizeFolder overload is available if you need to specify an authorization policy.
Require authorization to access an area page

Use the AuthorizeAreaPage convention via AddRazorPagesOptions to add an AuthorizeFilter to the area page at
the specified path:
options.Conventions.AuthorizeAreaPage("Identity", "/Manage/Accounts");
The page name is the path of the file without an extension relative to the pages root directory for the specified
area. For example, the page name for the file Areas/Identity/Pages/Manage/Accounts.cshtml is
/Manage/Accounts.
An AuthorizeAreaPage overload is available if you need to specify an authorization policy.
Require authorization to access a folder of areas

Use the AuthorizeAreaFolder convention via AddRazorPagesOptions to add an AuthorizeFilter to all of the areas
in a folder at the specified path:
options.Conventions.AuthorizeAreaFolder("Identity", "/Manage");
The folder path is the path of the folder relative to the pages root directory for the specified area. For example, the
folder path for the files under Areas/Identity/Pages/Manage/ is /Manage.
An AuthorizeAreaFolder overload is available if you need to specify an authorization policy.
Allow anonymous access to a page

Use the AllowAnonymousToPage convention via AddRazorPagesOptions to add an AllowAnonymousFilter to a
page at the specified path:
services.AddMvc()
{
})
The specified path is the View Engine path, which is the Razor Pages root relative path without an extension and
containing only forward slashes.
Allow anonymous access to a folder of pages
Use the AllowAnonymousToFolder convention via AddRazorPagesOptions to add an AllowAnonymousFilter to
all of the pages in a folder at the specified path:
services.AddMvc()
{
})
The specified path is the View Engine path, which is the Razor Pages root relative path.
Note on combining authorized and anonymous access

It's perfectly valid to specify that a folder of pages require authorization and specify that a page within that folder
allows anonymous access:
// This works.
.AuthorizeFolder("/Private").AllowAnonymousToPage("/Private/Public")
The reverse, however, isn't true. You can't declare a folder of pages for anonymous access and specify a page
within for authorization:
// This doesn't work!

.AllowAnonymousToFolder("/Public").AuthorizePage("/Public/Private")
Requiring authorization on the Private page won't work because when both the AllowAnonymousFilter and
AuthorizeFilter filters are applied to the page, the AllowAnonymousFilter wins and controls access.
Razor Pages custom route and page model providers
PageConventionCollection class
Simple authorization in ASP.NET Core
Authorization in MVC is controlled through the AuthorizeAttribute attribute and its various parameters. At its
simplest, applying the AuthorizeAttribute attribute to a controller or action limits access to the controller or
action to any authenticated user.
For example, the following code limits access to the AccountController to any authenticated user.
[Authorize]
{
public ActionResult Login()
{
}
public ActionResult Logout()

{
}
}
If you want to apply authorization to an action rather than the controller, apply the AuthorizeAttribute attribute
to the action itself:

{
{
}
[Authorize]
{
}
}
Now only authenticated users can access the Logout function.

You can also use the AllowAnonymous attribute to allow access by non-authenticated users to individual actions.
For example:
[Authorize]
{
[AllowAnonymous]
{
}

{
}
}
This would allow only authenticated users to the AccountController , except for the Login action, which is
accessible by everyone, regardless of their authenticated or unauthenticated / anonymous status.
WARNING
[AllowAnonymous] bypasses all authorization statements. If you combine [AllowAnonymous] and any [Authorize]
attribute, the [Authorize] attributes are ignored. For example if you apply [AllowAnonymous] at the controller level,
any [Authorize] attributes on the same controller (or on any action within it) is ignored.
Role-based authorization in ASP.NET Core
When an identity is created it may belong to one or more roles. For example, Tracy may belong to the
Administrator and User roles whilst Scott may only belong to the User role. How these roles are created and
managed depends on the backing store of the authorization process. Roles are exposed to the developer through
the IsInRole method on the ClaimsPrincipal class.
IMPORTANT
This topic does not apply to Razor Pages. Razor Pages supports IPageFilter and IAsyncPageFilter. For more information, see
Filter methods for Razor Pages.
Adding role checks

Role-based authorization checks are declarative—the developer embeds them within their code, against a
controller or an action within a controller, specifying roles which the current user must be a member of to access
the requested resource.
For example, the following code limits access to any actions on the AdministrationController to users who are a
member of the Administrator role:
[Authorize(Roles = "Administrator")]
public class AdministrationController : Controller
{
}
You can specify multiple roles as a comma separated list:
[Authorize(Roles = "HRManager,Finance")]
public class SalaryController : Controller
{
}
This controller would be only accessible by users who are members of the HRManager role or the Finance role.
If you apply multiple attributes then an accessing user must be a member of all the roles specified; the following
sample requires that a user must be a member of both the PowerUser and ControlPanelUser role.
[Authorize(Roles = "PowerUser")]
[Authorize(Roles = "ControlPanelUser")]
public class ControlPanelController : Controller
{
}
You can further limit access by applying additional role authorization attributes at the action level:
[Authorize(Roles = "Administrator, PowerUser")]
{
public ActionResult SetTime()
{
}
[Authorize(Roles = "Administrator")]
public ActionResult ShutDown()
{
}
}
In the previous code snippet members of the Administrator role or the PowerUser role can access the controller
and the SetTime action, but only members of the Administrator role can access the ShutDown action.
You can also lock down a controller but allow anonymous, unauthenticated access to individual actions.
[Authorize]
{
public ActionResult SetTime()
{
}
[AllowAnonymous]
{
}
}
Policy based role checks

Role requirements can also be expressed using the new Policy syntax, where a developer registers a policy at
startup as part of the Authorization service configuration. This normally occurs in ConfigureServices() in your
Startup.cs file.

{
services.AddMvc();
services.AddAuthorization(options =>
{
options.AddPolicy("RequireAdministratorRole", policy => policy.RequireRole("Administrator"));
});
}
Policies are applied using the Policy property on the AuthorizeAttribute attribute:
[Authorize(Policy = "RequireAdministratorRole")]
public IActionResult Shutdown()
{
return View();
}
If you want to specify multiple allowed roles in a requirement then you can specify them as parameters to the
RequireRole method:
options.AddPolicy("ElevatedRights", policy =>
policy.RequireRole("Administrator", "PowerUser", "BackupAdministrator"));
This example authorizes users who belong to the Administrator , PowerUser or BackupAdministrator roles.
Claims-based authorization in ASP.NET Core
When an identity is created it may be assigned one or more claims issued by a trusted party. A claim is a name
value pair that represents what the subject is, not what the subject can do. For example, you may have a driver's
license, issued by a local driving license authority. Your driver's license has your date of birth on it. In this case the
claim name would be DateOfBirth , the claim value would be your date of birth, for example 8th June 1970 and
the issuer would be the driving license authority. Claims based authorization, at its simplest, checks the value of a
claim and allows access to a resource based upon that value. For example if you want access to a night club the
authorization process might be:
The door security officer would evaluate the value of your date of birth claim and whether they trust the issuer
(the driving license authority) before granting you access.
An identity can contain multiple claims with multiple values and can contain multiple claims of the same type.
Adding claims checks

Claim based authorization checks are declarative - the developer embeds them within their code, against a
controller or an action within a controller, specifying claims which the current user must possess, and optionally
the value the claim must hold to access the requested resource. Claims requirements are policy based, the
developer must build and register a policy expressing the claims requirements.
The simplest type of claim policy looks for the presence of a claim and doesn't check the value.
First you need to build and register the policy. This takes place as part of the Authorization service configuration,
which normally takes part in ConfigureServices() in your Startup.cs file.

{
services.AddMvc();
{
options.AddPolicy("EmployeeOnly", policy => policy.RequireClaim("EmployeeNumber"));
});
}
In this case the EmployeeOnly policy checks for the presence of an EmployeeNumber claim on the current identity.
You then apply the policy using the Policy property on the AuthorizeAttribute attribute to specify the policy
name;
[Authorize(Policy = "EmployeeOnly")]
public IActionResult VacationBalance()
{
return View();
}
The AuthorizeAttribute attribute can be applied to an entire controller, in this instance only identities matching
the policy will be allowed access to any Action on the controller.
public class VacationController : Controller
{
public ActionResult VacationBalance()
{
}
}
If you have a controller that's protected by the AuthorizeAttribute attribute, but want to allow anonymous access
to particular actions you apply the AllowAnonymousAttribute attribute.
public class VacationController : Controller
{
public ActionResult VacationBalance()
{
}
[AllowAnonymous]
public ActionResult VacationPolicy()
{
}
}
Most claims come with a value. You can specify a list of allowed values when creating the policy. The following
example would only succeed for employees whose employee number was 1, 2, 3, 4 or 5.

{
services.AddMvc();
{
options.AddPolicy("Founders", policy =>
policy.RequireClaim("EmployeeNumber", "1", "2", "3", "4", "5"));
});
}
Add a generic claim check

If the claim value isn't a single value or a transformation is required, use RequireAssertion. For more information,
see Using a func to fulfill a policy.
Multiple Policy Evaluation

If you apply multiple policies to a controller or action, then all policies must pass before access is granted. For
example:
public class SalaryController : Controller
{
public ActionResult Payslip()
{
}
[Authorize(Policy = "HumanResources")]
public ActionResult UpdateSalary()
{
}
}
In the above example any identity which fulfills the EmployeeOnly policy can access the Payslip action as that
policy is enforced on the controller. However in order to call the UpdateSalary action the identity must fulfill both
the EmployeeOnly policy and the HumanResources policy.
If you want more complicated policies, such as taking a date of birth claim, calculating an age from it then
checking the age is 21 or older then you need to write custom policy handlers.
Policy-based authorization in ASP.NET Core
Underneath the covers, role-based authorization and claims-based authorization use a requirement, a
requirement handler, and a pre-configured policy. These building blocks support the expression of authorization
evaluations in code. The result is a richer, reusable, testable authorization structure.
An authorization policy consists of one or more requirements. It's registered as part of the authorization service
configuration, in the Startup.ConfigureServices method:

{
services.AddMvc();
{
options.AddPolicy("AtLeast21", policy =>
policy.Requirements.Add(new MinimumAgeRequirement(21)));
});
}
In the preceding example, an "AtLeast21" policy is created. It has a single requirement—that of a minimum age,
which is supplied as a parameter to the requirement.
Policies are applied by using the [Authorize] attribute with the policy name. For example:
[Authorize(Policy = "AtLeast21")]
public class AlcoholPurchaseController : Controller
{
public IActionResult Login() => View();
public IActionResult Logout() => View();

}
Requirements
An authorization requirement is a collection of data parameters that a policy can use to evaluate the current user
principal. In our "AtLeast21" policy, the requirement is a single parameter—the minimum age. A requirement
implements IAuthorizationRequirement, which is an empty marker interface. A parameterized minimum age
requirement could be implemented as follows:
public class MinimumAgeRequirement : IAuthorizationRequirement

{
public int MinimumAge { get; private set; }
public MinimumAgeRequirement(int minimumAge)

{
MinimumAge = minimumAge;
}
}
NOTE
A requirement doesn't need to have data or properties.
Authorization handlers
An authorization handler is responsible for the evaluation of a requirement's properties. The authorization
handler evaluates the requirements against a provided AuthorizationHandlerContext to determine if access is
allowed.
A requirement can have multiple handlers. A handler may inherit AuthorizationHandler<TRequirement>, where
TRequirement is the requirement to be handled. Alternatively, a handler may implement IAuthorizationHandler
to handle more than one type of requirement.
Use a handler for one requirement
The following is an example of a one-to-one relationship in which a minimum age handler utilizes a single
requirement:
using PoliciesAuthApp1.Services.Requirements;
using System;
using System.Security.Claims;
public class MinimumAgeHandler : AuthorizationHandler<MinimumAgeRequirement>

{
protected override Task HandleRequirementAsync(AuthorizationHandlerContext context,
MinimumAgeRequirement requirement)
{
if (!context.User.HasClaim(c => c.Type == ClaimTypes.DateOfBirth &&
c.Issuer == "http://contoso.com"))
{
//TODO: Use the following if targeting a version of
//.NET Framework older than 4.6:
// return Task.FromResult(0);
}
var dateOfBirth = Convert.ToDateTime(

context.User.FindFirst(c => c.Type == ClaimTypes.DateOfBirth &&
c.Issuer == "http://contoso.com").Value);
int calculatedAge = DateTime.Today.Year - dateOfBirth.Year;

if (dateOfBirth > DateTime.Today.AddYears(-calculatedAge))
{
calculatedAge--;
}
if (calculatedAge >= requirement.MinimumAge)

{
}

}
}
The preceding code determines if the current user principal has a date of birth claim which has been issued by a
known and trusted Issuer. Authorization can't occur when the claim is missing, in which case a completed task is
returned. When a claim is present, the user's age is calculated. If the user meets the minimum age defined by the
requirement, authorization is deemed successful. When authorization is successful, context.Succeed is invoked
with the satisfied requirement as its sole parameter.
Use a handler for multiple requirements
The following is an example of a one-to-many relationship in which a permission handler utilizes three
requirements:
public class PermissionHandler : IAuthorizationHandler

{
public Task HandleAsync(AuthorizationHandlerContext context)
{
var pendingRequirements = context.PendingRequirements.ToList();
foreach (var requirement in pendingRequirements)

{
if (requirement is ReadPermission)
{
if (IsOwner(context.User, context.Resource) ||
IsSponsor(context.User, context.Resource))
{
}
}
else if (requirement is EditPermission ||
requirement is DeletePermission)
{
if (IsOwner(context.User, context.Resource))
{
}
}
}

}
private bool IsOwner(ClaimsPrincipal user, object resource)

{
return true;
}
private bool IsSponsor(ClaimsPrincipal user, object resource)

{
return true;
}
}
The preceding code traverses PendingRequirements—a property containing requirements not marked as
successful. If the user has read permission, he or she must be either an owner or a sponsor to access the
requested resource. If the user has edit or delete permission, he or she must be an owner to access the requested
resource. When authorization is successful, context.Succeed is invoked with the satisfied requirement as its sole
parameter.
Handler registration
Handlers are registered in the services collection during configuration. For example:
{
services.AddMvc();
{
options.AddPolicy("AtLeast21", policy =>
policy.Requirements.Add(new MinimumAgeRequirement(21)));
});
services.AddSingleton<IAuthorizationHandler, MinimumAgeHandler>();
}
Each handler is added to the services collection by invoking

services.AddSingleton<IAuthorizationHandler, YourHandlerClass>(); .
What should a handler return?

Note that the Handle method in the handler example returns no value. How is a status of either success or
failure indicated?
A handler indicates success by calling context.Succeed(IAuthorizationRequirement requirement) , passing
the requirement that has been successfully validated.
A handler doesn't need to handle failures generally, as other handlers for the same requirement may
succeed.
To guarantee failure, even if other requirement handlers succeed, call context.Fail .
When set to false , the InvokeHandlersAfterFailure property (available in ASP.NET Core 1.1 and later) short-
circuits the execution of handlers when context.Fail is called. InvokeHandlersAfterFailure defaults to true , in
which case all handlers are called. This allows requirements to produce side effects, such as logging, which
always take place even if context.Fail has been called in another handler.
Why would I want multiple handlers for a requirement?

In cases where you want evaluation to be on an OR basis, implement multiple handlers for a single requirement.
For example, Microsoft has doors which only open with key cards. If you leave your key card at home, the
receptionist prints a temporary sticker and opens the door for you. In this scenario, you'd have a single
requirement, BuildingEntry, but multiple handlers, each one examining a single requirement.
BuildingEntryRequirement.cs
public class BuildingEntryRequirement : IAuthorizationRequirement

{
}
BadgeEntryHandler.cs
public class BadgeEntryHandler : AuthorizationHandler<BuildingEntryRequirement>

{
BuildingEntryRequirement requirement)
{
if (context.User.HasClaim(c => c.Type == ClaimTypes.BadgeId &&
c.Issuer == "http://microsoftsecurity"))
{
}

}
}
TemporaryStickerHandler.cs
public class TemporaryStickerHandler : AuthorizationHandler<BuildingEntryRequirement>

{
BuildingEntryRequirement requirement)
{
if (context.User.HasClaim(c => c.Type == ClaimTypes.TemporaryBadgeId &&
c.Issuer == "https://microsoftsecurity"))
{
// We'd also check the expiration date on the sticker.
}

}
}
Ensure that both handlers are registered. If either handler succeeds when a policy evaluates the
BuildingEntryRequirement , the policy evaluation succeeds.
Using a func to fulfill a policy

There may be situations in which fulfilling a policy is simple to express in code. It's possible to supply a
Func<AuthorizationHandlerContext, bool> when configuring your policy with the RequireAssertion policy builder.
For example, the previous BadgeEntryHandler could be rewritten as follows:

{
options.AddPolicy("BadgeEntry", policy =>
policy.RequireAssertion(context =>
context.User.HasClaim(c =>
(c.Type == ClaimTypes.BadgeId ||
c.Type == ClaimTypes.TemporaryBadgeId) &&
c.Issuer == "https://microsoftsecurity")));
});
Accessing MVC request context in handlers

The HandleRequirementAsync method you implement in an authorization handler has two parameters: an
AuthorizationHandlerContext and the TRequirement you are handling. Frameworks such as MVC or Jabbr are
free to add any object to the Resource property on the AuthorizationHandlerContext to pass extra information.
For example, MVC passes an instance of AuthorizationFilterContext in the Resource property. This property
provides access to HttpContext , RouteData , and everything else provided by MVC and Razor Pages.
The use of the Resource property is framework specific. Using information in the Resource property limits your
authorization policies to particular frameworks. You should cast the Resource property using the as keyword,
and then confirm the cast has succeed to ensure your code doesn't crash with an InvalidCastException when run
on other frameworks:
// Requires the following import:

// using Microsoft.AspNetCore.Mvc.Filters;
if (context.Resource is AuthorizationFilterContext mvcContext)
{
// Examine MVC-specific things like routing data.
}
Custom Authorization Policy Providers using
IAuthorizationPolicyProvider in ASP.NET Core
By Mike Rousos
Typically when using policy-based authorization, policies are registered by calling AuthorizationOptions.AddPolicy
as part of authorization service configuration. In some scenarios, it may not be possible (or desirable) to register all
authorization policies in this way. In those cases, you can use a custom IAuthorizationPolicyProvider to control
how authorization policies are supplied.
Examples of scenarios where a custom IAuthorizationPolicyProvider may be useful include:
Using an external service to provide policy evaluation.
Using a large range of policies (for different room numbers or ages, for example), so it doesn’t make sense to
add each individual authorization policy with an AuthorizationOptions.AddPolicy call.
Creating policies at runtime based on information in an external data source (like a database) or determining
authorization requirements dynamically through another mechanism.
View or download sample code from the aspnet/AuthSamples GitHub repository. Download the
aspnet/AuthSamples repository ZIP file. Unzip the AuthSamples-master.zip file. Navigate to the
samples/CustomPolicyProvider project folder.
Customize policy retrieval

ASP.NET Core apps use an implementation of the IAuthorizationPolicyProvider interface to retrieve authorization
policies. By default, DefaultAuthorizationPolicyProvider is registered and used.
DefaultAuthorizationPolicyProvider returns policies from the AuthorizationOptions provided in an
IServiceCollection.AddAuthorization call.
You can customize this behavior by registering a different IAuthorizationPolicyProvider implementation in the
app’s dependency injection container.
The IAuthorizationPolicyProvider interface contains two APIs:
GetPolicyAsync returns an authorization policy for a given name.
GetDefaultPolicyAsync returns the default authorization policy (the policy used for [Authorize] attributes
without a policy specified).
By implementing these two APIs, you can customize how authorization policies are provided.
Parameterized authorize attribute example

One scenario where IAuthorizationPolicyProvider is useful is enabling custom [Authorize] attributes whose
requirements depend on a parameter. For example, in policy-based authorization documentation, an age-based
(“AtLeast21”) policy was used as a sample. If different controller actions in an app should be made available to
users of different ages, it might be useful to have many different age-based policies. Instead of registering all the
different age-based policies that the application will need in AuthorizationOptions , you can generate the policies
dynamically with a custom IAuthorizationPolicyProvider . To make using the policies easier, you can annotate
actions with custom authorization attribute like [MinimumAgeAuthorize(20)] .
Custom Authorization Attributes
Authorization policies are identified by their names. The custom MinimumAgeAuthorizeAttribute described
previously needs to map arguments into a string that can be used to retrieve the corresponding authorization
policy. You can do this by deriving from AuthorizeAttribute and making the Age property wrap the
AuthorizeAttribute.Policy property.
internal class MinimumAgeAuthorizeAttribute : AuthorizeAttribute

{
const string POLICY_PREFIX = "MinimumAge";
public MinimumAgeAuthorizeAttribute(int age) => Age = age;
// Get or set the Age property by manipulating the underlying Policy property
public int Age
{
get
{
if (int.TryParse(Policy.Substring(POLICY_PREFIX.Length), out var age))
{
return age;
}
return default(int);
}
set
{
Policy = $"{POLICY_PREFIX}{value.ToString()}";
}
}
}
This attribute type has a Policy string based on the hard-coded prefix ( "MinimumAge" ) and an integer passed in via
the constructor.
You can apply it to actions in the same way as other Authorize attributes except that it takes an integer as a
parameter.
[MinimumAgeAuthorize(10)]
public IActionResult RequiresMinimumAge10()
Custom IAuthorizationPolicyProvider
The custom MinimumAgeAuthorizeAttribute makes it easy to request authorization policies for any minimum age
desired. The next problem to solve is making sure that authorization policies are available for all of those different
ages. This is where an IAuthorizationPolicyProvider is useful.
When using MinimumAgeAuthorizationAttribute , the authorization policy names will follow the pattern
"MinimumAge" + Age , so the custom IAuthorizationPolicyProvider should generate authorization policies by:
Parsing the age from the policy name.

Using AuthorizationPolicyBuilder to create a new AuthorizationPolicy
Adding requirements to the policy based on the age with AuthorizationPolicyBuilder.AddRequirements . In other
scenarios, you might use RequireClaim , RequireRole , or RequireUserName instead.
internal class MinimumAgePolicyProvider : IAuthorizationPolicyProvider
{
const string POLICY_PREFIX = "MinimumAge";
// Policies are looked up by string name, so expect 'parameters' (like age)

// to be embedded in the policy names. This is abstracted away from developers
// by the more strongly-typed attributes derived from AuthorizeAttribute
// (like [MinimumAgeAuthorize()] in this sample)
public Task<AuthorizationPolicy> GetPolicyAsync(string policyName)
{
if (policyName.StartsWith(POLICY_PREFIX, StringComparison.OrdinalIgnoreCase) &&
int.TryParse(policyName.Substring(POLICY_PREFIX.Length), out var age))
{
var policy = new AuthorizationPolicyBuilder();
policy.AddRequirements(new MinimumAgeRequirement(age));
return Task.FromResult(policy.Build());
}
return Task.FromResult<AuthorizationPolicy>(null);
}
}
Multiple authorization policy providers

When using custom IAuthorizationPolicyProvider implementations, keep in mind that ASP.NET Core only uses
one instance of IAuthorizationPolicyProvider . If a custom provider isn't able to provide authorization policies for
all policy names, it should fall back to a backup provider. Policy names might include those that come from a
default policy for [Authorize] attributes without a name.
For example, consider an application needed both custom age policies and more traditional role-based policy
retrieval. Such an app could use a custom authorization policy provider that:
Attempts to parse policy names.
Calls into a different policy provider (like DefaultAuthorizationPolicyProvider ) if the policy name doesn't
contain an age.
Default policy
In addition to providing named authorization policies, a custom IAuthorizationPolicyProvider needs to implement
GetDefaultPolicyAsync to provide an authorization policy for [Authorize] attributes without a policy name
specified.
In many cases, this authorization attribute only requires an authenticated user, so you can make the necessary
policy with a call to RequireAuthenticatedUser :
public Task<AuthorizationPolicy> GetDefaultPolicyAsync() =>

Task.FromResult(new AuthorizationPolicyBuilder().RequireAuthenticatedUser().Build());
As with all aspects of a custom IAuthorizationPolicyProvider , you can customize this, as needed. In some cases:
Default authorization policies might not be used.
Retrieving the default policy can be delegated to a fallback IAuthorizationPolicyProvider .
Use a custom IAuthorizationPolicyProvider

To use custom policies from an IAuthorizationPolicyProvider , you must:
Register the appropriate AuthorizationHandler types with dependency injection (described in policy-based
authorization), as with all policy-based authorization scenarios.
Register the custom IAuthorizationPolicyProvider type in the app's dependency injection service collection (in
Startup.ConfigureServices ) to replace the default policy provider.
services.AddTransient<IAuthorizationPolicyProvider, MinimumAgePolicyProvider>();
A complete custom IAuthorizationPolicyProvider sample is available in the aspnet/AuthSamples GitHub

repository.
Dependency injection in requirement handlers in
ASP.NET Core
Authorization handlers must be registered in the service collection during configuration (using dependency
injection).
Suppose you had a repository of rules you wanted to evaluate inside an authorization handler and that repository
was registered in the service collection. Authorization will resolve and inject that into your constructor.
For example, if you wanted to use ASP.NET's logging infrastructure you would want to inject ILoggerFactory into
your handler. Such a handler might look like:
public class LoggingAuthorizationHandler : AuthorizationHandler<MyRequirement>

{
ILogger _logger;
public LoggingAuthorizationHandler(ILoggerFactory loggerFactory)

{
_logger = loggerFactory.CreateLogger(this.GetType().FullName);
}
protected override Task HandleRequirementAsync(AuthorizationHandlerContext context, MyRequirement

requirement)
{
_logger.LogInformation("Inside my handler");
// Check if the requirement is fulfilled.
}
}
You would register the handler with services.AddSingleton() :
services.AddSingleton<IAuthorizationHandler, LoggingAuthorizationHandler>();
An instance of the handler will be created when your application starts, and DI will inject the registered
ILoggerFactory into your constructor.
NOTE
Handlers that use Entity Framework shouldn't be registered as singletons.
Resource-based authorization in ASP.NET Core
Authorization strategy depends upon the resource being accessed. Consider a document which has an author
property. Only the author is allowed to update the document. Consequently, the document must be retrieved from
the data store before authorization evaluation can occur.
Attribute evaluation occurs before data binding and before execution of the page handler or action which loads the
document. For these reasons, declarative authorization with an [Authorize] attribute won't suffice. Instead, you
can invoke a custom authorization method—a style known as imperative authorization.
Use the sample apps (how to download) to explore the features described in this topic.
Create an ASP.NET Core app with user data protected by authorization contains a sample app that uses resource-
based authorization.
Use imperative authorization

Authorization is implemented as an IAuthorizationService service and is registered in the service collection within
the Startup class. The service is made available via dependency injection to page handlers or actions.
public class DocumentController : Controller

{
private readonly IAuthorizationService _authorizationService;
private readonly IDocumentRepository _documentRepository;
public DocumentController(IAuthorizationService authorizationService,

IDocumentRepository documentRepository)
{
_authorizationService = authorizationService;
_documentRepository = documentRepository;
}
IAuthorizationService has two AuthorizeAsync method overloads: one accepting the resource and the policy
name and the other accepting the resource and a list of requirements to evaluate.
ASP.NET Core 2.x
ASP.NET Core 1.x
Task<AuthorizationResult> AuthorizeAsync(ClaimsPrincipal user,

object resource,
IEnumerable<IAuthorizationRequirement> requirements);
Task<AuthorizationResult> AuthorizeAsync(ClaimsPrincipal user,
object resource,
string policyName);
In the following example, the resource to be secured is loaded into a custom Document object. An AuthorizeAsync
overload is invoked to determine whether the current user is allowed to edit the provided document. A custom
"EditPolicy" authorization policy is factored into the decision. See Custom policy-based authorization for more on
creating authorization policies.
NOTE
The following code samples assume authentication has run and set the User property.
ASP.NET Core 2.x

ASP.NET Core 1.x
public async Task<IActionResult> OnGetAsync(Guid documentId)

{
Document = _documentRepository.Find(documentId);
if (Document == null)
{
return new NotFoundResult();
}
var authorizationResult = await _authorizationService

.AuthorizeAsync(User, Document, "EditPolicy");
if (authorizationResult.Succeeded)
{
return Page();
}
else if (User.Identity.IsAuthenticated)
{
return new ForbidResult();
}
else
{
}
}
Write a resource-based handler

Writing a handler for resource-based authorization isn't much different than writing a plain requirements handler.
Create a custom requirement class, and implement a requirement handler class. The handler class specifies both
the requirement and resource type. For example, a handler utilizing a SameAuthorRequirement requirement and a
Document resource looks as follows:
ASP.NET Core 2.x

ASP.NET Core 1.x
public class DocumentAuthorizationHandler :
AuthorizationHandler<SameAuthorRequirement, Document>
{
SameAuthorRequirement requirement,
Document resource)
{
if (context.User.Identity?.Name == resource.Author)
{
}
}
}
public class SameAuthorRequirement : IAuthorizationRequirement { }
Register the requirement and handler in the Startup.ConfigureServices method:
services.AddMvc();
{
options.AddPolicy("EditPolicy", policy =>
policy.Requirements.Add(new SameAuthorRequirement()));
});
services.AddSingleton<IAuthorizationHandler, DocumentAuthorizationHandler>();
services.AddSingleton<IAuthorizationHandler, DocumentAuthorizationCrudHandler>();
services.AddScoped<IDocumentRepository, DocumentRepository>();
Operational requirements
If you're making decisions based on the outcomes of CRUD (Create, Read, Update, Delete) operations, use the
OperationAuthorizationRequirement helper class. This class enables you to write a single handler instead of an
individual class for each operation type. To use it, provide some operation names:
public static class Operations

{
public static OperationAuthorizationRequirement Create =
new OperationAuthorizationRequirement { Name = nameof(Create) };
public static OperationAuthorizationRequirement Read =
new OperationAuthorizationRequirement { Name = nameof(Read) };
public static OperationAuthorizationRequirement Update =
new OperationAuthorizationRequirement { Name = nameof(Update) };
public static OperationAuthorizationRequirement Delete =
new OperationAuthorizationRequirement { Name = nameof(Delete) };
}
The handler is implemented as follows, using an OperationAuthorizationRequirement requirement and a Document

resource:
ASP.NET Core 2.x
ASP.NET Core 1.x
public class DocumentAuthorizationCrudHandler :
AuthorizationHandler<OperationAuthorizationRequirement, Document>
{
Document resource)
{
if (context.User.Identity?.Name == resource.Author &&
requirement.Name == Operations.Read.Name)
{
}
}
}
The preceding handler validates the operation using the resource, the user's identity, and the requirement's Name
property.
To call an operational resource handler, specify the operation when invoking AuthorizeAsync in your page handler
or action. The following example determines whether the authenticated user is permitted to view the provided
document.
NOTE
The following code samples assume authentication has run and set the User property.
ASP.NET Core 2.x

ASP.NET Core 1.x
public async Task<IActionResult> OnGetAsync(Guid documentId)

{
Document = _documentRepository.Find(documentId);
if (Document == null)
{
return new NotFoundResult();
}
var authorizationResult = await _authorizationService

.AuthorizeAsync(User, Document, Operations.Read);
if (authorizationResult.Succeeded)
{
return Page();
}
else if (User.Identity.IsAuthenticated)
{
return new ForbidResult();
}
else
{
}
}
If authorization succeeds, the page for viewing the document is returned. If authorization fails but the user is
authenticated, returning ForbidResult informs any authentication middleware that authorization failed. A
ChallengeResult is returned when authentication must be performed. For interactive browser clients, it may be
appropriate to redirect the user to a login page.
View-based authorization in ASP.NET Core MVC
A developer often wants to show, hide, or otherwise modify a UI based on the current user identity. You can access
the authorization service within MVC views via dependency injection. To inject the authorization service into a
Razor view, use the @inject directive:
@using Microsoft.AspNetCore.Authorization
@inject IAuthorizationService AuthorizationService
If you want the authorization service in every view, place the @inject directive into the _ViewImports.cshtml file of
the Views directory. For more information, see Dependency injection into views.
Use the injected authorization service to invoke AuthorizeAsync in exactly the same way you would check during
resource-based authorization:
ASP.NET Core 2.x
ASP.NET Core 1.x
@if ((await AuthorizationService.AuthorizeAsync(User, "PolicyName")).Succeeded)

{
<p>This paragraph is displayed because you fulfilled PolicyName.</p>
}
In some cases, the resource will be your view model. Invoke AuthorizeAsync in exactly the same way you would
check during resource-based authorization:
ASP.NET Core 2.x
ASP.NET Core 1.x
@if ((await AuthorizationService.AuthorizeAsync(User, Model, Operations.Edit)).Succeeded)

{
<p><a class="btn btn-default" role="button"
href="@Url.Action("Edit", "Document", new { id = Model.Id })">Edit</a></p>
}
In the preceding code, the model is passed as a resource the policy evaluation should take into consideration.
WARNING
Don't rely on toggling visibility of your app's UI elements as the sole authorization check. Hiding a UI element may not
completely prevent access to its associated controller action. For example, consider the button in the preceding code snippet.
A user can invoke the Edit action method if he or she knows the relative resource URL is /Document/Edit/1. For this
reason, the Edit action method should perform its own authorization check.
Authorize with a specific scheme in ASP.NET Core
In some scenarios, such as Single Page Applications (SPAs), it's common to use multiple authentication methods.
For example, the app may use cookie-based authentication to log in and JWT bearer authentication for JavaScript
requests. In some cases, the app may have multiple instances of an authentication handler. For example, two
cookie handlers where one contains a basic identity and one is created when a multi-factor authentication (MFA)
has been triggered. MFA may be triggered because the user requested an operation that requires extra security.
ASP.NET Core 2.x
ASP.NET Core 1.x
An authentication scheme is named when the authentication service is configured during authentication. For
example:

{
.AddCookie(options => {
options.LoginPath = "/Account/Unauthorized/";
options.AccessDeniedPath = "/Account/Forbidden/";
})
.AddJwtBearer(options => {
options.Audience = "http://localhost:5001/";
options.Authority = "http://localhost:5000/";
});
In the preceding code, two authentication handlers have been added: one for cookies and one for bearer.
NOTE
Specifying the default scheme results in the HttpContext.User property being set to that identity. If that behavior isn't
desired, disable it by invoking the parameterless form of AddAuthentication .
Selecting the scheme with the Authorize attribute

At the point of authorization, the app indicates the handler to be used. Select the handler with which the app will
authorize by passing a comma-delimited list of authentication schemes to [Authorize] . The [Authorize]
attribute specifies the authentication scheme or schemes to use regardless of whether a default is configured. For
example:
ASP.NET Core 2.x
ASP.NET Core 1.x
[Authorize(AuthenticationSchemes = AuthSchemes)]
public class MixedController : Controller
// Requires the following imports:
// using Microsoft.AspNetCore.Authentication.Cookies;
// using Microsoft.AspNetCore.Authentication.JwtBearer;
private const string AuthSchemes =
CookieAuthenticationDefaults.AuthenticationScheme + "," +
JwtBearerDefaults.AuthenticationScheme;
In the preceding example, both the cookie and bearer handlers run and have a chance to create and append an
identity for the current user. By specifying a single scheme only, the corresponding handler runs.
ASP.NET Core 2.x
ASP.NET Core 1.x
[Authorize(AuthenticationSchemes =
JwtBearerDefaults.AuthenticationScheme)]
public class MixedController : Controller
In the preceding code, only the handler with the "Bearer" scheme runs. Any cookie-based identities are ignored.
Selecting the scheme with policies

If you prefer to specify the desired schemes in policy, you can set the AuthenticationSchemes collection when
adding your policy:
{
options.AddPolicy("Over18", policy =>
{
policy.AuthenticationSchemes.Add(JwtBearerDefaults.AuthenticationScheme);
policy.RequireAuthenticatedUser();
policy.Requirements.Add(new MinimumAgeRequirement());
});
});
In the preceding example, the "Over18" policy only runs against the identity created by the "Bearer" handler. Use
the policy by setting the [Authorize] attribute's Policy property:
[Authorize(Policy = "Over18")]
public class RegistrationController : Controller
Data Protection in ASP.NET Core

Consumer APIs
Consumer APIs overview
Purpose strings
Hash passwords
Configuration
Configure ASP.NET Core Data Protection
Default settings
Machine-wide policy
Non DI-aware scenarios
Extensibility APIs
Miscellaneous APIs
Implementation
Context headers
Key management
Key storage format
Compatibility
Replacing ASP.NET in ASP.NET Core
ASP.NET Core Data Protection
Web applications often need to store security-sensitive data. Windows provides DPAPI for desktop applications
but this is unsuitable for web applications. The ASP.NET Core data protection stack provide a simple, easy to use
cryptographic API a developer can use to protect data, including key management and rotation.
The ASP.NET Core data protection stack is designed to serve as the long-term replacement for the
<machineKey> element in ASP.NET 1.x - 4.x. It was designed to address many of the shortcomings of the old
cryptographic stack while providing an out-of-the-box solution for the majority of use cases modern applications
are likely to encounter.
Problem statement
The overall problem statement can be succinctly stated in a single sentence: I need to persist trusted information
for later retrieval, but I don't trust the persistence mechanism. In web terms, this might be written as "I need to
round-trip trusted state via an untrusted client."
The canonical example of this is an authentication cookie or bearer token. The server generates an "I am Groot
and have xyz permissions" token and hands it to the client. At some future date the client will present that token
back to the server, but the server needs some kind of assurance that the client hasn't forged the token. Thus the
first requirement: authenticity (a.k.a. integrity, tamper-proofing).
Since the persisted state is trusted by the server, we anticipate that this state might contain information that's
specific to the operating environment. This could be in the form of a file path, a permission, a handle or other
indirect reference, or some other piece of server-specific data. Such information should generally not be disclosed
to an untrusted client. Thus the second requirement: confidentiality.
Finally, since modern applications are componentized, what we've seen is that individual components will want to
take advantage of this system without regard to other components in the system. For instance, if a bearer token
component is using this stack, it should operate without interference from an anti-CSRF mechanism that might
also be using the same stack. Thus the final requirement: isolation.
We can provide further constraints in order to narrow the scope of our requirements. We assume that all services
operating within the cryptosystem are equally trusted and that the data doesn't need to be generated or
consumed outside of the services under our direct control. Furthermore, we require that operations are as fast as
possible since each request to the web service might go through the cryptosystem one or more times. This makes
symmetric cryptography ideal for our scenario, and we can discount asymmetric cryptography until such a time
that it's needed.
Design philosophy
We started by identifying problems with the existing stack. Once we had that, we surveyed the landscape of
existing solutions and concluded that no existing solution quite had the capabilities we sought. We then
engineered a solution based on several guiding principles.
The system should offer simplicity of configuration. Ideally the system would be zero-configuration and
developers could hit the ground running. In situations where developers need to configure a specific aspect
(such as the key repository), consideration should be given to making those specific configurations simple.
Offer a simple consumer-facing API. The APIs should be easy to use correctly and difficult to use
incorrectly.
Developers shouldn't learn key management principles. The system should handle algorithm selection and
key lifetime on the developer's behalf. Ideally the developer should never even have access to the raw key
material.
Keys should be protected at rest when possible. The system should figure out an appropriate default
protection mechanism and apply it automatically.
With these principles in mind we developed a simple, easy to use data protection stack.
The ASP.NET Core data protection APIs are not primarily intended for indefinite persistence of confidential
payloads. Other technologies like Windows CNG DPAPI and Azure Rights Management are more suited to the
scenario of indefinite storage, and they have correspondingly strong key management capabilities. That said,
there's nothing prohibiting a developer from using the ASP.NET Core data protection APIs for long-term
protection of confidential data.
Audience
The data protection system is divided into five main packages. Various aspects of these APIs target three main
audiences;
1. The Consumer APIs Overview target application and framework developers.
"I don't want to learn about how the stack operates or about how it's configured. I simply want to perform
some operation in as simple a manner as possible with high probability of using the APIs successfully."
2. The configuration APIs target application developers and system administrators.
"I need to tell the data protection system that my environment requires non-default paths or settings."
3. The extensibility APIs target developers in charge of implementing custom policy. Usage of these APIs
would be limited to rare situations and experienced, security aware developers.
"I need to replace an entire component within the system because I have truly unique behavioral
requirements. I am willing to learn uncommonly-used parts of the API surface in order to build a plugin
that fulfills my requirements."
Package layout
The data protection stack consists of five packages.
Microsoft.AspNetCore.DataProtection.Abstractions contains the IDataProtectionProvider and
IDataProtector interfaces to create data protection services. It also contains useful extension methods for
working with these types (for example, IDataProtector.Protect). If the data protection system is instantiated
elsewhere and you're consuming the API, reference Microsoft.AspNetCore.DataProtection.Abstractions .
Microsoft.AspNetCore.DataProtection contains the core implementation of the data protection system,
including core cryptographic operations, key management, configuration, and extensibility. To instantiate
the data protection system (for example, adding it to an IServiceCollection) or modifying or extending its
behavior, reference Microsoft.AspNetCore.DataProtection .
Microsoft.AspNetCore.DataProtection.Extensions contains additional APIs which developers might find
useful but which don't belong in the core package. For instance, this package contains factory methods to
instantiate the data protection system to store keys at a location on the file system without dependency
injection (see DataProtectionProvider). It also contains extension methods for limiting the lifetime of
protected payloads (see ITimeLimitedDataProtector).
Microsoft.AspNetCore.DataProtection.SystemWeb can be installed into an existing ASP.NET 4.x app to
redirect its <machineKey> operations to use the new ASP.NET Core data protection stack. For more
information, see Replace the ASP.NET machineKey in ASP.NET Core.
Microsoft.AspNetCore.Cryptography.KeyDerivation provides an implementation of the PBKDF2 password
hashing routine and can be used by systems that must handle user passwords securely. For more
information, see Hash passwords in ASP.NET Core.
Get started with the Data Protection APIs in ASP.NET
Core
At its simplest, protecting data consists of the following steps:

1. Create a data protector from a data protection provider.
2. Call the Protect method with the data you want to protect.
3. Call the Unprotect method with the data you want to turn back into plain text.
Most frameworks and app models, such as ASP.NET Core or SignalR, already configure the data protection
system and add it to a service container you access via dependency injection. The following sample demonstrates
configuring a service container for dependency injection and registering the data protection stack, receiving the
data protection provider via DI, creating a protector and protecting then unprotecting data.
using System;
using Microsoft.AspNetCore.DataProtection;

{
{
// add data protection services
var serviceCollection = new ServiceCollection();
serviceCollection.AddDataProtection();
var services = serviceCollection.BuildServiceProvider();
// create an instance of MyClass using the service provider

var instance = ActivatorUtilities.CreateInstance<MyClass>(services);
instance.RunSample();
}

{
IDataProtector _protector;
// the 'provider' parameter is provided by DI

public MyClass(IDataProtectionProvider provider)
{
_protector = provider.CreateProtector("Contoso.MyClass.v1");
}
public void RunSample()

{
Console.Write("Enter input: ");
string input = Console.ReadLine();
// protect the payload

string protectedPayload = _protector.Protect(input);
Console.WriteLine($"Protect returned: {protectedPayload}");
// unprotect the payload

string unprotectedPayload = _protector.Unprotect(protectedPayload);
Console.WriteLine($"Unprotect returned: {unprotectedPayload}");
}
}
}
/*
* SAMPLE OUTPUT
*
* Enter input: Hello world!
* Protect returned: CfDJ8ICcgQwZZhlAlTZT...OdfH66i1PnGmpCR5e441xQ
* Unprotect returned: Hello world!
*/
When you create a protector you must provide one or more Purpose Strings. A purpose string provides isolation
between consumers. For example, a protector created with a purpose string of "green" wouldn't be able to
unprotect data provided by a protector with a purpose of "purple".
TIP
Instances of IDataProtectionProvider and IDataProtector are thread-safe for multiple callers. It's intended that once a
component gets a reference to an IDataProtector via a call to CreateProtector , it will use that reference for multiple
calls to Protect and Unprotect .
A call to Unprotect will throw CryptographicException if the protected payload cannot be verified or deciphered. Some
components may wish to ignore errors during unprotect operations; a component which reads authentication cookies might
handle this error and treat the request as if it had no cookie at all rather than fail the request outright. Components which
want this behavior should specifically catch CryptographicException instead of swallowing all exceptions.
Consumer APIs for ASP.NET Core
Consumer APIs Overview

Purpose Strings
Hash passwords
Consumer APIs overview for ASP.NET Core
The IDataProtectionProvider and IDataProtector interfaces are the basic interfaces through which consumers
use the data protection system. They're located in the Microsoft.AspNetCore.DataProtection.Abstractions
package.
IDataProtectionProvider
The provider interface represents the root of the data protection system. It cannot directly be used to protect or
unprotect data. Instead, the consumer must get a reference to an IDataProtector by calling
IDataProtectionProvider.CreateProtector(purpose) , where purpose is a string that describes the intended
consumer use case. See Purpose Strings for much more information on the intent of this parameter and how to
choose an appropriate value.
IDataProtector
The protector interface is returned by a call to CreateProtector , and it's this interface which consumers can use to
perform protect and unprotect operations.
To protect a piece of data, pass the data to the Protect method. The basic interface defines a method which
converts byte[] -> byte[], but there's also an overload (provided as an extension method) which converts string ->
string. The security offered by the two methods is identical; the developer should choose whichever overload is
most convenient for their use case. Irrespective of the overload chosen, the value returned by the Protect method
is now protected (enciphered and tamper-proofed), and the application can send it to an untrusted client.
To unprotect a previously-protected piece of data, pass the protected data to the Unprotect method. (There are
byte[]-based and string-based overloads for developer convenience.) If the protected payload was generated by
an earlier call to Protect on this same IDataProtector , the Unprotect method will return the original
unprotected payload. If the protected payload has been tampered with or was produced by a different
IDataProtector , the Unprotect method will throw CryptographicException.
The concept of same vs. different IDataProtector ties back to the concept of purpose. If two IDataProtector
instances were generated from the same root IDataProtectionProvider but via different purpose strings in the call
to IDataProtectionProvider.CreateProtector , then they're considered different protectors, and one won't be able to
unprotect payloads generated by the other.
Consuming these interfaces

For a DI-aware component, the intended usage is that the component take an IDataProtectionProvider
parameter in its constructor and that the DI system automatically provides this service when the component is
instantiated.
NOTE
Some applications (such as console applications or ASP.NET 4.x applications) might not be DI-aware so cannot use the
mechanism described here. For these scenarios consult the Non DI Aware Scenarios document for more information on
getting an instance of an IDataProtection provider without going through DI.
The following sample demonstrates three concepts:

1. Add the data protection system to the service container,
2. Using DI to receive an instance of an IDataProtectionProvider , and
3. Creating an IDataProtector from an IDataProtectionProvider and using it to protect and unprotect data.
using System;

{
{
// create an instance of MyClass using the service provider

var instance = ActivatorUtilities.CreateInstance<MyClass>(services);
instance.RunSample();
}

{
IDataProtector _protector;
// the 'provider' parameter is provided by DI

public MyClass(IDataProtectionProvider provider)
{
_protector = provider.CreateProtector("Contoso.MyClass.v1");
}
public void RunSample()

{

string protectedPayload = _protector.Protect(input);

string unprotectedPayload = _protector.Unprotect(protectedPayload);
}
}
}
/*
* SAMPLE OUTPUT
*
* Protect returned: CfDJ8ICcgQwZZhlAlTZT...OdfH66i1PnGmpCR5e441xQ
*/
The package Microsoft.AspNetCore.DataProtection.Abstractions contains an extension method

IServiceProvider.GetDataProtector as a developer convenience. It encapsulates as a single operation both
retrieving an IDataProtectionProvider from the service provider and calling
IDataProtectionProvider.CreateProtector . The following sample demonstrates its usage.
using System;

{
{
// get an IDataProtector from the IServiceProvider

var protector = services.GetDataProtector("Contoso.Example.v2");

string protectedPayload = protector.Protect(input);

string unprotectedPayload = protector.Unprotect(protectedPayload);
}
}
TIP
Instances of IDataProtectionProvider and IDataProtector are thread-safe for multiple callers. It's intended that once
a component gets a reference to an IDataProtector via a call to CreateProtector , it will use that reference for multiple
calls to Protect and Unprotect . A call to Unprotect will throw CryptographicException if the protected payload cannot
be verified or deciphered. Some components may wish to ignore errors during unprotect operations; a component which
reads authentication cookies might handle this error and treat the request as if it had no cookie at all rather than fail the
request outright. Components which want this behavior should specifically catch CryptographicException instead of
swallowing all exceptions.
Purpose strings in ASP.NET Core
Components which consume IDataProtectionProvider must pass a unique purposes parameter to the
CreateProtector method. The purposes parameter is inherent to the security of the data protection system, as it
provides isolation between cryptographic consumers, even if the root cryptographic keys are the same.
When a consumer specifies a purpose, the purpose string is used along with the root cryptographic keys to
derive cryptographic subkeys unique to that consumer. This isolates the consumer from all other cryptographic
consumers in the application: no other component can read its payloads, and it cannot read any other
component's payloads. This isolation also renders infeasible entire categories of attack against the component.
In the diagram above, IDataProtector instances A and B cannot read each other's payloads, only their own.
The purpose string doesn't have to be secret. It should simply be unique in the sense that no other well-behaved
component will ever provide the same purpose string.
TIP
Using the namespace and type name of the component consuming the data protection APIs is a good rule of thumb, as in
practice this information will never conflict.
A Contoso-authored component which is responsible for minting bearer tokens might use Contoso.Security.BearerToken as
its purpose string. Or - even better - it might use Contoso.Security.BearerToken.v1 as its purpose string. Appending the
version number allows a future version to use Contoso.Security.BearerToken.v2 as its purpose, and the different versions
would be completely isolated from one another as far as payloads go.
Since the purposes parameter to CreateProtectoris a string array, the above could've been instead specified as
[ "Contoso.Security.BearerToken", "v1" ] . This allows establishing a hierarchy of purposes and opens up the
possibility of multi-tenancy scenarios with the data protection system.
WARNING
Components shouldn't allow untrusted user input to be the sole source of input for the purposes chain.
For example, consider a component Contoso.Messaging.SecureMessage which is responsible for storing secure messages. If
the secure messaging component were to call CreateProtector([ username ]) , then a malicious user might create an
account with username "Contoso.Security.BearerToken" in an attempt to get the component to call
CreateProtector([ "Contoso.Security.BearerToken" ]) , thus inadvertently causing the secure messaging system to
mint payloads that could be perceived as authentication tokens.
A better purposes chain for the messaging component would be
CreateProtector([ "Contoso.Messaging.SecureMessage", "User: username" ]) , which provides proper isolation.
The isolation provided by and behaviors of IDataProtectionProvider , IDataProtector , and purposes are as
follows:
For a given IDataProtectionProvider object, the CreateProtector method will create an IDataProtector
object uniquely tied to both the IDataProtectionProvider object which created it and the purposes
parameter which was passed into the method.
The purpose parameter must not be null. (If purposes is specified as an array, this means that the array
must not be of zero length and all elements of the array must be non-null.) An empty string purpose is
technically allowed but is discouraged.
Two purposes arguments are equivalent if and only if they contain the same strings (using an ordinal
comparer) in the same order. A single purpose argument is equivalent to the corresponding single-
element purposes array.
Two IDataProtector objects are equivalent if and only if they're created from equivalent
IDataProtectionProvider objects with equivalent purposes parameters.
For a given IDataProtector object, a call to Unprotect(protectedData) will return the original
unprotectedData if and only if protectedData := Protect(unprotectedData) for an equivalent
IDataProtector object.
NOTE
We're not considering the case where some component intentionally chooses a purpose string which is known to conflict
with another component. Such a component would essentially be considered malicious, and this system isn't intended to
provide security guarantees in the event that malicious code is already running inside of the worker process.
Purpose hierarchy and multi-tenancy in ASP.NET
Core
Since an IDataProtector is also implicitly an IDataProtectionProvider , purposes can be chained together. In this
sense, provider.CreateProtector([ "purpose1", "purpose2" ]) is equivalent to
provider.CreateProtector("purpose1").CreateProtector("purpose2") .
This allows for some interesting hierarchical relationships through the data protection system. In the earlier
example of Contoso.Messaging.SecureMessage, the SecureMessage component can call
provider.CreateProtector("Contoso.Messaging.SecureMessage") once up-front and cache the result into a private
_myProvider field. Future protectors can then be created via calls to
_myProvider.CreateProtector("User: username") , and these protectors would be used for securing the individual
messages.
This can also be flipped. Consider a single logical application which hosts multiple tenants (a CMS seems
reasonable), and each tenant can be configured with its own authentication and state management system. The
umbrella application has a single master provider, and it calls provider.CreateProtector("Tenant 1") and
provider.CreateProtector("Tenant 2") to give each tenant its own isolated slice of the data protection system. The
tenants could then derive their own individual protectors based on their own needs, but no matter how hard they
try they cannot create protectors which collide with any other tenant in the system. Graphically, this is represented
as below.
WARNING
This assumes the umbrella application controls which APIs are available to individual tenants and that tenants cannot
execute arbitrary code on the server. If a tenant can execute arbitrary code, they could perform private reflection to break
the isolation guarantees, or they could just read the master keying material directly and derive whatever subkeys they
desire.
The data protection system actually uses a sort of multi-tenancy in its default out-of-the-box configuration. By
default master keying material is stored in the worker process account's user profile folder (or the registry, for IIS
application pool identities). But it's actually fairly common to use a single account to run multiple applications, and
thus all these applications would end up sharing the master keying material. To solve this, the data protection
system automatically inserts a unique-per-application identifier as the first element in the overall purpose chain.
This implicit purpose serves to isolate individual applications from one another by effectively treating each
application as a unique tenant within the system, and the protector creation process looks identical to the image
above.
Hash passwords in ASP.NET Core
The data protection code base includes a package Microsoft.AspNetCore.Cryptography.KeyDerivation which

contains cryptographic key derivation functions. This package is a standalone component and has no
dependencies on the rest of the data protection system. It can be used completely independently. The source exists
alongside the data protection code base as a convenience.
The package currently offers a method KeyDerivation.Pbkdf2 which allows hashing a password using the PBKDF2
algorithm. This API is very similar to the .NET Framework's existing Rfc2898DeriveBytes type, but there are three
important distinctions:
1. The KeyDerivation.Pbkdf2 method supports consuming multiple PRFs (currently HMACSHA1 , HMACSHA256 ,
and HMACSHA512 ), whereas the Rfc2898DeriveBytes type only supports HMACSHA1 .
2. The KeyDerivation.Pbkdf2 method detects the current operating system and attempts to choose the most
optimized implementation of the routine, providing much better performance in certain cases. (On
Windows 8, it offers around 10x the throughput of Rfc2898DeriveBytes .)
3. The KeyDerivation.Pbkdf2 method requires the caller to specify all parameters (salt, PRF, and iteration
count). The Rfc2898DeriveBytes type provides default values for these.
using System;
using System.Security.Cryptography;
using Microsoft.AspNetCore.Cryptography.KeyDerivation;

{
{
Console.Write("Enter a password: ");
string password = Console.ReadLine();
// generate a 128-bit salt using a secure PRNG

byte[] salt = new byte[128 / 8];
using (var rng = RandomNumberGenerator.Create())
{
rng.GetBytes(salt);
}
Console.WriteLine($"Salt: {Convert.ToBase64String(salt)}");
// derive a 256-bit subkey (use HMACSHA1 with 10,000 iterations)

string hashed = Convert.ToBase64String(KeyDerivation.Pbkdf2(
password: password,
salt: salt,
prf: KeyDerivationPrf.HMACSHA1,
iterationCount: 10000,
numBytesRequested: 256 / 8));
Console.WriteLine($"Hashed: {hashed}");
}
}
/*
* SAMPLE OUTPUT
*
* Enter a password: Xtw9NMgx
* Salt: NZsP6NnmfBuYeJrrAKNuVQ==
* Hashed: /OOoOer10+tGwTRDTrQSoeCxVTFr6dtYly7d0cPxIak=
*/
See the source code for ASP.NET Core Identity's PasswordHasher type for a real-world use case.
Limit the lifetime of protected payloads in ASP.NET
Core
There are scenarios where the application developer wants to create a protected payload that expires after a set
period of time. For instance, the protected payload might represent a password reset token that should only be
valid for one hour. It's certainly possible for the developer to create their own payload format that contains an
embedded expiration date, and advanced developers may wish to do this anyway, but for the majority of
developers managing these expirations can grow tedious.
To make this easier for our developer audience, the package Microsoft.AspNetCore.DataProtection.Extensions
contains utility APIs for creating payloads that automatically expire after a set period of time. These APIs hang off
of the ITimeLimitedDataProtector type.
API usage
The ITimeLimitedDataProtector interface is the core interface for protecting and unprotecting time-limited / self-
expiring payloads. To create an instance of an ITimeLimitedDataProtector , you'll first need an instance of a regular
IDataProtector constructed with a specific purpose. Once the IDataProtector instance is available, call the
IDataProtector.ToTimeLimitedDataProtector extension method to get back a protector with built-in expiration
capabilities.
ITimeLimitedDataProtector exposes the following API surface and extension methods:
CreateProtector(string purpose) : ITimeLimitedDataProtector - This API is similar to the existing
IDataProtectionProvider.CreateProtector in that it can be used to create purpose chains from a root time-
limited protector.
Protect(byte[] plaintext, DateTimeOffset expiration) : byte[]
Protect(byte[] plaintext, TimeSpan lifetime) : byte[]
Protect(byte[] plaintext) : byte[]
Protect(string plaintext, DateTimeOffset expiration) : string
Protect(string plaintext, TimeSpan lifetime) : string
Protect(string plaintext) : string
In addition to the core Protect methods which take only the plaintext, there are new overloads which allow
specifying the payload's expiration date. The expiration date can be specified as an absolute date (via a
DateTimeOffset ) or as a relative time (from the current system time, via a TimeSpan ). If an overload which doesn't
take an expiration is called, the payload is assumed never to expire.
Unprotect(byte[] protectedData, out DateTimeOffset expiration) : byte[]
Unprotect(byte[] protectedData) : byte[]
Unprotect(string protectedData, out DateTimeOffset expiration) : string
Unprotect(string protectedData) : string
The Unprotect methods return the original unprotected data. If the payload hasn't yet expired, the absolute
expiration is returned as an optional out parameter along with the original unprotected data. If the payload is
expired, all overloads of the Unprotect method will throw CryptographicException.
WARNING
It's not advised to use these APIs to protect payloads which require long-term or indefinite persistence. "Can I afford for the
protected payloads to be permanently unrecoverable after a month?" can serve as a good rule of thumb; if the answer is no
then developers should consider alternative APIs.
The sample below uses the non-DI code paths for instantiating the data protection system. To run this sample,
ensure that you have first added a reference to the Microsoft.AspNetCore.DataProtection.Extensions package.
using System;
using System.IO;
using System.Threading;

{
{
// create a protector for my application
var provider = DataProtectionProvider.Create(new DirectoryInfo(@"c:\myapp-keys\"));

var baseProtector = provider.CreateProtector("Contoso.TimeLimitedSample");
// convert the normal protector into a time-limited protector

var timeLimitedProtector = baseProtector.ToTimeLimitedDataProtector();
// get some input and protect it for five seconds

string protectedData = timeLimitedProtector.Protect(input, lifetime: TimeSpan.FromSeconds(5));
Console.WriteLine($"Protected data: {protectedData}");
// unprotect it to demonstrate that round-tripping works properly

string roundtripped = timeLimitedProtector.Unprotect(protectedData);
Console.WriteLine($"Round-tripped data: {roundtripped}");
// wait 6 seconds and perform another unprotect, demonstrating that the payload self-expires
Console.WriteLine("Waiting 6 seconds...");
Thread.Sleep(6000);
timeLimitedProtector.Unprotect(protectedData);
}
}
/*
* SAMPLE OUTPUT
*
* Enter input: Hello!
* Protected data: CfDJ8Hu5z0zwxn...nLk7Ok
* Round-tripped data: Hello!
* Waiting 6 seconds...
* <<throws CryptographicException with message 'The payload expired at ...'>>
*/
in ASP.NET Core
The ASP.NET Core data protection APIs are not primarily intended for indefinite persistence of confidential
payloads. Other technologies like Windows CNG DPAPI and Azure Rights Management are more suited to the
scenario of indefinite storage, and they have correspondingly strong key management capabilities. That said,
there's nothing prohibiting a developer from using the ASP.NET Core data protection APIs for long-term
protection of confidential data. Keys are never removed from the key ring, so IDataProtector.Unprotect can
always recover existing payloads as long as the keys are available and valid.
However, an issue arises when the developer tries to unprotect data that has been protected with a revoked key, as
IDataProtector.Unprotect will throw an exception in this case. This might be fine for short-lived or transient
payloads (like authentication tokens), as these kinds of payloads can easily be recreated by the system, and at
worst the site visitor might be required to log in again. But for persisted payloads, having Unprotect throw could
lead to unacceptable data loss.
IPersistedDataProtector
To support the scenario of allowing payloads to be unprotected even in the face of revoked keys, the data
protection system contains an IPersistedDataProtector type. To get an instance of IPersistedDataProtector ,
simply get an instance of IDataProtector in the normal fashion and try casting the IDataProtector to
IPersistedDataProtector .
NOTE
Not all IDataProtector instances can be cast to IPersistedDataProtector . Developers should use the C# as operator or
similar to avoid runtime exceptions caused by invalid casts, and they should be prepared to handle the failure case
appropriately.
IPersistedDataProtector exposes the following API surface:
DangerousUnprotect(byte[] protectedData, bool ignoreRevocationErrors,

out bool requiresMigration, out bool wasRevoked) : byte[]
This API takes the protected payload (as a byte array) and returns the unprotected payload. There's no string-
based overload. The two out parameters are as follows.
requiresMigration : will be set to true if the key used to protect this payload is no longer the active default
key, e.g., the key used to protect this payload is old and a key rolling operation has since taken place. The
caller may wish to consider reprotecting the payload depending on their business needs.
wasRevoked : will be set to true if the key used to protect this payload was revoked.
WARNING
Exercise extreme caution when passing ignoreRevocationErrors: true to the DangerousUnprotect method. If after
calling this method the wasRevoked value is true, then the key used to protect this payload was revoked, and the payload's
authenticity should be treated as suspect. In this case, only continue operating on the unprotected payload if you have
some separate assurance that it's authentic, e.g. that it's coming from a secure database rather than being sent by an
untrusted web client.
using System;
using System.IO;
using System.Text;
using Microsoft.AspNetCore.DataProtection.KeyManagement;

{
{
serviceCollection.AddDataProtection()
// point at a specific folder and use DPAPI to encrypt keys
.PersistKeysToFileSystem(new DirectoryInfo(@"c:\temp-keys"))
.ProtectKeysWithDpapi();
// get a protector and perform a protect operation

var protector = services.GetDataProtector("Sample.DangerousUnprotect");
Console.Write("Input: ");
byte[] input = Encoding.UTF8.GetBytes(Console.ReadLine());
var protectedData = protector.Protect(input);
Console.WriteLine($"Protected payload: {Convert.ToBase64String(protectedData)}");
// demonstrate that the payload round-trips properly

var roundTripped = protector.Unprotect(protectedData);
Console.WriteLine($"Round-tripped payload: {Encoding.UTF8.GetString(roundTripped)}");
// get a reference to the key manager and revoke all keys in the key ring
var keyManager = services.GetService<IKeyManager>();
Console.WriteLine("Revoking all keys in the key ring...");
keyManager.RevokeAllKeys(DateTimeOffset.Now, "Sample revocation.");
// try calling Protect - this should throw

Console.WriteLine("Calling Unprotect...");
try
{
var unprotectedPayload = protector.Unprotect(protectedData);
Console.WriteLine($"Unprotected payload: {Encoding.UTF8.GetString(unprotectedPayload)}");
}
{
Console.WriteLine($"{ex.GetType().Name}: {ex.Message}");
}
// try calling DangerousUnprotect

Console.WriteLine("Calling DangerousUnprotect...");
try
{
IPersistedDataProtector persistedProtector = protector as IPersistedDataProtector;
if (persistedProtector == null)
{
throw new Exception("Can't call DangerousUnprotect.");
}
bool requiresMigration, wasRevoked;

bool requiresMigration, wasRevoked;
var unprotectedPayload = persistedProtector.DangerousUnprotect(
protectedData: protectedData,
ignoreRevocationErrors: true,
requiresMigration: out requiresMigration,
wasRevoked: out wasRevoked);
Console.WriteLine($"Unprotected payload: {Encoding.UTF8.GetString(unprotectedPayload)}");
Console.WriteLine($"Requires migration = {requiresMigration}, was revoked = {wasRevoked}");
}
{
Console.WriteLine($"{ex.GetType().Name}: {ex.Message}");
}
}
}
/*
* SAMPLE OUTPUT
*
* Input: Hello!
* Protected payload: CfDJ8LHIzUCX1ZVBn2BZ...
* Round-tripped payload: Hello!
* Revoking all keys in the key ring...
* Calling Unprotect...
* CryptographicException: The key {...} has been revoked.
* Calling DangerousUnprotect...
* Unprotected payload: Hello!
* Requires migration = True, was revoked = True
*/
Data Protection configuration in ASP.NET Core
Visit these topics to learn about Data Protection configuration in ASP.NET Core:
An overview on configuring ASP.NET Core Data Protection.
Data Protection key management and lifetime
Information on Data Protection key management and lifetime.
Data Protection machine-wide policy support
Details on setting a default machine-wide policy for all apps that use Data Protection.
Non-DI aware scenarios for Data Protection in ASP.NET Core
How to use the DataProtectionProvider concrete type to use Data Protection without going through DI-
specific code paths.
When the Data Protection system is initialized, it applies default settings based on the operational
environment. These settings are generally appropriate for apps running on a single machine. There are cases
where a developer may want to change the default settings:
The app is spread across multiple machines.
For compliance reasons.
For these scenarios, the Data Protection system offers a rich configuration API.
WARNING
Similar to configuration files, the data protection key ring should be protected using appropriate permissions. You can
choose to encrypt keys at rest, but this doesn't prevent attackers from creating new keys. Consequently, your app's
security is impacted. The storage location configured with Data Protection should have its access limited to the app itself,
similar to the way you would protect configuration files. For example, if you choose to store your key ring on disk, use
file system permissions. Ensure only the identity under which your web app runs has read, write, and create access to
that directory. If you use Azure Table Storage, only the web app should have the ability to read, write, or create new
entries in the table store, etc.
The extension method AddDataProtection returns an IDataProtectionBuilder. IDataProtectionBuilder exposes
extension methods that you can chain together to configure Data Protection options.
ProtectKeysWithAzureKeyVault
To store keys in Azure Key Vault, configure the system with ProtectKeysWithAzureKeyVault in the Startup
class:

{
services.AddDataProtection()
.PersistKeysToAzureBlobStorage(new Uri("<blobUriWithSasToken>"))
.ProtectKeysWithAzureKeyVault("<keyIdentifier>", "<clientId>", "<clientSecret>");
}
Set the key ring storage location (for example, PersistKeysToAzureBlobStorage). The location must be set
because calling ProtectKeysWithAzureKeyVault implements an IXmlEncryptor that disables automatic data
protection settings, including the key ring storage location. The preceding example uses Azure Blob Storage to
persist the key ring. For more information, see Key storage providers: Azure and Redis. You can also persist the
key ring locally with PersistKeysToFileSystem.
The keyIdentifieris the key vault key identifier used for key encryption (for example,
https://contosokeyvault.vault.azure.net/keys/dataprotection/ ).
ProtectKeysWithAzureKeyVault overloads:
ProtectKeysWithAzureKeyVault(IDataProtectionBuilder, KeyVaultClient, String) permits the use of a
KeyVaultClient to enable the data protection system to use the key vault.
ProtectKeysWithAzureKeyVault(IDataProtectionBuilder, String, String, X509Certificate2) permits the use of
a ClientId and X509Certificate to enable the data protection system to use the key vault.
ProtectKeysWithAzureKeyVault(IDataProtectionBuilder, String, String, String) permits the use of a
ClientId and ClientSecret to enable the data protection system to use the key vault.
PersistKeysToFileSystem
To store keys on a UNC share instead of at the %LOCALAPPDATA% default location, configure the system
with PersistKeysToFileSystem:

{
.PersistKeysToFileSystem(new DirectoryInfo(@"\\server\share\directory\"));
}
WARNING
If you change the key persistence location, the system no longer automatically encrypts keys at rest, since it doesn't
know whether DPAPI is an appropriate encryption mechanism.
ProtectKeysWith*
You can configure the system to protect keys at rest by calling any of the ProtectKeysWith* configuration APIs.
Consider the example below, which stores keys on a UNC share and encrypts those keys at rest with a specific
X.509 certificate:

{
.PersistKeysToFileSystem(new DirectoryInfo(@"\\server\share\directory\"))
.ProtectKeysWithCertificate("thumbprint");
}
In ASP.NET Core 2.1 or later, you can provide an X509Certificate2 to ProtectKeysWithCertificate, such as a
certificate loaded from a file:

{
.ProtectKeysWithCertificate(
new X509Certificate2("certificate.pfx", "password"));
}
See Key Encryption At Rest for more examples and discussion on the built-in key encryption mechanisms.
UnprotectKeysWithAnyCertificate
In ASP.NET Core 2.1 or later, you can rotate certificates and decrypt keys at rest using an array of
X509Certificate2 certificates with UnprotectKeysWithAnyCertificate:
{
.ProtectKeysWithCertificate(
new X509Certificate2("certificate.pfx", "password"));
.UnprotectKeysWithAnyCertificate(
new X509Certificate2("certificate_old_1.pfx", "password_1"),
new X509Certificate2("certificate_old_2.pfx", "password_2"));
}
SetDefaultKeyLifetime
To configure the system to use a key lifetime of 14 days instead of the default 90 days, use
SetDefaultKeyLifetime:

{
.SetDefaultKeyLifetime(TimeSpan.FromDays(14));
}
SetApplicationName
By default, the Data Protection system isolates apps from one another, even if they're sharing the same
physical key repository. This prevents the apps from understanding each other's protected payloads. To share
protected payloads between two apps, use SetApplicationName with the same value for each app:

{
.SetApplicationName("shared app name");
}
DisableAutomaticKeyGeneration
You may have a scenario where you don't want an app to automatically roll keys (create new keys) as they
approach expiration. One example of this might be apps set up in a primary/secondary relationship, where
only the primary app is responsible for key management concerns and secondary apps simply have a read-
only view of the key ring. The secondary apps can be configured to treat the key ring as read-only by
configuring the system with DisableAutomaticKeyGeneration:

{
.DisableAutomaticKeyGeneration();
}
Per-application isolation
When the Data Protection system is provided by an ASP.NET Core host, it automatically isolates apps from
one another, even if those apps are running under the same worker process account and are using the same
master keying material. This is somewhat similar to the IsolateApps modifier from System.Web's
<machineKey> element.
The isolation mechanism works by considering each app on the local machine as a unique tenant, thus the
IDataProtector rooted for any given app automatically includes the app ID as a discriminator. The app's unique
ID comes from one of two places:
1. If the app is hosted in IIS, the unique identifier is the app's configuration path. If an app is deployed in a
web farm environment, this value should be stable assuming that the IIS environments are configured
similarly across all machines in the web farm.
2. If the app isn't hosted in IIS, the unique identifier is the physical path of the app.
The unique identifier is designed to survive resets — both of the individual app and of the machine itself.
This isolation mechanism assumes that the apps are not malicious. A malicious app can always impact any
other app running under the same worker process account. In a shared hosting environment where apps are
mutually untrusted, the hosting provider should take steps to ensure OS -level isolation between apps,
including separating the apps' underlying key repositories.
If the Data Protection system isn't provided by an ASP.NET Core host (for example, if you instantiate it via the
DataProtectionProvider concrete type) app isolation is disabled by default. When app isolation is disabled, all
apps backed by the same keying material can share payloads as long as they provide the appropriate
purposes. To provide app isolation in this environment, call the SetApplicationName method on the
configuration object and provide a unique name for each app.
Changing algorithms with UseCryptographicAlgorithms

The Data Protection stack allows you to change the default algorithm used by newly-generated keys. The
simplest way to do this is to call UseCryptographicAlgorithms from the configuration callback:
ASP.NET Core 2.x
ASP.NET Core 1.x
.UseCryptographicAlgorithms(
new AuthenticatedEncryptorConfiguration()
{
EncryptionAlgorithm = EncryptionAlgorithm.AES_256_CBC,
ValidationAlgorithm = ValidationAlgorithm.HMACSHA256
});
The default EncryptionAlgorithm is AES -256-CBC, and the default ValidationAlgorithm is HMACSHA256. The
default policy can be set by a system administrator via a machine-wide policy, but an explicit call to
UseCryptographicAlgorithms overrides the default policy.
Calling UseCryptographicAlgorithms allows you to specify the desired algorithm from a predefined built-in list.
You don't need to worry about the implementation of the algorithm. In the scenario above, the Data Protection
system attempts to use the CNG implementation of AES if running on Windows. Otherwise, it falls back to the
managed System.Security.Cryptography.Aes class.
You can manually specify an implementation via a call to UseCustomCryptographicAlgorithms.
TIP
Changing algorithms doesn't affect existing keys in the key ring. It only affects newly-generated keys.
Specifying custom managed algorithms

ASP.NET Core 2.x
ASP.NET Core 1.x
To specify custom managed algorithms, create a ManagedAuthenticatedEncryptorConfiguration instance that
points to the implementation types:
.UseCustomCryptographicAlgorithms(
new ManagedAuthenticatedEncryptorConfiguration()
{
// A type that subclasses SymmetricAlgorithm
EncryptionAlgorithmType = typeof(Aes),
// Specified in bits
EncryptionAlgorithmKeySize = 256,
// A type that subclasses KeyedHashAlgorithm

ValidationAlgorithmType = typeof(HMACSHA256)
});
Generally the *Type properties must point to concrete, instantiable (via a public parameterless ctor)
implementations of SymmetricAlgorithm and KeyedHashAlgorithm, though the system special-cases some
values like typeof(Aes) for convenience.
NOTE
The SymmetricAlgorithm must have a key length of ≥ 128 bits and a block size of ≥ 64 bits, and it must support CBC-
mode encryption with PKCS #7 padding. The KeyedHashAlgorithm must have a digest size of >= 128 bits, and it must
support keys of length equal to the hash algorithm's digest length. The KeyedHashAlgorithm isn't strictly required to be
HMAC.
Specifying custom Windows CNG algorithms

ASP.NET Core 2.x
ASP.NET Core 1.x
To specify a custom Windows CNG algorithm using CBC -mode encryption with HMAC validation, create a
CngCbcAuthenticatedEncryptorConfiguration instance that contains the algorithmic information:
new CngCbcAuthenticatedEncryptorConfiguration()
{
// Passed to BCryptOpenAlgorithmProvider
EncryptionAlgorithm = "AES",
EncryptionAlgorithmProvider = null,
EncryptionAlgorithmKeySize = 256,
HashAlgorithm = "SHA256",
HashAlgorithmProvider = null
});
NOTE
The symmetric block cipher algorithm must have a key length of >= 128 bits, a block size of >= 64 bits, and it must
support CBC-mode encryption with PKCS #7 padding. The hash algorithm must have a digest size of >= 128 bits and
must support being opened with the BCRYPT_ALG_HANDLE_HMAC_FLAG flag. The *Provider properties can be set to
null to use the default provider for the specified algorithm. See the BCryptOpenAlgorithmProvider documentation for
more information.
ASP.NET Core 2.x

ASP.NET Core 1.x
To specify a custom Windows CNG algorithm using Galois/Counter Mode encryption with validation, create a
CngGcmAuthenticatedEncryptorConfiguration instance that contains the algorithmic information:
new CngGcmAuthenticatedEncryptorConfiguration()
{
EncryptionAlgorithm = "AES",
EncryptionAlgorithmProvider = null,
EncryptionAlgorithmKeySize = 256
});
NOTE
The symmetric block cipher algorithm must have a key length of >= 128 bits, a block size of exactly 128 bits, and it
must support GCM encryption. You can set the EncryptionAlgorithmProvider property to null to use the default
provider for the specified algorithm. See the BCryptOpenAlgorithmProvider documentation for more information.
Specifying other custom algorithms

Though not exposed as a first-class API, the Data Protection system is extensible enough to allow specifying
almost any kind of algorithm. For example, it's possible to keep all keys contained within a Hardware Security
Module (HSM ) and to provide a custom implementation of the core encryption and decryption routines. See
IAuthenticatedEncryptor in Core cryptography extensibility for more information.
Persisting keys when hosting in a Docker container

When hosting in a Docker container, keys should be maintained in either:
A folder that's a Docker volume that persists beyond the container's lifetime, such as a shared volume or a
host-mounted volume.
An external provider, such as Azure Key Vault or Redis.
See also
Non-DI aware scenarios for Data Protection in ASP.NET Core
Data Protection machine-wide policy support in ASP.NET Core
Data Protection key management and lifetime in
ASP.NET Core
By Rick Anderson
Key management
The app attempts to detect its operational environment and handle key configuration on its own.
1. If the app is hosted in Azure Apps, keys are persisted to the %HOME%\ASP.NET\DataProtection-Keys
folder. This folder is backed by network storage and is synchronized across all machines hosting the app.
Keys aren't protected at rest.
The DataProtection-Keys folder supplies the key ring to all instances of an app in a single deployment
slot.
Separate deployment slots, such as Staging and Production, don't share a key ring. When you swap
between deployment slots, for example swapping Staging to Production or using A/B testing, any app
using Data Protection won't be able to decrypt stored data using the key ring inside the previous slot.
This leads to users being logged out of an app that uses the standard ASP.NET Core cookie
authentication, as it uses Data Protection to protect its cookies. If you desire slot-independent key rings,
use an external key ring provider, such as Azure Blob Storage, Azure Key Vault, a SQL store, or Redis
cache.
2. If the user profile is available, keys are persisted to the %LOCALAPPDATA%\ASP.NET\DataProtection-
Keys folder. If the operating system is Windows, the keys are encrypted at rest using DPAPI.
3. If the app is hosted in IIS, keys are persisted to the HKLM registry in a special registry key that's ACLed
only to the worker process account. Keys are encrypted at rest using DPAPI.
4. If none of these conditions match, keys aren't persisted outside of the current process. When the process
shuts down, all generated keys are lost.
The developer is always in full control and can override how and where keys are stored. The first three options
above should provide good defaults for most apps similar to how the ASP.NET <machineKey> auto-generation
routines worked in the past. The final, fallback option is the only scenario that requires the developer to specify
configuration upfront if they want key persistence, but this fallback only occurs in rare situations.
When hosting in a Docker container, keys should be persisted in a folder that's a Docker volume (a shared
volume or a host-mounted volume that persists beyond the container's lifetime) or in an external provider, such
as Azure Key Vault or Redis. An external provider is also useful in web farm scenarios if apps can't access a shared
network volume (see PersistKeysToFileSystem for more information).
WARNING
If the developer overrides the rules outlined above and points the Data Protection system at a specific key repository,
automatic encryption of keys at rest is disabled. At-rest protection can be re-enabled via configuration.
Key lifetime
Keys have a 90-day lifetime by default. When a key expires, the app automatically generates a new key and sets
the new key as the active key. As long as retired keys remain on the system, your app can decrypt any data
protected with them. See key management for more information.
Default algorithms
The default payload protection algorithm used is AES -256-CBC for confidentiality and HMACSHA256 for
authenticity. A 512-bit master key, changed every 90 days, is used to derive the two sub-keys used for these
algorithms on a per-payload basis. See subkey derivation for more information.
Key management extensibility in ASP.NET Core
Data Protection machine-wide policy support in
ASP.NET Core
By Rick Anderson
When running on Windows, the Data Protection system has limited support for setting a default machine-wide
policy for all apps that consume ASP.NET Core Data Protection. The general idea is that an administrator might
wish to change a default setting, such as the algorithms used or key lifetime, without the need to manually update
every app on the machine.
WARNING
The system administrator can set default policy, but they can't enforce it. The app developer can always override any value
with one of their own choosing. The default policy only affects apps where the developer hasn't specified an explicit value
for a setting.
Setting default policy

To set default policy, an administrator can set known values in the system registry under the following registry
key:
HKLM\SOFTWARE\Microsoft\DotNetPackages\Microsoft.AspNetCore.DataProtection
If you're on a 64-bit operating system and want to affect the behavior of 32-bit apps, remember to configure the
Wow6432Node equivalent of the above key.
The supported values are shown below.
VALUE TYPE DESCRIPTION
EncryptionType string Specifies which algorithms should be

used for data protection. The value
must be CNG-CBC, CNG-GCM, or
Managed and is described in more
detail below.
DefaultKeyLifetime DWORD Specifies the lifetime for newly-

generated keys. The value is specified in
days and must be >= 7.
KeyEscrowSinks string Specifies the types that are used for

key escrow. The value is a semicolon-
delimited list of key escrow sinks, where
each element in the list is the
assembly-qualified name of a type that
implements IKeyEscrowSink.
Encryption types
If EncryptionType is CNG -CBC, the system is configured to use a CBC -mode symmetric block cipher for
confidentiality and HMAC for authenticity with services provided by Windows CNG (see Specifying custom
Windows CNG algorithms for more details). The following additional values are supported, each of which
corresponds to a property on the CngCbcAuthenticatedEncryptionSettings type.
EncryptionAlgorithm string The name of a symmetric block cipher

algorithm understood by CNG. This
algorithm is opened in CBC mode.
EncryptionAlgorithmProvider string The name of the CNG provider

implementation that can produce the
algorithm EncryptionAlgorithm.
EncryptionAlgorithmKeySize DWORD The length (in bits) of the key to derive

for the symmetric block cipher
algorithm.
HashAlgorithm string The name of a hash algorithm

understood by CNG. This algorithm is
opened in HMAC mode.
HashAlgorithmProvider string The name of the CNG provider

algorithm HashAlgorithm.
If EncryptionType is CNG -GCM, the system is configured to use a Galois/Counter Mode symmetric block cipher
for confidentiality and authenticity with services provided by Windows CNG (see Specifying custom Windows
CNG algorithms for more details). The following additional values are supported, each of which corresponds to a
property on the CngGcmAuthenticatedEncryptionSettings type.
EncryptionAlgorithm string The name of a symmetric block cipher

algorithm understood by CNG. This
algorithm is opened in Galois/Counter
Mode.
EncryptionAlgorithmProvider string The name of the CNG provider

algorithm EncryptionAlgorithm.

for the symmetric block cipher
algorithm.
If EncryptionType is Managed, the system is configured to use a managed SymmetricAlgorithm for

confidentiality and KeyedHashAlgorithm for authenticity (see Specifying custom managed algorithms for more
details). The following additional values are supported, each of which corresponds to a property on the
ManagedAuthenticatedEncryptionSettings type.
EncryptionAlgorithmType string The assembly-qualified name of a type

that implements SymmetricAlgorithm.

for the symmetric encryption
algorithm.
ValidationAlgorithmType string The assembly-qualified name of a type

that implements KeyedHashAlgorithm.
If EncryptionType has any other value other than null or empty, the Data Protection system throws an exception
at startup.
WARNING
When configuring a default policy setting that involves type names (EncryptionAlgorithmType, ValidationAlgorithmType,
KeyEscrowSinks), the types must be available to the app. This means that for apps running on Desktop CLR, the assemblies
that contain these types should be present in the Global Assembly Cache (GAC). For ASP.NET Core apps running on .NET
Core, the packages that contain these types should be installed.
Non-DI aware scenarios for Data Protection in
ASP.NET Core
By Rick Anderson
The ASP.NET Core Data Protection system is normally added to a service container and consumed by dependent
components via dependency injection (DI). However, there are cases where this isn't feasible or desired, especially
when importing the system into an existing app.
To support these scenarios, the Microsoft.AspNetCore.DataProtection.Extensions package provides a concrete
type, DataProtectionProvider, which offers a simple way to use Data Protection without relying on DI. The
DataProtectionProvider type implements IDataProtectionProvider. Constructing DataProtectionProvider only
requires providing a DirectoryInfo instance to indicate where the provider's cryptographic keys should be stored,
as seen in the following code sample:
using System;
using System.IO;

{
{
// Get the path to %LOCALAPPDATA%\myapp-keys
var destFolder = Path.Combine(
System.Environment.GetEnvironmentVariable("LOCALAPPDATA"),
"myapp-keys");
// Instantiate the data protection system at this folder

var dataProtectionProvider = DataProtectionProvider.Create(
new DirectoryInfo(destFolder));
var protector = dataProtectionProvider.CreateProtector("Program.No-DI");

var input = Console.ReadLine();
// Protect the payload

var protectedPayload = protector.Protect(input);
// Unprotect the payload

var unprotectedPayload = protector.Unprotect(protectedPayload);
Console.WriteLine();
Console.WriteLine("Press any key...");
Console.ReadKey();
}
}
/*
* SAMPLE OUTPUT
*
* Protect returned: CfDJ8FWbAn6...ch3hAPm1NJA
*
* Press any key...
*/
By default, the DataProtectionProvider concrete type doesn't encrypt raw key material before persisting it to the
file system. This is to support scenarios where the developer points to a network share and the Data Protection
system can't automatically deduce an appropriate at-rest key encryption mechanism.
Additionally, the DataProtectionProvider concrete type doesn't isolate apps by default. All apps using the same
key directory can share payloads as long as their purpose parameters match.
The DataProtectionProvider constructor accepts an optional configuration callback that can be used to adjust the
behaviors of the system. The sample below demonstrates restoring isolation with an explicit call to
SetApplicationName. The sample also demonstrates configuring the system to automatically encrypt persisted
keys using Windows DPAPI. If the directory points to a UNC share, you may wish to distribute a shared
certificate across all relevant machines and to configure the system to use certificate-based encryption with a call
to ProtectKeysWithCertificate.
using System;
using System.IO;

{
{
// Get the path to %LOCALAPPDATA%\myapp-keys
var destFolder = Path.Combine(
System.Environment.GetEnvironmentVariable("LOCALAPPDATA"),
"myapp-keys");
// Instantiate the data protection system at this folder

var dataProtectionProvider = DataProtectionProvider.Create(
new DirectoryInfo(destFolder),
configuration =>
{
configuration.SetApplicationName("my app name");
configuration.ProtectKeysWithDpapi();
});
var protector = dataProtectionProvider.CreateProtector("Program.No-DI");

var input = Console.ReadLine();
// Protect the payload

var protectedPayload = protector.Protect(input);
// Unprotect the payload

var unprotectedPayload = protector.Unprotect(protectedPayload);
Console.WriteLine();
Console.WriteLine("Press any key...");
Console.ReadKey();
}
}
TIP
Instances of the DataProtectionProvider concrete type are expensive to create. If an app maintains multiple instances of
this type and if they're all using the same key storage directory, app performance might degrade. If you use the
DataProtectionProvider type, we recommend that you create this type once and reuse it as much as possible. The
DataProtectionProvider type and all IDataProtector instances created from it are thread-safe for multiple callers.
ASP.NET Core Data Protection extensibility APIs

Miscellaneous APIs
Core cryptography extensibility in ASP.NET Core
WARNING
Types that implement any of the following interfaces should be thread-safe for multiple callers.
IAuthenticatedEncryptor
The IAuthenticatedEncryptor interface is the basic building block of the cryptographic subsystem. There's
generally one IAuthenticatedEncryptor per key, and the IAuthenticatedEncryptor instance wraps all cryptographic
key material and algorithmic information necessary to perform cryptographic operations.
As its name suggests, the type is responsible for providing authenticated encryption and decryption services. It
exposes the following two APIs.
Decrypt(ArraySegment ciphertext, ArraySegment additionalAuthenticatedData) : byte[]
Encrypt(ArraySegment plaintext, ArraySegment additionalAuthenticatedData) : byte[]
The Encrypt method returns a blob that includes the enciphered plaintext and an authentication tag. The
authentication tag must encompass the additional authenticated data (AAD ), though the AAD itself need not be
recoverable from the final payload. The Decrypt method validates the authentication tag and returns the
deciphered payload. All failures (except ArgumentNullException and similar) should be homogenized to
CryptographicException.
NOTE
The IAuthenticatedEncryptor instance itself doesn't actually need to contain the key material. For example, the
implementation could delegate to an HSM for all operations.
How to create an IAuthenticatedEncryptor

ASP.NET Core 2.x
ASP.NET Core 1.x
The IAuthenticatedEncryptorFactory interface represents a type that knows how to create an
IAuthenticatedEncryptor instance. Its API is as follows.
CreateEncryptorInstance(IKey key) : IAuthenticatedEncryptor
For any given IKey instance, any authenticated encryptors created by its CreateEncryptorInstance method should
be considered equivalent, as in the below code sample.
// we have an IAuthenticatedEncryptorFactory instance and an IKey instance
IAuthenticatedEncryptorFactory factory = ...;
IKey key = ...;
// get an encryptor instance and perform an authenticated encryption operation

ArraySegment<byte> plaintext = new ArraySegment<byte>(Encoding.UTF8.GetBytes("plaintext"));
ArraySegment<byte> aad = new ArraySegment<byte>(Encoding.UTF8.GetBytes("AAD"));
var encryptor1 = factory.CreateEncryptorInstance(key);
byte[] ciphertext = encryptor1.Encrypt(plaintext, aad);
// get another encryptor instance and perform an authenticated decryption operation

var encryptor2 = factory.CreateEncryptorInstance(key);
byte[] roundTripped = encryptor2.Decrypt(new ArraySegment<byte>(ciphertext), aad);
// the 'roundTripped' and 'plaintext' buffers should be equivalent
IAuthenticatedEncryptorDescriptor (ASP.NET Core 2.x only)

ASP.NET Core 2.x
ASP.NET Core 1.x
The IAuthenticatedEncryptorDescriptor interface represents a type that knows how to export itself to XML. Its
API is as follows.
ExportToXml() : XmlSerializedDescriptorInfo
XML Serialization
The primary difference between IAuthenticatedEncryptor and IAuthenticatedEncryptorDescriptor is that the
descriptor knows how to create the encryptor and supply it with valid arguments. Consider an
IAuthenticatedEncryptor whose implementation relies on SymmetricAlgorithm and KeyedHashAlgorithm. The
encryptor's job is to consume these types, but it doesn't necessarily know where these types came from, so it can't
really write out a proper description of how to recreate itself if the application restarts. The descriptor acts as a
higher level on top of this. Since the descriptor knows how to create the encryptor instance (e.g., it knows how to
create the required algorithms), it can serialize that knowledge in XML form so that the encryptor instance can be
recreated after an application reset.
The descriptor can be serialized via its ExportToXml routine. This routine returns an XmlSerializedDescriptorInfo
which contains two properties: the XElement representation of the descriptor and the Type which represents an
IAuthenticatedEncryptorDescriptorDeserializer which can be used to resurrect this descriptor given the
corresponding XElement.
The serialized descriptor may contain sensitive information such as cryptographic key material. The data
protection system has built-in support for encrypting information before it's persisted to storage. To take
advantage of this, the descriptor should mark the element which contains sensitive information with the attribute
name "requiresEncryption" (xmlns "http://schemas.asp.net/2015/03/dataProtection"), value "true".
TIP
There's a helper API for setting this attribute. Call the extension method XElement.MarkAsRequiresEncryption() located in
namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.ConfigurationModel.
There can also be cases where the serialized descriptor doesn't contain sensitive information. Consider again the
case of a cryptographic key stored in an HSM. The descriptor cannot write out the key material when serializing
itself since the HSM won't expose the material in plaintext form. Instead, the descriptor might write out the key-
wrapped version of the key (if the HSM allows export in this fashion) or the HSM's own unique identifier for the
key.
IAuthenticatedEncryptorDescriptorDeserializer
The IAuthenticatedEncryptorDescriptorDeserializer interface represents a type that knows how to deserialize
an IAuthenticatedEncryptorDescriptor instance from an XElement. It exposes a single method:
ImportFromXml(XElement element) : IAuthenticatedEncryptorDescriptor
The ImportFromXml method takes the XElement that was returned by
IAuthenticatedEncryptorDescriptor.ExportToXml and creates an equivalent of the original
IAuthenticatedEncryptorDescriptor.
Types which implement IAuthenticatedEncryptorDescriptorDeserializer should have one of the following two
public constructors:
.ctor(IServiceProvider)
.ctor()
NOTE
The IServiceProvider passed to the constructor may be null.
The top-level factory

ASP.NET Core 2.x
ASP.NET Core 1.x
The AlgorithmConfiguration class represents a type which knows how to create
IAuthenticatedEncryptorDescriptor instances. It exposes a single API.
CreateNewDescriptor() : IAuthenticatedEncryptorDescriptor
Think of AlgorithmConfiguration as the top-level factory. The configuration serves as a template. It wraps
algorithmic information (e.g., this configuration produces descriptors with an AES -128-GCM master key), but it's
not yet associated with a specific key.
When CreateNewDescriptor is called, fresh key material is created solely for this call, and a new
IAuthenticatedEncryptorDescriptor is produced which wraps this key material and the algorithmic information
required to consume the material. The key material could be created in software (and held in memory), it could be
created and held within an HSM, and so on. The crucial point is that any two calls to CreateNewDescriptor should
never create equivalent IAuthenticatedEncryptorDescriptor instances.
The AlgorithmConfiguration type serves as the entry point for key creation routines such as automatic key rolling.
To change the implementation for all future keys, set the AuthenticatedEncryptorConfiguration property in
KeyManagementOptions.
Key management extensibility in ASP.NET Core
TIP
Read the key management section before reading this section, as it explains some of the fundamental concepts behind these
APIs.
WARNING
Key
The IKey interface is the basic representation of a key in cryptosystem. The term key is used here in the abstract
sense, not in the literal sense of "cryptographic key material". A key has the following properties:
Activation, creation, and expiration dates
Revocation status
Key identifier (a GUID )
Additionally, IKey exposes a CreateEncryptor method which can be used to create an IAuthenticatedEncryptor
instance tied to this key.
Additionally, IKey exposes a CreateEncryptorInstance method which can be used to create an
IAuthenticatedEncryptor instance tied to this key.
NOTE
There's no API to retrieve the raw cryptographic material from an IKey instance.
IKeyManager
The IKeyManager interface represents an object responsible for general key storage, retrieval, and manipulation. It
exposes three high-level operations:
Create a new key and persist it to storage.
Get all keys from storage.
Revoke one or more keys and persist the revocation information to storage.
WARNING
Writing an IKeyManager is a very advanced task, and the majority of developers shouldn't attempt it. Instead, most
developers should take advantage of the facilities offered by the XmlKeyManager class.
XmlKeyManager
The XmlKeyManager type is the in-box concrete implementation of IKeyManager . It provides several useful facilities,
including key escrow and encryption of keys at rest. Keys in this system are represented as XML elements
(specifically, XElement).
XmlKeyManager depends on several other components in the course of fulfilling its tasks:
AlgorithmConfiguration , which dictates the algorithms used by new keys.
IXmlRepository , which controls where keys are persisted in storage.
IXmlEncryptor [optional], which allows encrypting keys at rest.
IKeyEscrowSink [optional], which provides key escrow services.
IXmlRepository , which controls where keys are persisted in storage.

IXmlEncryptor [optional], which allows encrypting keys at rest.
IKeyEscrowSink [optional], which provides key escrow services.
Below are high-level diagrams which indicate how these components are wired together within XmlKeyManager .
Key Creation / CreateNewKey

In the implementation of , the AlgorithmConfiguration component is used to create a unique
CreateNewKey
IAuthenticatedEncryptorDescriptor , which is then serialized as XML. If a key escrow sink is present, the raw
(unencrypted) XML is provided to the sink for long-term storage. The unencrypted XML is then run through an
IXmlEncryptor (if required) to generate the encrypted XML document. This encrypted document is persisted to
long-term storage via the IXmlRepository . (If no IXmlEncryptor is configured, the unencrypted document is
persisted in the IXmlRepository .)
Key Creation / CreateNewKey
In the implementation of CreateNewKey , the IAuthenticatedEncryptorConfiguration component is used to create a
unique IAuthenticatedEncryptorDescriptor , which is then serialized as XML. If a key escrow sink is present, the
raw (unencrypted) XML is provided to the sink for long-term storage. The unencrypted XML is then run through
an IXmlEncryptor (if required) to generate the encrypted XML document. This encrypted document is persisted to
long-term storage via the IXmlRepository . (If no IXmlEncryptor is configured, the unencrypted document is
persisted in the IXmlRepository .)
Key Retrieval / GetAllKeys

In the implementation of GetAllKeys , the XML documents representing keys and revocations are read from the
underlying IXmlRepository . If these documents are encrypted, the system will automatically decrypt them.
XmlKeyManager creates the appropriate IAuthenticatedEncryptorDescriptorDeserializer instances to deserialize the
documents back into IAuthenticatedEncryptorDescriptor instances, which are then wrapped in individual IKey
instances. This collection of IKey instances is returned to the caller.
Further information on the particular XML elements can be found in the key storage format document.
IXmlRepository
The IXmlRepository interface represents a type that can persist XML to and retrieve XML from a backing store. It
exposes two APIs:
GetAllElements : IReadOnlyCollection<XElement>
StoreElement(XElement element, string friendlyName)
Implementations of IXmlRepository don't need to parse the XML passing through them. They should treat the
XML documents as opaque and let higher layers worry about generating and parsing the documents.
There are four built-in concrete types which implement IXmlRepository :
FileSystemXmlRepository
RegistryXmlRepository
AzureStorage.AzureBlobXmlRepository
RedisXmlRepository
See the key storage providers document for more information.
Registering a custom IXmlRepository is appropriate when using a different backing store (for example, Azure
Table Storage).
To change the default repository application-wide, register a custom IXmlRepository instance:
services.Configure<KeyManagementOptions>(options => options.XmlRepository = new MyCustomXmlRepository());
services.AddSingleton<IXmlRepository>(new MyCustomXmlRepository());
IXmlEncryptor
The IXmlEncryptor interface represents a type that can encrypt a plaintext XML element. It exposes a single API:
Encrypt(XElement plaintextElement) : EncryptedXmlInfo
If a serialized contains any elements marked as "requires encryption", then
IAuthenticatedEncryptorDescriptor
XmlKeyManager will run those elements through the configured IXmlEncryptor 's Encrypt method, and it will
persist the enciphered element rather than the plaintext element to the IXmlRepository . The output of the
Encrypt method is an EncryptedXmlInfo object. This object is a wrapper which contains both the resultant
enciphered XElement and the Type which represents an IXmlDecryptor which can be used to decipher the
corresponding element.
There are four built-in concrete types which implement IXmlEncryptor :
CertificateXmlEncryptor
DpapiNGXmlEncryptor
DpapiXmlEncryptor
NullXmlEncryptor
See the key encryption at rest document for more information.
To change the default key-encryption-at-rest mechanism application-wide, register a custom IXmlEncryptor
instance:
services.Configure<KeyManagementOptions>(options => options.XmlEncryptor = new MyCustomXmlEncryptor());
services.AddSingleton<IXmlEncryptor>(new MyCustomXmlEncryptor());
IXmlDecryptor
The IXmlDecryptor interface represents a type that knows how to decrypt an XElement that was enciphered via an
IXmlEncryptor . It exposes a single API:
Decrypt(XElement encryptedElement) : XElement

The Decryptmethod undoes the encryption performed by IXmlEncryptor.Encrypt . Generally, each concrete
IXmlEncryptor implementation will have a corresponding concrete IXmlDecryptor implementation.
Types which implement IXmlDecryptor should have one of the following two public constructors:
.ctor(IServiceProvider)
.ctor()
NOTE
The IServiceProvider passed to the constructor may be null.
IKeyEscrowSink
The IKeyEscrowSink interface represents a type that can perform escrow of sensitive information. Recall that
serialized descriptors might contain sensitive information (such as cryptographic material), and this is what led to
the introduction of the IXmlEncryptor type in the first place. However, accidents happen, and key rings can be
deleted or become corrupted.
The escrow interface provides an emergency escape hatch, allowing access to the raw serialized XML before it's
transformed by any configured IXmlEncryptor. The interface exposes a single API:
Store(Guid keyId, XElement element)
It's up to the IKeyEscrowSink implementation to handle the provided element in a secure manner consistent with
business policy. One possible implementation could be for the escrow sink to encrypt the XML element using a
known corporate X.509 certificate where the certificate's private key has been escrowed; the
CertificateXmlEncryptor type can assist with this. The IKeyEscrowSink implementation is also responsible for
persisting the provided element appropriately.
By default no escrow mechanism is enabled, though server administrators can configure this globally. It can also
be configured programmatically via the IDataProtectionBuilder.AddKeyEscrowSink method as shown in the sample
below. The AddKeyEscrowSink method overloads mirror the IServiceCollection.AddSingleton and
IServiceCollection.AddInstance overloads, as IKeyEscrowSink instances are intended to be singletons. If multiple
IKeyEscrowSink instances are registered, each one will be called during key generation, so keys can be escrowed
to multiple mechanisms simultaneously.
There's no API to read material from an IKeyEscrowSink instance. This is consistent with the design theory of the
escrow mechanism: it's intended to make the key material accessible to a trusted authority, and since the
application is itself not a trusted authority, it shouldn't have access to its own escrowed material.
The following sample code demonstrates creating and registering an IKeyEscrowSink where keys are escrowed
such that only members of "CONTOSODomain Admins" can recover them.
NOTE
To run this sample, you must be on a domain-joined Windows 8 / Windows Server 2012 machine, and the domain controller
must be Windows Server 2012 or later.
using System;
using System.IO;
using System.Xml.Linq;
using Microsoft.AspNetCore.DataProtection.XmlEncryption;

{
{
.ProtectKeysWithDpapi()
.AddKeyEscrowSink(sp => new MyKeyEscrowSink(sp));
// get a reference to the key manager and force a new key to be generated
Console.WriteLine("Generating new key...");
keyManager.CreateNewKey(
activationDate: DateTimeOffset.Now,
expirationDate: DateTimeOffset.Now.AddDays(7));
}
// A key escrow sink where keys are escrowed such that they
// can be read by members of the CONTOSO\Domain Admins group.
private class MyKeyEscrowSink : IKeyEscrowSink
{
private readonly IXmlEncryptor _escrowEncryptor;
public MyKeyEscrowSink(IServiceProvider services)

{
// Assuming I'm on a machine that's a member of the CONTOSO
// domain, I can use the Domain Admins SID to generate an
// encrypted payload that only they can read. Sample SID from
// https://technet.microsoft.com/library/cc778824(v=ws.10).aspx.
_escrowEncryptor = new DpapiNGXmlEncryptor(
"SID=S-1-5-21-1004336348-1177238915-682003330-512",
DpapiNGProtectionDescriptorFlags.None,
services);
}
public void Store(Guid keyId, XElement element)

{
// Encrypt the key element to the escrow encryptor.
var encryptedXmlInfo = _escrowEncryptor.Encrypt(element);
// A real implementation would save the escrowed key to a

// A real implementation would save the escrowed key to a
// write-only file share or some other stable storage, but
// in this sample we'll just write it out to the console.
Console.WriteLine($"Escrowing key {keyId}");
Console.WriteLine(encryptedXmlInfo.EncryptedElement);
// Note: We cannot read the escrowed key material ourselves.

// We need to get a member of CONTOSO\Domain Admins to read
// it for us in the event we need to recover it.
}
}
}
/*
* SAMPLE OUTPUT
*
* Generating new key...
* Escrowing key 38e74534-c1b8-4b43-aea1-79e856a822e5
* <encryptedKey>
* 
* 
* <value>MIIIfAYJKoZIhvcNAQcDoIIIbTCCCGkCAQ...T5rA4g==</value>
* </encryptedKey>
*/
Miscellaneous ASP.NET Core Data Protection APIs
WARNING
ISecret
The ISecret interface represents a secret value, such as cryptographic key material. It contains the following API
surface:
Length : int
Dispose() : void
WriteSecretIntoBuffer(ArraySegment<byte> buffer) : void
The WriteSecretIntoBuffer method populates the supplied buffer with the raw secret value. The reason this API
takes the buffer as a parameter rather than returning a byte[] directly is that this gives the caller the opportunity
to pin the buffer object, limiting secret exposure to the managed garbage collector.
The Secret type is a concrete implementation of ISecret where the secret value is stored in in-process memory.
On Windows platforms, the secret value is encrypted via CryptProtectMemory.
ASP.NET Core Data Protection implementation

Subkey Derivation and Authenticated Encryption
Context headers
Key Management
Key Storage Providers
Key Encryption At Rest
Key Storage Format
Authenticated encryption details in ASP.NET Core
Calls to IDataProtector.Protect are authenticated encryption operations. The Protect method offers both
confidentiality and authenticity, and it's tied to the purpose chain that was used to derive this particular
IDataProtector instance from its root IDataProtectionProvider.
IDataProtector.Protect takes a byte[] plaintext parameter and produces a byte[] protected payload, whose format
is described below. (There's also an extension method overload which takes a string plaintext parameter and
returns a string protected payload. If this API is used the protected payload format will still have the below
structure, but it will be base64url-encoded.)
Protected payload format

The protected payload format consists of three primary components:
A 32-bit magic header that identifies the version of the data protection system.
A 128-bit key id that identifies the key used to protect this particular payload.
The remainder of the protected payload is specific to the encryptor encapsulated by this key. In the example
below the key represents an AES -256-CBC + HMACSHA256 encryptor, and the payload is further
subdivided as follows: * A 128-bit key modifier. * A 128-bit initialization vector. * 48 bytes of AES -256-CBC
output. * An HMACSHA256 authentication tag.
A sample protected payload is illustrated below.
09 F0 C9 F0 80 9C 81 0C 19 66 19 40 95 36 53 F8
AA FF EE 57 57 2F 40 4C 3F 7F CC 9D CC D9 32 3E
84 17 99 16 EC BA 1F 4A A1 18 45 1F 2D 13 7A 28
79 6B 86 9C F8 B7 84 F9 26 31 FC B1 86 0A F1 56
61 CF 14 58 D3 51 6F CF 36 50 85 82 08 2D 3F 73
5F B0 AD 9E 1A B2 AE 13 57 90 C8 F5 7C 95 4E 6A
8A AA 06 EF 43 CA 19 62 84 7C 11 B2 C8 71 9D AA
52 19 2E 5B 4C 1E 54 F0 55 BE 88 92 12 C1 4B 5E
52 C9 74 A0
From the payload format above the first 32 bits, or 4 bytes are the magic header identifying the version (09 F0 C9
F0)
The next 128 bits, or 16 bytes is the key identifier (80 9C 81 0C 19 66 19 40 95 36 53 F8 AA FF EE 57)
The remainder contains the payload and is specific to the format used.
WARNING
All payloads protected to a given key will begin with the same 20-byte (magic value, key id) header. Administrators can use
this fact for diagnostic purposes to approximate when a payload was generated. For example, the payload above
corresponds to key {0c819c80-6619-4019-9536-53f8aaffee57}. If after checking the key repository you find that this
specific key's activation date was 2015-01-01 and its expiration date was 2015-03-01, then it's reasonable to assume that
the payload (if not tampered with) was generated within that window, give or take a small fudge factor on either side.
Subkey derivation and authenticated encryption in
ASP.NET Core
Most keys in the key ring will contain some form of entropy and will have algorithmic information stating "CBC -
mode encryption + HMAC validation" or "GCM encryption + validation". In these cases, we refer to the embedded
entropy as the master keying material (or KM ) for this key, and we perform a key derivation function to derive the
keys that will be used for the actual cryptographic operations.
NOTE
Keys are abstract, and a custom implementation might not behave as below. If the key provides its own implementation of
IAuthenticatedEncryptor rather than using one of our built-in factories, the mechanism described in this section no
longer applies.
Additional authenticated data and subkey derivation

The IAuthenticatedEncryptorinterface serves as the core interface for all authenticated encryption operations. Its
Encrypt method takes two buffers: plaintext and additionalAuthenticatedData ( AAD ). The plaintext contents flow
unchanged the call to IDataProtector.Protect , but the AAD is generated by the system and consists of three
components:
1. The 32-bit magic header 09 F0 C9 F0 that identifies this version of the data protection system.
2. The 128-bit key id.
3. A variable-length string formed from the purpose chain that created the IDataProtector that's performing
this operation.
Because the AAD is unique for the tuple of all three components, we can use it to derive new keys from KM
instead of using KM itself in all of our cryptographic operations. For every call to IAuthenticatedEncryptor.Encrypt
, the following key derivation process takes place:
( K_E, K_H ) = SP800_108_CTR_HMACSHA512(K_M, AAD, contextHeader || keyModifier)
Here, we're calling the NIST SP800-108 KDF in Counter Mode (see NIST SP800-108, Sec. 5.1) with the following
parameters:
Key derivation key (KDK) = K_M
PRF = HMACSHA512
label = additionalAuthenticatedData
context = contextHeader || keyModifier
The context header is of variable length and essentially serves as a thumbprint of the algorithms for which we're
deriving K_E and K_H. The key modifier is a 128-bit string randomly generated for each call to Encrypt and
serves to ensure with overwhelming probability that KE and KH are unique for this specific authentication
encryption operation, even if all other input to the KDF is constant.
For CBC -mode encryption + HMAC validation operations, | K_E | is the length of the symmetric block cipher key,
and | K_H | is the digest size of the HMAC routine. For GCM encryption + validation operations, | K_H | = 0.
CBC-mode encryption + HMAC validation

Once K_E is generated via the above mechanism, we generate a random initialization vector and run the
symmetric block cipher algorithm to encipher the plaintext. The initialization vector and ciphertext are then run
through the HMAC routine initialized with the key K_H to produce the MAC. This process and the return value is
represented graphically below.
output:= keyModifier || iv || E_cbc (K_E,iv,data ) || HMAC (K_H, iv || E_cbc (K_E,iv,data ))
NOTE
The IDataProtector.Protect implementation will prepend the magic header and key id to output before returning it to
the caller. Because the magic header and key id are implicitly part of AAD, and because the key modifier is fed as input to the
KDF, this means that every single byte of the final returned payload is authenticated by the MAC.
Galois/Counter Mode encryption + validation

Once K_E is generated via the above mechanism, we generate a random 96-bit nonce and run the symmetric
block cipher algorithm to encipher the plaintext and produce the 128-bit authentication tag.
output := keyModifier || nonce || E_gcm (K_E,nonce,data ) || authTag

NOTE
Even though GCM natively supports the concept of AAD, we're still feeding AAD only to the original KDF, opting to pass an
empty string into GCM for its AAD parameter. The reason for this is two-fold. First, to support agility we never want to use
K_M directly as the encryption key. Additionally, GCM imposes very strict uniqueness requirements on its inputs. The
probability that the GCM encryption routine is ever invoked on two or more distinct sets of input data with the same (key,
nonce) pair must not exceed 2^32. If we fix K_E we cannot perform more than 2^32 encryption operations before we run
afoul of the 2^-32 limit. This might seem like a very large number of operations, but a high-traffic web server can go
through 4 billion requests in mere days, well within the normal lifetime for these keys. To stay compliant of the 2^-32
probability limit, we continue to use a 128-bit key modifier and 96-bit nonce, which radically extends the usable operation
count for any given K_M. For simplicity of design we share the KDF code path between CBC and GCM operations, and since
AAD is already considered in the KDF there's no need to forward it to the GCM routine.
Context headers in ASP.NET Core
Background and theory

In the data protection system, a "key" means an object that can provide authenticated encryption services. Each
key is identified by a unique id (a GUID ), and it carries with it algorithmic information and entropic material. It's
intended that each key carry unique entropy, but the system cannot enforce that, and we also need to account for
developers who might change the key ring manually by modifying the algorithmic information of an existing key
in the key ring. To achieve our security requirements given these cases the data protection system has a concept of
cryptographic agility, which allows securely using a single entropic value across multiple cryptographic
algorithms.
Most systems which support cryptographic agility do so by including some identifying information about the
algorithm inside the payload. The algorithm's OID is generally a good candidate for this. However, one problem
that we ran into is that there are multiple ways to specify the same algorithm: "AES" (CNG ) and the managed Aes,
AesManaged, AesCryptoServiceProvider, AesCng, and RijndaelManaged (given specific parameters) classes are
all actually the same thing, and we'd need to maintain a mapping of all of these to the correct OID. If a developer
wanted to provide a custom algorithm (or even another implementation of AES!), they'd have to tell us its OID.
This extra registration step makes system configuration particularly painful.
Stepping back, we decided that we were approaching the problem from the wrong direction. An OID tells you
what the algorithm is, but we don't actually care about this. If we need to use a single entropic value securely in
two different algorithms, it's not necessary for us to know what the algorithms actually are. What we actually care
about is how they behave. Any decent symmetric block cipher algorithm is also a strong pseudorandom
permutation (PRP ): fix the inputs (key, chaining mode, IV, plaintext) and the ciphertext output will with
overwhelming probability be distinct from any other symmetric block cipher algorithm given the same inputs.
Similarly, any decent keyed hash function is also a strong pseudorandom function (PRF ), and given a fixed input
set its output will overwhelmingly be distinct from any other keyed hash function.
We use this concept of strong PRPs and PRFs to build up a context header. This context header essentially acts as
a stable thumbprint over the algorithms in use for any given operation, and it provides the cryptographic agility
needed by the data protection system. This header is reproducible and is used later as part of the subkey
derivation process. There are two different ways to build the context header depending on the modes of operation
of the underlying algorithms.
CBC-mode encryption + HMAC authentication

The context header consists of the following components:
[16 bits] The value 00 00, which is a marker meaning "CBC encryption + HMAC authentication".
[32 bits] The key length (in bytes, big-endian) of the symmetric block cipher algorithm.
[32 bits] The block size (in bytes, big-endian) of the symmetric block cipher algorithm.
[32 bits] The key length (in bytes, big-endian) of the HMAC algorithm. (Currently the key size always
matches the digest size.)
[32 bits] The digest size (in bytes, big-endian) of the HMAC algorithm.
EncCBC (K_E, IV, ""), which is the output of the symmetric block cipher algorithm given an empty string
input and where IV is an all-zero vector. The construction of K_E is described below.
MAC (K_H, ""), which is the output of the HMAC algorithm given an empty string input. The construction of
K_H is described below.
Ideally, we could pass all-zero vectors for K_E and K_H. However, we want to avoid the situation where the
underlying algorithm checks for the existence of weak keys before performing any operations (notably DES and
3DES ), which precludes using a simple or repeatable pattern like an all-zero vector.
Instead, we use the NIST SP800-108 KDF in Counter Mode (see NIST SP800-108, Sec. 5.1) with a zero-length
key, label, and context and HMACSHA512 as the underlying PRF. We derive | K_E | + | K_H | bytes of output, then
decompose the result into K_E and K_H themselves. Mathematically, this is represented as follows.
( K_E || K_H ) = SP800_108_CTR (prf = HMACSHA512, key = "", label = "", context = "")
Example: AES -192-CBC + HMACSHA256
As an example, consider the case where the symmetric block cipher algorithm is AES -192-CBC and the validation
algorithm is HMACSHA256. The system would generate the context header using the following steps.
First, let ( K_E || K_H ) = SP800_108_CTR (prf = HMACSHA512, key = "", label = "", context = ""), where | K_E | =
192 bits and | K_H | = 256 bits per the specified algorithms. This leads to K_E = 5BB6..21DD and K_H =
A04A..00A9 in the example below:
5B B6 C9 83 13 78 22 1D 8E 10 73 CA CF 65 8E B0
61 62 42 71 CB 83 21 DD A0 4A 05 00 5B AB C0 A2
49 6F A5 61 E3 E2 49 87 AA 63 55 CD 74 0A DA C4
B7 92 3D BF 59 90 00 A9
Next, compute Enc_CBC (K_E, IV, "") for AES -192-CBC given IV = 0* and K_E as above.
result := F474B1872B3B53E4721DE19C0841DB6F
Next, compute MAC (K_H, "") for HMACSHA256 given K_H as above.
result := D4791184B996092EE1202F36E8608FA8FBD98ABDFF5402F264B1D7211536220C
This produces the full context header below:
00 00 00 00 00 18 00 00 00 10 00 00 00 20 00 00
00 20 F4 74 B1 87 2B 3B 53 E4 72 1D E1 9C 08 41
DB 6F D4 79 11 84 B9 96 09 2E E1 20 2F 36 E8 60
8F A8 FB D9 8A BD FF 54 02 F2 64 B1 D7 21 15 36
22 0C
This context header is the thumbprint of the authenticated encryption algorithm pair (AES -192-CBC encryption +
HMACSHA256 validation). The components, as described above are:
the marker (00 00)
the block cipher key length (00 00 00 18)
the block cipher block size (00 00 00 10)
the HMAC key length (00 00 00 20)
the HMAC digest size (00 00 00 20)
the block cipher PRP output (F4 74 - DB 6F ) and
the HMAC PRF output (D4 79 - end).
NOTE
The CBC-mode encryption + HMAC authentication context header is built the same way regardless of whether the
algorithms implementations are provided by Windows CNG or by managed SymmetricAlgorithm and KeyedHashAlgorithm
types. This allows applications running on different operating systems to reliably produce the same context header even
though the implementations of the algorithms differ between OSes. (In practice, the KeyedHashAlgorithm doesn't have to be
a proper HMAC. It can be any keyed hash algorithm type.)
Example: 3DES -192-CBC + HMACSHA1

First, let ( K_E || K_H ) = SP800_108_CTR (prf = HMACSHA512, key = "", label = "", context = ""), where | K_E | =
192 bits and | K_H | = 160 bits per the specified algorithms. This leads to K_E = A219..E2BB and K_H =
DC4A..B464 in the example below:
A2 19 60 2F 83 A9 13 EA B0 61 3A 39 B8 A6 7E 22
61 D9 F8 6C 10 51 E2 BB DC 4A 00 D7 03 A2 48 3E
D1 F7 5A 34 EB 28 3E D7 D4 67 B4 64
Next, compute Enc_CBC (K_E, IV, "") for 3DES -192-CBC given IV = 0* and K_E as above.
result := ABB100F81E53E10E
Next, compute MAC (K_H, "") for HMACSHA1 given K_H as above.
result := 76EB189B35CF03461DDF877CD9F4B1B4D63A7555
This produces the full context header which is a thumbprint of the authenticated encryption algorithm pair (3DES -
192-CBC encryption + HMACSHA1 validation), shown below:
00 00 00 00 00 18 00 00 00 08 00 00 00 14 00 00
00 14 AB B1 00 F8 1E 53 E1 0E 76 EB 18 9B 35 CF
03 46 1D DF 87 7C D9 F4 B1 B4 D6 3A 75 55
The components break down as follows:

the marker (00 00)
the HMAC key length (00 00 00 14)
the HMAC digest size (00 00 00 14)
the block cipher PRP output (AB B1 - E1 0E ) and
the HMAC PRF output (76 EB - end).
Galois/Counter Mode encryption + authentication

The context header consists of the following components:
[16 bits] The value 00 01, which is a marker meaning "GCM encryption + authentication".
[32 bits] The key length (in bytes, big-endian) of the symmetric block cipher algorithm.
[32 bits] The nonce size (in bytes, big-endian) used during authenticated encryption operations. (For our
system, this is fixed at nonce size = 96 bits.)
[32 bits] The block size (in bytes, big-endian) of the symmetric block cipher algorithm. (For GCM, this is
fixed at block size = 128 bits.)
[32 bits] The authentication tag size (in bytes, big-endian) produced by the authenticated encryption
function. (For our system, this is fixed at tag size = 128 bits.)
[128 bits] The tag of Enc_GCM (K_E, nonce, ""), which is the output of the symmetric block cipher algorithm
given an empty string input and where nonce is a 96-bit all-zero vector.
K_E is derived using the same mechanism as in the CBC encryption + HMAC authentication scenario. However,
since there's no K_H in play here, we essentially have | K_H | = 0, and the algorithm collapses to the below form.
K_E = SP800_108_CTR (prf = HMACSHA512, key = "", label = "", context = "")
Example: AES -256-GCM
First, let K_E = SP800_108_CTR (prf = HMACSHA512, key = "", label = "", context = ""), where | K_E | = 256 bits.
K_E := 22BC6F1B171C08C4AE2F27444AF8FC8B3087A90006CAEA91FDCFB47C1B8733B8
Next, compute the authentication tag of Enc_GCM (K_E, nonce, "") for AES -256-GCM given nonce = 096 and K_E
as above.
result := E7DCCE66DF855A323A6BB7BD7A59BE45
This produces the full context header below:
00 01 00 00 00 20 00 00 00 0C 00 00 00 10 00 00
00 10 E7 DC CE 66 DF 85 5A 32 3A 6B B7 BD 7A 59
BE 45
The components break down as follows:

the marker (00 01)
the nonce size (00 00 00 0C )
the authentication tag size (00 00 00 10) and
the authentication tag from running the block cipher (E7 DC - end).
Key management in ASP.NET Core
The data protection system automatically manages the lifetime of master keys used to protect and unprotect
payloads. Each key can exist in one of four stages:
Created - the key exists in the key ring but has not yet been activated. The key shouldn't be used for new
Protect operations until sufficient time has elapsed that the key has had a chance to propagate to all
machines that are consuming this key ring.
Active - the key exists in the key ring and should be used for all new Protect operations.
Expired - the key has run its natural lifetime and should no longer be used for new Protect operations.
Revoked - the key is compromised and must not be used for new Protect operations.
Created, active, and expired keys may all be used to unprotect incoming payloads. Revoked keys by default may
not be used to unprotect payloads, but the application developer can override this behavior if necessary.
WARNING
The developer might be tempted to delete a key from the key ring (e.g., by deleting the corresponding file from the file
system). At that point, all data protected by the key is permanently undecipherable, and there's no emergency override like
there's with revoked keys. Deleting a key is truly destructive behavior, and consequently the data protection system
exposes no first-class API for performing this operation.
Default key selection

When the data protection system reads the key ring from the backing repository, it will attempt to locate a
"default" key from the key ring. The default key is used for new Protect operations.
The general heuristic is that the data protection system chooses the key with the most recent activation date as
the default key. (There's a small fudge factor to allow for server-to-server clock skew.) If the key is expired or
revoked, and if the application has not disabled automatic key generation, then a new key will be generated with
immediate activation per the key expiration and rolling policy below.
The reason the data protection system generates a new key immediately rather than falling back to a different
key is that new key generation should be treated as an implicit expiration of all keys that were activated prior to
the new key. The general idea is that new keys may have been configured with different algorithms or
encryption-at-rest mechanisms than old keys, and the system should prefer the current configuration over falling
back.
There's an exception. If the application developer has disabled automatic key generation, then the data protection
system must choose something as the default key. In this fallback scenario, the system will choose the non-
revoked key with the most recent activation date, with preference given to keys that have had time to propagate
to other machines in the cluster. The fallback system may end up choosing an expired default key as a result. The
fallback system will never choose a revoked key as the default key, and if the key ring is empty or every key has
been revoked then the system will produce an error upon initialization.
Key expiration and rolling

When a key is created, it's automatically given an activation date of { now + 2 days } and an expiration date of {
now + 90 days }. The 2-day delay before activation gives the key time to propagate through the system. That is, it
allows other applications pointing at the backing store to observe the key at their next auto-refresh period, thus
maximizing the chances that when the key ring does become active it has propagated to all applications that
might need to use it.
If the default key will expire within 2 days and if the key ring doesn't already have a key that will be active upon
expiration of the default key, then the data protection system will automatically persist a new key to the key ring.
This new key has an activation date of { default key's expiration date } and an expiration date of { now + 90 days }.
This allows the system to automatically roll keys on a regular basis with no interruption of service.
There might be circumstances where a key will be created with immediate activation. One example would be
when the application hasn't run for a time and all keys in the key ring are expired. When this happens, the key is
given an activation date of { now } without the normal 2-day activation delay.
The default key lifetime is 90 days, though this is configurable as in the following example.
// use 14-day lifetime instead of 90-day lifetime
.SetDefaultKeyLifetime(TimeSpan.FromDays(14));
An administrator can also change the default system-wide, though an explicit call to SetDefaultKeyLifetime will
override any system-wide policy. The default key lifetime cannot be shorter than 7 days.
Automatic key ring refresh

When the data protection system initializes, it reads the key ring from the underlying repository and caches it in
memory. This cache allows Protect and Unprotect operations to proceed without hitting the backing store. The
system will automatically check the backing store for changes approximately every 24 hours or when the current
default key expires, whichever comes first.
WARNING
Developers should very rarely (if ever) need to use the key management APIs directly. The data protection system will
perform automatic key management as described above.
The data protection system exposes an interface IKeyManager that can be used to inspect and make changes to
the key ring. The DI system that provided the instance of IDataProtectionProvider can also provide an instance
of IKeyManager for your consumption. Alternatively, you can pull the IKeyManager straight from the
IServiceProvider as in the example below.
Any operation which modifies the key ring (creating a new key explicitly or performing a revocation) will
invalidate the in-memory cache. The next call to Protect or Unprotect will cause the data protection system to
reread the key ring and recreate the cache.
The sample below demonstrates using the IKeyManager interface to inspect and manipulate the key ring,
including revoking existing keys and generating a new key manually.
using System;
using System.IO;
using System.Threading;

{
{
// point at a specific folder and use DPAPI to encrypt keys
// perform a protect operation to force the system to put at least

// one key in the key ring
services.GetDataProtector("Sample.KeyManager.v1").Protect("payload");
Console.WriteLine("Performed a protect operation.");
Thread.Sleep(2000);
// get a reference to the key manager

// list all keys in the key ring

var allKeys = keyManager.GetAllKeys();
Console.WriteLine($"The key ring contains {allKeys.Count} key(s).");
foreach (var key in allKeys)
{
Console.WriteLine($"Key {key.KeyId:B}: Created = {key.CreationDate:u}, IsRevoked =
{key.IsRevoked}");
}
// revoke all keys in the key ring

keyManager.RevokeAllKeys(DateTimeOffset.Now, reason: "Revocation reason here.");
Console.WriteLine("Revoked all existing keys.");
// add a new key to the key ring with immediate activation and a 1-month expiration
keyManager.CreateNewKey(
activationDate: DateTimeOffset.Now,
expirationDate: DateTimeOffset.Now.AddMonths(1));
Console.WriteLine("Added a new key.");
// list all keys in the key ring

allKeys = keyManager.GetAllKeys();
Console.WriteLine($"The key ring contains {allKeys.Count} key(s).");
foreach (var key in allKeys)
{
Console.WriteLine($"Key {key.KeyId:B}: Created = {key.CreationDate:u}, IsRevoked =
{key.IsRevoked}");
}
}
}
/*
* SAMPLE OUTPUT
*
* Performed a protect operation.
* The key ring contains 1 key(s).
* Key {1b948618-be1f-440b-b204-64ff5a152552}: Created = 2015-03-18 22:20:49Z, IsRevoked = False
* Revoked all existing keys.
* Added a new key.
* The key ring contains 2 key(s).
* Key {1b948618-be1f-440b-b204-64ff5a152552}: Created = 2015-03-18 22:20:49Z, IsRevoked = True
* Key {2266fc40-e2fb-48c6-8ce2-5fde6b1493f7}: Created = 2015-03-18 22:20:51Z, IsRevoked = False
*/
Key storage
The data protection system has a heuristic whereby it attempts to deduce an appropriate key storage location
and encryption-at-rest mechanism automatically. The key persistence mechanism is also configurable by the app
developer. The following documents discuss the in-box implementations of these mechanisms:
The data protection system employs a discovery mechanism by default to determine where cryptographic keys
should be persisted. The developer can override the default discovery mechanism and manually specify the
location.
WARNING
If you specify an explicit key persistence location, the data protection system deregisters the default key encryption at rest
mechanism, so keys are no longer encrypted at rest. It's recommended that you additionally specify an explicit key
encryption mechanism for production deployments.
File system
To configure a file system-based key repository, call the PersistKeysToFileSystem configuration routine as shown
below. Provide a DirectoryInfo pointing to the repository where keys should be stored:

{
.PersistKeysToFileSystem(new DirectoryInfo(@"c:\temp-keys\"));
}
The DirectoryInfo can point to a directory on the local machine, or it can point to a folder on a network share. If
pointing to a directory on the local machine (and the scenario is that only apps on the local machine require
access to use this repository), consider using Windows DPAPI (on Windows) to encrypt the keys at rest.
Otherwise, consider using an X.509 certificate to encrypt keys at rest.
Azure and Redis

The Microsoft.AspNetCore.DataProtection.AzureStorage and Microsoft.AspNetCore.DataProtection.Redis
packages allow storing data protection keys in Azure Storage or a Redis cache. Keys can be shared across several
instances of a web app. Apps can share authentication cookies or CSRF protection across multiple servers. To
configure the Azure Blob Storage provider, call one of the PersistKeysToAzureBlobStorage overloads:

{
.PersistKeysToAzureBlobStorage(new Uri("<blob URI including SAS token>"));
}
To configure on Redis, call one of the PersistKeysToRedis overloads:

{
var redis = ConnectionMultiplexer.Connect("<URI>");
.PersistKeysToRedis(redis, "DataProtection-Keys");
}
For more information, see the following topics:
StackExchange.Redis ConnectionMultiplexer
Azure Redis Cache
aspnet/DataProtection samples
Registry
Only applies to Windows deployments.
Sometimes the app might not have write access to the file system. Consider a scenario where an app is running
as a virtual service account (such as w3wp.exe's app pool identity). In these cases, the administrator can
provision a registry key that's accessible by the service account identity. Call the PersistKeysToRegistry extension
method as shown below. Provide a RegistryKey pointing to the location where cryptographic keys should be
stored:

{
.PersistKeysToRegistry(Registry.CurrentUser.OpenSubKey(@"SOFTWARE\Sample\keys"));
}
IMPORTANT
We recommend using Windows DPAPI to encrypt the keys at rest.

The Microsoft.AspNetCore.DataProtection.EntityFrameworkCore package provides a mechanism for storing
data protection keys to a database using Entity Framework Core. The
Microsoft.AspNetCore.DataProtection.EntityFrameworkCore NuGet package must be added to the project file, it's
not part of the Microsoft.AspNetCore.App metapackage.
With this package, keys can be shared across multiple instances of a web app.
To configure the EF Core provider, call the PersistKeysToDbContext<TContext> method:
{
{
});
// using Microsoft.AspNetCore.DataProtection;
.PersistKeysToDbContext<MyKeysContext>();
.AddDefaultUI(UIFramework.Bootstrap4)
}
The generic parameter, TContext , must inherit from DbContext and IDataProtectionKeyContext:
using Microsoft.AspNetCore.DataProtection.EntityFrameworkCore;
using WebApp1.Data;
namespace WebApp1
{
class MyKeysContext : DbContext, IDataProtectionKeyContext
{
// A recommended constructor overload when using EF Core
// with dependency injection.
public MyKeysContext(DbContextOptions<ApplicationDbContext> options)
: base(options) { }
// This maps to the table that stores keys.

public DbSet<DataProtectionKey> DataProtectionKeys { get; set; }
}
}
Custom key repository

If the in-box mechanisms aren't appropriate, the developer can specify their own key persistence mechanism by
providing a custom IXmlRepository.
Key encryption at rest in ASP.NET Core
The data protection system employs a discovery mechanism by default to determine how cryptographic keys
should be encrypted at rest. The developer can override the discovery mechanism and manually specify how
keys should be encrypted at rest.
WARNING
If you specify an explicit key persistence location, the data protection system deregisters the default key encryption at
rest mechanism. Consequently, keys are no longer encrypted at rest. We recommend that you specify an explicit key
encryption mechanism for production deployments. The encryption-at-rest mechanism options are described in this
topic.
Azure Key Vault

To store keys in Azure Key Vault, configure the system with ProtectKeysWithAzureKeyVault in the Startup
class:

{
.PersistKeysToAzureBlobStorage(new Uri("<blobUriWithSasToken>"))
.ProtectKeysWithAzureKeyVault("<keyIdentifier>", "<clientId>", "<clientSecret>");
}
For more information, see Configure ASP.NET Core Data Protection: ProtectKeysWithAzureKeyVault.
Windows DPAPI
Only applies to Windows deployments.
When Windows DPAPI is used, key material is encrypted with CryptProtectData before being persisted to
storage. DPAPI is an appropriate encryption mechanism for data that's never read outside of the current
machine (though it's possible to back these keys up to Active Directory; see DPAPI and Roaming Profiles). To
configure DPAPI key-at-rest encryption, call one of the ProtectKeysWithDpapi extension methods:

{
// Only the local user account can decrypt the keys
}
If ProtectKeysWithDpapi is called with no parameters, only the current Windows user account can decipher the
persisted key ring. You can optionally specify that any user account on the machine (not just the current user
account) be able to decipher the key ring:
{
// All user accounts on the machine can decrypt the keys
.ProtectKeysWithDpapi(protectToLocalMachine: true);
}
X.509 certificate
If the app is spread across multiple machines, it may be convenient to distribute a shared X.509 certificate
across the machines and configure the hosted apps to use the certificate for encryption of keys at rest:

{
.ProtectKeysWithCertificate("3BCE558E2AD3E0E34A7743EAB5AEA2A9BD2575A0");
}
Due to .NET Framework limitations, only certificates with CAPI private keys are supported. See the content
below for possible workarounds to these limitations.
Windows DPAPI-NG
This mechanism is available only on Windows 8/Windows Server 2012 or later.
Beginning with Windows 8, Windows OS supports DPAPI-NG (also called CNG DPAPI). For more
information, see About CNG DPAPI.
The principal is encoded as a protection descriptor rule. In the following example that calls
ProtectKeysWithDpapiNG, only the domain-joined user with the specified SID can decrypt the key ring:

{
// Uses the descriptor rule "SID=S-1-5-21-..."
.ProtectKeysWithDpapiNG("SID=S-1-5-21-...",
flags: DpapiNGProtectionDescriptorFlags.None);
}
There's also a parameterless overload of ProtectKeysWithDpapiNG . Use this convenience method to specify the
rule "SID={CURRENT_ACCOUNT_SID }", where CURRENT_ACCOUNT_SID is the SID of the current
Windows user account:

{
// Use the descriptor rule "SID={current account SID}"
.ProtectKeysWithDpapiNG();
}
In this scenario, the AD domain controller is responsible for distributing the encryption keys used by the
DPAPI-NG operations. The target user can decipher the encrypted payload from any domain-joined machine
(provided that the process is running under their identity).
Certificate-based encryption with Windows DPAPI-NG

If the app is running on Windows 8.1/Windows Server 2012 R2 or later, you can use Windows DPAPI-NG to
perform certificate-based encryption. Use the rule descriptor string "CERTIFICATE=HashId:THUMBPRINT",
where THUMBPRINT is the hex-encoded SHA1 thumbprint of the certificate:

{
.ProtectKeysWithDpapiNG("CERTIFICATE=HashId:3BCE558E2...B5AEA2A9BD2575A0",
flags: DpapiNGProtectionDescriptorFlags.None);
}
Any app pointed at this repository must be running on Windows 8.1/Windows Server 2012 R2 or later to
decipher the keys.
Custom key encryption

If the in-box mechanisms aren't appropriate, the developer can specify their own key encryption mechanism by
providing a custom IXmlEncryptor.
Key immutability and key settings in ASP.NET Core
Once an object is persisted to the backing store, its representation is forever fixed. New data can be added to the
backing store, but existing data can never be mutated. The primary purpose of this behavior is to prevent data
corruption.
One consequence of this behavior is that once a key is written to the backing store, it's immutable. Its creation,
activation, and expiration dates can never be changed, though it can revoked by using IKeyManager . Additionally,
its underlying algorithmic information, master keying material, and encryption at rest properties are also
immutable.
If the developer changes any setting that affects key persistence, those changes won't go into effect until the next
time a key is generated, either via an explicit call to IKeyManager.CreateNewKey or via the data protection system's
own automatic key generation behavior. The settings that affect key persistence are as follows:
The default key lifetime
The key encryption at rest mechanism
The algorithmic information contained within the key
If you need these settings to kick in earlier than the next automatic key rolling time, consider making an explicit
call to IKeyManager.CreateNewKey to force the creation of a new key. Remember to provide an explicit activation
date ({ now + 2 days } is a good rule of thumb to allow time for the change to propagate) and expiration date in
the call.
TIP
All applications touching the repository should specify the same settings with the IDataProtectionBuilder extension
methods. Otherwise, the properties of the persisted key will be dependent on the particular application that invoked the key
generation routines.
Key storage format in ASP.NET Core
Objects are stored at rest in XML representation. The default directory for key storage is
%LOCALAPPDATA%\ASP.NET\DataProtection-Keys.
The <key> element

Keys exist as top-level objects in the key repository. By convention keys have the filename key-{guid}.xml, where
{guid} is the id of the key. Each such file contains a single key. The format of the file is as follows.

<key id="80732141-ec8f-4b80-af9c-c4d2d1ff8901" version="1">
<creationDate>2015-03-19T23:32:02.3949887Z</creationDate>
<activationDate>2015-03-19T23:32:02.3839429Z</activationDate>
<expirationDate>2015-06-17T23:32:02.3839429Z</expirationDate>
<descriptor deserializerType="{deserializerType}">
<descriptor>
<encryption algorithm="AES_256_CBC" />
<validation algorithm="HMACSHA256" />
<enc:encryptedSecret decryptorType="{decryptorType}" xmlns:enc="...">
<encryptedKey>

<value>AQAAANCM...8/zeP8lcwAg==</value>
</encryptedKey>
</enc:encryptedSecret>
</descriptor>
</descriptor>
</key>
The <key> element contains the following attributes and child elements:
The key id. This value is treated as authoritative; the filename is simply a nicety for human readability.
The version of the <key> element, currently fixed at 1.
The key's creation, activation, and expiration dates.
A <descriptor> element, which contains information on the authenticated encryption implementation
contained within this key.
In the above example, the key's id is {80732141-ec8f-4b80-af9c-c4d2d1ff8901}, it was created and activated on
March 19, 2015, and it has a lifetime of 90 days. (Occasionally the activation date might be slightly before the
creation date as in this example. This is due to a nit in how the APIs work and is harmless in practice.)
The <descriptor> element

The outer <descriptor> element contains an attribute deserializerType, which is the assembly-qualified name of a
type which implements IAuthenticatedEncryptorDescriptorDeserializer. This type is responsible for reading the
inner <descriptor> element and for parsing the information contained within.
The particular format of the <descriptor> element depends on the authenticated encryptor implementation
encapsulated by the key, and each deserializer type expects a slightly different format for this. In general, though,
this element will contain algorithmic information (names, types, OIDs, or similar) and secret key material. In the
above example, the descriptor specifies that this key wraps AES -256-CBC encryption + HMACSHA256 validation.
The <encryptedSecret> element
An <encryptedSecret> element which contains the encrypted form of the secret key material may be present if
encryption of secrets at rest is enabled. The attribute decryptorType is the assembly-qualified name of a type
which implements IXmlDecryptor. This type is responsible for reading the inner <encryptedKey> element and
decrypting it to recover the original plaintext.
As with <descriptor>, the particular format of the element depends on the at-rest encryption mechanism in use.
In the above example, the master key is encrypted using Windows DPAPI per the comment.
The <revocation> element

Revocations exist as top-level objects in the key repository. By convention revocations have the filename
revocation-{timestamp}.xml (for revoking all keys before a specific date) or revocation-{guid}.xml (for
revoking a specific key). Each file contains a single <revocation> element.
For revocations of individual keys, the file contents will be as below.

<revocation version="1">
<revocationDate>2015-03-20T22:45:30.2616742Z</revocationDate>
<key id="eb4fc299-8808-409d-8a34-23fc83d026c9" />
<reason>human-readable reason</reason>
</revocation>
In this case, only the specified key is revoked. If the key id is "*", however, as in the below example, all keys whose
creation date is prior to the specified revocation date are revoked.

<revocation version="1">
<revocationDate>2015-03-20T15:45:45.7366491-07:00</revocationDate>

<key id="*" />
<reason>human-readable reason</reason>
</revocation>
The <reason> element is never read by the system. It's simply a convenient place to store a human-readable
reason for revocation.
Ephemeral data protection providers in ASP.NET
Core
There are scenarios where an application needs a throwaway IDataProtectionProvider . For example, the
developer might just be experimenting in a one-off console application, or the application itself is transient (it's
scripted or a unit test project). To support these scenarios the Microsoft.AspNetCore.DataProtection package
includes a type EphemeralDataProtectionProvider . This type provides a basic implementation of
IDataProtectionProvider whose key repository is held solely in-memory and isn't written out to any backing store.
Each instance of EphemeralDataProtectionProvider uses its own unique master key. Therefore, if an IDataProtector
rooted at an EphemeralDataProtectionProvider generates a protected payload, that payload can only be
unprotected by an equivalent IDataProtector (given the same purpose chain) rooted at the same
EphemeralDataProtectionProvider instance.
The following sample demonstrates instantiating an EphemeralDataProtectionProvider and using it to protect and
unprotect data.
using System;

{
{
const string purpose = "Ephemeral.App.v1";
// create an ephemeral provider and demonstrate that it can round-trip a payload

var provider = new EphemeralDataProtectionProvider();
var protector = provider.CreateProtector(purpose);

string protectedPayload = protector.Protect(input);

string unprotectedPayload = protector.Unprotect(protectedPayload);
// if I create a new ephemeral provider, it won't be able to unprotect existing

// payloads, even if I specify the same purpose
provider = new EphemeralDataProtectionProvider();
protector = provider.CreateProtector(purpose);
unprotectedPayload = protector.Unprotect(protectedPayload); // THROWS
}
}
/*
* SAMPLE OUTPUT
*
* Enter input: Hello!
* Protect returned: CfDJ8AAAAAAAAAAAAAAAAAAAAA...uGoxWLjGKtm1SkNACQ
* Unprotect returned: Hello!
* << throws CryptographicException >>
*/
Compatibility in ASP.NET Core
Replacing ASP.NET <machineKey> in ASP.NET Core

Replace the ASP.NET machineKey in ASP.NET Core
The implementation of the <machineKey> element in ASP.NET is replaceable. This allows most calls to ASP.NET
cryptographic routines to be routed through a replacement data protection mechanism, including the new data
protection system.
NOTE
The new data protection system can only be installed into an existing ASP.NET application targeting .NET 4.5.1 or higher.
Installation will fail if the application targets .NET 4.5 or lower.
To install the new data protection system into an existing ASP.NET 4.5.1+ project, install the package
Microsoft.AspNetCore.DataProtection.SystemWeb. This will instantiate the data protection system using the
default configuration settings.
When you install the package, it inserts a line into Web.config that tells ASP.NET to use it for most cryptographic
operations, including forms authentication, view state, and calls to MachineKey.Protect. The line that's inserted
reads as follows.
<machineKey compatibilityMode="Framework45" dataProtectorType="..." />
TIP
You can tell if the new data protection system is active by inspecting fields like __VIEWSTATE , which should begin with
"CfDJ8" as in the example below. "CfDJ8" is the base64 representation of the magic "09 F0 C9 F0" header that identifies a
payload protected by the data protection system.
<input type="hidden" name="__VIEWSTATE" id="__VIEWSTATE" value="CfDJ8AWPr2EQPTBGs3L2GCZOpk..." />
Package configuration
The data protection system is instantiated with a default zero-setup configuration. However, since by default keys
are persisted to the local file system, this won't work for applications which are deployed in a farm. To resolve this,
you can provide configuration by creating a type which subclasses DataProtectionStartup and overrides its
ConfigureServices method.
Below is an example of a custom data protection startup type which configured both where keys are persisted and
how they're encrypted at rest. It also overrides the default app isolation policy by providing its own application
name.
using System;
using System.IO;
using Microsoft.AspNetCore.DataProtection.SystemWeb;
namespace DataProtectionDemo
{
public class MyDataProtectionStartup : DataProtectionStartup
{
public override void ConfigureServices(IServiceCollection services)
{
.SetApplicationName("my-app")
.PersistKeysToFileSystem(new DirectoryInfo(@"\\server\share\myapp-keys\"))
}
}
}
TIP
You can also use <machineKey applicationName="my-app" ... /> in place of an explicit call to SetApplicationName. This is
a convenience mechanism to avoid forcing the developer to create a DataProtectionStartup-derived type if all they wanted
to configure was setting the application name.
To enable this custom configuration, go back to Web.config and look for the <appSettings> element that the
package install added to the config file. It will look like the following markup:
<appSettings>

<add key="aspnet:dataProtectionStartupType" value="" />
</appSettings>
Fill in the blank value with the assembly-qualified name of the DataProtectionStartup-derived type you just
created. If the name of the application is DataProtectionDemo, this would look like the below.
<add key="aspnet:dataProtectionStartupType"
value="DataProtectionDemo.MyDataProtectionStartup, DataProtectionDemo" />
The newly-configured data protection system is now ready for use inside the application.
Enforce HTTPS in ASP.NET Core
By Rick Anderson
This document shows how to:
Require HTTPS for all requests.
Redirect all HTTP requests to HTTPS.
No API can prevent a client from sending sensitive data on the first request.
WARNING
Do not use RequireHttpsAttribute on Web APIs that receive sensitive information. RequireHttpsAttribute uses HTTP
status codes to redirect browsers from HTTP to HTTPS. API clients may not understand or obey redirects from HTTP to
HTTPS. Such clients may send information over HTTP. Web APIs should either:
Not listen on HTTP.
Close the connection with status code 400 (Bad Request) and not serve the request.
Require HTTPS
We recommend all production ASP.NET Core web apps call:
The HTTPS Redirection Middleware (UseHttpsRedirection) to redirect all HTTP requests to HTTPS.
UseHsts, HTTP Strict Transport Security Protocol (HSTS ).
UseHttpsRedirection
The following code calls UseHttpsRedirection in the Startup class:

{
{
}
else
{
app.UseHsts();
}
app.UseMvc();
}
The preceding highlighted code:

Uses the default HttpsRedirectionOptions.RedirectStatusCode ( Status307TemporaryRedirect ).
Uses the default HttpsRedirectionOptions.HttpsPort (null) unless overridden by the ASPNETCORE_HTTPS_PORT
environment variable or IServerAddressesFeature.
WARNING
A port must be available for the middleware to redirect to HTTPS. If no port is available, redirection to HTTPS does not
occur. The HTTPS port can be specified by any of the following setting:
HttpsRedirectionOptions.HttpsPort
The ASPNETCORE_HTTPS_PORT environment variable.
In development, an HTTPS url in launchsettings.json.
An HTTPS url configured directly on Kestrel or HttpSys.
The following highlighted code calls AddHttpsRedirection to configure middleware options:

{
services.AddMvc();
services.AddHsts(options =>
{
options.Preload = true;
options.IncludeSubDomains = true;
options.MaxAge = TimeSpan.FromDays(60);
options.ExcludedHosts.Add("example.com");
options.ExcludedHosts.Add("www.example.com");
});
services.AddHttpsRedirection(options =>
{
options.RedirectStatusCode = StatusCodes.Status307TemporaryRedirect;
options.HttpsPort = 5001;
});
}
Calling AddHttpsRedirection is only necessary to change the values of HttpsPort or RedirectStatusCode ;

The preceding highlighted code:
Sets HttpsRedirectionOptions.RedirectStatusCode to Status307TemporaryRedirect , which is the default value.
Sets the HTTPS port to 5001. The default value is 443.
The following mechanisms set the port automatically:
The middleware can discover the ports via IServerAddressesFeature when the following conditions apply:
Kestrel or HTTP.sys is used directly with HTTPS endpoints (also applies to running the app with Visual
Studio Code's debugger).
Only one HTTPS port is used by the app.
Visual Studio is used:
IIS Express has HTTPS enabled.
launchSettings.json sets the sslPort for IIS Express.
NOTE
When an app is run behind a reverse proxy (for example, IIS, IIS Express), IServerAddressesFeature isn't available. The
port must be manually configured. When the port isn't set, requests aren't redirected.
The port can be configured by setting the https_port Web Host configuration setting:
Key: https_port
Type: string
Default: A default value isn't set.
Environment variable: <PREFIX_>HTTPS_PORT (The prefix is ASPNETCORE_ when using the Web Host.)
.UseSetting("https_port", "8080")
NOTE
The port can be configured indirectly by setting the URL with the ASPNETCORE_URLS environment variable. The
environment variable configures the server, and then the middleware indirectly discovers the HTTPS port via
IServerAddressesFeature .
If no port is set:
Requests aren't redirected.
The middleware logs the warning "Failed to determine the https port for redirect."
NOTE
An alternative to using HTTPS Redirection Middleware ( UseHttpsRedirection ) is to use URL Rewriting Middleware (
AddRedirectToHttps ). AddRedirectToHttps can also set the status code and port when the redirect is executed. For
more information, see URL Rewriting Middleware.
When redirecting to HTTPS without the requirement for additional redirect rules, we recommend using HTTPS Redirection
Middleware ( UseHttpsRedirection ) described in this topic.
The RequireHttpsAttribute is used to require HTTPS. [RequireHttpsAttribute] can decorate controllers or

methods, or can be applied globally. To apply the attribute globally, add the following code to ConfigureServices
in Startup :
// Requires using Microsoft.AspNetCore.Mvc;

{
services.Configure<MvcOptions>(options =>
{
options.Filters.Add(new RequireHttpsAttribute());
});
The preceding highlighted code requires all requests use HTTPS ; therefore, HTTP requests are ignored. The
following highlighted code redirects all HTTP requests to HTTPS:
// Requires using Microsoft.AspNetCore.Rewrite;
{

.AddRedirectToHttps();
For more information, see URL Rewriting Middleware. The middleware also permits the app to set the status
code or the status code and the port when the redirect is executed.
Requiring HTTPS globally ( options.Filters.Add(new RequireHttpsAttribute()); ) is a security best practice.
Applying the [RequireHttps] attribute to all controllers/Razor Pages isn't considered as secure as requiring
HTTPS globally. You can't guarantee the [RequireHttps] attribute is applied when new controllers and Razor
Pages are added.
HTTP Strict Transport Security Protocol (HSTS)

Per OWASP, HTTP Strict Transport Security (HSTS ) is an opt-in security enhancement that's specified by a web
app through the use of a response header. When a browser that supports HSTS receives this header:
The browser stores configuration for the domain that prevents sending any communication over HTTP. The
browser forces all communication over HTTPS.
The browser prevents the user from using untrusted or invalid certificates. The browser disables prompts that
allow a user to temporarily trust such a certificate.
Because HSTS is enforced by the client it has some limitations:
The client must support HSTS.
HSTS requires at least one successful HTTPS request to establish the HSTS policy.
The application must check every HTTP request and redirect or reject the HTTP request.
ASP.NET Core 2.1 or later implements HSTS with the UseHsts extension method. The following code calls
UseHsts when the app isn't in development mode:

{
{
}
else
{
app.UseHsts();
}
app.UseMvc();
}
UseHsts isn't recommended in development because the HSTS settings are highly cacheable by browsers. By
default, UseHsts excludes the local loopback address.
For production environments implementing HTTPS for the first time, set the initial HSTS value to a small value.
Set the value from hours to no more than a single day in case you need to revert the HTTPS infrastructure to
HTTP. After you're confident in the sustainability of the HTTPS configuration, increase the HSTS max-age value;
a commonly used value is one year.
The following code:

{
services.AddMvc();
services.AddHsts(options =>
{
options.Preload = true;
options.IncludeSubDomains = true;
options.MaxAge = TimeSpan.FromDays(60);
options.ExcludedHosts.Add("example.com");
options.ExcludedHosts.Add("www.example.com");
});
services.AddHttpsRedirection(options =>
{
options.RedirectStatusCode = StatusCodes.Status307TemporaryRedirect;
options.HttpsPort = 5001;
});
}
Sets the preload parameter of the Strict-Transport-Security header. Preload isn't part of the RFC HSTS
specification, but is supported by web browsers to preload HSTS sites on fresh install. See
https://hstspreload.org/ for more information.
Enables includeSubDomain, which applies the HSTS policy to Host subdomains.
Explicitly sets the max-age parameter of the Strict-Transport-Security header to 60 days. If not set, defaults to
30 days. See the max-age directive for more information.
Adds example.com to the list of hosts to exclude.
UseHsts excludes the following loopback hosts:

localhost : The IPv4 loopback address.
127.0.0.1 : The IPv4 loopback address.
[::1] : The IPv6 loopback address.
The preceding example shows how to add additional hosts.
Opt-out of HTTPS on project creation

The ASP.NET Core 2.1 or later web application templates (from Visual Studio or the dotnet command line)
enable HTTPS redirection and HSTS. For deployments that don't require HTTPS, you can opt-out of HTTPS. For
example, some backend services where HTTPS is being handled externally at the edge, using HTTPS at each
node isn't needed.
To opt-out of HTTPS:
Visual Studio
.NET Core CLI
Uncheck the Configure for HTTPS checkbox.
How to set up a developer certificate for Docker
See this GitHub issue.
Additional information
OWASP HSTS browser support
EU General Data Protection Regulation (GDPR)
support in ASP.NET Core
By Rick Anderson
ASP.NET Core provides APIs and templates to help meet some of the EU General Data Protection Regulation
(GDPR ) requirements:
The project templates include extension points and stubbed markup that you can replace with your privacy
and cookie use policy.
A cookie consent feature allows you to ask for (and track) consent from your users for storing personal
information. If a user hasn't consented to data collection and the app has CheckConsentNeeded set to true ,
non-essential cookies aren't sent to the browser.
Cookies can be marked as essential. Essential cookies are sent to the browser even when the user hasn't
consented and tracking is disabled.
TempData and Session cookies aren't functional when tracking is disabled.
The Identity manage page provides a link to download and delete user data.
The sample app allows you test most of the GDPR extension points and APIs added to the ASP.NET Core 2.1
templates. See the ReadMe file for testing instructions.
ASP.NET Core GDPR support in template generated code

Razor Pages and MVC projects created with the project templates include the following GDPR support:
CookiePolicyOptions and UseCookiePolicy are set in Startup .
The _CookieConsentPartial.cshtml partial view.
The Pages/Privacy.cshtml page or Views/Home/Privacy.cshtml view provides a page to detail your site's
privacy policy. The _CookieConsentPartial.cshtml file generates a link to the Privacy page.
For apps created with individual user accounts, the Manage page provides links to download and delete
personal user data.
CookiePolicyOptions and UseCookiePolicy
CookiePolicyOptions are initialized in Startup.ConfigureServices :
{
{
}
// This method gets called by the runtime. Use this method to add services
// to the container.
{
{
// This lambda determines whether user consent for non-essential cookies
// is needed for a given request.
});
// If the app uses session state, call AddSession.

// services.AddSession();
}
// This method gets called by the runtime. Use this method to configure the
// HTTP request pipeline.
{
{
}
else
{
app.UseHsts();
}
// app.UseSession();
app.UseMvc();
}
}
UseCookiePolicy is called in Startup.Configure :

{
{
}
// This method gets called by the runtime. Use this method to add services
// to the container.
{
{
// This lambda determines whether user consent for non-essential cookies
// is needed for a given request.
});
// If the app uses session state, call AddSession.

// services.AddSession();
}
// This method gets called by the runtime. Use this method to configure the
// HTTP request pipeline.
{
{
}
else
{
app.UseHsts();
}
app.UseMvc();
}
}
_CookieConsentPartial.cshtml partial view

The _CookieConsentPartial.cshtml partial view:
@using Microsoft.AspNetCore.Http.Features
@{
var consentFeature = Context.Features.Get<ITrackingConsentFeature>();
var showBanner = !consentFeature?.CanTrack ?? false;
var cookieString = consentFeature?.CreateConsentCookie();
}
@if (showBanner)
{
<nav id="cookieConsent" class="navbar navbar-default navbar-fixed-top" role="alert">
target="#cookieConsent .navbar-collapse">
<span class="sr-only">Toggle cookie consent banner</span>
</button>
<span class="navbar-brand"><span class="glyphicon glyphicon-info-sign" aria-hidden="true">
</span></span>
</div>
<div class="collapse navbar-collapse">
<p class="navbar-text">
Use this space to summarize your privacy and cookie use policy.
</p>
<div class="navbar-right">
<a asp-page="/Privacy" class="btn btn-info navbar-btn">Learn More</a>
<button type="button" class="btn btn-default navbar-btn" data-cookie-
string="@cookieString">Accept</button>
</div>
</div>
</div>
</nav>
<script>
(function () {
document.querySelector("#cookieConsent button[data-cookie-string]").addEventListener("click",
function (el) {
document.cookie = el.target.dataset.cookieString;
document.querySelector("#cookieConsent").classList.add("hidden");
}, false);
})();
</script>
}
This partial:
Obtains the state of tracking for the user. If the app is configured to require consent, the user must consent
before cookies can be tracked. If consent is required, the cookie consent panel is fixed at top of the
navigation bar created by the _Layout.cshtml file.
Provides an HTML <p> element to summarize your privacy and cookie use policy.
Provides a link to Privacy page or view where you can detail your site's privacy policy.
Essential cookies
If consent has not been given, only cookies marked essential are sent to the browser. The following code makes
a cookie essential:
public IActionResult OnPostCreateEssentialAsync()
{
HttpContext.Response.Cookies.Append(Constants.EssentialSec,
DateTime.Now.Second.ToString(),
new CookieOptions() { IsEssential = true });
ResponseCookies = Response.Headers[HeaderNames.SetCookie].ToString();
}
Tempdata provider and session state cookies are not essential

The Tempdata provider cookie isn't essential. If tracking is disabled, the Tempdata provider isn't functional. To
enable the Tempdata provider when tracking is disabled, mark the TempData cookie as essential in
// The Tempdata provider cookie is not essential. Make it essential

// so Tempdata is functional when tracking is disabled.
services.Configure<CookieTempDataProviderOptions>(options => {
options.Cookie.IsEssential = true;
});
Session state cookies are not essential. Session state isn't functional when tracking is disabled.
Personal data
ASP.NET Core apps created with individual user accounts include code to download and delete personal data.
Select the user name and then select Personal data:
Notes:
To generate the Account/Manage code, see Scaffold Identity.
Delete and download only impact the default identity data. Apps that create custom user data must be
extended to delete/download the custom user data. For more information, see Add, download, and delete
custom user data to Identity.
Saved tokens for the user that are stored in the Identity database table AspNetUserTokens are deleted when
the user is deleted via the cascading delete behavior due to the foreign key.
Encryption at rest
Some databases and storage mechanisms allow for encryption at rest. Encryption at rest:
Encrypts stored data automatically.
Encrypts without configuration, programming, or other work for the software that accesses the data.
Is the easiest and safest option.
Allows the database to manage keys and encryption.
For example:
Microsoft SQL and Azure SQL provide Transparent Data Encryption (TDE ).
SQL Azure encrypts the database by default
Azure Blobs, Files, Table, and Queue Storage are encrypted by default.
For databases that don't provide built-in encryption at rest, you may be able to use disk encryption to provide
the same protection. For example:
BitLocker for Windows Server
Linux:
eCryptfs
EncFS.
Microsoft.com/GDPR
Safe storage of app secrets in development in
ASP.NET Core
By Rick Anderson, Daniel Roth, and Scott Addie

This document explains techniques for storing and retrieving sensitive data during the development of an
ASP.NET Core app. Never store passwords or other sensitive data in source code. Production secrets
shouldn't be used for development or test. You can store and protect Azure test and production secrets with
the Azure Key Vault configuration provider.
Environment variables are used to avoid storage of app secrets in code or in local configuration files.
Environment variables override configuration values for all previously specified configuration sources.
Configure the reading of environment variable values by calling AddEnvironmentVariables in the Startup
constructor:

{
.AddJsonFile("appsettings.json",
optional: false,
.AddEnvironmentVariables();
{
builder.AddUserSecrets<Startup>();
}
}
Consider an ASP.NET Core web app in which Individual User Accounts security is enabled. A default
database connection string is included in the project's appsettings.json file with the key DefaultConnection .
The default connection string is for LocalDB, which runs in user mode and doesn't require a password.
During app deployment, the DefaultConnection key value can be overridden with an environment
variable's value. The environment variable may store the complete connection string with sensitive
credentials.
WARNING
Environment variables are generally stored in plain, unencrypted text. If the machine or process is compromised,
environment variables can be accessed by untrusted parties. Additional measures to prevent disclosure of user
secrets may be required.
Secret Manager
The Secret Manager tool stores sensitive data during the development of an ASP.NET Core project. In this
context, a piece of sensitive data is an app secret. App secrets are stored in a separate location from the
project tree. The app secrets are associated with a specific project or shared across several projects. The app
secrets aren't checked into source control.
WARNING
The Secret Manager tool doesn't encrypt the stored secrets and shouldn't be treated as a trusted store. It's for
development purposes only. The keys and values are stored in a JSON configuration file in the user profile directory.
How the Secret Manager tool works

The Secret Manager tool abstracts away the implementation details, such as where and how the values are
stored. You can use the tool without knowing these implementation details. The values are stored in a
JSON configuration file in a system-protected user profile folder on the local machine:
Windows
macOS
Linux
File system path:
%APPDATA%\Microsoft\UserSecrets\<user_secrets_id>\secrets.json
In the preceding file paths, replace <user_secrets_id> with the UserSecretsId value specified in the .csproj
file.
Don't write code that depends on the location or format of data saved with the Secret Manager tool. These
implementation details may change. For example, the secret values aren't encrypted, but could be in the
future.
Install the Secret Manager tool

The Secret Manager tool is bundled with the .NET Core CLI in .NET Core SDK 2.1.300 or later. For .NET
Core SDK versions before 2.1.300, tool installation is necessary.
TIP
Run dotnet --version from a command shell to see the installed .NET Core SDK version number.
A warning is displayed if the .NET Core SDK being used includes the tool:
The tool 'Microsoft.Extensions.SecretManager.Tools' is now included in the .NET Core SDK. Information
on resolving this warning is available at (https://aka.ms/dotnetclitools-in-box).
Install the Microsoft.Extensions.SecretManager.Tools NuGet package in your ASP.NET Core project. For
example:
<PropertyGroup>
<UserSecretsId>1242d6d6-9df3-4031-b031-d9b27d13c25a</UserSecretsId>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore"
Version="1.1.6" />
<PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets"
Version="1.1.2" />
<PackageReference Include="System.Data.SqlClient"
Version="4.5.0" />
</ItemGroup>
<ItemGroup>
<DotNetCliToolReference Include="Microsoft.Extensions.SecretManager.Tools"
Version="1.0.1" />
</ItemGroup>
</Project>
Execute the following command in a command shell to validate the tool installation:
dotnet user-secrets -h
The Secret Manager tool displays sample usage, options, and command help:
Usage: dotnet user-secrets [options] [command]
Options:
-?|-h|--help Show help information
--version Show version information
-v|--verbose Show verbose output
-p|--project <PROJECT> Path to project. Defaults to searching the current directory.
-c|--configuration <CONFIGURATION> The project configuration to use. Defaults to 'Debug'.
--id The user secret ID to use.
Commands:
clear Deletes all the application secrets
list Lists all the application secrets
remove Removes the specified user secret
set Sets the user secret to the specified value
Use "dotnet user-secrets [command] --help" for more information about a command.
NOTE
You must be in the same directory as the .csproj file to run tools defined in the .csproj file's
DotNetCliToolReference elements.
Set a secret
The Secret Manager tool operates on project-specific configuration settings stored in your user profile. To
use user secrets, define a UserSecretsId element within a PropertyGroup of the .csproj file. The value of
UserSecretsId is arbitrary, but is unique to the project. Developers typically generate a GUID for the
UserSecretsId .
<PropertyGroup>
<UserSecretsId>79a3edd0-2092-40a2-a04d-dcb46d5ca9ed</UserSecretsId>
</PropertyGroup>
<PropertyGroup>
<UserSecretsId>1242d6d6-9df3-4031-b031-d9b27d13c25a</UserSecretsId>
</PropertyGroup>
TIP
In Visual Studio, right-click the project in Solution Explorer, and select Manage User Secrets from the context
menu. This gesture adds a UserSecretsId element, populated with a GUID, to the .csproj file. Visual Studio opens
a secrets.json file in the text editor. Replace the contents of secrets.json with the key-value pairs to be stored. For
example:
{
"Movies": {
"ConnectionString": "Server=(localdb)\\mssqllocaldb;Database=Movie-
1;Trusted_Connection=True;MultipleActiveResultSets=true",
"ServiceApiKey": "12345"
}
}
The JSON structure is flattened after modifications via dotnet user-secrets remove or
dotnet user-secrets set . For example, running dotnet user-secrets remove "Movies:ConnectionString"
collapses the Movies object literal. The modified file resembles the following:
{
"Movies:ServiceApiKey": "12345"
}
Define an app secret consisting of a key and its value. The secret is associated with the project's
UserSecretsId value. For example, run the following command from the directory in which the .csproj file
exists:
dotnet user-secrets set "Movies:ServiceApiKey" "12345"
In the preceding example, the colon denotes that Movies is an object literal with a ServiceApiKey property.
The Secret Manager tool can be used from other directories too. Use the --project option to supply the
file system path at which the .csproj file exists. For example:
dotnet user-secrets set "Movies:ServiceApiKey" "12345" --project "C:\apps\WebApp1\src\WebApp1"
Set multiple secrets

A batch of secrets can be set by piping JSON to the set command. In the following example, the
input.json file's contents are piped to the set command.
Windows
macOS
Linux
Open a command shell, and execute the following command:
type .\input.json | dotnet user-secrets set
Access a secret
The ASP.NET Core Configuration API provides access to Secret Manager secrets. If your project targets
the .NET Framework, install the Microsoft.Extensions.Configuration.UserSecrets NuGet package.
In ASP.NET Core 2.0 or later, the user secrets configuration source is automatically added in development
mode when the project calls CreateDefaultBuilder to initialize a new instance of the host with
preconfigured defaults. CreateDefaultBuilder calls AddUserSecrets when the EnvironmentName is
Development:

When CreateDefaultBuilder isn't called during host construction, add the user secrets configuration source
with a call to AddUserSecrets in the Startup constructor:

{
optional: false,
{
}
}
The ASP.NET Core Configuration API provides access to Secret Manager secrets. Install the
Microsoft.Extensions.Configuration.UserSecrets NuGet package.
Add the user secrets configuration source with a call to AddUserSecrets in the Startup constructor:
{
optional: false,
{
}
}
User secrets can be retrieved via the Configuration API:

{
private string _moviesApiKey = null;

{
}

{
_moviesApiKey = Configuration["Movies:ServiceApiKey"];
}

{
var result = string.IsNullOrEmpty(_moviesApiKey) ? "Null" : "Not Null";
{
await context.Response.WriteAsync($"Secret is {result}");
});
}
}
{
private string _moviesApiKey = null;

{
optional: false,
{
}
}
public IConfigurationRoot Configuration { get; }

{
_moviesApiKey = Configuration["Movies:ServiceApiKey"];
}

{
var result = string.IsNullOrEmpty(_moviesApiKey) ? "Null" : "Not Null";
{
await context.Response.WriteAsync($"Secret is {result}");
});
}
}
Map secrets to a POCO

Mapping an entire object literal to a POCO (a simple .NET class with properties) is useful for aggregating
related properties.
Assume the app's secrets.json file contains the following two secrets:
{
"Movies:ConnectionString": "Server=(localdb)\\mssqllocaldb;Database=Movie-
}
To map the preceding secrets to a POCO, use the Configuration API's object graph binding feature. The
following code binds to a custom MovieSettings POCO and accesses the ServiceApiKey property value:
var moviesConfig = Configuration.GetSection("Movies")

.Get<MovieSettings>();
_moviesApiKey = moviesConfig.ServiceApiKey;
var moviesConfig = new MovieSettings();
Configuration.GetSection("Movies").Bind(moviesConfig);
_moviesApiKey = moviesConfig.ServiceApiKey;
The Movies:ConnectionString and Movies:ServiceApiKey secrets are mapped to the respective properties in
MovieSettings :
public class MovieSettings

{
public string ConnectionString { get; set; }
public string ServiceApiKey { get; set; }

}
String replacement with secrets

Storing passwords in plain text is insecure. For example, a database connection string stored in
appsettings.json may include a password for the specified user:
{
"Movies": "Server=(localdb)\\mssqllocaldb;Database=Movie-1;User
Id=johndoe;Password=pass123;MultipleActiveResultSets=true"
}
}
A more secure approach is to store the password as a secret. For example:
dotnet user-secrets set "DbPassword" "pass123"
Remove the Password key-value pair from the connection string in appsettings.json. For example:
{
"Movies": "Server=(localdb)\\mssqllocaldb;Database=Movie-1;User
Id=johndoe;MultipleActiveResultSets=true"
}
}
The secret's value can be set on a SqlConnectionStringBuilder object's Password property to complete the
connection string:
{
private string _connection = null;

{
}

{
var builder = new SqlConnectionStringBuilder(
Configuration.GetConnectionString("Movies"));
builder.Password = Configuration["DbPassword"];
_connection = builder.ConnectionString;
}

{
{
await context.Response.WriteAsync($"DB Connection: {_connection}");
});
}
}
{
private string _connection = null;

{
optional: false,
{
}
}

{
var builder = new SqlConnectionStringBuilder(
Configuration.GetConnectionString("Movies"));
builder.Password = Configuration["DbPassword"];
_connection = builder.ConnectionString;
}

{
{
await context.Response.WriteAsync($"DB Connection: {_connection}");
});
}
}
List the secrets

{
}
Run the following command from the directory in which the .csproj file exists:
dotnet user-secrets list
The following output appears:
Movies:ConnectionString = Server=(localdb)\mssqllocaldb;Database=Movie-
1;Trusted_Connection=True;MultipleActiveResultSets=true
Movies:ServiceApiKey = 12345
In the preceding example, a colon in the key names denotes the object hierarchy within secrets.json.
Remove a single secret

{
}
dotnet user-secrets remove "Movies:ConnectionString"
The app's secrets.json file was modified to remove the key-value pair associated with the
MoviesConnectionString key:
{
"Movies": {
"ServiceApiKey": "12345"
}
}
Running dotnet user-secrets list displays the following message:
Movies:ServiceApiKey = 12345
Remove all secrets

{
}
dotnet user-secrets clear
All user secrets for the app have been deleted from the secrets.json file:
{}
Running dotnet user-secrets list displays the following message:
No secrets configured for this application.

Azure Key Vault configuration provider in ASP.NET Core
Azure Key Vault configuration provider in ASP.NET
Core
By Luke Latham and Andrew Stanton-Nurse

This document explains how to use the Microsoft Azure Key Vault configuration provider to load app
configuration values from Azure Key Vault secrets. Azure Key Vault is a cloud-based service that helps you
safeguard cryptographic keys and secrets used by apps and services. Common scenarios include controlling
access to sensitive configuration data and meeting the requirement for FIPS 140-2 Level 2 validated Hardware
Security Modules (HSM's) when storing configuration data. This feature is available for apps that target
ASP.NET Core 1.1 or higher.
Package
To use the provider, add a reference to the Microsoft.Extensions.Configuration.AzureKeyVault package.
App configuration
You can explore the provider with the sample apps. Once you establish a key vault and create secrets in the
vault, the sample apps securely load the secret values into their configurations and display them in webpages.
The provider is added to the app's configuration with the AddAzureKeyVault extension. In the sample apps, the
extension uses three configuration values loaded from the appsettings.json file.
APP SETTING DESCRIPTION EXAMPLE
Vault Azure Key Vault name contosovault
ClientId Azure Active Directory App Id 627e911e-43cc-61d4-992e-

12db9c81b413
ClientSecret Azure Active Directory App Key g58K3dtg59o1Pa+e59v2Tx829w6VxT

B2yv9sv/101di=

{
var builtConfig = config.Build();
config.AddAzureKeyVault(
$"https://{builtConfig["Vault"]}.vault.azure.net/",
builtConfig["ClientId"],
builtConfig["ClientSecret"]);
})
Create key vault secrets and load configuration values (basic-sample)

1. Create a key vault and set up Azure Active Directory (Azure AD ) for the app following the guidance in
Get started with Azure Key Vault.
Add secrets to the key vault using the AzureRM Key Vault PowerShell Module available from the
PowerShell Gallery, the Azure Key Vault REST API, or the Azure Portal. Secrets are created as either
Manual or Certificate secrets. Certificate secrets are certificates for use by apps and services but are
not supported by the configuration provider. You should use the Manual option to create name-value
pair secrets for use with the configuration provider.
Simple secrets are created as name-value pairs. Azure Key Vault secret names are limited to
alphanumeric characters and dashes.
Hierarchical values (configuration sections) use -- (two dashes) as a separator in the sample.
Colons, which are normally used to delimit a section from a subkey in ASP.NET Core
configuration, aren't allowed in secret names. Therefore, two dashes are used and swapped for
a colon when the secrets are loaded into the app's configuration.
Create two Manual secrets with the following name-value pairs. The first secret is a simple
name and value, and the second secret creates a secret value with a section and subkey in the
secret name:
SecretName : secret_value_1
Section--SecretName : secret_value_2
Register the sample app with Azure Active Directory.
Authorize the app to access the key vault. When you use the Set-AzureRmKeyVaultAccessPolicy
PowerShell cmdlet to authorize the app to access the key vault, provide List and Get access to
secrets with -PermissionsToSecrets list,get .
2. Update the app's appsettings.json file with the values of Vault , ClientId , and ClientSecret .
3. Run the sample app, which obtains its configuration values from IConfigurationRoot with the same
name as the secret name.
Non-hierarchical values: The value for SecretName is obtained with config["SecretName"] .
Hierarchical values (sections): Use : (colon) notation or the GetSection extension method. Use
either of these approaches to obtain the configuration value:
config["Section:SecretName"]
config.GetSection("Section")["SecretName"]
When you run the app, a webpage shows the loaded secret values:
Create prefixed key vault secrets and load configuration values (key-
name-prefix-sample)
AddAzureKeyVault also provides an overload that accepts an implementation of IKeyVaultSecretManager , which
allows you to control how key vault secrets are converted into configuration keys. For example, you can
implement the interface to load secret values based on a prefix value you provide at app startup. This allows
you, for example, to load secrets based on the version of the app.
WARNING
Don't use prefixes on key vault secrets to place secrets for multiple apps into the same key vault or to place
environmental secrets (for example, development versus production secrets) into the same vault. We recommend that
different apps and development/production environments use separate key vaults to isolate app environments for the
highest level of security.
Using the second sample app, you create a secret in the key vault for 5000-AppSecret (periods aren't allowed in
key vault secret names) representing an app secret for version 5.0.0.0 of your app. For another version, 5.1.0.0,
you create a secret for 5100-AppSecret . Each app version loads its own secret value into its configuration as
AppSecret , stripping off the version as it loads the secret. The sample's implementation is shown below:

{
// The appVersion obtains the app version (5.0.0.0), which
// is set in the project file and obtained from the entry
// assembly. The versionPrefix holds the version without
// dot notation for the PrefixKeyVaultSecretManager.
var appVersion = Assembly.GetEntryAssembly().GetName().Version.ToString();
var versionPrefix = appVersion.Replace(".", string.Empty);
$"https://{builtConfig["Vault"]}.vault.azure.net/",
builtConfig["ClientSecret"],
new PrefixKeyVaultSecretManager(versionPrefix));
})
public class PrefixKeyVaultSecretManager : IKeyVaultSecretManager

{
private readonly string _prefix;
public PrefixKeyVaultSecretManager(string prefix)

{
_prefix = $"{prefix}-";
}
public bool Load(SecretItem secret)

{
// Load a vault secret when its secret name starts with the
// prefix. Other secrets won't be loaded.
return secret.Identifier.Name.StartsWith(_prefix);
}
public string GetKey(SecretBundle secret)

{
// Remove the prefix from the secret name and replace two
// dashes in any name with the KeyDelimiter, which is the
// delimiter used in configuration (usually a colon). Azure
// Key Vault doesn't allow a colon in secret names.
return secret.SecretIdentifier.Name
.Substring(_prefix.Length)
.Replace("--", ConfigurationPath.KeyDelimiter);
}
}
The Load method is called by a provider algorithm that iterates through the vault secrets to find the ones that
have the version prefix. When a version prefix is found with Load , the algorithm uses the GetKey method to
return the configuration name of the secret name. It strips off the version prefix from the secret's name and
returns the rest of the secret name for loading into the app's configuration name-value pairs.
When you implement this approach:
1. The key vault secrets are loaded.
2. The string secret for 5000-AppSecret is matched.
3. The version, 5000 (with the dash), is stripped off of the key name leaving AppSecret to load with the secret
value into the app's configuration.
NOTE
You can also provide your own KeyVaultClient implementation to AddAzureKeyVault . Supplying a custom client
allows you to share a single instance of the client between the configuration provider and other parts of your app.
1. Create a key vault and set up Azure Active Directory (Azure AD ) for the app following the guidance in
Get started with Azure Key Vault.
Add secrets to the key vault using the AzureRM Key Vault PowerShell Module available from the
PowerShell Gallery, the Azure Key Vault REST API, or the Azure Portal. Secrets are created as either
Manual or Certificate secrets. Certificate secrets are certificates for use by apps and services but are
not supported by the configuration provider. You should use the Manual option to create name-value
pair secrets for use with the configuration provider.
Hierarchical values (configuration sections) use -- (two dashes) as a separator.
Create two Manual secrets with the following name-value pairs:
5000-AppSecret : 5.0.0.0_secret_value
5100-AppSecret : 5.1.0.0_secret_value
Register the sample app with Azure Active Directory.
Authorize the app to access the key vault. When you use the Set-AzureRmKeyVaultAccessPolicy
PowerShell cmdlet to authorize the app to access the key vault, provide List and Get access to
secrets with -PermissionsToSecrets list,get .
2. Update the app's appsettings.json file with the values of Vault , ClientId , and ClientSecret .
3. Run the sample app, which obtains its configuration values from IConfigurationRoot with the same
name as the prefixed secret name. In this sample, the prefix is the app's version, which you provided to
the PrefixKeyVaultSecretManager when you added the Azure Key Vault configuration provider. The value
for AppSecret is obtained with config["AppSecret"] . The webpage generated by the app shows the
loaded value:
4. Change the version of the app assembly in the project file from 5.0.0.0 to 5.1.0.0 and run the app
again. This time, the secret value returned is 5.1.0.0_secret_value . The webpage generated by the app
shows the loaded value:
Control access to the ClientSecret
Use the Secret Manager tool to maintain the ClientSecret outside of your project source tree. With Secret
Manager, you associate app secrets with a specific project and share them across multiple projects.
When developing a .NET Framework app in an environment that supports certificates, you can authenticate to
Azure Key Vault with an X.509 certificate. The X.509 certificate's private key is managed by the OS. For more
information, see Authenticate with a Certificate instead of a Client Secret. Use the AddAzureKeyVault overload
that accepts an X509Certificate2 ( _env in the following example :
var store = new X509Store(StoreLocation.CurrentUser);

store.Open(OpenFlags.ReadOnly);
var cert = store.Certificates
.Find(X509FindType.FindByThumbprint,
config["CertificateThumbprint"], false);
builtConfig["Vault"],
cert.OfType<X509Certificate2>().Single(),
new EnvironmentSecretManager(context.HostingEnvironment.ApplicationName));
store.Close();
Reload secrets
Secrets are cached until IConfigurationRoot.Reload() is called. Expired, disabled, and updated secrets in the key
vault are not respected by the app until Reload is executed.
Configuration.Reload();
Disabled and expired secrets

Disabled and expired secrets throw a KeyVaultClientException . To prevent your app from throwing, replace
your app or update the disabled/expired secret.
Troubleshoot
When the app fails to load configuration using the provider, an error message is written to the ASP.NET Core
Logging infrastructure. The following conditions will prevent configuration from loading:
The app isn't configured correctly in Azure Active Directory.
The key vault doesn't exist in Azure Key Vault.
The app isn't authorized to access the key vault.
The access policy doesn't include Get and List permissions.
In the key vault, the configuration data (name-value pair) is incorrectly named, missing, disabled, or expired.
The app has the wrong key vault name ( Vault ), Azure AD App Id ( ClientId ), or Azure AD Key (
ClientSecret ).
The Azure AD Key ( ClientSecret ) is expired.
The configuration key (name) is incorrect in the app for the value you're trying to load.
Microsoft Azure: Key Vault
Microsoft Azure: Key Vault Documentation
How to generate and transfer HSM -protected keys for Azure Key Vault
KeyVaultClient Class
Prevent Cross-Site Request Forgery (XSRF/CSRF)
attacks in ASP.NET Core
By Steve Smith, Fiyaz Hasan, and Rick Anderson

Cross-site request forgery (also known as XSRF or CSRF, pronounced see-surf) is an attack against web-
hosted apps whereby a malicious web app can influence the interaction between a client browser and a
web app that trusts that browser. These attacks are possible because web browsers send some types of
authentication tokens automatically with every request to a website. This form of exploit is also known as
a one-click attack or session riding because the attack takes advantage of the user's previously
authenticated session.
An example of a CSRF attack:
1. A user signs into www.good-banking-site.com using forms authentication. The server authenticates
the user and issues a response that includes an authentication cookie. The site is vulnerable to
attack because it trusts any request that it receives with a valid authentication cookie.
2. The user visits a malicious site, www.bad-crook-site.com .
The malicious site, www.bad-crook-site.com , contains an HTML form similar to the following:
<h1>Congratulations! You're a Winner!</h1>

<form action="http://good-banking-site.com/api/account" method="post">
<input type="hidden" name="Transaction" value="withdraw">
<input type="hidden" name="Amount" value="1000000">
<input type="submit" value="Click to collect your prize!">
</form>
Notice that the form's action posts to the vulnerable site, not to the malicious site. This is the
"cross-site" part of CSRF.
3. The user selects the submit button. The browser makes the request and automatically includes the
authentication cookie for the requested domain, www.good-banking-site.com .
4. The request runs on the www.good-banking-site.com server with the user's authentication context
and can perform any action that an authenticated user is allowed to perform.
In addition to the scenario where the user selects the button to submit the form, the malicious site could:
Run a script that automatically submits the form.
Send the form submission as an AJAX request.
Hide the form using CSS.
These alternative scenarios don't require any action or input from the user other than initially visiting the
malicious site.
Using HTTPS doesn't prevent a CSRF attack. The malicious site can send an
https://www.good-banking-site.com/ request just as easily as it can send an insecure request.
Some attacks target endpoints that respond to GET requests, in which case an image tag can be used to
perform the action. This form of attack is common on forum sites that permit images but block JavaScript.
Apps that change state on GET requests, where variables or resources are altered, are vulnerable to
malicious attacks. GET requests that change state are insecure. A best practice is to never change
state on a GET request.
CSRF attacks are possible against web apps that use cookies for authentication because:
Browsers store cookies issued by a web app.
Stored cookies include session cookies for authenticated users.
Browsers send all of the cookies associated with a domain to the web app every request regardless of
how the request to app was generated within the browser.
However, CSRF attacks aren't limited to exploiting cookies. For example, Basic and Digest authentication
are also vulnerable. After a user signs in with Basic or Digest authentication, the browser automatically
sends the credentials until the session† ends.
†In this context, session refers to the client-side session during which the user is authenticated. It's
unrelated to server-side sessions or ASP.NET Core Session Middleware.
Users can guard against CSRF vulnerabilities by taking precautions:
Sign off of web apps when finished using them.
Clear browser cookies periodically.
However, CSRF vulnerabilities are fundamentally a problem with the web app, not the end user.
Authentication fundamentals
Cookie-based authentication is a popular form of authentication. Token-based authentication systems are
growing in popularity, especially for Single Page Applications (SPAs).
Cookie -based authentication
When a user authenticates using their username and password, they're issued a token, containing an
authentication ticket that can be used for authentication and authorization. The token is stored as a cookie
that accompanies every request the client makes. Generating and validating this cookie is performed by
the Cookie Authentication Middleware. The middleware serializes a user principal into an encrypted
cookie. On subsequent requests, the middleware validates the cookie, recreates the principal, and assigns
the principal to the User property of HttpContext.
Token-based authentication
When a user is authenticated, they're issued a token (not an antiforgery token). The token contains user
information in the form of claims or a reference token that points the app to user state maintained in the
app. When a user attempts to access a resource requiring authentication, the token is sent to the app with
an additional authorization header in form of Bearer token. This makes the app stateless. In each
subsequent request, the token is passed in the request for server-side validation. This token isn't
encrypted; it's encoded. On the server, the token is decoded to access its information. To send the token on
subsequent requests, store the token in the browser's local storage. Don't be concerned about CSRF
vulnerability if the token is stored in the browser's local storage. CSRF is a concern when the token is
stored in a cookie.
Multiple apps hosted at one domain
Shared hosting environments are vulnerable to session hijacking, login CSRF, and other attacks.
Although example1.contoso.net and example2.contoso.net are different hosts, there's an implicit trust
relationship between hosts under the *.contoso.net domain. This implicit trust relationship allows
potentially untrusted hosts to affect each other's cookies (the same-origin policies that govern AJAX
requests don't necessarily apply to HTTP cookies).
Attacks that exploit trusted cookies between apps hosted on the same domain can be prevented by not
sharing domains. When each app is hosted on its own domain, there is no implicit cookie trust relationship
to exploit.
ASP.NET Core antiforgery configuration

WARNING
ASP.NET Core implements antiforgery using ASP.NET Core Data Protection. The data protection stack must be
configured to work in a server farm. See Configuring data protection for more information.
In ASP.NET Core 2.0 or later, the FormTagHelper injects antiforgery tokens into HTML form elements.
The following markup in a Razor file automatically generates antiforgery tokens:
...
</form>
Similarily, IHtmlHelper.BeginForm generates antiforgery tokens by default if the form's method isn't GET.
The automatic generation of antiforgery tokens for HTML form elements happens when the <form> tag
contains the method="post" attribute and either of the following are true:
The action attribute is empty ( action="" ).
The action attribute isn't supplied ( <form method="post"> ).
Automatic generation of antiforgery tokens for HTML form elements can be disabled:
Explicitly disable antiforgery tokens with the asp-antiforgery attribute:
<form method="post" asp-antiforgery="false">

...
</form>
The form element is opted-out of Tag Helpers by using the Tag Helper ! opt-out symbol:
<!form method="post">
...
</!form>
Remove the FormTagHelper from the view. The FormTagHelper can be removed from a view by
adding the following directive to the Razor view:
@removeTagHelper Microsoft.AspNetCore.Mvc.TagHelpers.FormTagHelper,
Microsoft.AspNetCore.Mvc.TagHelpers
NOTE
Razor Pages are automatically protected from XSRF/CSRF. For more information, see XSRF/CSRF and Razor Pages.
The most common approach to defending against CSRF attacks is to use the Synchronizer Token Pattern
(STP ). STP is used when the user requests a page with form data:
1. The server sends a token associated with the current user's identity to the client.
2. The client sends back the token to the server for verification.
3. If the server receives a token that doesn't match the authenticated user's identity, the request is
rejected.
The token is unique and unpredictable. The token can also be used to ensure proper sequencing of a series
of requests (for example, ensuring the request sequence of: page 1 – page 2 – page 3). All of the forms in
ASP.NET Core MVC and Razor Pages templates generate antiforgery tokens. The following pair of view
examples generate antiforgery tokens:
<form asp-controller="Manage" asp-action="ChangePassword" method="post">

...
</form>
@using (Html.BeginForm("ChangePassword", "Manage"))

{
...
}
Explicitly add an antiforgery token to a <form> element without using Tag Helpers with the HTML helper
@Html.AntiForgeryToken:
<form action="/" method="post">

@Html.AntiForgeryToken()
</form>
In each of the preceding cases, ASP.NET Core adds a hidden form field similar to the following:
<input name="__RequestVerificationToken" type="hidden" value="CfDJ8NrAkS ... s2-m9Yw">
ASP.NET Core includes three filters for working with antiforgery tokens:
ValidateAntiForgeryToken
AutoValidateAntiforgeryToken
IgnoreAntiforgeryToken
Antiforgery options
Customize antiforgery options in Startup.ConfigureServices :
services.AddAntiforgery(options =>
{
options.CookieDomain = "contoso.com";
options.CookieName = "X-CSRF-TOKEN-COOKIENAME";
options.CookiePath = "Path";
options.FormFieldName = "AntiforgeryFieldname";
options.HeaderName = "X-CSRF-TOKEN-HEADERNAME";
options.RequireSsl = false;
options.SuppressXFrameOptionsHeader = false;
});
OPTION DESCRIPTION
Cookie Determines the settings used to create the antiforgery

cookies.
OPTION DESCRIPTION
CookieDomain The domain of the cookie. Defaults to null . This

property is obsolete and will be removed in a future
version. The recommended alternative is Cookie.Domain.
CookieName The name of the cookie. If not set, the system generates
a unique name beginning with the DefaultCookiePrefix
(".AspNetCore.Antiforgery."). This property is obsolete
and will be removed in a future version. The
recommended alternative is Cookie.Name.
CookiePath The path set on the cookie. This property is obsolete and
will be removed in a future version. The recommended
alternative is Cookie.Path.
FormFieldName The name of the hidden form field used by the

antiforgery system to render antiforgery tokens in views.
HeaderName The name of the header used by the antiforgery system.

If null , the system considers only form data.
RequireSsl Specifies whether SSL is required by the antiforgery

system. If true , non-SSL requests fail. Defaults to
false . This property is obsolete and will be removed in
a future version. The recommended alternative is to set
Cookie.SecurePolicy.
SuppressXFrameOptionsHeader Specifies whether to suppress generation of the

X-Frame-Options header. By default, the header is
generated with a value of "SAMEORIGIN". Defaults to
false .
For more information, see CookieAuthenticationOptions.
Configure antiforgery features with IAntiforgery

IAntiforgery provides the API to configure antiforgery features. IAntiforgery can be requested in the
Configure method of the Startup class. The following example uses middleware from the app's home
page to generate an antiforgery token and send it in the response as a cookie (using the default Angular
naming convention described later in this topic):
public void Configure(IApplicationBuilder app, IAntiforgery antiforgery)
{
app.Use(next => context =>
{
string path = context.Request.Path.Value;
if (
string.Equals(path, "/", StringComparison.OrdinalIgnoreCase) ||
string.Equals(path, "/index.html", StringComparison.OrdinalIgnoreCase))
{
// The request token can be sent as a JavaScript-readable cookie,
// and Angular uses it by default.
var tokens = antiforgery.GetAndStoreTokens(context);
context.Response.Cookies.Append("XSRF-TOKEN", tokens.RequestToken,
new CookieOptions() { HttpOnly = false });
}
return next(context);
});
}
Require antiforgery validation

ValidateAntiForgeryToken is an action filter that can be applied to an individual action, a controller, or
globally. Requests made to actions that have this filter applied are blocked unless the request includes a
valid antiforgery token.
[HttpPost]
public async Task<IActionResult> RemoveLogin(RemoveLoginViewModel account)
{
ManageMessageId? message = ManageMessageId.Error;
var user = await GetCurrentUserAsync();
if (user != null)
{
var result =
await _userManager.RemoveLoginAsync(
user, account.LoginProvider, account.ProviderKey);
{
message = ManageMessageId.RemoveLoginSuccess;
}
}
return RedirectToAction(nameof(ManageLogins), new { Message = message });

}
The ValidateAntiForgeryToken attribute requires a token for requests to the action methods it decorates,
including HTTP GET requests. If the ValidateAntiForgeryToken attribute is applied across the app's
controllers, it can be overridden with the IgnoreAntiforgeryToken attribute.
NOTE
ASP.NET Core doesn't support adding antiforgery tokens to GET requests automatically.
Automatically validate antiforgery tokens for unsafe HTTP methods only

ASP.NET Core apps don't generate antiforgery tokens for safe HTTP methods (GET, HEAD, OPTIONS,
and TRACE ). Instead of broadly applying the ValidateAntiForgeryToken attribute and then overriding it
with IgnoreAntiforgeryToken attributes, the AutoValidateAntiforgeryToken attribute can be used. This
attribute works identically to the ValidateAntiForgeryToken attribute, except that it doesn't require tokens
for requests made using the following HTTP methods:
GET
HEAD
OPTIONS
TRACE
We recommend use of AutoValidateAntiforgeryToken broadly for non-API scenarios. This ensures POST
actions are protected by default. The alternative is to ignore antiforgery tokens by default, unless
ValidateAntiForgeryToken is applied to individual action methods. It's more likely in this scenario for a
POST action method to be left unprotected by mistake, leaving the app vulnerable to CSRF attacks. All
POSTs should send the antiforgery token.
APIs don't have an automatic mechanism for sending the non-cookie part of the token. The
implementation probably depends on the client code implementation. Some examples are shown below:
Class-level example:
[Authorize]
[AutoValidateAntiforgeryToken]
public class ManageController : Controller
{
Global example:
options.Filters.Add(new AutoValidateAntiforgeryTokenAttribute()));
Override global or controller antiforgery attributes

The IgnoreAntiforgeryToken filter is used to eliminate the need for an antiforgery token for a given action
(or controller). When applied, this filter overrides ValidateAntiForgeryToken and
AutoValidateAntiforgeryToken filters specified at a higher level (globally or on a controller ).
[Authorize]
[AutoValidateAntiforgeryToken]
public class ManageController : Controller
{
[HttpPost]
[IgnoreAntiforgeryToken]
public async Task<IActionResult> DoSomethingSafe(SomeViewModel model)
{
// no antiforgery token required
}
}
Refresh tokens after authentication

Tokens should be refreshed after the user is authenticated by redirecting the user to a view or Razor Pages
page.
JavaScript, AJAX, and SPAs

In traditional HTML -based apps, antiforgery tokens are passed to the server using hidden form fields. In
modern JavaScript-based apps and SPAs, many requests are made programmatically. These AJAX
requests may use other techniques (such as request headers or cookies) to send the token.
If cookies are used to store authentication tokens and to authenticate API requests on the server, CSRF is
a potential problem. If local storage is used to store the token, CSRF vulnerability might be mitigated
because values from local storage aren't sent automatically to the server with every request. Thus, using
local storage to store the antiforgery token on the client and sending the token as a request header is a
recommended approach.
JavaScript
Using JavaScript with views, the token can be created using a service from within the view. Inject the
Microsoft.AspNetCore.Antiforgery.IAntiforgery service into the view and call GetAndStoreTokens:
@{
ViewData["Title"] = "AJAX Demo";
}
@inject Microsoft.AspNetCore.Antiforgery.IAntiforgery Xsrf
@functions{
public string GetAntiXsrfRequestToken()
{
return Xsrf.GetAndStoreTokens(Context).RequestToken;
}
}
<input type="hidden" id="RequestVerificationToken"

name="RequestVerificationToken" value="@GetAntiXsrfRequestToken()">
<div class="row">
<p><input type="button" id="antiforgery" value="Antiforgery"></p>
<script>
var xhttp = new XMLHttpRequest();
xhttp.onreadystatechange = function() {
if (xhttp.readyState == XMLHttpRequest.DONE) {
if (xhttp.status == 200) {
alert(xhttp.responseText);
} else {
alert('There was an error processing the AJAX request.');
}
}
};
document.addEventListener('DOMContentLoaded', function() {
document.getElementById("antiforgery").onclick = function () {
xhttp.open('POST', '@Url.Action("Antiforgery", "Home")', true);
xhttp.setRequestHeader("RequestVerificationToken",
document.getElementById('RequestVerificationToken').value);
xhttp.send();
}
});
</script>
</div>
This approach eliminates the need to deal directly with setting cookies from the server or reading them
from the client.
The preceding example uses JavaScript to read the hidden field value for the AJAX POST header.
JavaScript can also access tokens in cookies and use the cookie's contents to create a header with the
token's value.
context.Response.Cookies.Append("CSRF-TOKEN", tokens.RequestToken,
new Microsoft.AspNetCore.Http.CookieOptions { HttpOnly = false });
Assuming the script requests to send the token in a header called X-CSRF-TOKEN , configure the antiforgery
service to look for the X-CSRF-TOKEN header:
services.AddAntiforgery(options => options.HeaderName = "X-CSRF-TOKEN");
The following example uses JavaScript to make an AJAX request with the appropriate header:
function getCookie(cname) {
var name = cname + "=";
var decodedCookie = decodeURIComponent(document.cookie);
var ca = decodedCookie.split(';');
for(var i = 0; i <ca.length; i++) {
var c = ca[i];
while (c.charAt(0) == ' ') {
c = c.substring(1);
}
if (c.indexOf(name) == 0) {
return c.substring(name.length, c.length);
}
}
return "";
}
var csrfToken = getCookie("CSRF-TOKEN");
var xhttp = new XMLHttpRequest();

xhttp.onreadystatechange = function() {
if (xhttp.readyState == XMLHttpRequest.DONE) {
if (xhttp.status == 200) {
alert(xhttp.responseText);
} else {
alert('There was an error processing the AJAX request.');
}
}
};
xhttp.open('POST', '/api/password/changepassword', true);
xhttp.setRequestHeader("Content-type", "application/json");
xhttp.setRequestHeader("X-CSRF-TOKEN", csrfToken);
xhttp.send(JSON.stringify({ "newPassword": "ReallySecurePassword999$$$" }));
AngularJS
AngularJS uses a convention to address CSRF. If the server sends a cookie with the name XSRF-TOKEN , the
AngularJS $http service adds the cookie value to a header when it sends a request to the server. This
process is automatic. The header doesn't need to be set explicitly. The header name is X-XSRF-TOKEN . The
server should detect this header and validate its contents.
For ASP.NET Core API work with this convention:
Configure your app to provide a token in a cookie called XSRF-TOKEN .
Configure the antiforgery service to look for a header named X-XSRF-TOKEN .
services.AddAntiforgery(options => options.HeaderName = "X-XSRF-TOKEN");

Extend antiforgery
The IAntiForgeryAdditionalDataProvider type allows developers to extend the behavior of the anti-CSRF
system by round-tripping additional data in each token. The GetAdditionalData method is called each time
a field token is generated, and the return value is embedded within the generated token. An implementer
could return a timestamp, a nonce, or any other value and then call ValidateAdditionalData to validate this
data when the token is validated. The client's username is already embedded in the generated tokens, so
there's no need to include this information. If a token includes supplemental data but no
IAntiForgeryAdditionalDataProvider is configured, the supplemental data isn't validated.
CSRF on Open Web Application Security Project (OWASP ).
Prevent open redirect attacks in ASP.NET Core
A web app that redirects to a URL that's specified via the request such as the querystring or form data can
potentially be tampered with to redirect users to an external, malicious URL. This tampering is called an open
redirection attack.
Whenever your application logic redirects to a specified URL, you must verify that the redirection URL hasn't been
tampered with. ASP.NET Core has built-in functionality to help protect apps from open redirect (also known as
open redirection) attacks.
What is an open redirect attack?

Web applications frequently redirect users to a login page when they access resources that require authentication.
The redirection typically includes a returnUrl querystring parameter so that the user can be returned to the
originally requested URL after they have successfully logged in. After the user authenticates, they're redirected to
the URL they had originally requested.
Because the destination URL is specified in the querystring of the request, a malicious user could tamper with the
querystring. A tampered querystring could allow the site to redirect the user to an external, malicious site. This
technique is called an open redirect (or redirection) attack.
An example attack
A malicious user can develop an attack intended to allow the malicious user access to a user's credentials or
sensitive information. To begin the attack, the malicious user convinces the user to click a link to your site's login
page with a returnUrl querystring value added to the URL. For example, consider an app at contoso.com that
includes a login page at http://contoso.com/Account/LogOn?returnUrl=/Home/About . The attack follows these steps:
1. The user clicks a malicious link to
http://contoso.com/Account/LogOn?returnUrl=http://contoso1.com/Account/LogOn (the second URL is
"contoso1.com", not "contoso.com").
2. The user logs in successfully.
3. The user is redirected (by the site) to http://contoso1.com/Account/LogOn (a malicious site that looks exactly like
real site).
4. The user logs in again (giving malicious site their credentials) and is redirected back to the real site.
The user likely believes that their first attempt to log in failed and that their second attempt is successful. The user
most likely remains unaware that their credentials are compromised.
In addition to login pages, some sites provide redirect pages or endpoints. Imagine your app has a page with an
open redirect, /Home/Redirect . An attacker could create, for example, a link in an email that goes to
[yoursite]/Home/Redirect?url=http://phishingsite.com/Home/Login . A typical user will look at the URL and see it
begins with your site name. Trusting that, they will click the link. The open redirect would then send the user to the
phishing site, which looks identical to yours, and the user would likely login to what they believe is your site.
Protecting against open redirect attacks

When developing web applications, treat all user-provided data as untrustworthy. If your application has
functionality that redirects the user based on the contents of the URL, ensure that such redirects are only done
locally within your app (or to a known URL, not any URL that may be supplied in the querystring).
LocalRedirect
Use the LocalRedirect helper method from the base Controller class:
public IActionResult SomeAction(string redirectUrl)

{
return LocalRedirect(redirectUrl);
}
LocalRedirect will throw an exception if a non-local URL is specified. Otherwise, it behaves just like the Redirect
method.
IsLocalUrl
Use the IsLocalUrl method to test URLs before redirecting:
The following example shows how to check whether a URL is local before redirecting.
private IActionResult RedirectToLocal(string returnUrl)

{
if (Url.IsLocalUrl(returnUrl))
{
return Redirect(returnUrl);
}
else
{
}
}
The IsLocalUrl method protects users from being inadvertently redirected to a malicious site. You can log the
details of the URL that was provided when a non-local URL is supplied in a situation where you expected a local
URL. Logging redirect URLs may help in diagnosing redirection attacks.
Prevent Cross-Site Scripting (XSS) in ASP.NET Core
By Rick Anderson
Cross-Site Scripting (XSS ) is a security vulnerability which enables an attacker to place client side scripts (usually
JavaScript) into web pages. When other users load affected pages the attackers scripts will run, enabling the
attacker to steal cookies and session tokens, change the contents of the web page through DOM manipulation or
redirect the browser to another page. XSS vulnerabilities generally occur when an application takes user input and
outputs it in a page without validating, encoding or escaping it.
Protecting your application against XSS

At a basic level XSS works by tricking your application into inserting a <script> tag into your rendered page, or
by inserting an On* event into an element. Developers should use the following prevention steps to avoid
introducing XSS into their application.
1. Never put untrusted data into your HTML input, unless you follow the rest of the steps below. Untrusted
data is any data that may be controlled by an attacker, HTML form inputs, query strings, HTTP headers,
even data sourced from a database as an attacker may be able to breach your database even if they cannot
breach your application.
2. Before putting untrusted data inside an HTML element ensure it's HTML encoded. HTML encoding takes
characters such as < and changes them into a safe form like <
3. Before putting untrusted data into an HTML attribute ensure it's HTML attribute encoded. HTML attribute
encoding is a superset of HTML encoding and encodes additional characters such as " and '.
4. Before putting untrusted data into JavaScript place the data in an HTML element whose contents you
retrieve at runtime. If this isn't possible then ensure the data is JavaScript encoded. JavaScript encoding
takes dangerous characters for JavaScript and replaces them with their hex, for example < would be
encoded as \u003C .
5. Before putting untrusted data into a URL query string ensure it's URL encoded.
HTML Encoding using Razor

The Razor engine used in MVC automatically encodes all output sourced from variables, unless you work really
hard to prevent it doing so. It uses HTML Attribute encoding rules whenever you use the @ directive. As HTML
attribute encoding is a superset of HTML encoding this means you don't have to concern yourself with whether
you should use HTML encoding or HTML attribute encoding. You must ensure that you only use @ in an HTML
context, not when attempting to insert untrusted input directly into JavaScript. Tag helpers will also encode input
you use in tag parameters.
Take the following Razor view;
@{
var untrustedInput = "<\"123\">";
}
@untrustedInput
This view outputs the contents of the untrustedInput variable. This variable includes some characters which are
used in XSS attacks, namely <, " and >. Examining the source shows the rendered output encoded as:
<"123">
WARNING
ASP.NET Core MVC provides an HtmlString class which isn't automatically encoded upon output. This should never be
used in combination with untrusted input as this will expose an XSS vulnerability.
Javascript Encoding using Razor

There may be times you want to insert a value into JavaScript to process in your view. There are two ways to do
this. The safest way to insert values is to place the value in a data attribute of a tag and retrieve it in your
JavaScript. For example:
@{
}
<div
id="injectedData"
data-untrustedinput="@untrustedInput" />
<script>
var injectedData = document.getElementById("injectedData");
// All clients
var clientSideUntrustedInputOldStyle =
injectedData.getAttribute("data-untrustedinput");
// HTML 5 clients only

var clientSideUntrustedInputHtml5 =
injectedData.dataset.untrustedinput;
document.write(clientSideUntrustedInputOldStyle);
document.write("<br />")
document.write(clientSideUntrustedInputHtml5);
</script>
This will produce the following HTML
<div
id="injectedData"
data-untrustedinput="<"123">" />
<script>
var injectedData = document.getElementById("injectedData");
var clientSideUntrustedInputOldStyle =
injectedData.getAttribute("data-untrustedinput");
var clientSideUntrustedInputHtml5 =
injectedData.dataset.untrustedinput;
document.write(clientSideUntrustedInputOldStyle);
document.write("<br />")
document.write(clientSideUntrustedInputHtml5);
</script>
Which, when it runs, will render the following;
<"123">
<"123">
You can also call the JavaScript encoder directly,
@using System.Text.Encodings.Web;
@inject JavaScriptEncoder encoder;
@{
}
<script>
document.write("@encoder.Encode(untrustedInput)");
</script>
This will render in the browser as follows;
<script>
document.write("\u003C\u0022123\u0022\u003E");
</script>
WARNING
Don't concatenate untrusted input in JavaScript to create DOM elements. You should use createElement() and assign
property values appropriately such as node.TextContent= , or use element.SetAttribute() / element[attribute]=
otherwise you expose yourself to DOM-based XSS.
Accessing encoders in code

The HTML, JavaScript and URL encoders are available to your code in two ways, you can inject them via
dependency injection or you can use the default encoders contained in the System.Text.Encodings.Web namespace.
If you use the default encoders then any you applied to character ranges to be treated as safe won't take effect -
the default encoders use the safest encoding rules possible.
To use the configurable encoders via DI your constructors should take an HtmlEncoder, JavaScriptEncoder and
UrlEncoder parameter as appropriate. For example;

{
HtmlEncoder _htmlEncoder;
JavaScriptEncoder _javaScriptEncoder;
UrlEncoder _urlEncoder;
public HomeController(HtmlEncoder htmlEncoder,

JavaScriptEncoder javascriptEncoder,
UrlEncoder urlEncoder)
{
_htmlEncoder = htmlEncoder;
_javaScriptEncoder = javascriptEncoder;
_urlEncoder = urlEncoder;
}
}
Encoding URL Parameters
If you want to build a URL query string with untrusted input as a value use the UrlEncoder to encode the value.
For example,
var example = "\"Quoted Value with spaces and &\"";

var encodedValue = _urlEncoder.Encode(example);
After encoding the encodedValue variable will contain %22Quoted%20Value%20with%20spaces%20and%20%26%22 . Spaces,

quotes, punctuation and other unsafe characters will be percent encoded to their hexadecimal value, for example a
space character will become %20.
WARNING
Don't use untrusted input as part of a URL path. Always pass untrusted input as a query string value.
Customizing the Encoders

By default encoders use a safe list limited to the Basic Latin Unicode range and encode all characters outside of
that range as their character code equivalents. This behavior also affects Razor TagHelper and HtmlHelper
rendering as it will use the encoders to output your strings.
The reasoning behind this is to protect against unknown or future browser bugs (previous browser bugs have
tripped up parsing based on the processing of non-English characters). If your web site makes heavy use of non-
Latin characters, such as Chinese, Cyrillic or others this is probably not the behavior you want.
You can customize the encoder safe lists to include Unicode ranges appropriate to your application during startup,
in ConfigureServices() .
For example, using the default configuration you might use a Razor HtmlHelper like so;
<p>This link text is in Chinese: @Html.ActionLink("汉语/漢語", "Index")</p>
When you view the source of the web page you will see it has been rendered as follows, with the Chinese text
encoded;
<p>This link text is in Chinese: <a href="/">汉语/漢語</a></p>
To widen the characters treated as safe by the encoder you would insert the following line into the
ConfigureServices() method in startup.cs ;
services.AddSingleton<HtmlEncoder>(
HtmlEncoder.Create(allowedRanges: new[] { UnicodeRanges.BasicLatin,
UnicodeRanges.CjkUnifiedIdeographs }));
This example widens the safe list to include the Unicode Range CjkUnifiedIdeographs. The rendered output would
now become
<p>This link text is in Chinese: <a href="/">汉语/漢語</a></p>
Safe list ranges are specified as Unicode code charts, not languages. The Unicode standard has a list of code
charts you can use to find the chart containing your characters. Each encoder, Html, JavaScript and Url, must be
configured separately.
NOTE
Customization of the safe list only affects encoders sourced via DI. If you directly access an encoder via
System.Text.Encodings.Web.*Encoder.Default then the default, Basic Latin only safelist will be used.
Where should encoding take place?

The general accepted practice is that encoding takes place at the point of output and encoded values should never
be stored in a database. Encoding at the point of output allows you to change the use of data, for example, from
HTML to a query string value. It also enables you to easily search your data without having to encode values
before searching and allows you to take advantage of any changes or bug fixes made to encoders.
Validation as an XSS prevention technique

Validation can be a useful tool in limiting XSS attacks. For example, a numeric string containing only the
characters 0-9 won't trigger an XSS attack. Validation becomes more complicated should you wish to accept
HTML in user input - parsing HTML input is difficult, if not impossible. MarkDown and other text formats would
be a safer option for rich input. You should never rely on validation alone. Always encode untrusted input before
output, no matter what validation you have performed.
Enable Cross-Origin Requests (CORS) in ASP.NET
Core
By Mike Wasson, Shayne Boyer, and Tom Dykstra

Browser security prevents a web page from making requests to a different domain than the one that served the
web page. This restriction is called the same-origin policy. The same-origin policy prevents a malicious site from
reading sensitive data from another site. Sometimes, you might want to allow other sites make cross-origin
requests to your app.
Cross Origin Resource Sharing (CORS ) is a W3C standard that allows a server to relax the same-origin policy.
Using CORS, a server can explicitly allow some cross-origin requests while rejecting others. CORS is safer and
more flexible than earlier techniques, such as JSONP. This topic shows how to enable CORS in an ASP.NET
Core app.
Same origin
Two URLs have the same origin if they have identical schemes, hosts, and ports ( RFC 6454).
These two URLs have the same origin:
https://example.com/foo.html
https://example.com/bar.html
These URLs have different origins than the previous two URLs:
https://example.net – Different domain
https://www.example.com/foo.html – Different subdomain
http://example.com/foo.html – Different scheme
https://example.com:9000/foo.html – Different port
NOTE
Internet Explorer doesn't consider the port when comparing origins.
Register CORS services

Microsoft.AspNetCore.Cors package.
Microsoft.AspNetCore.Cors package.
Add a package reference to the Microsoft.AspNetCore.Cors package.
Call AddCors in Startup.ConfigureServices to add CORS services to the app's service container:
{
services.AddCors();
}
Enable CORS
After registering CORS services, use either of the following approaches to enable CORS in an ASP.NET Core
app:
CORS Middleware – Apply CORS policies globally to the app via middleware.
CORS in MVC – Apply CORS policies per action or per controller. CORS Middleware isn't used.
Enable CORS with CORS Middleware
CORS Middleware handles cross-origin requests to the app. To enable CORS Middleware in the request
processing pipeline, call the UseCors extension method in Startup.Configure .
CORS Middleware must precede any defined endpoints in your app where you want to support cross-origin
requests (for example, before the call to UseMvc for MVC/Razor Pages Middleware).
A cross-origin policy can be specified when adding the CORS Middleware using the CorsPolicyBuilder class.
There are two approaches for defining a CORS policy:
Call UseCors with a lambda:

{
{
}
// Shows UseCors with CorsPolicyBuilder.

app.UseCors(builder =>
builder.WithOrigins("http://example.com"));

{
});
The lambda takes a CorsPolicyBuilder object. Configuration options, such as WithOrigins , are described
later in this topic. In the preceding example, the policy allows cross-origin requests from
https://example.com and no other origins.
The URL must be specified without a trailing slash ( / ). If the URL terminates with / , the comparison
returns false and no header is returned.
CorsPolicyBuilder has a fluent API, so you can chain method calls:
app.UseCors(builder =>
.AllowAnyHeader()
);
Define one or more named CORS policies and select the policy by name at runtime. The following
example adds a user-defined CORS policy named AllowSpecificOrigin. To select the policy, pass the name
to UseCors :

{
services.AddCors(options =>
{
options.AddPolicy("AllowSpecificOrigin",
builder => builder.WithOrigins("http://example.com"));
});
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env,

{
{
}
// Shows UseCors with named policy.

app.UseCors("AllowSpecificOrigin");

{
});
}
Enable CORS in MVC

You can alternatively use MVC to apply specific CORS policies per action or per controller. When using MVC to
enable CORS, the registered CORS services are used. The CORS Middleware isn't used.
Per action
To specify a CORS policy for a specific action, add the [EnableCors] attribute to the action. Specify the policy
name.
[HttpGet]
[EnableCors("AllowSpecificOrigin")]
public IEnumerable<string> Get()
{
return new string[] { "value1", "value2" };
}
Per controller
To specify the CORS policy for a specific controller, add the [EnableCors] attribute to the controller class. Specify
the policy name.
[EnableCors("AllowSpecificOrigin")]
public class ValuesController : ControllerBase
The precedence order is:

1. action
2. controller
Disable CORS
To disable CORS for a controller or action, use the [DisableCors] attribute:
[HttpGet("{id}")]
[DisableCors]
public string Get(int id)
{
return "value";
}
CORS policy options

This section describes the various options that you can set in a CORS policy.
Set the allowed origins
Set the allowed HTTP methods
Set the allowed request headers
Set the exposed response headers
Credentials in cross-origin requests
Set the preflight expiration time
For some options, it may be helpful to read the How CORS works section first.
Set the allowed origins
To allow one or more specific origins, call WithOrigins:
options.AddPolicy("AllowSpecificOrigins",
builder =>
{
builder.WithOrigins("http://example.com", "http://www.contoso.com");
});
To allow all origins, call AllowAnyOrigin:
options.AddPolicy("AllowAllOrigins",
builder =>
{
builder.AllowAnyOrigin();
});
Consider carefully before allowing requests from any origin. Allowing requests from any origin means that any
website can make cross-origin requests to your app.
This setting affects preflight requests and the Access-Control-Allow -Origin header (described later in this topic).
Set the allowed HTTP methods
To allow all HTTP methods, call AllowAnyMethod:
options.AddPolicy("AllowAllMethods",
builder =>
{
.AllowAnyMethod();
});
This setting affects preflight requests and the Access-Control-Allow -Methods header (described later in this
topic).
Set the allowed request headers
To allow specific headers to be sent in a CORS request, called author request headers, call WithHeaders and
specify the allowed headers:
options.AddPolicy("AllowHeaders",
builder =>
{
.WithHeaders(HeaderNames.ContentType, "x-custom-header");
});
To allow all author request headers, call AllowAnyHeader:
options.AddPolicy("AllowAllHeaders",
builder =>
{
.AllowAnyHeader();
});
This setting affects preflight requests and the Access-Control-Request-Headers header (described later in this
topic).
A CORS Middleware policy match to specific headers specified by WithHeaders is only possible when the
headers sent in Access-Control-Request-Headers exactly match the headers stated in WithHeaders .
For instance, consider an app configured as follows:
app.UseCors(policy => policy.WithHeaders(HeaderNames.CacheControl));
CORS Middleware declines a preflight request with the following request header because Content-Language
(HeaderNames.ContentLanguage) isn't listed in WithHeaders :
Access-Control-Request-Headers: Cache-Control, Content-Language
The app returns a 200 OK response but doesn't send the CORS headers back. Therefore, the browser doesn't
attempt the cross-origin request.
CORS Middleware always allows four headers in the Access-Control-Request-Headers to be sent regardless of
the values configured in CorsPolicy.Headers. This list of headers includes:
Accept
Accept-Language
Content-Language
Origin
For instance, consider an app configured as follows:
app.UseCors(policy => policy.WithHeaders(HeaderNames.CacheControl));
CORS Middleware responds successfully to a preflight request with the following request header because
Content-Language is always whitelisted:
Access-Control-Request-Headers: Cache-Control, Content-Language
Set the exposed response headers

By default, the browser doesn't expose all of the response headers to the app. For more information, see W3C
Cross-Origin Resource Sharing (Terminology): Simple Response Header.
The response headers that are available by default are:
Cache-Control
Content-Language
Content-Type
Expires
Last-Modified
Pragma
The CORS specification calls these headers simple response headers. To make other headers available to the app,
call WithExposedHeaders:
options.AddPolicy("ExposeResponseHeaders",
builder =>
{
.WithExposedHeaders("x-custom-header");
});
Credentials in cross-origin requests

Credentials require special handling in a CORS request. By default, the browser doesn't send credentials with a
cross-origin request. Credentials include cookies and HTTP authentication schemes. To send credentials with a
cross-origin request, the client must set XMLHttpRequest.withCredentials to true .
Using XMLHttpRequest directly:
var xhr = new XMLHttpRequest();

xhr.open('get', 'https://www.example.com/api/test');
xhr.withCredentials = true;
In jQuery:
$.ajax({
type: 'get',
url: 'https://www.example.com/home',
xhrFields: {
withCredentials: true
}
In addition, the server must allow the credentials. To allow cross-origin credentials, call AllowCredentials:
options.AddPolicy("AllowCredentials",
builder =>
{
});
The HTTP response includes an Access-Control-Allow-Credentials header, which tells the browser that the
server allows credentials for a cross-origin request.
If the browser sends credentials but the response doesn't include a valid Access-Control-Allow-Credentials
header, the browser doesn't expose the response to the app, and the cross-origin request fails.
Be careful when allowing cross-origin credentials. A website at another domain can send a signed-in user's
credentials to the app on the user's behalf without the user's knowledge.
The CORS specification also states that setting origins to "*" (all origins) is invalid if the
Access-Control-Allow-Credentials header is present.
Preflight requests
For some CORS requests, the browser sends an additional request before making the actual request. This
request is called a preflight request. The browser can skip the preflight request if the following conditions are
true:
The request method is GET, HEAD, or POST.
The app doesn't set request headers other than Accept , Accept-Language , Content-Language , Content-Type ,
or Last-Event-ID .
The Content-Type header, if set, has one of the one of the following values:
application/x-www-form-urlencoded
multipart/form-data
text/plain
The rule on request headers set for the client request applies to headers that the app sets by calling
setRequestHeader on the XMLHttpRequest object. The CORS specification calls these headers author request
headers. The rule doesn't apply to headers the browser can set, such as User-Agent , Host , or Content-Length .
The following is an example of a preflight request:
OPTIONS https://myservice.azurewebsites.net/api/test HTTP/1.1

Accept: */*
Origin: https://myclient.azurewebsites.net
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: accept, x-my-custom-header
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; WOW64; Trident/6.0)
Host: myservice.azurewebsites.net
Content-Length: 0
The pre-flight request uses the HTTP OPTIONS method. It includes two special headers:
Access-Control-Request-Method : The HTTP method that will be used for the actual request.
Access-Control-Request-Headers : A list of request headers that the app sets on the actual request. As stated
earlier, this doesn't include headers that the browser sets, such as User-Agent .
A CORS preflight request might include an Access-Control-Request-Headers header, which indicates to the server
the headers that are sent with the actual request.
To allow specific headers, call WithHeaders:
options.AddPolicy("AllowHeaders",
builder =>
{
.WithHeaders(HeaderNames.ContentType, "x-custom-header");
});
To allow all author request headers, call AllowAnyHeader:
options.AddPolicy("AllowAllHeaders",
builder =>
{
.AllowAnyHeader();
});
Browsers aren't entirely consistent in how they set Access-Control-Request-Headers . If you set headers to
anything other than "*" (or use AllowAnyHeader), you should include at least Accept , Content-Type , and
Origin , plus any custom headers that you want to support.
The following is an example response to the preflight request (assuming that the server allows the request):
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 0
Access-Control-Allow-Origin: https://myclient.azurewebsites.net
Access-Control-Allow-Headers: x-my-custom-header
Access-Control-Allow-Methods: PUT
Date: Wed, 20 May 2015 06:33:22 GMT
The response includes an Access-Control-Allow-Methods header that lists the allowed methods and optionally an
Access-Control-Allow-Headers header, which lists the allowed headers. If the preflight request succeeds, the
browser sends the actual request.
If the preflight request is denied, the app returns a 200 OK response but doesn't send the CORS headers back.
Therefore, the browser doesn't attempt the cross-origin request.
Set the preflight expiration time
The Access-Control-Max-Age header specifies how long the response to the preflight request can be cached. To
set this header, call SetPreflightMaxAge:
options.AddPolicy("SetPreflightExpiration",
builder =>
{
.SetPreflightMaxAge(TimeSpan.FromSeconds(2520));
});
How CORS works

This section describes what happens in a CORS request at the level of the HTTP messages. It's important to
understand how CORS works so that the CORS policy can be configured correctly and debugged when
unexpected behaviors occur.
The CORS specification introduces several new HTTP headers that enable cross-origin requests. If a browser
supports CORS, it sets these headers automatically for cross-origin requests. Custom JavaScript code isn't
required to enable CORS.
The following is an example of a cross-origin request. The Origin header provides the domain of the site that's
making the request:
GET https://myservice.azurewebsites.net/api/test HTTP/1.1

Referer: https://myclient.azurewebsites.net/
Accept: */*
Accept-Language: en-US
Origin: https://myclient.azurewebsites.net
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; WOW64; Trident/6.0)
Host: myservice.azurewebsites.net
If the server allows the request, it sets the Access-Control-Allow-Origin header in the response. The value of this
header either matches the Origin header from the request or is the wildcard value "*" , meaning that any
origin is allowed:
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: text/plain; charset=utf-8
Access-Control-Allow-Origin: https://myclient.azurewebsites.net
Date: Wed, 20 May 2015 06:27:30 GMT
Content-Length: 12
Test message
If the response doesn't include the Access-Control-Allow-Origin header, the cross-origin request fails.
Specifically, the browser disallows the request. Even if the server returns a successful response, the browser
doesn't make the response available to the client app.
Cross-Origin Resource Sharing (CORS )
Share cookies among apps with ASP.NET and
ASP.NET Core
By Rick Anderson and Luke Latham

Websites often consist of individual web apps working together. To provide a single sign-on (SSO ) experience, web
apps within a site must share authentication cookies. To support this scenario, the data protection stack allows
sharing Katana cookie authentication and ASP.NET Core cookie authentication tickets.
The sample illustrates cookie sharing across three apps that use cookie authentication:
ASP.NET Core 2.0 Razor Pages app without using ASP.NET Core Identity
ASP.NET Core 2.0 MVC app with ASP.NET Core Identity
ASP.NET Framework 4.6.1 MVC app with ASP.NET Identity
In the examples that follow:
The authentication cookie name is set to a common value of .AspNet.SharedCookie .
The AuthenticationType is set to Identity.Application either explicitly or by default.
A common app name is used to enable the data protection system to share data protection keys (
SharedCookieApp ).
Identity.Application is used as the authentication scheme. Whatever scheme is used, it must be used
consistently within and across the shared cookie apps either as the default scheme or by explicitly setting it. The
scheme is used when encrypting and decrypting cookies, so a consistent scheme must be used across apps.
A common data protection key storage location is used. The sample app uses a folder named KeyRing at the
root of the solution to hold the data protection keys.
In the ASP.NET Core apps, PersistKeysToFileSystem is used to set the key storage location.
SetApplicationName is used to configure a common shared app name.
In the .NET Framework app, the cookie authentication middleware uses an implementation of
DataProtectionProvider. DataProtectionProvider provides data protection services for the encryption and
decryption of authentication cookie payload data. The DataProtectionProvider instance is isolated from the
data protection system used by other parts of the app.
DataProtectionProvider.Create(System.IO.DirectoryInfo, Action<IDataProtectionBuilder>) accepts a
DirectoryInfo to specify the location for data protection key storage. The sample app provides the path
of the KeyRing folder to DirectoryInfo . DataProtectionBuilderExtensions.SetApplicationName sets the
common app name.
DataProtectionProvider requires the Microsoft.AspNetCore.DataProtection.Extensions NuGet package.
To obtain this package for ASP.NET Core 2.1 and later apps, reference the Microsoft.AspNetCore.App
metapackage. When targeting the .NET Framework, add a package reference to
Microsoft.AspNetCore.DataProtection.Extensions .
Share authentication cookies among ASP.NET Core apps

When using ASP.NET Core Identity:
In the ConfigureServices method, use the ConfigureApplicationCookie extension method to set up the data
protection service for cookies.
.PersistKeysToFileSystem(GetKeyRingDirInfo())
.SetApplicationName("SharedCookieApp");
services.ConfigureApplicationCookie(options => {
options.Cookie.Name = ".AspNet.SharedCookie";
});
Data protection keys and the app name must be shared among apps. In the sample apps, GetKeyRingDirInfo
returns the common key storage location to the PersistKeysToFileSystem method. Use SetApplicationName to
configure a common shared app name ( SharedCookieApp in the sample). For more information, see Configuring
Data Protection.
When hosting apps that share cookies across subdomains, specify a common domain in the Cookie.Domain
property. To share cookies across apps at contoso.com , such as first_subdomain.contoso.com and
second_subdomain.contoso.com , specify the Cookie.Domain as .contoso.com :
options.Cookie.Domain = ".contoso.com";
See the CookieAuthWithIdentity.Core project in the sample code (how to download).

In the Configure method, use the CookieAuthenticationOptions to set up:
The data protection service for cookies.
The AuthenticationScheme to match ASP.NET 4.x.
app.AddIdentity<ApplicationUser, IdentityRole>(options =>

{
options.Cookies.ApplicationCookie.AuthenticationScheme =
"ApplicationCookie";
var protectionProvider =
DataProtectionProvider.Create(
new DirectoryInfo(@"PATH_TO_KEY_RING_FOLDER"));
options.Cookies.ApplicationCookie.DataProtectionProvider =
protectionProvider;
options.Cookies.ApplicationCookie.TicketDataFormat =
new TicketDataFormat(protectionProvider.CreateProtector(
"Microsoft.AspNetCore.Authentication.Cookies.CookieAuthenticationMiddleware",
"Cookies",
"v2"));
});
When using cookies directly:
.PersistKeysToFileSystem(GetKeyRingDirInfo())
.SetApplicationName("SharedCookieApp");
services.AddAuthentication("Identity.Application")
.AddCookie("Identity.Application", options =>
{
options.Cookie.Name = ".AspNet.SharedCookie";
});
Data protection keys and the app name must be shared among apps. In the sample apps, GetKeyRingDirInfo
returns the common key storage location to the PersistKeysToFileSystem method. Use SetApplicationName to
configure a common shared app name ( SharedCookieApp in the sample). For more information, see Configuring
Data Protection.
When hosting apps that share cookies across subdomains, specify a common domain in the Cookie.Domain
property. To share cookies across apps at contoso.com , such as first_subdomain.contoso.com and
second_subdomain.contoso.com , specify the Cookie.Domain as .contoso.com :
options.Cookie.Domain = ".contoso.com";
See the CookieAuth.Core project in the sample code (how to download).
app.UseCookieAuthentication(new CookieAuthenticationOptions
{
DataProtectionProvider =
DataProtectionProvider.Create(
new DirectoryInfo(@"PATH_TO_KEY_RING_FOLDER"))
});
Encrypting data protection keys at rest

For production deployments, configure the DataProtectionProvider to encrypt keys at rest with DPAPI or an
X509Certificate. See Key Encryption At Rest for more information.
{
DataProtectionProvider = DataProtectionProvider.Create(
new DirectoryInfo(@"PATH_TO_KEY_RING"),
configure =>
{
configure.ProtectKeysWithCertificate("thumbprint");
})
});
Sharing authentication cookies between ASP.NET 4.x and ASP.NET

Core apps
ASP.NET 4.x apps which use Katana cookie authentication middleware can be configured to generate
authentication cookies that are compatible with the ASP.NET Core cookie authentication middleware. This allows
upgrading a large site's individual apps piecemeal while providing a smooth SSO experience across the site.
When an app uses Katana cookie authentication middleware, it calls UseCookieAuthentication in the project's
Startup.Auth.cs file. ASP.NET 4.x web app projects created with Visual Studio 2013 and later use the Katana cookie
authentication middleware by default. Although UseCookieAuthentication is obsolete and unsupported for
ASP.NET Core apps, calling UseCookieAuthentication in an ASP.NET 4.x app that uses Katana cookie
authentication middleware is valid.
An ASP.NET 4.x app must target .NET Framework 4.5.1 or higher. Otherwise, the necessary NuGet packages fail
to install.
To share authentication cookies between an ASP.NET 4.x app and an ASP.NET Core app, configure the ASP.NET
Core app as stated above, then configure the ASP.NET 4.x app by following these steps:
1. Install the package Microsoft.Owin.Security.Interop into each ASP.NET 4.x app.
2. In Startup.Auth.cs, locate the call to UseCookieAuthentication and modify it as follows. Change the cookie
name to match the name used by the ASP.NET Core cookie authentication middleware. Provide an instance
of a DataProtectionProvider initialized to the common data protection key storage location. Make sure that
the app name is set to the common app name used by all apps that share cookies, SharedCookieApp in the
sample app.
{
AuthenticationType = "Identity.Application",
CookieName = ".AspNet.SharedCookie",
LoginPath = new PathString("/Account/Login"),
Provider = new CookieAuthenticationProvider
{
OnValidateIdentity =
SecurityStampValidator
.OnValidateIdentity<ApplicationUserManager, ApplicationUser>(
validateInterval: TimeSpan.FromMinutes(30),
regenerateIdentity: (manager, user) =>
user.GenerateUserIdentityAsync(manager))
},
TicketDataFormat = new AspNetTicketDataFormat(
new DataProtectorShim(
DataProtectionProvider.Create(GetKeyRingDirInfo(),
(builder) => { builder.SetApplicationName("SharedCookieApp"); })
.CreateProtector(
"Microsoft.AspNetCore.Authentication.Cookies.CookieAuthenticationMiddleware",
"Identity.Application",
"v2"))),
CookieManager = new ChunkingCookieManager()
});
// If not setting http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier and

// http://schemas.microsoft.com/accesscontrolservice/2010/07/claims/identityprovider,
// then set UniqueClaimTypeIdentifier to a claim that distinguishes unique users.
System.Web.Helpers.AntiForgeryConfig.UniqueClaimTypeIdentifier =
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name";
See the CookieAuthWithIdentity.NETFramework project in the sample code (how to download).

When generating a user identity, the authentication type must match the type defined in AuthenticationType set
with UseCookieAuthentication .
Models/IdentityModels.cs:
public async Task<ClaimsIdentity> GenerateUserIdentityAsync(UserManager<ApplicationUser> manager)

{
// Note the authenticationType must match the one defined in
CookieAuthenticationOptions.AuthenticationType
var userIdentity = await manager.CreateIdentityAsync(this, "Identity.Application");
// Add custom user claims here
return userIdentity;
}
Use a common user database

Confirm that the identity system for each app is pointed at the same user database. Otherwise, the identity system
produces failures at runtime when it attempts to match the information in the authentication cookie against the
information in its database.
Client IP safelist for ASP.NET Core
By Damien Bowden and Tom Dykstra

This article shows three ways to implement an IP safelist (also known as a whitelist) in an ASP.NET Core app. You
can use:
Middleware to check the remote IP address of every request.
Action filters to check the remote IP address of requests for specific controllers or action methods.
Razor Pages filters to check the remote IP address of requests for Razor pages.
The sample app illustrates both approaches. In each case, a string containing approved client IP addresses is stored
in an app setting. The middleware or filter parses the string into a list and checks if the remote IP is in the list. If
not, an HTTP 403 Forbidden status code is returned.
The safelist
The list is configured in the appsettings.json file. It's a semicolon-delimited list and can contain IPv4 and IPv6
addresses.
{
"AdminSafeList": "127.0.0.1;192.168.1.5;::1",
"Logging": {
"LogLevel": {
"Default": "Debug",
}
}
}
Middleware
The Configure method adds the middleware and passes the safelist string to it in a constructor parameter.
public void Configure(

IApplicationBuilder app,
{
loggerFactory.AddNLog();
app.UseMiddleware<AdminSafeListMiddleware>(
Configuration["AdminSafeList"]);
app.UseMvc();
}
The middleware parses the string into an array and looks for the remote IP address in the array. If the remote IP
address is not found, the middleware returns HTTP 401 Forbidden. This validation process is bypassed for HTTP
Get requests.
public class AdminSafeListMiddleware

{
private readonly ILogger<AdminSafeListMiddleware> _logger;
private readonly string _adminSafeList;
public AdminSafeListMiddleware(
RequestDelegate next,
ILogger<AdminSafeListMiddleware> logger,
string adminSafeList)
{
_adminSafeList = adminSafeList;
_next = next;
_logger = logger;
}
public async Task Invoke(HttpContext context)

{
if (context.Request.Method != "GET")
{
var remoteIp = context.Connection.RemoteIpAddress;
_logger.LogDebug($"Request from Remote IP address: {remoteIp}");
string[] ip = _adminSafeList.Split(';');
var bytes = remoteIp.GetAddressBytes();

var badIp = true;
foreach (var address in ip)
{
var testIp = IPAddress.Parse(address);
if(testIp.GetAddressBytes().SequenceEqual(bytes))
{
badIp = false;
break;
}
}
if(badIp)
{
$"Forbidden Request from Remote IP address: {remoteIp}");
context.Response.StatusCode = (int)HttpStatusCode.Forbidden;
return;
}
}
await _next.Invoke(context);
}
}
Action filter
If you want a safelist only for specific controllers or action methods, use an action filter. Here's an example:
using System.Linq;
using System.Net;
using Microsoft.AspNetCore.Mvc.Authorization;
namespace ClientIpAspNetCore.Filters
{
public class ClientIdCheckFilter : ActionFilterAttribute
{
private readonly string _safelist;
public ClientIdCheckFilter
(ILoggerFactory loggerFactory, IConfiguration configuration)
{
_logger = loggerFactory.CreateLogger("ClientIdCheckFilter");
_safelist = configuration["AdminSafeList"];
}
public override void OnActionExecuting(ActionExecutingContext context)

{
$"Remote IpAddress: {context.HttpContext.Connection.RemoteIpAddress}");
var remoteIp = context.HttpContext.Connection.RemoteIpAddress;

string[] ip = _safelist.Split(';');

var badIp = true;
{
if (testIp.GetAddressBytes().SequenceEqual(bytes))
{
badIp = false;
break;
}
}
if (badIp)
{
context.Result = new StatusCodeResult(401);
return;
}
base.OnActionExecuting(context);
}
}
}
The action filter is added to the services container.

{
services.AddScoped<ClientIdCheckFilter>();
{
options.Filters.Add
(new ClientIdCheckPageFilter
(_loggerFactory, Configuration));
}).SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
}
The filter can then be used on a controller or action method.
[ServiceFilter(typeof(ClientIdCheckFilter))]
[HttpGet]
In the sample app, the filter is applied to the Get method. So when you test the app by sending a Get API
request, the attribute is validating the client IP address. When you test by calling the API with any other HTTP
method, the middleware is validating the client IP.
Razor Pages filter

If you want a safelist for a Razor Pages app, use a Razor Pages filter. Here's an example:
using System;
using System.Linq;
using System.Net;
namespace ClientIpAspNetCore
{
public class ClientIdCheckPageFilter : IPageFilter
{
private readonly string _safelist;
public ClientIdCheckPageFilter
(ILoggerFactory loggerFactory, IConfiguration configuration)
{
_logger = loggerFactory.CreateLogger("ClientIdCheckPageFilter");
_safelist = configuration["AdminSafeList"];
}
public void OnPageHandlerExecuting(PageHandlerExecutingContext context)

{
$"Remote IpAddress: {context.HttpContext.Connection.RemoteIpAddress}");
var remoteIp = context.HttpContext.Connection.RemoteIpAddress;

string[] ip = _safelist.Split(';');

var badIp = true;
{
if (testIp.GetAddressBytes().SequenceEqual(bytes))
{
badIp = false;
break;
}
}
if (badIp)
{
context.Result = new StatusCodeResult(401);
return;
}
}
public void OnPageHandlerExecuted(PageHandlerExecutedContext context)

{
}
public void OnPageHandlerSelected(PageHandlerSelectedContext context)

{
}
}
}
This filter is enabled by adding it to the MVC Filters collection.

{
services.AddScoped<ClientIdCheckFilter>();
{
options.Filters.Add
(new ClientIdCheckPageFilter
(_loggerFactory, Configuration));
}
When you run the app and request a Razor page, the Razor Pages filter is validating the client IP.
Next steps
Learn more about ASP.NET Core Middleware.
Performance in ASP.NET Core
The following topic areas cover performance scenarios in ASP.NET Core:

Cache responses
Learn how to cache data and responses in ASP.NET Core.
Learn about response compression and how to use Response Compression Middleware in ASP.NET Core apps.
Cache responses in ASP.NET Core
Cache in-memory
Learn how to cache data in memory in ASP.NET Core.
Learn how to use ASP.NET Core distributed caching to improve app performance and scalability, especially in a
cloud or server farm environment.
Response caching
Learn how to use response caching to lower bandwidth requirements and increase performance of ASP.NET Core
apps.
Learn how to configure and use Response Caching Middleware in ASP.NET Core.
Cache Tag Helper
Learn how to use the Cache Tag Helper.
Learn how to use the Distributed Cache Tag Helper.
By Rick Anderson, John Luo, and Steve Smith

Caching basics
Caching can significantly improve the performance and scalability of an app by reducing the work required to
generate content. Caching works best with data that changes infrequently. Caching makes a copy of data that
can be returned much faster than from the original source. You should write and test your app to never depend
on cached data.
ASP.NET Core supports several different caches. The simplest cache is based on the IMemoryCache, which
represents a cache stored in the memory of the web server. Apps which run on a server farm of multiple servers
should ensure that sessions are sticky when using the in-memory cache. Sticky sessions ensure that subsequent
requests from a client all go to the same server. For example, Azure Web apps use Application Request Routing
(ARR ) to route all subsequent requests to the same server.
Non-sticky sessions in a web farm require a distributed cache to avoid cache consistency problems. For some
apps, a distributed cache can support higher scale-out than an in-memory cache. Using a distributed cache
offloads the cache memory to an external process.
The IMemoryCache cache will evict cache entries under memory pressure unless the cache priority is set to
CacheItemPriority.NeverRemove . You can set the CacheItemPriority to adjust the priority with which the cache
evicts items under memory pressure.
The in-memory cache can store any object; the distributed cache interface is limited to byte[] .
System.Runtime.Caching/MemoryCache
System.Runtime.Caching/MemoryCache (NuGet package) can be used with:
.NET Standard 2.0 or later.
Any .NET implementation that targets .NET Standard 2.0 or later. For example, ASP.NET Core 2.0 or later.
.NET Framework 4.5 or later.
Microsoft.Extensions.Caching.Memory/ IMemoryCache (described in this topic) is recommended over
System.Runtime.Caching / MemoryCache because it's better integrated into ASP.NET Core. For example,
IMemoryCache works natively with ASP.NET Core dependency injection.
Use System.Runtime.Caching / MemoryCache as a compatibility bridge when porting code from ASP.NET 4.x to
ASP.NET Core.
Cache guidelines
Code should always have a fallback option to fetch data and not depend on a cached value being available.
The cache uses a scarce resource, memory. Limit cache growth:
Do not use external input as cache keys.
Use expirations to limit cache growth.
Use SetSize, Size, and SizeLimit to limit cache size
Using IMemoryCache
In-memory caching is a service that's referenced from your app using Dependency Injection. Call
AddMemoryCache in ConfigureServices :

{
{
services.AddMemoryCache();
}

{
}
}
Request the IMemoryCache instance in the constructor:

{
private IMemoryCache _cache;
public HomeController(IMemoryCache memoryCache)

{
_cache = memoryCache;
}
IMemoryCache requires NuGet package Microsoft.Extensions.Caching.Memory.

IMemoryCache requires NuGet package Microsoft.Extensions.Caching.Memory, which is available in the
Microsoft.AspNetCore.All metapackage.
IMemoryCache requires NuGet package Microsoft.Extensions.Caching.Memory, which is available in the
The following code uses TryGetValue to check if a time is in the cache. If a time isn't cached, a new entry is
created and added to the cache with Set.
public static class CacheKeys
{
public static string Entry { get { return "_Entry"; } }
public static string CallbackEntry { get { return "_Callback"; } }
public static string CallbackMessage { get { return "_CallbackMessage"; } }
public static string Parent { get { return "_Parent"; } }
public static string Child { get { return "_Child"; } }
public static string DependentMessage { get { return "_DependentMessage"; } }
public static string DependentCTS { get { return "_DependentCTS"; } }
public static string Ticks { get { return "_Ticks"; } }
public static string CancelMsg { get { return "_CancelMsg"; } }
public static string CancelTokenSource { get { return "_CancelTokenSource"; } }
}
public IActionResult CacheTryGetValueSet()

{
DateTime cacheEntry;
// Look for cache key.

if (!_cache.TryGetValue(CacheKeys.Entry, out cacheEntry))
{
// Key not in cache, so get data.
cacheEntry = DateTime.Now;
// Set cache options.

// Keep in cache for this time, reset time if accessed.
.SetSlidingExpiration(TimeSpan.FromSeconds(3));
// Save data in cache.

_cache.Set(CacheKeys.Entry, cacheEntry, cacheEntryOptions);
}
return View("Cache", cacheEntry);

}
The current time and the cached time are displayed:
@model DateTime?
<div>
<h2>Actions</h2>
<ul>
<li><a asp-controller="Home" asp-action="CacheTryGetValueSet">TryGetValue and Set</a></li>
<li><a asp-controller="Home" asp-action="CacheGet">Get</a></li>
<li><a asp-controller="Home" asp-action="CacheGetOrCreate">GetOrCreate</a></li>
<li><a asp-controller="Home" asp-action="CacheGetOrCreateAsync">GetOrCreateAsync</a></li>
<li><a asp-controller="Home" asp-action="CacheRemove">Remove</a></li>
</ul>
</div>
<h3>Current Time: @DateTime.Now.TimeOfDay.ToString()</h3>

<h3>Cached Time: @(Model == null ? "No cached entry found" : Model.Value.TimeOfDay.ToString())</h3>
The cached DateTime value remains in the cache while there are requests within the timeout period (and no
eviction due to memory pressure). The following image shows the current time and an older time retrieved from
the cache:
The following code uses GetOrCreate and GetOrCreateAsync to cache data.
public IActionResult CacheGetOrCreate()

{
var cacheEntry = _cache.GetOrCreate(CacheKeys.Entry, entry =>
{
entry.SlidingExpiration = TimeSpan.FromSeconds(3);
return DateTime.Now;
});

}
public async Task<IActionResult> CacheGetOrCreateAsync()

{
var cacheEntry = await
_cache.GetOrCreateAsync(CacheKeys.Entry, entry =>
{
entry.SlidingExpiration = TimeSpan.FromSeconds(3);
return Task.FromResult(DateTime.Now);
});

}
The following code calls Get to fetch the cached time:
public IActionResult CacheGet()

{
var cacheEntry = _cache.Get<DateTime?>(CacheKeys.Entry);
}
See IMemoryCache methods and CacheExtensions methods for a description of the cache methods.
MemoryCacheEntryOptions
The following sample:
Sets the absolute expiration time. This is the maximum time the entry can be cached and prevents the item
from becoming too stale when the sliding expiration is continuously renewed.
Sets a sliding expiration time. Requests that access this cached item will reset the sliding expiration clock.
Sets the cache priority to CacheItemPriority.NeverRemove .
Sets a PostEvictionDelegate that will be called after the entry is evicted from the cache. The callback is run on
a different thread from the code that removes the item from the cache.
public IActionResult CreateCallbackEntry()

{
// Pin to cache.
.SetPriority(CacheItemPriority.NeverRemove)
// Add eviction callback
.RegisterPostEvictionCallback(callback: EvictionCallback, state: this);
_cache.Set(CacheKeys.CallbackEntry, DateTime.Now, cacheEntryOptions);
return RedirectToAction("GetCallbackEntry");
}
public IActionResult GetCallbackEntry()

{
return View("Callback", new CallbackViewModel
{
CachedTime = _cache.Get<DateTime?>(CacheKeys.CallbackEntry),
Message = _cache.Get<string>(CacheKeys.CallbackMessage)
});
}
public IActionResult RemoveCallbackEntry()

{
_cache.Remove(CacheKeys.CallbackEntry);
return RedirectToAction("GetCallbackEntry");
}
private static void EvictionCallback(object key, object value,

EvictionReason reason, object state)
{
var message = $"Entry was evicted. Reason: {reason}.";
((HomeController)state)._cache.Set(CacheKeys.CallbackMessage, message);
}
Use SetSize, Size, and SizeLimit to limit cache size

A MemoryCache instance may optionally specify and enforce a size limit. The memory size limit does not have a
defined unit of measure because the cache has no mechanism to measure the size of entries. If the cache
memory size limit is set, all entries must specify size. The size specified is in units the developer chooses.
For example:
If the web app was primarily caching strings, each cache entry size could be the string length.
The app could specify the size of all entries as 1, and the size limit is the count of entries.
The following code creates a unitless fixed size MemoryCache accessible by dependency injection:
// using Microsoft.Extensions.Caching.Memory;
public class MyMemoryCache
{
public MemoryCache Cache { get; set; }
public MyMemoryCache()
{
Cache = new MemoryCache(new MemoryCacheOptions
{
SizeLimit = 1024
});
}
}
SizeLimit does not have units. Cached entries must specify size in whatever units they deem most appropriate if
the cache memory size has been set. All users of a cache instance should use the same unit system. An entry will
not be cached if the sum of the cached entry sizes exceeds the value specified by SizeLimit . If no cache size
limit is set, the cache size set on the entry will be ignored.
The following code registers MyMemoryCache with the dependency injection container.

{
services.AddSingleton<MyMemoryCache>();
}
MyMemoryCache is created as an independent memory cache for components that are aware of this size limited
cache and know how to set cache entry size appropriately.
The following code uses MyMemoryCache :
{
private MemoryCache _cache;
public static readonly string MyKey = "_MyKey";
public AboutModel(MyMemoryCache memoryCache)

{
_cache = memoryCache.Cache;
}
[TempData]
public string DateTime_Now { get; set; }

{
if (!_cache.TryGetValue(MyKey, out string cacheEntry))
{
cacheEntry = DateTime.Now.TimeOfDay.ToString();

// Set cache entry size by extension method.
.SetSize(1)
// Set cache entry size via property.

// cacheEntryOptions.Size = 1;

_cache.Set(MyKey, cacheEntry, cacheEntryOptions);
}
DateTime_Now = cacheEntry;
}
}
The size of the cache entry can be set by Size or the SetSize extension method:
{
if (!_cache.TryGetValue(MyKey, out string cacheEntry))
{
cacheEntry = DateTime.Now.TimeOfDay.ToString();

// Set cache entry size by extension method.
.SetSize(1)
// Set cache entry size via property.

// cacheEntryOptions.Size = 1;

_cache.Set(MyKey, cacheEntry, cacheEntryOptions);
}
DateTime_Now = cacheEntry;
}
Cache dependencies
The following sample shows how to expire a cache entry if a dependent entry expires. A
CancellationChangeToken is added to the cached item. When Cancel is called on the CancellationTokenSource ,
both cache entries are evicted.
public IActionResult CreateDependentEntries()
{
var cts = new CancellationTokenSource();
_cache.Set(CacheKeys.DependentCTS, cts);
using (var entry = _cache.CreateEntry(CacheKeys.Parent))

{
// expire this entry if the dependant entry expires.
entry.Value = DateTime.Now;
entry.RegisterPostEvictionCallback(DependentEvictionCallback, this);
_cache.Set(CacheKeys.Child,
DateTime.Now,
new CancellationChangeToken(cts.Token));
}
return RedirectToAction("GetDependentEntries");
}
public IActionResult GetDependentEntries()

{
return View("Dependent", new DependentViewModel
{
ParentCachedTime = _cache.Get<DateTime?>(CacheKeys.Parent),
ChildCachedTime = _cache.Get<DateTime?>(CacheKeys.Child),
Message = _cache.Get<string>(CacheKeys.DependentMessage)
});
}
public IActionResult RemoveChildEntry()

{
_cache.Get<CancellationTokenSource>(CacheKeys.DependentCTS).Cancel();
return RedirectToAction("GetDependentEntries");
}
private static void DependentEvictionCallback(object key, object value,

EvictionReason reason, object state)
{
var message = $"Parent entry was evicted. Reason: {reason}.";
((HomeController)state)._cache.Set(CacheKeys.DependentMessage, message);
}
Using a CancellationTokenSource allows multiple cache entries to be evicted as a group. With the using pattern
in the code above, cache entries created inside the using block will inherit triggers and expiration settings.
Additional notes
When using a callback to repopulate a cache item:
Multiple requests can find the cached key value empty because the callback hasn't completed.
This can result in several threads repopulating the cached item.
When one cache entry is used to create another, the child copies the parent entry's expiration tokens and
time-based expiration settings. The child isn't expired by manual removal or updating of the parent entry.
Use PostEvictionCallbacks to set the callbacks that will be fired after the cache entry is evicted from the
cache.
Detect changes with change tokens
Response caching
Cache Tag Helper
Work with a distributed cache in ASP.NET Core
By Steve Smith
Distributed caches can improve the performance and scalability of ASP.NET Core apps, especially when hosted
in the cloud or a server farm.
What is a distributed cache

A distributed cache is shared by multiple app servers (see Cache Basics). The information in the cache isn't
stored in the memory of individual web servers, and the cached data is available to all of the app's servers. This
provides several advantages:
1. Cached data is coherent on all web servers. Users don't see different results depending on which web
server handles their request
2. Cached data survives web server restarts and deployments. Individual web servers can be removed or
added without impacting the cache.
3. The source data store has fewer requests made to it (than with multiple in-memory caches or no cache
at all).
NOTE
If using a SQL Server Distributed Cache, some of these advantages are only true if a separate database instance is used
for the cache than for the app's source data.
Like any cache, a distributed cache can dramatically improve an app's responsiveness, since typically data can
be retrieved from the cache much faster than from a relational database (or web service).
Cache configuration is implementation specific. This article describes how to configure both Redis and SQL
Server distributed caches. Regardless of which implementation is selected, the app interacts with the cache
using a common IDistributedCache interface.
The IDistributedCache Interface

The IDistributedCache interface includes synchronous and asynchronous methods. The interface allows items
to be added, retrieved, and removed from the distributed cache implementation. The IDistributedCache
interface includes the following methods:
Get, GetAsync
Takes a string key and retrieves a cached item as a byte[] if found in the cache.
Set, SetAsync
Adds an item (as byte[] ) to the cache using a string key.
Refresh, RefreshAsync
Refreshes an item in the cache based on its key, resetting its sliding expiration timeout (if any).
Remove, RemoveAsync
Removes a cache entry based on its key.
To use the IDistributedCache interface:
1. Add the required NuGet packages to your project file.
2. Configure the specific implementation of IDistributedCache in your Startup class's ConfigureServices
method, and add it to the container there.
3. From the app's Middleware or MVC controller classes, request an instance of IDistributedCache from
the constructor. The instance will be provided by Dependency Injection (DI).
NOTE
There's no need to use a Singleton or Scoped lifetime for IDistributedCache instances (at least for the built-in
implementations). You can also create an instance wherever you might need one (instead of using Dependency Injection),
but this can make your code harder to test, and violates the Explicit Dependencies Principle.
The following example shows how to use an instance of IDistributedCache in a simple middleware component:
using System.Linq;
using System.Text;
using Microsoft.Extensions.Caching.Distributed;
namespace DistCacheSample
{
public class StartTimeHeader
{
private readonly IDistributedCache _cache;
public StartTimeHeader(RequestDelegate next,

IDistributedCache cache)
{
_next = next;
_cache = cache;
}

{
var startTimeUTC = "Not found";
var cacheStartTimeUTC = await _cache.GetAsync("lastServerStartTimeUTC");
if (cacheStartTimeUTC != null)
{
startTimeUTC = Encoding.UTF8.GetString(cacheStartTimeUTC);
}
httpContext.Response.Headers.Append(
"Last-Server-Start-Time-UTC", startTimeUTC);
await _next.Invoke(httpContext);
}
}
// Add the middleware to the HTTP request pipeline.

public static class StartTimeHeaderExtensions
{
public static IApplicationBuilder UseStartTimeHeader(
{
return builder.UseMiddleware<StartTimeHeader>();
}
}
}
In the code above, the cached value is read, but never written. In this sample, the value is only set when a server
starts up, and doesn't change. In a multi-server scenario, the most recent server to start will overwrite any
previous values that were set by other servers. The Get and Set methods use the byte[] type. Therefore, the
string value must be converted using Encoding.UTF8.GetString (for Get ) and Encoding.UTF8.GetBytes (for Set
).
The following code from Startup.cs shows the value being set:
IDistributedCache cache)
{
var startTimeUTC = DateTime.UtcNow.ToString();
byte[] encodedStartTimeUTC = Encoding.UTF8.GetBytes(startTimeUTC);
var cacheEntryOptions = new DistributedCacheEntryOptions()
cache.Set("lastServerStartTimeUTC", encodedStartTimeUTC, cacheEntryOptions);
Since IDistributedCache is configured in the ConfigureServices method, it's available to the Configure
method as a parameter. Adding it as a parameter will allow the configured instance to be provided through DI.
Using a Redis distributed cache

Redis is an open source in-memory data store, which is often used as a distributed cache. You can use it locally,
and you can configure an Azure Redis Cache for your Azure-hosted ASP.NET Core apps. Your ASP.NET Core
app configures the cache implementation using a RedisDistributedCache instance.
The Redis cache requires Microsoft.Extensions.Caching.Redis
You configure the Redis implementation in ConfigureServices and access it in your app code by requesting an
instance of IDistributedCache (see the code above).
In the sample code, a RedisCache implementation is used when the server is configured for a Staging
environment. Thus the ConfigureStagingServices method configures the RedisCache :
public void ConfigureStagingServices(IServiceCollection services)

{
services.AddDistributedRedisCache(options =>
{
options.Configuration = "localhost";
options.InstanceName = "SampleInstance";
});
}
To install Redis on your local machine, install the chocolatey package https://chocolatey.org/packages/redis-64/
and run redis-server from a command prompt.
Using a SQL Server distributed cache

The SqlServerCache implementation allows the distributed cache to use a SQL Server database as its backing
store. To create SQL Server table you can use sql-cache tool, the tool creates a table with the name and schema
you specify.
Add SqlConfig.Tools to the <ItemGroup> element of the project file and run dotnet restore .
<ItemGroup>
<DotNetCliToolReference Include="Microsoft.Extensions.Caching.SqlConfig.Tools"
Version="2.0.2" />
</ItemGroup>
Test SqlConfig.Tools by running the following command:
dotnet sql-cache create --help
SqlConfig.Tools displays usage, options, and command help.

Create a table in SQL Server by running the sql-cache create command :
dotnet sql-cache create "Data Source=(localdb)\v11.0;Initial Catalog=DistCache;Integrated Security=True;"

dbo TestCache
info: Microsoft.Extensions.Caching.SqlConfig.Tools.Program[0]
Table and index were created successfully.
The created table has the following schema:
Like all cache implementations, your app should get and set cache values using an instance of
IDistributedCache , not a SqlServerCache . The sample implements SqlServerCache in the Production
environment (so it's configured in ConfigureProductionServices ).
public void ConfigureProductionServices(IServiceCollection services)

{
services.AddDistributedSqlServerCache(options =>
{
options.ConnectionString =
@"Data Source=(localdb)\v11.0;Initial Catalog=DistCache;" +
@"Integrated Security=True;";
options.SchemaName = "dbo";
options.TableName = "TestCache";
});
}
NOTE
The ConnectionString (and optionally, SchemaName and TableName ) should typically be stored outside of source
control (such as UserSecrets), as they may contain credentials.
Recommendations
When deciding which implementation of IDistributedCache is right for your app, choose between Redis and
SQL Server based on your existing infrastructure and environment, your performance requirements, and your
team's experience. If your team is more comfortable working with Redis, it's an excellent choice. If your team
prefers SQL Server, you can be confident in that implementation as well. Note that a traditional caching
solution stores data in-memory which allows for fast retrieval of data. You should store commonly used data in
a cache and store the entire data in a backend persistent store such as SQL Server or Azure Storage. Redis
Cache is a caching solution which gives you high throughput and low latency as compared to SQL Cache.
Redis Cache on Azure
SQL Database on Azure
Detect changes with change tokens in ASP.NET Core
Response caching in ASP.NET Core
Response Caching Middleware in ASP.NET Core
Distributed Cache Tag Helper in ASP.NET Core
Response caching in ASP.NET Core
By John Luo, Rick Anderson, Steve Smith, and Luke Latham
NOTE
Response caching in Razor Pages is available in ASP.NET Core 2.1 or later.

Response caching reduces the number of requests a client or proxy makes to a web server. Response caching also
reduces the amount of work the web server performs to generate a response. Response caching is controlled by
headers that specify how you want client, proxy, and middleware to cache responses.
The web server can cache responses when you add Response Caching Middleware.
HTTP-based response caching

The HTTP 1.1 Caching specification describes how Internet caches should behave. The primary HTTP header
used for caching is Cache-Control, which is used to specify cache directives. The directives control caching
behavior as requests make their way from clients to servers and as reponses make their way from servers back to
clients. Requests and responses move through proxy servers, and proxy servers must also conform to the HTTP
1.1 Caching specification.
Common Cache-Control directives are shown in the following table.
DIRECTIVE ACTION
public A cache may store the response.
private The response must not be stored by a shared cache. A private

cache may store and reuse the response.
max-age The client won't accept a response whose age is greater than
the specified number of seconds. Examples: max-age=60 (60
seconds), max-age=2592000 (1 month)
no-cache On requests: A cache must not use a stored response to

satisfy the request. Note: The origin server re-generates the
response for the client, and the middleware updates the
stored response in its cache.
On responses: The response must not be used for a

subsequent request without validation on the origin server.
no-store On requests: A cache must not store the request.
On responses: A cache must not store any part of the

response.
Other cache headers that play a role in caching are shown in the following table.
HEADER FUNCTION
Age An estimate of the amount of time in seconds since the

response was generated or successfully validated at the origin
server.
Expires The date/time after which the response is considered stale.
Pragma Exists for backwards compatibility with HTTP/1.0 caches for

setting no-cache behavior. If the Cache-Control header is
present, the Pragma header is ignored.
Vary Specifies that a cached response must not be sent unless all
of the Vary header fields match in both the cached
response's original request and the new request.
HTTP-based caching respects request Cache-Control directives

The HTTP 1.1 Caching specification for the Cache-Control header requires a cache to honor a valid
Cache-Control header sent by the client. A client can make requests with a no-cache header value and force the
server to generate a new response for every request.
Always honoring client Cache-Control request headers makes sense if you consider the goal of HTTP caching.
Under the official specification, caching is meant to reduce the latency and network overhead of satisfying
requests across a network of clients, proxies, and servers. It isn't necessarily a way to control the load on an origin
server.
There's no current developer control over this caching behavior when using the Response Caching Middleware
because the middleware adheres to the official caching specification. Future enhancements to the middleware will
permit configuring the middleware to ignore a request's Cache-Control header when deciding to serve a cached
response. This will offer you an opportunity to better control the load on your server when you use the
middleware.
Other caching technology in ASP.NET Core

In-memory caching
In-memory caching uses server memory to store cached data. This type of caching is suitable for a single server
or multiple servers using sticky sessions. Sticky sessions means that the requests from a client are always routed
to the same server for processing.
For more information, see Cache in-memory.
Distributed Cache
Use a distributed cache to store data in memory when the app is hosted in a cloud or server farm. The cache is
shared across the servers that process requests. A client can submit a request that's handled by any server in the
group if cached data for the client is available. ASP.NET Core offers SQL Server and Redis distributed caches.
For more information, see Work with a distributed cache.
Cache Tag Helper
You can cache the content from an MVC view or Razor Page with the Cache Tag Helper. The Cache Tag Helper
uses in-memory caching to store data.
For more information, see Cache Tag Helper in ASP.NET Core MVC.
You can cache the content from an MVC view or Razor Page in distributed cloud or web farm scenarios with the
Distributed Cache Tag Helper. The Distributed Cache Tag Helper uses SQL Server or Redis to store data.
For more information, see Distributed Cache Tag Helper.
ResponseCache attribute
The ResponseCacheAttribute specifies the parameters necessary for setting appropriate headers in response
caching.
WARNING
Disable caching for content that contains information for authenticated clients. Caching should only be enabled for content
that doesn't change based on a user's identity or whether a user is signed in.
VaryByQueryKeys varies the stored response by the values of the given list of query keys. When a single value of
* is provided, the middleware varies responses by all request query string parameters. VaryByQueryKeys
requires ASP.NET Core 1.1 or later.
The Response Caching Middleware must be enabled to set the VaryByQueryKeys property; otherwise, a runtime
exception is thrown. There isn't a corresponding HTTP header for the VaryByQueryKeys property. The property is
an HTTP feature handled by the Response Caching Middleware. For the middleware to serve a cached response,
the query string and query string value must match a previous request. For example, consider the sequence of
requests and results shown in the following table.
REQUEST RESULT
http://example.com?key1=value1 Returned from server
http://example.com?key1=value1 Returned from middleware
http://example.com?key1=value2 Returned from server
The first request is returned by the server and cached in middleware. The second request is returned by
middleware because the query string matches the previous request. The third request isn't in the middleware
cache because the query string value doesn't match a previous request.
The ResponseCacheAttribute is used to configure and create (via IFilterFactory ) a ResponseCacheFilter. The
ResponseCacheFilter performs the work of updating the appropriate HTTP headers and features of the response.
The filter:
Removes any existing headers for Vary , Cache-Control , and Pragma .
Writes out the appropriate headers based on the properties set in the ResponseCacheAttribute .
Updates the response caching HTTP feature if VaryByQueryKeys is set.
Vary
This header is only written when the VaryByHeader property is set. It's set to the Vary property's value. The
following sample uses the VaryByHeader property:
[ResponseCache(VaryByHeader = "User-Agent", Duration = 30)]

public IActionResult About2()
{
[ResponseCache(VaryByHeader = "User-Agent", Duration = 30)]
public IActionResult About2()
{
You can view the response headers with your browser's network tools. The following image shows the Edge F12
output on the Network tab when the About2 action method is refreshed:
NoStore and Location.None

NoStore overrides most of the other properties. When this property is set to true , the Cache-Control header is
set to no-store . If Location is set to None :
Cache-Control is set to no-store,no-cache .
Pragma is set to no-cache .
If NoStore is false and Location is None , Cache-Control and Pragma are set to no-cache .
You typically set NoStore to true on error pages. For example:
[ResponseCache(Location = ResponseCacheLocation.None, NoStore = true)]

{
return View();
}
[ResponseCache(Location = ResponseCacheLocation.None, NoStore = true)]

{
return View();
}
This results in the following headers:

Cache-Control: no-store,no-cache
Pragma: no-cache
Location and Duration

To enable caching, Duration must be set to a positive value and Location must be either Any (the default) or
Client . In this case, the Cache-Control header is set to the location value followed by the max-age of the
response.
NOTE
Location 's options of Any and Client translate into Cache-Control header values of public and private ,
respectively. As noted previously, setting Location to None sets both Cache-Control and Pragma headers to
no-cache .
Below is an example showing the headers produced by setting Duration and leaving the default Location value:
[ResponseCache(Duration = 60)]
{
return View();
}
{
return View();
}
This produces the following header:
Cache-Control: public,max-age=60
Cache profiles
Instead of duplicating ResponseCache settings on many controller action attributes, cache profiles can be
configured as options when setting up MVC in the ConfigureServices method in Startup . Values found in a
referenced cache profile are used as the defaults by the ResponseCache attribute and are overridden by any
properties specified on the attribute.
Setting up a cache profile:
{
{
options.CacheProfiles.Add("Default",
new CacheProfile()
{
Duration = 60
});
options.CacheProfiles.Add("Never",
new CacheProfile()
{
Location = ResponseCacheLocation.None,
NoStore = true
});
}

{
{
options.CacheProfiles.Add("Default",
new CacheProfile()
{
Duration = 60
});
options.CacheProfiles.Add("Never",
new CacheProfile()
{
Location = ResponseCacheLocation.None,
NoStore = true
});
});
}
Referencing a cache profile:
{
[ResponseCache(CacheProfileName = "Default")]
{
return View();
}
{
[ResponseCache(CacheProfileName = "Default")]
{
return View();
}
The ResponseCache attribute can be applied both to actions (methods) and controllers (classes). Method-level
attributes override the settings specified in class-level attributes.
In the above example, a class-level attribute specifies a duration of 30 seconds, while a method-level attribute
references a cache profile with a duration set to 60 seconds.
The resulting header:
Cache-Control: public,max-age=60
Storing Responses in Caches
Cache-Control
Cache in-memory
Cache Tag Helper
Response Caching Middleware in ASP.NET Core
By Luke Latham and John Luo

View or download ASP.NET Core 2.1 sample code (how to download)
This article explains how to configure Response Caching Middleware in an ASP.NET Core app. The middleware
determines when responses are cacheable, stores responses, and serves responses from cache. For an
introduction to HTTP caching and the ResponseCache attribute, see Response Caching.
Package
Microsoft.AspNetCore.ResponseCaching package.
Microsoft.AspNetCore.ResponseCaching package.
Add a package reference to the Microsoft.AspNetCore.ResponseCaching package.
Configuration
In Startup.ConfigureServices , add the middleware to the service collection.

{
{
});
services.AddResponseCaching();
services.AddMvc()
}
Configure the app to use the middleware with the UseResponseCaching extension method, which adds the
middleware to the request processing pipeline. The sample app adds a Cache-Control header to the response
that caches cacheable responses for up to 10 seconds. The sample sends a Vary header to configure the
middleware to serve a cached response only if the Accept-Encoding header of subsequent requests matches
that of the original request. In the code example that follows, CacheControlHeaderValue and HeaderNames
require a using statement for the Microsoft.Net.Http.Headers namespace.
{
{
}
else
{
app.UseHsts();
}
app.UseResponseCaching();

{
// For GetTypedHeaders, add: using Microsoft.AspNetCore.Http;
context.Response.GetTypedHeaders().CacheControl =
new Microsoft.Net.Http.Headers.CacheControlHeaderValue()
{
Public = true,
MaxAge = TimeSpan.FromSeconds(10)
};
context.Response.Headers[Microsoft.Net.Http.Headers.HeaderNames.Vary] =
new string[] { "Accept-Encoding" };
await next();
});
app.UseMvc();
}
Response Caching Middleware only caches server responses that result in a 200 (OK) status code. Any other
responses, including error pages, are ignored by the middleware.
WARNING
Responses containing content for authenticated clients must be marked as not cacheable to prevent the middleware from
storing and serving those responses. See Conditions for caching for details on how the middleware determines if a
response is cacheable.
Options
The middleware offers three options for controlling response caching.
OPTION DESCRIPTION
UseCaseSensitivePaths Determines if responses are cached on case-sensitive paths.

The default value is false .
MaximumBodySize The largest cacheable size for the response body in bytes.
The default value is 64 * 1024 * 1024 (64 MB).
SizeLimit The size limit for the response cache middleware in bytes.
The default value is 100 * 1024 * 1024 (100 MB).
The following example configures the middleware to:
Cache responses smaller than or equal to 1,024 bytes.
Store the responses by case-sensitive paths (for example, /page1 and /Page1 are stored separately).
services.AddResponseCaching(options =>
{
options.UseCaseSensitivePaths = true;
options.MaximumBodySize = 1024;
});
VaryByQueryKeys
When using MVC/Web API controllers or Razor Pages page models, the ResponseCache attribute specifies the
parameters necessary for setting the appropriate headers for response caching. The only parameter of the
ResponseCache attribute that strictly requires the middleware is VaryByQueryKeys , which doesn't correspond to
an actual HTTP header. For more information, see ResponseCache Attribute.
When not using the ResponseCache attribute, response caching can be varied with the VaryByQueryKeys feature.
Use the ResponseCachingFeature directly from the IFeatureCollection of the HttpContext :
var responseCachingFeature = context.HttpContext.Features.Get<IResponseCachingFeature>();

if (responseCachingFeature != null)
{
responseCachingFeature.VaryByQueryKeys = new[] { "MyKey" };
}
Using a single value equal to * in VaryByQueryKeys varies the cache by all request query parameters.
HTTP headers used by Response Caching Middleware

Response caching by the middleware is configured using HTTP headers.
HEADER DETAILS
Authorization The response isn't cached if the header exists.

HEADER DETAILS
Cache-Control The middleware only considers caching responses marked

with the public cache directive. Control caching with the
following parameters:
max-age
max-stale†
min-fresh
must-revalidate
no-cache
no-store
only-if-cached
private
public
s-maxage
proxy-revalidate‡
†If no limit is specified to max-stale , the middleware takes
no action.
‡ proxy-revalidate has the same effect as
must-revalidate .
For more information, see RFC 7231: Request Cache-Control

Directives.
Pragma A Pragma: no-cache header in the request produces the

same effect as Cache-Control: no-cache . This header is
overridden by the relevant directives in the Cache-Control
header, if present. Considered for backward compatibility
with HTTP/1.0.
Set-Cookie The response isn't cached if the header exists. Any

middleware in the request processing pipeline that sets one
or more cookies prevents the Response Caching Middleware
from caching the response (for example, the cookie-based
TempData provider).
Vary The Vary header is used to vary the cached response by

another header. For example, cache responses by encoding
by including the Vary: Accept-Encoding header, which
caches responses for requests with headers
Accept-Encoding: gzip and
Accept-Encoding: text/plain separately. A response with
a header value of * is never stored.
Expires A response deemed stale by this header isn't stored or

retrieved unless overridden by other Cache-Control
headers.
If-None-Match The full response is served from cache if the value isn't *
and the ETag of the response doesn't match any of the
values provided. Otherwise, a 304 (Not Modified) response
is served.
If-Modified-Since If the If-None-Match header isn't present, a full response is

served from cache if the cached response date is newer than
the value provided. Otherwise, a 304 (Not Modified)
response is served.
HEADER DETAILS
Date When serving from cache, the Date header is set by the
middleware if it wasn't provided on the original response.
Content-Length When serving from cache, the Content-Length header is

set by the middleware if it wasn't provided on the original
response.
Age The Age header sent in the original response is ignored.

The middleware computes a new value when serving a
cached response.
Caching respects request Cache-Control directives

The middleware respects the rules of the HTTP 1.1 Caching specification. The rules require a cache to honor a
valid Cache-Control header sent by the client. Under the specification, a client can make requests with a
no-cache header value and force the server to generate a new response for every request. Currently, there's no
developer control over this caching behavior when using the middleware because the middleware adheres to
the official caching specification.
For more control over caching behavior, explore other caching features of ASP.NET Core. See the following
topics:
Cache in-memory
Troubleshooting
If caching behavior isn't as expected, confirm that responses are cacheable and capable of being served from
the cache. Examine the request's incoming headers and the response's outgoing headers. Enable logging to help
with debugging.
When testing and troubleshooting caching behavior, a browser may set request headers that affect caching in
undesirable ways. For example, a browser may set the Cache-Control header to no-cache or max-age=0 when
refreshing a page. The following tools can explicitly set request headers and are preferred for testing caching:
Fiddler
Postman
Conditions for caching
The request must result in a server response with a 200 (OK) status code.
The request method must be GET or HEAD.
Terminal middleware, such as Static File Middleware, must not process the response prior to the Response
Caching Middleware.
The Authorization header must not be present.
Cache-Control header parameters must be valid, and the response must be marked public and not marked
private .
The Pragma: no-cache header must not be present if the Cache-Control header isn't present, as the
Cache-Control header overrides the Pragma header when present.
The Set-Cookie header must not be present.
Vary header parameters must be valid and not equal to * .
The Content-Length header value (if set) must match the size of the response body.
The IHttpSendFileFeature isn't used.
The response must not be stale as specified by the Expires header and the max-age and s-maxage cache
directives.
Response buffering must be successful, and the size of the response must be smaller than the configured or
default SizeLimit .
The response must be cacheable according to the RFC 7234 specifications. For example, the no-store
directive must not exist in request or response header fields. See Section 3: Storing Responses in Caches of
RFC 7234 for details.
NOTE
The Antiforgery system for generating secure tokens to prevent Cross-Site Request Forgery (CSRF) attacks sets the
Cache-Control and Pragma headers to no-cache so that responses aren't cached. For information on how to disable
antiforgery tokens for HTML form elements, see ASP.NET Core antiforgery configuration.
Application Startup
Middleware
Cache in-memory
Response caching
Cache Tag Helper
Response compression in ASP.NET Core
By Luke Latham
Network bandwidth is a limited resource. Reducing the size of the response usually increases the responsiveness
of an app, often dramatically. One way to reduce payload sizes is to compress an app's responses.
When to use Response Compression Middleware

Use server-based response compression technologies in IIS, Apache, or Nginx. The performance of the
middleware probably won't match that of the server modules. HTTP.sys server and Kestrel don't currently offer
built-in compression support.
Use Response Compression Middleware when you're:
Unable to use the following server-based compression technologies:
IIS Dynamic Compression module
Apache mod_deflate module
Nginx Compression and Decompression
Hosting directly on:
HTTP.sys server (formerly called WebListener)
Kestrel
Usually, any response not natively compressed can benefit from response compression. Responses not natively
compressed typically include: CSS, JavaScript, HTML, XML, and JSON. You shouldn't compress natively
compressed assets, such as PNG files. If you attempt to further compress a natively compressed response, any
small additional reduction in size and transmission time will likely be overshadowed by the time it took to process
the compression. Don't compress files smaller than about 150-1000 bytes (depending on the file's content and
the efficiency of compression). The overhead of compressing small files may produce a compressed file larger
than the uncompressed file.
When a client can process compressed content, the client must inform the server of its capabilities by sending the
Accept-Encoding header with the request. When a server sends compressed content, it must include information
in the Content-Encoding header on how the compressed response is encoded. Content encoding designations
supported by the middleware are shown in the following table.
ACCEPT-ENCODING HEADER VALUES MIDDLEWARE SUPPORTED DESCRIPTION
br Yes (default) Brotli compressed data format
deflate No DEFLATE compressed data format
exi No W3C Efficient XML Interchange
gzip Yes Gzip file format

identity Yes "No encoding" identifier: The response

must not be encoded.
pack200-gzip No Network Transfer Format for Java

Archives
* Yes Any available content encoding not

explicitly requested
br No Brotli compressed data format
deflate No DEFLATE compressed data format
exi No W3C Efficient XML Interchange
gzip Yes (default) Gzip file format
identity Yes "No encoding" identifier: The response

must not be encoded.
pack200-gzip No Network Transfer Format for Java

Archives
* Yes Any available content encoding not

explicitly requested
For more information, see the IANA Official Content Coding List.
The middleware allows you to add additional compression providers for custom Accept-Encoding header values.
For more information, see Custom Providers below.
The middleware is capable of reacting to quality value (qvalue, q ) weighting when sent by the client to prioritize
compression schemes. For more information, see RFC 7231: Accept-Encoding.
Compression algorithms are subject to a tradeoff between compression speed and the effectiveness of the
compression. Effectiveness in this context refers to the size of the output after compression. The smallest size is
achieved by the most optimal compression.
The headers involved in requesting, sending, caching, and receiving compressed content are described in the table
below.
HEADER ROLE
Accept-Encoding Sent from the client to the server to indicate the content
encoding schemes acceptable to the client.
Content-Encoding Sent from the server to the client to indicate the encoding of
the content in the payload.
HEADER ROLE
Content-Length When compression occurs, the Content-Length header is

removed, since the body content changes when the response
is compressed.
Content-MD5 When compression occurs, the Content-MD5 header is

removed, since the body content has changed and the hash is
no longer valid.
Content-Type Specifies the MIME type of the content. Every response

should specify its Content-Type . The middleware checks this
value to determine if the response should be compressed. The
middleware specifies a set of default MIME types that it can
encode, but you can replace or add MIME types.
Vary When sent by the server with a value of Accept-Encoding

to clients and proxies, the Vary header indicates to the
client or proxy that it should cache (vary) responses based on
the value of the Accept-Encoding header of the request.
The result of returning content with the
Vary: Accept-Encoding header is that both compressed
and uncompressed responses are cached separately.
Explore the features of the Response Compression Middleware with the sample app. The sample illustrates:
The compression of app responses using Gzip and custom compression providers.
How to add a MIME type to the default list of MIME types for compression.
Package
To include the middleware in a project, add a reference to the Microsoft.AspNetCore.App metapackage, which
includes the Microsoft.AspNetCore.ResponseCompression package.
To include the middleware in a project, add a reference to the Microsoft.AspNetCore.All metapackage, which
includes the Microsoft.AspNetCore.ResponseCompression package.
To include the middleware in a project, add a reference to the Microsoft.AspNetCore.ResponseCompression
package.
Configuration
The following code shows how to enable the Response Compression Middleware for default MIME types and
compression providers (Brotli and Gzip):
The following code shows how to enable the Response Compression Middleware for default MIME types and the
Gzip Compression Provider:
{
{
services.AddResponseCompression();
}

{
}
}
NOTE
Use a tool like Fiddler, Firebug, or Postman to set the Accept-Encoding request header and study the response headers,
size, and body.
Submit a request to the sample app without the Accept-Encoding header and observe that the response is
uncompressed. The Content-Encoding and Vary headers aren't present on the response.
Submit a request to the sample app with the Accept-Encoding: gzip header and observe that the response is
compressed. The Content-Encoding and Vary headers are present on the response.
Providers
Brotli Compression Provider
Use the BrotliCompressionProvider to compress responses with the Brotli compressed data format.
If no compression providers are explicitly added to the CompressionProviderCollection:
The Brotli Compression Provider is added by default to the array of compression providers along with the
Gzip compression provider.
Compression defaults to Brotli compression when the Brotli compressed data format is supported by the
client. If Brotli isn't supported by the client, compression defaults to Gzip when the client supports Gzip
compression.

{
}
The Brotoli Compression Provider must be added when any compression providers are explicitly added:
{
services.AddResponseCompression(options =>
{
options.Providers.Add<BrotliCompressionProvider>();
options.Providers.Add<GzipCompressionProvider>();
options.Providers.Add<CustomCompressionProvider>();
options.MimeTypes =
ResponseCompressionDefaults.MimeTypes.Concat(
new[] { "image/svg+xml" });
});
}
Set the compression level with BrotliCompressionProviderOptions . The Brotli Compression Provider defaults to
the fastest compression level (CompressionLevel.Fastest), which might not produce the most efficient
compression. If the most efficient compression is desired, configure the middleware for optimal compression.
COMPRESSION LEVEL DESCRIPTION
CompressionLevel.Fastest Compression should complete as quickly as possible, even if

the resulting output isn't optimally compressed.
CompressionLevel.NoCompression No compression should be performed.
CompressionLevel.Optimal Responses should be optimally compressed, even if the

compression takes more time to complete.

{
services.Configure<BrotliCompressionProviderOptions>(options =>
{
options.Level = CompressionLevel.Fastest;
});
}
Gzip Compression Provider

Use the GzipCompressionProvider to compress responses with the Gzip file format.
If no compression providers are explicitly added to the CompressionProviderCollection:
The Gzip Compression Provider is added by default to the array of compression providers along with the
Brotli Compression Provider.
Compression defaults to Brotli compression when the Brotli compressed data format is supported by the
client. If Brotli isn't supported by the client, compression defaults to Gzip when the client supports Gzip
compression.
The Gzip Compression Provider is added by default to the array of compression providers.
Compression defaults to Gzip when the client supports Gzip compression.

{
}
The Gzip Compression Provider must be added when any compression providers are explicitly added:

{
{
options.MimeTypes =
});
}

{
{
options.MimeTypes =
});
}

{
{
options.MimeTypes =
});
}
Set the compression level with GzipCompressionProviderOptions. The Gzip Compression Provider defaults to the
fastest compression level (CompressionLevel.Fastest), which might not produce the most efficient compression. If
the most efficient compression is desired, configure the middleware for optimal compression.
COMPRESSION LEVEL DESCRIPTION
CompressionLevel.Fastest Compression should complete as quickly as possible, even if

the resulting output isn't optimally compressed.
CompressionLevel.NoCompression No compression should be performed.
CompressionLevel.Optimal Responses should be optimally compressed, even if the

compression takes more time to complete.
{
services.Configure<GzipCompressionProviderOptions>(options =>
{
options.Level = CompressionLevel.Fastest;
});
}
Custom providers
Create custom compression implementations with ICompressionProvider. The EncodingName represents the
content encoding that this ICompressionProvider produces. The middleware uses this information to choose the
provider based on the list specified in the Accept-Encoding header of the request.
Using the sample app, the client submits a request with the Accept-Encoding: mycustomcompression header. The
middleware uses the custom compression implementation and returns the response with a
Content-Encoding: mycustomcompression header. The client must be able to decompress the custom encoding in
order for a custom compression implementation to work.

{
{
options.MimeTypes =
});
}
public class CustomCompressionProvider : ICompressionProvider

{
public string EncodingName => "mycustomcompression";
public bool SupportsFlush => true;
public Stream CreateStream(Stream outputStream)

{
// Create a custom compression stream wrapper here
return outputStream;
}
}

{
{
options.MimeTypes =
});
}
{

{
}
}

{
{
options.MimeTypes =
});
}

{

{
}
}
Submit a request to the sample app with the Accept-Encoding: mycustomcompression header and observe the
response headers. The Vary and Content-Encoding headers are present on the response. The response body (not
shown) isn't compressed by the sample. There isn't a compression implementation in the
CustomCompressionProvider class of the sample. However, the sample shows where you would implement such a
compression algorithm.
MIME types
The middleware specifies a default set of MIME types for compression:
application/javascript
application/json
application/xml
text/css
text/html
text/json
text/plain
text/xml
Replace or append MIME types with the Response Compression Middleware options. Note that wildcard MIME
types, such as text/* aren't supported. The sample app adds a MIME type for image/svg+xml and compresses
and serves the ASP.NET Core banner image (banner.svg).

{
{
options.MimeTypes =
});
}
{
{
options.MimeTypes =
});
}

{
{
options.MimeTypes =
});
}
Compression with secure protocol

Compressed responses over secure connections can be controlled with the EnableForHttps option, which is
disabled by default. Using compression with dynamically generated pages can lead to security problems such as
the CRIME and BREACH attacks.
Adding the Vary header

When compressing responses based on the Accept-Encoding header, there are potentially multiple compressed
versions of the response and an uncompressed version. In order to instruct client and proxy caches that multiple
versions exist and should be stored, the Vary header is added with an Accept-Encoding value. In ASP.NET Core
2.0 or later, the middleware adds the Vary header automatically when the response is compressed.
When compressing responses based on the Accept-Encoding header, there are potentially multiple compressed
versions of the response and an uncompressed version. In order to instruct client and proxy caches that multiple
versions exist and should be stored, the Vary header is added with an Accept-Encoding value. In ASP.NET Core
1.x, adding the Vary header to the response is accomplished manually:
// ONLY REQUIRED FOR ASP.NET CORE 1.x APPS

private void ManageVaryHeader(HttpContext context)
{
// If the Accept-Encoding header is present, add the Vary header
var accept = context.Request.Headers[HeaderNames.AcceptEncoding];
if (!StringValues.IsNullOrEmpty(accept))
{
context.Response.Headers.Append(HeaderNames.Vary, HeaderNames.AcceptEncoding);
}
}
Middleware issue when behind an Nginx reverse proxy

When a request is proxied by Nginx, the Accept-Encoding header is removed. This prevents the middleware from
compressing the response. For more information, see NGINX: Compression and Decompression. This issue is
tracked by Figure out pass-through compression for Nginx (BasicMiddleware #123).
Working with IIS dynamic compression

If you have an active IIS Dynamic Compression Module configured at the server level that you would like to
disable for an app, disable the module with an addition to the web.config file. For more information, see Disabling
IIS modules.
Troubleshooting
Use a tool like Fiddler, Firebug, or Postman, which allow you to set the Accept-Encoding request header and study
the response headers, size, and body. By default, Response Compression Middleware compresses responses that
meet the following conditions:
The Accept-Encoding header is present with a value of br , gzip , * , or custom encoding that matches a
custom compression provider that you've established. The value must not be identity or have a quality value
(qvalue, q ) setting of 0 (zero).
The MIME type ( Content-Type ) must be set and must match a MIME type configured on the
ResponseCompressionOptions.
The request must not include the Content-Range header.
The request must use insecure protocol (http), unless secure protocol (https) is configured in the Response
Compression Middleware options. Note the danger described above when enabling secure content
compression.
The Accept-Encoding header is present with a value of gzip , * , or custom encoding that matches a custom
compression provider that you've established. The value must not be identity or have a quality value (qvalue,
q ) setting of 0 (zero).
The MIME type ( Content-Type ) must be set and must match a MIME type configured on the
ResponseCompressionOptions.
The request must not include the Content-Range header.
The request must use insecure protocol (http), unless secure protocol (https) is configured in the Response
Compression Middleware options. Note the danger described above when enabling secure content
compression.
Mozilla Developer Network: Accept-Encoding
RFC 7231 Section 3.1.2.1: Content Codings
RFC 7230 Section 4.2.3: Gzip Coding
GZIP file format specification version 4.3
Migration to ASP.NET Core
ASP.NET to ASP.NET Core

Migrate from ASP.NET to ASP.NET Core
Migrate from ASP.NET MVC to ASP.NET Core MVC
Migrate from ASP.NET Web API to ASP.NET Core Web API
Migrate configuration
Migrate authentication and Identity
Migrate ClaimsPrincipal.Current usage
Migrate ASP.NET Membership to ASP.NET Core Identity
Migrate HTTP modules to middleware
ASP.NET Core 1.x to 2.0

Migrate from ASP.NET Core 1.x to 2.0
Migrate authentication and Identity
ASP.NET Core 2.0 to 2.1

Migrate from ASP.NET Core 2.0 to 2.1
Migrate from ASP.NET Core 2.0 to 2.1
By Rick Anderson
See What's new in ASP.NET Core 2.1 for an overview of the new features in ASP.NET Core 2.1.
This article:
Covers the basics of migrating an ASP.NET Core 2.0 app to 2.1.
Provides an overview of the changes to the ASP.NET Core web application templates.
A quick way to get an overview of the changes in 2.1 is to:
Create an ASP.NET Core 2.0 web app named WebApp1.
Commit the WebApp1 in a source control system.
Delete WebApp1 and create an ASP.NET Core 2.1 web app named WebApp1 in the same place.
Review the changes in the 2.1 version.
This article provides an overview on migration to ASP.NET Core 2.1. It doesn't contain a complete list of all
changes needed to migrate to version 2.1. Some projects might require more steps depending on the options
selected when the project was created and modifications made to the project.
Update the project file to use 2.1 versions

Update the project file:
Change the target framework to .NET Core 2.1 by updating the project file to
<TargetFramework>netcoreapp2.1</TargetFramework> .
Replace the package reference for Microsoft.AspNetCore.All with a package reference for
Microsoft.AspNetCore.App . You may need to add dependencies that were removed from
Microsoft.AspNetCore.All . For more information, see Microsoft.AspNetCore.All metapackage for ASP.NET
Core 2.0 and Microsoft.AspNetCore.App metapackage for ASP.NET Core 2.1 and later.
Remove the "Version" attribute on the package reference to Microsoft.AspNetCore.App . Projects which use
<Project Sdk="Microsoft.NET.Sdk.Web"> do not need to set the version. The version will be implied by the target
framework and selected to best match the way ASP.NET Core 2.1 works. (See below for more information.)
For apps that target the .NET Framework, update each package reference to 2.1.
Remove references to <DotNetCliToolReference> elements for the following packages. These tools are
bundled by default in the .NET Core CLI and don't need to be installed separately.
Microsoft.DotNet.Watcher.Tools ( dotnet watch )
Microsoft.EntityFrameworkCore.Tools.DotNet ( dotnet ef )
Microsoft.Extensions.Caching.SqlConfig.Tools ( dotnet sql-cache )
Microsoft.Extensions.SecretManager.Tools ( dotnet user-secrets )
Optional: you can remove the <DotNetCliToolReference> element for
Microsoft.VisualStudio.Web.CodeGeneration.Tools . You can replace this tool with a globally installed version by
running dotnet tool install -g dotnet-aspnet-codegenerator .
For 2.1, a Razor Class Library is the recommended solution to distribute Razor files. If your app uses embedded
views, or otherwise relies on runtime compilation of Razor files, add
<CopyRefAssembliesToPublishDirectory>true</CopyRefAssembliesToPublishDirectory> to your project file.
The following markup shows the template-generated 2.0 project file:
<PropertyGroup>
<UserSecretsId>aspnet-{Project Name}-{GUID}</UserSecretsId>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="2.0.3" PrivateAssets="All" />
<PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.0.4"
</ItemGroup>
<ItemGroup>
<DotNetCliToolReference Include="Microsoft.Extensions.SecretManager.Tools" Version="2.0.2" />
</ItemGroup>
</Project>
The following markup shows the template-generated 2.1 project file:
<PropertyGroup>
<UserSecretsId>aspnet-{Project Name}-{GUID}</UserSecretsId>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
</Project>
Rules for projects targeting the shared framework

ASP.NET Core 2.1 includes the following shared frameworks:
Microsoft.AspNetCore.All
The version specified by the package reference is the minimum required version. For example, a project
referencing the 2.1.1 versions of these packages won't run on a machine with only the 2.1.0 runtime installed.
Known issues for projects targeting the shared framework:
The .NET Core 2.1.300 SDK (first included in Visual Studio 15.6) set the implicit version of
Microsoft.AspNetCore.App to 2.1.0 which caused conflicts with Entity Framework Core 2.1.1. The
recommended solution is to upgrade the .NET Core SDK to 2.1.301 or later. For more information, see
Packages that share dependencies with Microsoft.AspNetCore.App cannot reference patch versions.
All projects that must use Microsoft.AspNetCore.All or Microsoft.AspNetCore.App should add a package
reference for the package in the project file, even if they contain a project reference to another project using
Microsoft.AspNetCore.All or Microsoft.AspNetCore.App .
Example:
MyApp has a package reference to Microsoft.AspNetCore.App .
MyApp.Tests has a project reference to MyApp.csproj .
Add a package reference for Microsoft.AspNetCore.App to MyApp.Tests . For more information, see
Integration testing is hard to set up and may break on shared framework servicing.
Update to the 2.1 Docker images

In ASP.NET Core 2.1, the Docker images migrated to the dotnet/dotnet-docker GitHub repository. The following
table shows the Docker image and tag changes:
2.0 2.1
microsoft/aspnetcore:2.0 microsoft/dotnet:2.1-aspnetcore-runtime
microsoft/aspnetcore-build:2.0 microsoft/dotnet:2.1-sdk
Change the FROM lines in your Dockerfile to use the new image names and tags in the preceding table's 2.1
column. For more information, see Migrating from aspnetcore docker repos to dotnet.
Changes to take advantage of the new code-based idioms that are

recommended in ASP.NET Core 2.1
Changes to Main
The following images show the changes made to the templated generated Program.cs file.
The preceding image shows the 2.0 version with the deletions in red.
The following image shows the 2.1 code. The code in green replaced the 2.0 version:
The following code shows the 2.1 version of Program.cs:

namespace WebApp1
{
{
{
}

}
}
The new Main replaces the call to BuildWebHost with CreateWebHostBuilder. IWebHostBuilder was added to
support a new integration test infrastructure.
Changes to Startup
The following code shows the changes to 2.1 template generated code. All changes are newly added code, except
that UseBrowserLink has been removed:
namespace WebApp1
{
{
{
}

{
{
request.
});
services.AddMvc()
}

{
{
}
else
{
app.UseHsts();
}
// If the app uses Session or TempData based on Session:
app.UseMvc();
}
}
}
The preceding code changes are detailed in:

GDPR support in ASP.NET Core for CookiePolicyOptions and UseCookiePolicy .
HTTP Strict Transport Security Protocol (HSTS ) for UseHsts .
Require HTTPS for UseHttpsRedirection .
SetCompatibilityVersion for SetCompatibilityVersion(CompatibilityVersion.Version_2_1) .
Changes to authentication code
ASP.NET Core 2.1 provides ASP.NET Core Identity as a Razor Class Library (RCL ).
The default 2.1 Identity UI doesn't currently provide significant new features over the 2.0 version. Replacing
Identity with the RCL package is optional. The advantages to replacing the template generated Identity code with
the RCL version include:
Many files are moved out of your source tree.
Any bug fixes or new features to Identity are included in the Microsoft.AspNetCore.App metapackage. You
automatically get the updated Identity when Microsoft.AspNetCore.App is updated.
If you've made non-trivial changes to the template generated Identity code:
The preceding advantages probably do not justify converting to the RCL version.
You can keep your ASP.NET Core 2.0 Identity code, it's fully supported.
Identity 2.1 exposes endpoints with the Identity area. For example, the follow table shows examples of Identity
endpoints that change from 2.0 to 2.1:
2.0 URL 2.1 URL
/Account/Login /Identity/Account/Login
/Account/Logout /Identity/Account/Logout
/Account/Manage /Identity/Account/Manage
Applications that have code using Identity and replace 2.0 Identity UI with the 2.1 Identity Library need to take into
account Identity URLs have /Identity segment prepended to the URIs. One way to handle the new Identity
endpoints is to set up redirects, for example from /Account/Login to /Identity/Account/Login .
Update Identity to version 2.1
The following options are available to update Identity to 2.1.
Use the Identity UI 2.0 code with no changes. Using Identity UI 2.0 code is fully supported. This is a good
approach when significant changes have been made to the generated Identity code.
Delete your existing Identity 2.0 code and Scaffold Identity into your project. Your project will use the ASP.NET
Core Identity Razor Class Library. You can generate code and UI for any of the Identity UI code that you
modified. Apply your code changes to the newly scaffolded UI code.
Delete your existing Identity 2.0 code and Scaffold Identity into your project with the option to Override all
files.
Replace Identity 2.0 UI with the Identity 2.1 Razor Class Library
This section outlines the steps to replace the ASP.NET Core 2.0 template generated Identity code with the
ASP.NET Core Identity Razor Class Library. The following steps are for a Razor Pages project, but the approach
for an MVC project is similar.
Verify the project file is updated to use 2.1 versions
Delete the following folders and all the files in them:
Controllers
Pages/Account/
Extensions
Build the project.
Scaffold Identity into your project:
Select the projects exiting _Layout.cshtml file.
Select the + icon on the right side of the Data context class. Accept the default name.
Select Add to create a new Data context class. Creating a new data context is required for to scaffold.
You remove the new data context in the next section.
Update after scaffolding Identity
Delete the Identity scaffolder generated IdentityDbContext derived class in the Areas/Identity/Data/ folder.
Delete Areas/Identity/IdentityHostingStartup.cs
Update the _LoginPartial.cshtml file:
Move Pages/_LoginPartial.cshtml to Pages/Shared/_LoginPartial.cshtml
Add asp-area="Identity" to the form and anchor links.
Update the <form /> element to
<form asp-area="Identity" asp-page="/Account/Logout" asp-route-returnUrl="@Url.Page("/Index", new {
area = "" })" method="post" id="logoutForm" class="navbar-right">
The following code shows the updated _LoginPartial.cshtml file:
@inject SignInManager<ApplicationUser> SignInManager

@inject UserManager<ApplicationUser> UserManager
{
<form asp-area="Identity" asp-page="/Account/Logout" asp-route-returnUrl="@Url.Page("/Index", new {
area = "" })" method="post" id="logoutForm" class="navbar-right">
<li>
<a asp-area="Identity" asp-page="/Account/Manage/Index" title="Manage">Hello
@UserManager.GetUserName(User)!</a>
</li>
<li>
<button type="submit" class="btn btn-link navbar-btn navbar-link">Log out</button>
</li>
</ul>
</form>
}
else
{
<li><a asp-area="Identity" asp-page="/Account/Register">Register</a></li>
<li><a asp-area="Identity" asp-page="/Account/Login">Log in</a></li>
</ul>
}
Update ConfigureServices with the following code:

{
services.AddMvc();
// Register no-op EmailSender used by account confirmation and password reset

// during development
}
Changes to Razor Pages projects Razor files

The layout file
Move Pages/_Layout.cshtml to Pages/Shared/_Layout.cshtml
The Layout.cshtml file has the following changes:
<partial name="_CookieConsentPartial" /> is added. For more information, see GDPR support in
ASP.NET Core.
jQuery changes from 2.2.0 to 3.3.1
_ValidationScriptsPartial.cshtml
Pages/_ValidationScriptsPartial.cshtml moves to Pages/Shared/_ValidationScriptsPartial.cshtml
jquery.validate/1.14.0 changes to jquery.validate/1.17.0
New files
The following files are added:
Privacy.cshtml
Privacy.cshtml.cs
See GDPR support in ASP.NET Core for information on the preceding files.
Changes to MVC projects Razor files

The layout file
The Layout.cshtml file has the following changes:
<partial name="_CookieConsentPartial" /> is added.
jQuery changes from 2.2.0 to 3.3.1
_ValidationScriptsPartial.cshtml
jquery.validate/1.14.0 changes to jquery.validate/1.17.0
New files and action methods
The following are added:
Views/Home/Privacy.cshtml
The Privacy action method is added to the Home controller.
See GDPR support in ASP.NET Core for information on the preceding files.
Additional changes
If hosting the app on Windows with IIS, install the latest .NET Core Hosting Bundle.
SetCompatibilityVersion
Transport configuration
Migrate from ASP.NET to ASP.NET Core
By Isaac Levin
This article serves as a reference guide for migrating ASP.NET apps to ASP.NET Core.
Prerequisites
Target frameworks
ASP.NET Core projects offer developers the flexibility of targeting .NET Core, .NET Framework, or both. See
Choosing between .NET Core and .NET Framework for server apps to determine which target framework is most
appropriate.
When targeting .NET Framework, projects need to reference individual NuGet packages.
Targeting .NET Core allows you to eliminate numerous explicit package references, thanks to the ASP.NET Core
metapackage. Install the Microsoft.AspNetCore.All metapackage in your project:
<ItemGroup>
</ItemGroup>
When the metapackage is used, no packages referenced in the metapackage are deployed with the app. The .NET
Core Runtime Store includes these assets, and they're precompiled to improve performance. See
Microsoft.AspNetCore.All metapackage for ASP.NET Core 2.x for more detail.
Project structure differences

The .csproj file format has been simplified in ASP.NET Core. Some notable changes include:
Explicit inclusion of files isn't necessary for them to be considered part of the project. This reduces the risk
of XML merge conflicts when working on large teams.
There are no GUID -based references to other projects, which improves file readability.
The file can be edited without unloading it in Visual Studio:
Global.asax file replacement
ASP.NET Core introduced a new mechanism for bootstrapping an app. The entry point for ASP.NET applications
is the Global.asax file. Tasks such as route configuration and filter and area registrations are handled in the
Global.asax file.
public class MvcApplication : System.Web.HttpApplication

{
protected void Application_Start()
{
AreaRegistration.RegisterAllAreas();
FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters);
RouteConfig.RegisterRoutes(RouteTable.Routes);
BundleConfig.RegisterBundles(BundleTable.Bundles);
}
}
This approach couples the application and the server to which it's deployed in a way that interferes with the
implementation. In an effort to decouple, OWIN was introduced to provide a cleaner way to use multiple
frameworks together. OWIN provides a pipeline to add only the modules needed. The hosting environment takes a
Startup function to configure services and the app's request pipeline. Startup registers a set of middleware with
the application. For each request, the application calls each of the middleware components with the head pointer of
a linked list to an existing set of handlers. Each middleware component can add one or more handlers to the
request handling pipeline. This is accomplished by returning a reference to the handler that's the new head of the
list. Each handler is responsible for remembering and invoking the next handler in the list. With ASP.NET Core, the
entry point to an application is Startup , and you no longer have a dependency on Global.asax. When using OWIN
with .NET Framework, use something like the following as a pipeline:
using Owin;
using System.Web.Http;
namespace WebApi
{
// Note: By default all requests go through this OWIN pipeline. Alternatively you can turn this off by
adding an appSetting owin:AutomaticAppStartup with value “false”.
// With this turned off you can still have OWIN apps listening on specific routes by adding routes in
global.asax file using MapOwinPath or MapOwinRoute extensions on RouteTable.Routes
{
// Invoked once at startup to configure your application.
public void Configuration(IAppBuilder builder)
{
HttpConfiguration config = new HttpConfiguration();
config.Routes.MapHttpRoute("Default", "{controller}/{customerID}", new { controller = "Customer",
customerID = RouteParameter.Optional });
config.Formatters.XmlFormatter.UseXmlSerializer = true;
config.Formatters.Remove(config.Formatters.JsonFormatter);
// config.Formatters.JsonFormatter.UseDataContractJsonSerializer = true;
builder.UseWebApi(config);
}
}
}
This configures your default routes, and defaults to XmlSerialization over Json. Add other Middleware to this
pipeline as needed (loading services, configuration settings, static files, etc.).
ASP.NET Core uses a similar approach, but doesn't rely on OWIN to handle the entry. Instead, that's done through
the Program.cs Main method (similar to console applications) and Startup is loaded through there.
namespace WebApplication2
{
{
{
}

.Build();
}
}
Startup must include a Configure method. In Configure , add the necessary middleware to the pipeline. In the
following example (from the default web site template), several extension methods are used to configure the
pipeline with support for:
BrowserLink
Error pages
Static files
ASP.NET Core MVC
Identity
{
{
}
else
{
}
app.UseIdentity();
{
routes.MapRoute(
name: "default",
});
}
The host and application have been decoupled, which provides the flexibility of moving to a different platform in
the future.
NOTE
For a more in-depth reference to ASP.NET Core Startup and Middleware, see Startup in ASP.NET Core
Store configurations
ASP.NET supports storing settings. These setting are used, for example, to support the environment to which the
applications were deployed. A common practice was to store all custom key-value pairs in the <appSettings>
section of the Web.config file:
<appSettings>
<add key="UserName" value="User" />
<add key="Password" value="Password" />
</appSettings>
Applications read these settings using the ConfigurationManager.AppSettings collection in the

System.Configuration namespace:
string userName = System.Web.Configuration.ConfigurationManager.AppSettings["UserName"];

string password = System.Web.Configuration.ConfigurationManager.AppSettings["Password"];
ASP.NET Core can store configuration data for the application in any file and load them as part of middleware
bootstrapping. The default file used in the project templates is appsettings.json:
{
"Logging": {
"LogLevel": {
"Default": "Debug",
}
},
// Here is where you can supply custom configuration settings, Since it is is JSON, everything is
represented as key: value pairs
// Name of section is your choice
"AppConfiguration": {
"UserName": "UserName",
"Password": "Password"
}
}
Loading this file into an instance of IConfiguration inside your application is done in Startup.cs:

{
}
The app reads from Configuration to get the settings:
string userName = Configuration.GetSection("AppConfiguration")["UserName"];

string password = Configuration.GetSection("AppConfiguration")["Password"];
There are extensions to this approach to make the process more robust, such as using Dependency Injection (DI)
to load a service with these values. The DI approach provides a strongly-typed set of configuration objects.
// Assume AppConfiguration is a class representing a strongly-typed version of AppConfiguration section

services.Configure<AppConfiguration>(Configuration.GetSection("AppConfiguration"));
NOTE
For a more in-depth reference to ASP.NET Core configuration, see Configuration in ASP.NET Core.
Native dependency injection

An important goal when building large, scalable applications is the loose coupling of components and services.
Dependency Injection is a popular technique for achieving this, and it's a native component of ASP.NET Core.
In ASP.NET apps, developers rely on a third-party library to implement Dependency Injection. One such library is
Unity, provided by Microsoft Patterns & Practices.
An example of setting up Dependency Injection with Unity is implementing IDependencyResolver that wraps a
UnityContainer :
using Microsoft.Practices.Unity;
using System;
using System.Web.Http.Dependencies;
public class UnityResolver : IDependencyResolver

{
protected IUnityContainer container;
public UnityResolver(IUnityContainer container)

{
if (container == null)
{
throw new ArgumentNullException("container");
}
this.container = container;
}
public object GetService(Type serviceType)

{
try
{
return container.Resolve(serviceType);
}
catch (ResolutionFailedException)
{
return null;
}
}
public IEnumerable<object> GetServices(Type serviceType)

{
try
{
return container.ResolveAll(serviceType);
}
catch (ResolutionFailedException)
{
return new List<object>();
}
}
public IDependencyScope BeginScope()

{
var child = container.CreateChildContainer();
return new UnityResolver(child);
}

{
Dispose(true);
}
protected virtual void Dispose(bool disposing)

{
container.Dispose();
}
}
Create an instance of your UnityContainer , register your service, and set the dependency resolver of
HttpConfiguration to the new instance of UnityResolver for your container:
public static void Register(HttpConfiguration config)
{
var container = new UnityContainer();
container.RegisterType<IProductRepository, ProductRepository>(new HierarchicalLifetimeManager());
config.DependencyResolver = new UnityResolver(container);
// Other Web API configuration not shown.

}
Inject IProductRepository where needed:
public class ProductsController : ApiController

{
private IProductRepository _repository;
public ProductsController(IProductRepository repository)

{
}
// Other controller methods not shown.

}
Because Dependency Injection is part of ASP.NET Core, you can add your service in the ConfigureServices
method of Startup.cs:

{
services.AddTransient<IProductRepository, ProductRepository>();
}
The repository can be injected anywhere, as was true with Unity.
NOTE
For more information on dependency injection, see Dependency injection.
Serve static files

An important part of web development is the ability to serve static, client-side assets. The most common examples
of static files are HTML, CSS, Javascript, and images. These files need to be saved in the published location of the
app (or CDN ) and referenced so they can be loaded by a request. This process has changed in ASP.NET Core.
In ASP.NET, static files are stored in various directories and referenced in the views.
In ASP.NET Core, static files are stored in the "web root" (<content root>/wwwroot), unless configured otherwise.
The files are loaded into the request pipeline by invoking the UseStaticFiles extension method from
Startup.Configure :

{
}
NOTE
If targeting .NET Framework, install the NuGet package Microsoft.AspNetCore.StaticFiles .
For example, an image asset in the wwwroot/images folder is accessible to the browser at a location such as
http://<app>/images/<imageFileName> .
NOTE
For a more in-depth reference to serving static files in ASP.NET Core, see Static files.
Porting Libraries to .NET Core
Migrate from ASP.NET MVC to ASP.NET Core MVC
By Rick Anderson, Daniel Roth, Steve Smith, and Scott Addie

This article shows how to get started migrating an ASP.NET MVC project to ASP.NET Core MVC. In the process,
it highlights many of the things that have changed from ASP.NET MVC. Migrating from ASP.NET MVC is a
multiple step process and this article covers the initial setup, basic controllers and views, static content, and client-
side dependencies. Additional articles cover migrating configuration and identity code found in many ASP.NET
MVC projects.
NOTE
The version numbers in the samples might not be current. You may need to update your projects accordingly.
Create the starter ASP.NET MVC project

To demonstrate the upgrade, we'll start by creating a ASP.NET MVC app. Create it with the name WebApp1 so the
namespace matches the ASP.NET Core project we create in the next step.
Optional: Change the name of the Solution from WebApp1 to Mvc5. Visual Studio displays the new solution name
(Mvc5), which makes it easier to tell this project from the next project.
Create the ASP.NET Core project

Create a new empty ASP.NET Core web app with the same name as the previous project (WebApp1) so the
namespaces in the two projects match. Having the same namespace makes it easier to copy code between the two
projects. You'll have to create this project in a different directory than the previous project to use the same name.
Optional: Create a new ASP.NET Core app using the Web Application project template. Name the project
WebApp1, and select an authentication option of Individual User Accounts. Rename this app to
FullAspNetCore. Creating this project saves you time in the conversion. You can look at the template-generated
code to see the end result or to copy code to the conversion project. It's also helpful when you get stuck on a
conversion step to compare with the template-generated project.
Configure the site to use MVC

When targeting .NET Core, the ASP.NET Core metapackage is added to the project, called
Microsoft.AspNetCore.All by default. This package contains packages like Microsoft.AspNetCore.Mvc and
Microsoft.AspNetCore.StaticFiles . If targeting .NET Framework, package references need to be listed
individually in the *.csproj file.
Microsoft.AspNetCore.Mvc is the ASP.NET Core MVC framework. Microsoft.AspNetCore.StaticFiles is the static
file handler. The ASP.NET Core runtime is modular, and you must explicitly opt in to serve static files (see Static
files).
Open the Startup.cs file and change the code to match the following:
namespace WebApp1
{
{
// For more information on how to configure your application, visit
https://go.microsoft.com/fwlink/?LinkID=398940
{
services.AddMvc();
}
pipeline.
{
{
}
{
routes.MapRoute(
name: "default",
});
}
}
}
The UseStaticFiles extension method adds the static file handler. As mentioned previously, the ASP.NET runtime
is modular, and you must explicitly opt in to serve static files. The UseMvc extension method adds routing. For
more information, see Application Startup and Routing.
Add a controller and view

In this section, you'll add a minimal controller and view to serve as placeholders for the ASP.NET MVC controller
and views you'll migrate in the next section.
Add a Controllers folder.
Add a Controller Class named HomeController.cs to the Controllers folder.
Add a Views folder.
Add a Views/Home folder.
Add a Razor View named Index.cshtml to the Views/Home folder.
The project structure is shown below:

Replace the contents of the Views/Home/Index.cshtml file with the following:
<h1>Hello world!</h1>
Run the app.
See Controllers and Views for more information.

Now that we have a minimal working ASP.NET Core project, we can start migrating functionality from the
ASP.NET MVC project. We need to move the following:
client-side content (CSS, fonts, and scripts)
controllers
views
models
bundling
filters
Log in/out, Identity (This is done in the next tutorial.)
Controllers and views

Copy each of the methods from the ASP.NET MVC HomeController to the new HomeController . Note that
in ASP.NET MVC, the built-in template's controller action method return type is ActionResult; in ASP.NET
Core MVC, the action methods return IActionResult instead. ActionResult implements IActionResult , so
there's no need to change the return type of your action methods.
Copy the About.cshtml, Contact.cshtml, and Index.cshtml Razor view files from the ASP.NET MVC project
to the ASP.NET Core project.
Run the ASP.NET Core app and test each method. We haven't migrated the layout file or styles yet, so the
rendered views only contain the content in the view files. You won't have the layout file generated links for
the About and Contact views, so you'll have to invoke them from the browser (replace 4492 with the port
number used in your project).
http://localhost:4492/home/about
http://localhost:4492/home/contact
Note the lack of styling and menu items. We'll fix that in the next section.
Static content
In previous versions of ASP.NET MVC, static content was hosted from the root of the web project and was
intermixed with server-side files. In ASP.NET Core, static content is hosted in the wwwroot folder. You'll want to
copy the static content from your old ASP.NET MVC app to the wwwroot folder in your ASP.NET Core project. In
this sample conversion:
Copy the favicon.ico file from the old MVC project to the wwwroot folder in the ASP.NET Core project.
The old ASP.NET MVC project uses Bootstrap for its styling and stores the Bootstrap files in the Content and
Scripts folders. The template, which generated the old ASP.NET MVC project, references Bootstrap in the layout
file (Views/Shared/_Layout.cshtml). You could copy the bootstrap.js and bootstrap.css files from the ASP.NET MVC
project to the wwwroot folder in the new project. Instead, we'll add support for Bootstrap (and other client-side
libraries) using CDNs in the next section.
Migrate the layout file

Copy the _ViewStart.cshtml file from the old ASP.NET MVC project's Views folder into the ASP.NET Core
project's Views folder. The _ViewStart.cshtml file has not changed in ASP.NET Core MVC.
Create a Views/Shared folder.
Optional: Copy _ViewImports.cshtml from the FullAspNetCore MVC project's Views folder into the
ASP.NET Core project's Views folder. Remove any namespace declaration in the _ViewImports.cshtml file.
The _ViewImports.cshtml file provides namespaces for all the view files and brings in Tag Helpers. Tag
Helpers are used in the new layout file. The _ViewImports.cshtml file is new for ASP.NET Core.
Copy the _Layout.cshtml file from the old ASP.NET MVC project's Views/Shared folder into the ASP.NET
Core project's Views/Shared folder.
Open _Layout.cshtml file and make the following changes (the completed code is shown below ):
Replace @Styles.Render("~/Content/css") with a <link> element to load bootstrap.css (see below ).
Remove @Scripts.Render("~/bundles/modernizr") .
Comment out the @Html.Partial("_LoginPartial") line (surround the line with @*...*@ ). We'll return to it
in a future tutorial.
Replace @Scripts.Render("~/bundles/jquery") with a <script> element (see below ).
Replace @Scripts.Render("~/bundles/bootstrap") with a <script> element (see below ).
The replacement markup for Bootstrap CSS inclusion:
href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"
integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u"
crossorigin="anonymous">
The replacement markup for jQuery and Bootstrap JavaScript inclusion:
<script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"
integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa"
The updated _Layout.cshtml file is shown below:

<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>@ViewBag.Title - My ASP.NET Application</title>
href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"
integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u"
crossorigin="anonymous">
</head>
<body>
collapse">
</button>
@Html.ActionLink("Application name", "Index", "Home", new { area = "" }, new { @class =
"navbar-brand" })
</div>
<li>@Html.ActionLink("Home", "Index", "Home")</li>
<li>@Html.ActionLink("About", "About", "Home")</li>
<li>@Html.ActionLink("Contact", "Contact", "Home")</li>
</ul>
@*@Html.Partial("_LoginPartial")*@
</div>
</div>
</div>
@RenderBody()
<hr />
<footer>
<p>© @DateTime.Now.Year - My ASP.NET Application</p>
</footer>
</div>
<script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"
integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa"
</body>
</html>
View the site in the browser. It should now load correctly, with the expected styles in place.
Optional: You might want to try using the new layout file. For this project you can copy the layout file from the
FullAspNetCore project. The new layout file uses Tag Helpers and has other improvements.
Configure bundling and minification

For information about how to configure bundling and minification, see Bundling and Minification.
Solve HTTP 500 errors

There are many problems that can cause a HTTP 500 error message that contain no information on the source of
the problem. For example, if the Views/_ViewImports.cshtml file contains a namespace that doesn't exist in your
project, you'll get a HTTP 500 error. By default in ASP.NET Core apps, the UseDeveloperExceptionPage extension is
added to the IApplicationBuilder and executed when the configuration is Development. This is detailed in the
following code:
namespace WebApp1
{
{
// For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?
LinkID=398940
{
services.AddMvc();
}
{
{
}
{
routes.MapRoute(
name: "default",
});
}
}
}
ASP.NET Core converts unhandled exceptions in a web app into HTTP 500 error responses. Normally, error
details aren't included in these responses to prevent disclosure of potentially sensitive information about the
server. See Using the Developer Exception Page in Handle errors for more information.
Tag Helpers
Migrate from ASP.NET Web API to ASP.NET Core

Web APIs are HTTP services that reach a broad range of clients, including browsers and mobile devices. ASP.NET
Core MVC includes support for building Web APIs providing a single, consistent way of building web applications.
In this article, we demonstrate the steps required to migrate a Web API implementation from ASP.NET Web API
to ASP.NET Core MVC.
Review ASP.NET Web API project

This article uses the sample project, ProductsApp, created in the article Getting Started with ASP.NET Web API 2
as its starting point. In that project, a simple ASP.NET Web API project is configured as follows.
In Global.asax.cs, a call is made to WebApiConfig.Register :
using System;
using System.Linq;
using System.Web;
using System.Web.Routing;
namespace ProductsApp
{
public class WebApiApplication : System.Web.HttpApplication
{
protected void Application_Start()
{
GlobalConfiguration.Configure(WebApiConfig.Register);
}
}
}
WebApiConfig is defined in App_Start, and has just one static Register method:
using System;
using System.Linq;
namespace ProductsApp
{
public static class WebApiConfig
{
public static void Register(HttpConfiguration config)
{
// Web API configuration and services
// Web API routes

config.MapHttpAttributeRoutes();
config.Routes.MapHttpRoute(
name: "DefaultApi",
routeTemplate: "api/{controller}/{id}",
defaults: new { id = RouteParameter.Optional }
);
}
}
}
This class configures attribute routing, although it's not actually being used in the project. It also configures the
routing table, which is used by ASP.NET Web API. In this case, ASP.NET Web API will expect URLs to match the
format /api/{controller }/{id }, with {id } being optional.
The ProductsApp project includes just one simple controller, which inherits from ApiController and exposes two
methods:
using ProductsApp.Models;
using System;
using System.Linq;
using System.Net;
namespace ProductsApp.Controllers
{
public class ProductsController : ApiController
{
Product[] products = new Product[]
{
new Product { Id = 1, Name = "Tomato Soup", Category = "Groceries", Price = 1 },
new Product { Id = 2, Name = "Yo-yo", Category = "Toys", Price = 3.75M },
new Product { Id = 3, Name = "Hammer", Category = "Hardware", Price = 16.99M }
};
public IEnumerable<Product> GetAllProducts()

{
return products;
}
public IHttpActionResult GetProduct(int id)

{
var product = products.FirstOrDefault((p) => p.Id == id);
if (product == null)
{
return NotFound();
}
return Ok(product);
}
}
}
Finally, the model, Product, used by the ProductsApp, is a simple class:
namespace ProductsApp.Models
{
{
public string Category { get; set; }
}
}
Now that we have a simple project from which to start, we can demonstrate how to migrate this Web API project
to ASP.NET Core MVC.
Create the Destination Project

Using Visual Studio, create a new, empty solution, and name it WebAPIMigration. Add the existing ProductsApp
project to it, then, add a new ASP.NET Core Web Application Project to the solution. Name the new project
ProductsCore.
Next, choose the Web API project template. We will migrate the ProductsApp contents to this new project.
Delete the Project_Readme.html file from the new project. Your solution should now look like this:
Migrate Configuration
ASP.NET Core no longer uses Global.asax, web.config, or App_Start folders. Instead, all startup tasks are done in
Startup.cs in the root of the project (see Application Startup). In ASP.NET Core MVC, attribute-based routing is
now included by default when UseMvc() is called; and, this is the recommended approach for configuring Web API
routes (and is how the Web API starter project handles routing).
namespace ProductsCore
{
{
{
}
{
services.AddMvc();
}
{
app.UseMvc();
}
}
}
Assuming you want to use attribute routing in your project going forward, no additional configuration is needed.
Simply apply the attributes as needed to your controllers and actions, as is done in the sample ValuesController
class that's included in the Web API starter project:
using System;
using System.Linq;
namespace ProductsCore.Controllers
{
public class ValuesController : Controller
{
// GET api/values
[HttpGet]
{
return new string[] { "value1", "value2" };
}
// GET api/values/5
[HttpGet("{id}")]
public string Get(int id)
{
return "value";
}
// POST api/values
[HttpPost]
public void Post([FromBody]string value)
{
}
// PUT api/values/5
[HttpPut("{id}")]
public void Put(int id, [FromBody]string value)
{
}
// DELETE api/values/5
public void Delete(int id)
{
}
}
}
Note the presence of [controller ] on line 8. Attribute-based routing now supports certain tokens, such as
[controller ] and [action]. These tokens are replaced at runtime with the name of the controller or action,
respectively, to which the attribute has been applied. This serves to reduce the number of magic strings in the
project, and it ensures the routes will be kept synchronized with their corresponding controllers and actions when
automatic rename refactorings are applied.
To migrate the Products API controller, we must first copy ProductsController to the new project. Then simply
include the route attribute on the controller:
You also need to add the [HttpGet] attribute to the two methods, since they both should be called via HTTP Get.
Include the expectation of an "id" parameter in the attribute for GetProduct() :
// /api/products
[HttpGet]
...
// /api/products/1
[HttpGet("{id}")]
At this point, routing is configured correctly; however, we can't yet test it. Additional changes must be made before
ProductsController will compile.
Migrate Models and Controllers

The last step in the migration process for this simple Web API project is to copy over the Controllers and any
Models they use. In this case, simply copy Controllers/ProductsController.cs from the original project to the new
one. Then, copy the entire Models folder from the original project to the new one. Adjust the namespaces to match
the new project name (ProductsCore). At this point, you can build the application, and you will find a number of
compilation errors. These should generally fall into the following categories:
ApiController does not exist
System.Web.Http namespace does not exist
IHttpActionResult does not exist
Fortunately, these are all very easy to correct:
Change ApiController to Controller (you may need to add using Microsoft.AspNetCore.Mvc)
Delete any using statement referring to System.Web.Http
Change any method returning IHttpActionResult to return a IActionResult
Once these changes have been made and unused using statements removed, the migrated ProductsController
class looks like this:
using ProductsCore.Models;
using System.Linq;
namespace ProductsCore.Controllers
{
{
Product[] products = new Product[]
{
new Product { Id = 1, Name = "Tomato Soup", Category = "Groceries", Price = 1 },
new Product { Id = 2, Name = "Yo-yo", Category = "Toys", Price = 3.75M },
new Product { Id = 3, Name = "Hammer", Category = "Hardware", Price = 16.99M }
};
// /api/products
[HttpGet]
public IEnumerable<Product> GetAllProducts()
{
return products;
}
// /api/products/1
[HttpGet("{id}")]
public IActionResult GetProduct(int id)
{
var product = products.FirstOrDefault((p) => p.Id == id);
if (product == null)
{
return NotFound();
}
return Ok(product);
}
}
}
You should now be able to run the migrated project and browse to /api/products; and, you should see the full list
of 3 products. Browse to /api/products/1 and you should see the first product.
ASP.NET 4.x Web API 2 compatibility shim

A useful tool when migrating ASP.NET Web API projects to ASP.NET Core is the
Microsoft.AspNetCore.Mvc.WebApiCompatShim library. The compatibility shim extends ASP.NET Core to allow a
number of different Web API 2 conventions to be used. The sample ported previously in this document is basic
enough that the compatibility shim was not necessary. For larger projects, using the compatibility shim can be
useful for temporarily bridging the API gap between ASP.NET Core and ASP.NET Web API 2.
The Web API compatibility shim is meant to be used as a temporary measure to facilitate migrating large Web API
projects to ASP.NET Core. Over time, projects should be updated to use ASP.NET Core patterns instead of relying
on the compatibility shim.
Compatibility features included in Microsoft.AspNetCore.Mvc.WebApiCompatShim include:
Adds an ApiController type so that controllers' base types don't need to be updated.
Enables Web API-style model binding. ASP.NET Core MVC model binding functions similarly to MVC 5, by
default. The compatibility shim changes model binding to be more similar to Web API 2 model binding
conventions. For example, complex types are automatically bound from the request body.
Extends model binding so that controller actions can take parameters of type HttpRequestMessage .
Adds message formatters allowing actions to return results of type HttpResponseMessage .
Adds additional response methods that Web API 2 actions may have used to serve responses:
HttpResponseMessage generators:
CreateResponse<T>
CreateErrorResponse
Action result methods:
BadRequestErrorMessageResult
ExceptionResult
InternalServerErrorResult
InvalidModelStateResult
NegotiatedContentResult
ResponseMessageResult
Adds an instance of IContentNegotiator to the app's DI container and makes content negotiation-related types
from Microsoft.AspNet.WebApi.Client available. This includes types like DefaultContentNegotiator ,
MediaTypeFormatter , etc.
To use the compatibility shim, you need to:

Install the Microsoft.AspNetCore.Mvc.WebApiCompatShim NuGet package.
Register the compatibility shim's services with the app's DI container by calling
services.AddMvc().AddWebApiConventions() in the app's Startup.ConfigureServices method.
Define Web API-specific routes using MapWebApiRoute on the IRouteBuilder in the app's
IApplicationBuilder.UseMvc call.
Summary
Migrating a simple ASP.NET Web API project to ASP.NET Core MVC is fairly straightforward, thanks to the built-
in support for Web APIs in ASP.NET Core MVC. The main pieces every ASP.NET Web API project will need to
migrate are routes, controllers, and models, along with updates to the types used by controllers and actions.
Migrate configuration to ASP.NET Core

In the previous article, we began migrate an ASP.NET MVC project to ASP.NET Core MVC. In this article, we
migrate configuration.
Setup configuration
ASP.NET Core no longer uses the Global.asax and web.config files that previous versions of ASP.NET utilized. In
earlier versions of ASP.NET, application startup logic was placed in an Application_StartUp method within
Global.asax. Later, in ASP.NET MVC, a Startup.cs file was included in the root of the project; and, it was called
when the application started. ASP.NET Core has adopted this approach completely by placing all startup logic in
the Startup.cs file.
The web.config file has also been replaced in ASP.NET Core. Configuration itself can now be configured, as part of
the application startup procedure described in Startup.cs. Configuration can still utilize XML files, but typically
ASP.NET Core projects will place configuration values in a JSON -formatted file, such as appsettings.json.
ASP.NET Core's configuration system can also easily access environment variables, which can provide a more
secure and robust location for environment-specific values. This is especially true for secrets like connection strings
and API keys that shouldn't be checked into source control. See Configuration to learn more about configuration
in ASP.NET Core.
For this article, we are starting with the partially migrated ASP.NET Core project from the previous article. To
setup configuration, add the following constructor and property to the Startup.cs file located in the root of the
project:

{
}
Note that at this point, the Startup.cs file won't compile, as we still need to add the following using statement:
Add an appsettings.json file to the root of the project using the appropriate item template:
Migrate configuration settings from web.config
Our ASP.NET MVC project included the required database connection string in web.config, in the
<connectionStrings> element. In our ASP.NET Core project, we are going to store this information in the
appsettings.json file. Open appsettings.json, and note that it already includes the following:
{
"Data": {
"DefaultConnection": {
"ConnectionString": "Server=(localdb)\\MSSQLLocalDB;Database=_CHANGE_ME;Trusted_Connection=True;"
}
}
}
In the highlighted line depicted above, change the name of the database from _CHANGE_ME to the name of your
database.
Summary
ASP.NET Core places all startup logic for the application in a single file, in which the necessary services and
dependencies can be defined and configured. It replaces the web.config file with a flexible configuration feature
that can leverage a variety of file formats, such as JSON, as well as environment variables.
Migrate Authentication and Identity to ASP.NET Core
By Steve Smith
In the previous article, we migrated configuration from an ASP.NET MVC project to ASP.NET Core MVC. In this
article, we migrate the registration, login, and user management features.
Configure Identity and Membership

In ASP.NET MVC, authentication and identity features are configured using ASP.NET Identity in Startup.Auth.cs
and IdentityConfig.cs, located in the App_Start folder. In ASP.NET Core MVC, these features are configured in
Startup.cs.
Install the Microsoft.AspNetCore.Identity.EntityFrameworkCore and Microsoft.AspNetCore.Authentication.Cookies
NuGet packages.
Then, open Startup.cs and update the Startup.ConfigureServices method to use Entity Framework and Identity
services:

{
// Add EF services to the services container.
services.AddMvc();
}
At this point, there are two types referenced in the above code that we haven't yet migrated from the ASP.NET
MVC project: ApplicationDbContext and ApplicationUser . Create a new Models folder in the ASP.NET Core
project, and add two classes to it corresponding to these types. You will find the ASP.NET MVC versions of these
classes in /Models/IdentityModels.cs, but we will use one file per class in the migrated project since that's more
clear.
ApplicationUser.cs:
namespace NewMvcProject.Models
{
{
}
}
ApplicationDbContext.cs:
using Microsoft.AspNetCore.Identity.EntityFramework;
using Microsoft.Data.Entity;
namespace NewMvcProject.Models
{
{
: base(options)
{
}
protected override void OnModelCreating(ModelBuilder builder)

{
base.OnModelCreating(builder);
// Customize the ASP.NET Core Identity model and override the defaults if needed.
// For example, you can rename the ASP.NET Core Identity table names and more.
// Add your customizations after calling base.OnModelCreating(builder);
}
}
}
The ASP.NET Core MVC Starter Web project doesn't include much customization of users, or the
ApplicationDbContext . When migrating a real app, you also need to migrate all of the custom properties and
methods of your app's user and DbContext classes, as well as any other Model classes your app utilizes. For
example, if your DbContext has a DbSet<Album> , you need to migrate the Album class.
With these files in place, the Startup.cs file can be made to compile by updating its using statements:
Our app is now ready to support authentication and Identity services. It just needs to have these features exposed
to users.
Migrate registration and login logic

With Identity services configured for the app and data access configured using Entity Framework and SQL Server,
we're ready to add support for registration and login to the app. Recall that earlier in the migration process we
commented out a reference to _LoginPartial in _Layout.cshtml. Now it's time to return to that code, uncomment it,
and add in the necessary controllers and views to support login functionality.
Uncomment the @Html.Partial line in _Layout.cshtml:
<li>@Html.ActionLink("Contact", "Contact", "Home")</li>

</ul>
@*@Html.Partial("_LoginPartial")*@
</div>
</div>
Now, add a new Razor view called _LoginPartial to the Views/Shared folder:
Update _LoginPartial.cshtml with the following code (replace all of its contents):
@inject SignInManager<ApplicationUser> SignInManager
@inject UserManager<ApplicationUser> UserManager
{
<form asp-area="" asp-controller="Account" asp-action="Logout" method="post" id="logoutForm"
class="navbar-right">
<li>
<a asp-area="" asp-controller="Manage" asp-action="Index" title="Manage">Hello
@UserManager.GetUserName(User)!</a>
</li>
<li>
<button type="submit" class="btn btn-link navbar-btn navbar-link">Log out</button>
</li>
</ul>
</form>
}
else
{
<li><a asp-area="" asp-controller="Account" asp-action="Register">Register</a></li>
<li><a asp-area="" asp-controller="Account" asp-action="Login">Log in</a></li>
</ul>
}
At this point, you should be able to refresh the site in your browser.
Summary
ASP.NET Core introduces changes to the ASP.NET Identity features. In this article, you have seen how to migrate
the authentication and user management features of ASP.NET Identity to ASP.NET Core.
Migrate from ClaimsPrincipal.Current
In ASP.NET 4.x projects, it was common to use ClaimsPrincipal.Current to retrieve the current authenticated user's
identity and claims. In ASP.NET Core, this property is no longer set. Code that was depending on it needs to be
updated to get the current authenticated user's identity through a different means.
Context-specific data instead of static data

When using ASP.NET Core, the values of both ClaimsPrincipal.Current and Thread.CurrentPrincipal aren't set.
These properties both represent static state, which ASP.NET Core generally avoids. Instead, ASP.NET Core's
architecture is to retrieve dependencies (like the current user's identity) from context-specific service collections
(using its dependency injection (DI) model). What's more, Thread.CurrentPrincipal is thread static, so it may not
persist changes in some asynchronous scenarios (and ClaimsPrincipal.Current just calls Thread.CurrentPrincipal
by default).
To understand the sorts of problems thread static members can lead to in asynchronous scenarios, consider the
following code snippet:
// Create a ClaimsPrincipal and set Thread.CurrentPrincipal

var identity = new ClaimsIdentity();
identity.AddClaim(new Claim(ClaimTypes.Name, "User1"));
Thread.CurrentPrincipal = new ClaimsPrincipal(identity);
// Check the current user

Console.WriteLine($"Current user: {Thread.CurrentPrincipal?.Identity.Name}");
// For the method to complete asynchronously

await Task.Yield();
// Check the current user after

Console.WriteLine($"Current user: {Thread.CurrentPrincipal?.Identity.Name}");
The preceding sample code sets Thread.CurrentPrincipal and checks its value before and after awaiting an
asynchronous call. Thread.CurrentPrincipal is specific to the thread on which it's set, and the method is likely to
resume execution on a different thread after the await. Consequently, Thread.CurrentPrincipal is present when it's
first checked but is null after the call to await Task.Yield() .
Getting the current user's identity from the app's DI service collection is more testable, too, since test identities can
be easily injected.
Retrieve the current user in an ASP.NET Core app

There are several options for retrieving the current authenticated user's ClaimsPrincipal in ASP.NET Core in place
of ClaimsPrincipal.Current :
ControllerBase.User. MVC controllers can access the current authenticated user with their User property.
HttpContext.User. Components with access to the current HttpContext (middleware, for example) can get
the current user's ClaimsPrincipal from HttpContext.User.
Passed in from caller. Libraries without access to the current HttpContext are often called from controllers
or middleware components and can have the current user's identity passed as an argument.
IHttpContextAccessor. The project being migrated to ASP.NET Core may be too large to easily pass the
current user's identity to all necessary locations. In such cases, IHttpContextAccessor can be used as a
workaround. IHttpContextAccessor is able to access the current HttpContext (if one exists). A short-term
solution to getting the current user's identity in code that hasn't yet been updated to work with ASP.NET
Core's DI-driven architecture would be:
Make IHttpContextAccessor available in the DI container by calling AddHttpContextAccessor in
Get an instance of IHttpContextAccessor during startup and store it in a static variable. The instance is
made available to code that was previously retrieving the current user from a static property.
Retrieve the current user's ClaimsPrincipal using HttpContextAccessor.HttpContext?.User . If this code is
used outside of the context of an HTTP request, the HttpContext is null.
The final option, using IHttpContextAccessor , is contrary to ASP.NET Core principles (preferring injected
dependencies to static dependencies). Plan to eventually remove the dependency on the static
IHttpContextAccessor helper. It can be a useful bridge, though, when migrating large existing ASP.NET apps that
were previously using ClaimsPrincipal.Current .
Migrate from ASP.NET Membership authentication to
ASP.NET Core 2.0 Identity
By Isaac Levin
This article demonstrates migrating the database schema for ASP.NET apps using Membership authentication to
ASP.NET Core 2.0 Identity.
NOTE
This document provides the steps needed to migrate the database schema for ASP.NET Membership-based apps to the
database schema used for ASP.NET Core Identity. For more information about migrating from ASP.NET Membership-based
authentication to ASP.NET Identity, see Migrate an existing app from SQL Membership to ASP.NET Identity. For more
information about ASP.NET Core Identity, see Introduction to Identity on ASP.NET Core.
Review of Membership schema

Prior to ASP.NET 2.0, developers were tasked with creating the entire authentication and authorization process for
their apps. With ASP.NET 2.0, Membership was introduced, providing a boilerplate solution to handling security
within ASP.NET apps. Developers were now able to bootstrap a schema into a SQL Server database with the
aspnet_regsql.exe command. After running this command, the following tables were created in the database.
To migrate existing apps to ASP.NET Core 2.0 Identity, the data in these tables needs to be migrated to the tables
used by the new Identity schema.
ASP.NET Core Identity 2.0 schema

ASP.NET Core 2.0 follows the Identity principle introduced in ASP.NET 4.5. Though the principle is shared, the
implementation between the frameworks is different, even between versions of ASP.NET Core (see Migrate
authentication and Identity to ASP.NET Core 2.0).
The fastest way to view the schema for ASP.NET Core 2.0 Identity is to create a new ASP.NET Core 2.0 app.
Follow these steps in Visual Studio 2017:
Select File > New > Project.
Create a new ASP.NET Core Web Application and name the project CoreIdentitySample.
Select ASP.NET Core 2.0 in the dropdown and then select Web Application. This template produces a Razor
Pages app. Before clicking OK, click Change Authentication.
Choose Individual User Accounts for the Identity templates. Finally, click OK, then OK. Visual Studio creates
a project using the ASP.NET Core Identity template.
ASP.NET Core 2.0 Identity uses Entity Framework Core to interact with the database storing the authentication
data. In order for the newly created app to work, there needs to be a database to store this data. After creating a
new app, the fastest way to inspect the schema in a database environment is to create the database using Entity
Framework migrations. This process creates a database, either locally or elsewhere, which mimics that schema.
Review the preceding documentation for more information.
To create a database with the ASP.NET Core Identity schema, run the Update-Database command in Visual
Studio's Package Manager Console (PMC ) window —it's located at Tools > NuGet Package
Manager > Package Manager Console. PMC supports running Entity Framework commands.
Entity Framework commands use the connection string for the database specified in appsettings.json. The
following connection string targets a database on localhost named asp -net-core-identity. In this setting, Entity
Framework is configured to use the DefaultConnection connection string.
{
"DefaultConnection": "Server=localhost;Database=aspnet-core-
identity;Trusted_Connection=True;MultipleActiveResultSets=true"
}
}
This command builds the database specified with the schema and any data needed for app initialization. The
following image depicts the table structure that's created with the preceding steps.
Migrate the schema

There are subtle differences in the table structures and fields for both Membership and ASP.NET Core Identity.
The pattern has changed substantially for authentication/authorization with ASP.NET and ASP.NET Core apps.
The key objects that are still used with Identity are Users and Roles. Here are mapping tables for Users, Roles, and
UserRoles.
Users
MEMBERSHIP(ASPNET_USERS/A
IDENTITY(ASPNETUSERS) SPNET_MEMBERSHIP)
Field Name Type Field Name Type

MEMBERSHIP(ASPNET_USERS/A
IDENTITY(ASPNETUSERS) SPNET_MEMBERSHIP)
Id string aspnet_Users.UserId string
UserName string aspnet_Users.UserName string
Email string aspnet_Membership.Email string
NormalizedUserName string aspnet_Users.LoweredUserName string
NormalizedEmail string string

aspnet_Membership.LoweredEmail
PhoneNumber string aspnet_Users.MobileAlias string
LockoutEnabled bit aspnet_Membership.IsLockedOutbit
NOTE
Not all the field mappings resemble one-to-one relationships from Membership to ASP.NET Core Identity. The preceding
table takes the default Membership User schema and maps it to the ASP.NET Core Identity schema. Any other custom fields
that were used for Membership need to be mapped manually. In this mapping, there's no map for passwords, as both
password criteria and password salts don't migrate between the two. It's recommended to leave the password as null
and to ask users to reset their passwords. In ASP.NET Core Identity, LockoutEnd should be set to some date in the
future if the user is locked out. This is shown in the migration script.
Roles
IDENTITY(ASPNETROLES) MEMBERSHIP(ASPNET_ROLES)
Id string RoleId string
Name string RoleName string
NormalizedName string LoweredRoleName string
User Roles
MEMBERSHIP(ASPNET_USERSI
IDENTITY(ASPNETUSERROLES) NROLES)
RoleId string RoleId string
UserId string UserId string
Reference the preceding mapping tables when creating a migration script for Users and Roles. The following
example assumes you have two databases on a database server. One database contains the existing ASP.NET
Membership schema and data. The other database was created using steps described earlier. Comments are
included inline for more details.
-- THIS SCRIPT NEEDS TO RUN FROM THE CONTEXT OF THE MEMBERSHIP DB
BEGIN TRANSACTION MigrateUsersAndRoles
use aspnetdb
-- INSERT USERS
INSERT INTO coreidentity.dbo.aspnetusers
(id,
username,
normalizedusername,
passwordhash,
securitystamp,
emailconfirmed,
phonenumber,
phonenumberconfirmed,
twofactorenabled,
lockoutend,
lockoutenabled,
accessfailedcount,
email,
normalizedemail)
SELECT aspnet_users.userid,
aspnet_users.username,
aspnet_users.loweredusername,
--Creates an empty password since passwords don't map between the two schemas
'',
--Security Stamp is a token used to verify the state of an account and is subject to change at any
time. It should be initialized as a new ID.
NewID(),
--EmailConfirmed is set when a new user is created and confirmed via email. Users must have this set
during migration to ensure they're able to reset passwords.
1,
aspnet_users.mobilealias,
CASE
WHEN aspnet_Users.MobileAlias is null THEN 0
ELSE 1
END,
--2-factor Auth likely wasn't setup in Membership for users, so setting as false.
0,
CASE
--Setting lockout date to time in the future (1000 years)
WHEN aspnet_membership.islockedout = 1 THEN Dateadd(year, 1000,
Sysutcdatetime())
ELSE NULL
END,
aspnet_membership.islockedout,
--AccessFailedAccount is used to track failed logins. This is stored in membership in multiple columns.
Setting to 0 arbitrarily.
0,
aspnet_membership.email,
aspnet_membership.loweredemail
FROM aspnet_users
LEFT OUTER JOIN aspnet_membership
ON aspnet_membership.applicationid =
aspnet_users.applicationid
AND aspnet_users.userid = aspnet_membership.userid
LEFT OUTER JOIN coreidentity.dbo.aspnetusers
ON aspnet_membership.userid = aspnetusers.id
WHERE aspnetusers.id IS NULL
-- INSERT ROLES
INSERT INTO coreIdentity.dbo.aspnetroles(id,name)
SELECT roleId,rolename
FROM aspnet_roles;
-- INSERT USER ROLES

INSERT INTO coreidentity.dbo.aspnetuserroles(userid,roleid)
SELECT userid,roleid
FROM aspnet_usersinroles;
IF @@ERROR <> 0
BEGIN
ROLLBACK TRANSACTION MigrateUsersAndRoles
RETURN
END
COMMIT TRANSACTION MigrateUsersAndRoles
After completion of this script, the ASP.NET Core Identity app created earlier is populated with Membership users.
Users need to change their passwords before logging in.
NOTE
If the Membership system had users with user names that didn't match their email address, changes are required to the app
created earlier to accommodate this. The default template expects UserName and Email to be the same. For situations in
which they're different, the login process needs to be modified to use UserName instead of Email .
In the PageModel of the Login Page, located at Pages\Account\Login.cshtml.cs, remove the [EmailAddress]
attribute from the Email property. Rename it to UserName. This requires a change wherever EmailAddress is
mentioned, in the View and PageModel. The result looks like the following:
Next steps
In this tutorial, you learned how to port users from SQL membership to ASP.NET Core 2.0 Identity. For more
information regarding ASP.NET Core Identity, see Introduction to Identity.
Migrate HTTP handlers and modules to ASP.NET
Core middleware
By Matt Perdeck
This article shows how to migrate existing ASP.NET HTTP modules and handlers from system.webserver to
ASP.NET Core middleware.
Modules and handlers revisited

Before proceeding to ASP.NET Core middleware, let's first recap how HTTP modules and handlers work:
Handlers are:
Classes that implement IHttpHandler
Used to handle requests with a given file name or extension, such as .report
Configured in Web.config
Modules are:
Classes that implement IHttpModule
Invoked for every request
Able to short-circuit (stop further processing of a request)
Able to add to the HTTP response, or create their own
Configured in Web.config
The order in which modules process incoming requests is determined by:
1. The application life cycle, which is a series events fired by ASP.NET: BeginRequest, AuthenticateRequest,
etc. Each module can create a handler for one or more events.
2. For the same event, the order in which they're configured in Web.config.
In addition to modules, you can add handlers for the life cycle events to your Global.asax.cs file. These handlers
run after the handlers in the configured modules.
From handlers and modules to middleware
Middleware are simpler than HTTP modules and handlers:
Modules, handlers, Global.asax.cs, Web.config (except for IIS configuration) and the application life cycle
are gone
The roles of both modules and handlers have been taken over by middleware
Middleware are configured using code rather than in Web.config
Pipeline branching lets you send requests to specific middleware, based on not only the URL but also on
request headers, query strings, etc.
Middleware are very similar to modules:
Invoked in principle for every request
Able to short-circuit a request, by not passing the request to the next middleware
Able to create their own HTTP response
Middleware and modules are processed in a different order:
Order of middleware is based on the order in which they're inserted into the request pipeline, while order
of modules is mainly based on application life cycle events
Order of middleware for responses is the reverse from that for requests, while order of modules is the
same for requests and responses
See Create a middleware pipeline with IApplicationBuilder
Note how in the image above, the authentication middleware short-circuited the request.
Migrating module code to middleware

An existing HTTP module will look similar to this:
// ASP.NET 4 module
using System;
using System.Web;
namespace MyApp.Modules
{
public class MyModule : IHttpModule
{
{
}
public void Init(HttpApplication application)

{
application.BeginRequest += (new EventHandler(this.Application_BeginRequest));
application.EndRequest += (new EventHandler(this.Application_EndRequest));
}
private void Application_BeginRequest(Object source, EventArgs e)

{
HttpContext context = ((HttpApplication)source).Context;
// Do something with context near the beginning of request processing.

}
private void Application_EndRequest(Object source, EventArgs e)

{
// Do something with context near the end of request processing.

}
}
}
As shown in the Middleware page, an ASP.NET Core middleware is a class that exposes an Invoke method
taking an HttpContext and returning a Task . Your new middleware will look like this:
// ASP.NET Core middleware
namespace MyApp.Middleware
{
public class MyMiddleware
{
public MyMiddleware(RequestDelegate next)

{
_next = next;
}

{
// Clean up.
}
}
public static class MyMiddlewareExtensions

{
public static IApplicationBuilder UseMyMiddleware(this IApplicationBuilder builder)
{
return builder.UseMiddleware<MyMiddleware>();
}
}
}
The preceding middleware template was taken from the section on writing middleware.
The MyMiddlewareExtensions helper class makes it easier to configure your middleware in your Startup class.
The UseMyMiddleware method adds your middleware class to the request pipeline. Services required by the
middleware get injected in the middleware's constructor.
Your module might terminate a request, for example if the user isn't authorized:
// ASP.NET 4 module that may terminate the request
private void Application_BeginRequest(Object source, EventArgs e)

{
if (TerminateRequest())
{
context.Response.End();
return;
}
}
A middleware handles this by not calling Invoke on the next middleware in the pipeline. Keep in mind that this
doesn't fully terminate the request, because previous middlewares will still be invoked when the response makes
its way back through the pipeline.
// ASP.NET Core middleware that may terminate the request

{
if (!TerminateRequest())
// Clean up.
}
When you migrate your module's functionality to your new middleware, you may find that your code doesn't
compile because the HttpContext class has significantly changed in ASP.NET Core. Later on, you'll see how to
migrate to the new ASP.NET Core HttpContext.
Migrating module insertion into the request pipeline

HTTP modules are typically added to the request pipeline using Web.config:


<configuration>
<system.webServer>
<modules>
<add name="MyModule" type="MyApp.Modules.MyModule"/>
</modules>
</system.webServer>
</configuration>
Convert this by adding your new middleware to the request pipeline in your Startup class:
{
{
}
else
{
}
app.UseMyMiddleware();
app.UseMyMiddlewareWithParams();
var myMiddlewareOptions = Configuration.GetSection("MyMiddlewareOptionsSection").Get<MyMiddlewareOptions>

();
var myMiddlewareOptions2 =
Configuration.GetSection("MyMiddlewareOptionsSection2").Get<MyMiddlewareOptions>();
app.UseMyMiddlewareWithParams(myMiddlewareOptions);
app.UseMyMiddlewareWithParams(myMiddlewareOptions2);
app.UseMyTerminatingMiddleware();
// Create branch to the MyHandlerMiddleware.

// All requests ending in .report will follow this branch.
app.MapWhen(
context => context.Request.Path.ToString().EndsWith(".report"),
appBranch => {
// ... optionally add more middleware to this branch
appBranch.UseMyHandler();
});
app.MapWhen(
context => context.Request.Path.ToString().EndsWith(".context"),
appBranch => {
appBranch.UseHttpContextDemoMiddleware();
});
{
routes.MapRoute(
name: "default",
});
}
The exact spot in the pipeline where you insert your new middleware depends on the event that it handled as a
module ( BeginRequest , EndRequest , etc.) and its order in your list of modules in Web.config.
As previously stated, there's no application life cycle in ASP.NET Core and the order in which responses are
processed by middleware differs from the order used by modules. This could make your ordering decision more
challenging.
If ordering becomes a problem, you could split your module into multiple middleware components that can be
ordered independently.
Migrating handler code to middleware

An HTTP handler looks something like this:
// ASP.NET 4 handler
using System.Web;
namespace MyApp.HttpHandlers
{
public class MyHandler : IHttpHandler
{
public bool IsReusable { get { return true; } }
public void ProcessRequest(HttpContext context)

{
string response = GenerateResponse(context);
context.Response.ContentType = GetContentType();
context.Response.Output.Write(response);
}
// ...
private string GenerateResponse(HttpContext context)

{
string title = context.Request.QueryString["title"];
return string.Format("Title of the report: {0}", title);
}
private string GetContentType()

{
return "text/plain";
}
}
}
In your ASP.NET Core project, you would translate this to a middleware similar to this:
// ASP.NET Core middleware migrated from a handler
namespace MyApp.Middleware
{
public class MyHandlerMiddleware
{
// Must have constructor with this signature, otherwise exception at run time
public MyHandlerMiddleware(RequestDelegate next)
{
// This is an HTTP Handler, so no need to store next
}

{
string response = GenerateResponse(context);
context.Response.ContentType = GetContentType();
await context.Response.WriteAsync(response);
}
// ...
private string GenerateResponse(HttpContext context)

{
string title = context.Request.Query["title"];
return string.Format("Title of the report: {0}", title);
}
private string GetContentType()

{
return "text/plain";
}
}
public static class MyHandlerExtensions

{
public static IApplicationBuilder UseMyHandler(this IApplicationBuilder builder)
{
return builder.UseMiddleware<MyHandlerMiddleware>();
}
}
}
This middleware is very similar to the middleware corresponding to modules. The only real difference is that here
there's no call to _next.Invoke(context) . That makes sense, because the handler is at the end of the request
pipeline, so there will be no next middleware to invoke.
Migrating handler insertion into the request pipeline

Configuring an HTTP handler is done in Web.config and looks something like this:

<configuration>
<system.webServer>
<handlers>
<add name="MyHandler" verb="*" path="*.report" type="MyApp.HttpHandlers.MyHandler"
resourceType="Unspecified" preCondition="integratedMode"/>
</handlers>
</system.webServer>
</configuration>
You could convert this by adding your new handler middleware to the request pipeline in your Startup class,
similar to middleware converted from modules. The problem with that approach is that it would send all requests
to your new handler middleware. However, you only want requests with a given extension to reach your
middleware. That would give you the same functionality you had with your HTTP handler.
One solution is to branch the pipeline for requests with a given extension, using the MapWhen extension method.
You do this in the same Configure method where you add the other middleware:
{
{
}
else
{
}
var myMiddlewareOptions = Configuration.GetSection("MyMiddlewareOptionsSection").Get<MyMiddlewareOptions>

();

app.MapWhen(
appBranch => {
});
app.MapWhen(
appBranch => {
});
{
routes.MapRoute(
name: "default",
});
}
MapWhen takes these parameters:

1. A lambda that takes the HttpContext and returns true if the request should go down the branch. This
means you can branch requests not just based on their extension, but also on request headers, query string
parameters, etc.
2. A lambda that takes an IApplicationBuilder and adds all the middleware for the branch. This means you
can add additional middleware to the branch in front of your handler middleware.
Middleware added to the pipeline before the branch will be invoked on all requests; the branch will have no
impact on them.
Loading middleware options using the options pattern
Some modules and handlers have configuration options that are stored in Web.config. However, in ASP.NET
Core a new configuration model is used in place of Web.config.
The new configuration system gives you these options to solve this:
Directly inject the options into the middleware, as shown in the next section.
Use the options pattern:
1. Create a class to hold your middleware options, for example:
public class MyMiddlewareOptions

{
public string Param1 { get; set; }
public string Param2 { get; set; }
}
2. Store the option values

The configuration system allows you to store option values anywhere you want. However, most sites use
appsettings.json, so we'll take that approach:
{
"MyMiddlewareOptionsSection": {
"Param1": "Param1Value",
"Param2": "Param2Value"
}
}
MyMiddlewareOptionsSection here is a section name. It doesn't have to be the same as the name of your
options class.
3. Associate the option values with the options class
The options pattern uses ASP.NET Core's dependency injection framework to associate the options type
(such as MyMiddlewareOptions ) with a MyMiddlewareOptions object that has the actual options.
Update your Startup class:
a. If you're using appsettings.json, add it to the configuration builder in the Startup constructor:

{
.AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true)
}
b. Configure the options service:

{
// Setup options service
// Load options from section "MyMiddlewareOptionsSection"

services.Configure<MyMiddlewareOptions>(
Configuration.GetSection("MyMiddlewareOptionsSection"));

services.AddMvc();
}
c. Associate your options with your options class:

{
// Setup options service
// Load options from section "MyMiddlewareOptionsSection"

services.Configure<MyMiddlewareOptions>(
Configuration.GetSection("MyMiddlewareOptionsSection"));

services.AddMvc();
}
4. Inject the options into your middleware constructor. This is similar to injecting options into a controller.
public class MyMiddlewareWithParams

{
private readonly MyMiddlewareOptions _myMiddlewareOptions;
public MyMiddlewareWithParams(RequestDelegate next,

IOptions<MyMiddlewareOptions> optionsAccessor)
{
_next = next;
_myMiddlewareOptions = optionsAccessor.Value;
}

{
// Do something with context near the beginning of request processing
// using configuration in _myMiddlewareOptions
// Do something with context near the end of request processing

// using configuration in _myMiddlewareOptions
}
}
The UseMiddleware extension method that adds your middleware to the IApplicationBuilder takes care
of dependency injection.
This isn't limited to IOptions objects. Any other object that your middleware requires can be injected this
way.
Loading middleware options through direct injection

The options pattern has the advantage that it creates loose coupling between options values and their consumers.
Once you've associated an options class with the actual options values, any other class can get access to the
options through the dependency injection framework. There's no need to pass around options values.
This breaks down though if you want to use the same middleware twice, with different options. For example an
authorization middleware used in different branches allowing different roles. You can't associate two different
options objects with the one options class.
The solution is to get the options objects with the actual options values in your Startup class and pass those
directly to each instance of your middleware.
1. Add a second key to appsettings.json
To add a second set of options to the appsettings.json file, use a new key to uniquely identify it:
{
"MyMiddlewareOptionsSection2": {
"Param1": "Param1Value2",
"Param2": "Param2Value2"
},
"MyMiddlewareOptionsSection": {
"Param1": "Param1Value",
"Param2": "Param2Value"
}
}
2. Retrieve options values and pass them to middleware. The Use... extension method (which adds your
middleware to the pipeline) is a logical place to pass in the option values:
{
{
}
else
{
}
var myMiddlewareOptions =
Configuration.GetSection("MyMiddlewareOptionsSection").Get<MyMiddlewareOptions>();

app.MapWhen(
appBranch => {
});
app.MapWhen(
appBranch => {
});
{
routes.MapRoute(
name: "default",
});
}
3. Enable middleware to take an options parameter. Provide an overload of the Use... extension method
(that takes the options parameter and passes it to UseMiddleware ). When UseMiddleware is called with
parameters, it passes the parameters to your middleware constructor when it instantiates the middleware
object.
public static class MyMiddlewareWithParamsExtensions
{
public static IApplicationBuilder UseMyMiddlewareWithParams(
{
return builder.UseMiddleware<MyMiddlewareWithParams>();
}
public static IApplicationBuilder UseMyMiddlewareWithParams(

this IApplicationBuilder builder, MyMiddlewareOptions myMiddlewareOptions)
{
return builder.UseMiddleware<MyMiddlewareWithParams>(
new OptionsWrapper<MyMiddlewareOptions>(myMiddlewareOptions));
}
}
Note how this wraps the options object in an OptionsWrapper object. This implements IOptions , as
expected by the middleware constructor.
Migrating to the new HttpContext

You saw earlier that the Invoke method in your middleware takes a parameter of type HttpContext :
HttpContext has significantly changed in ASP.NET Core. This section shows how to translate the most commonly
used properties of System.Web.HttpContext to the new Microsoft.AspNetCore.Http.HttpContext .
HttpContext
HttpContext.Items translates to:
IDictionary<object, object> items = httpContext.Items;
Unique request ID (no System.Web.HttpContext counterpart)

Gives you a unique id for each request. Very useful to include in your logs.
string requestId = httpContext.TraceIdentifier;
HttpContext.Request
HttpContext.Request.HttpMethod translates to:
string httpMethod = httpContext.Request.Method;
HttpContext.Request.QueryString translates to:

IQueryCollection queryParameters = httpContext.Request.Query;
// If no query parameter "key" used, values will have 0 items

// If single value used for a key (...?key=v1), values will have 1 item ("v1")
// If key has multiple values (...?key=v1&key=v2), values will have 2 items ("v1" and "v2")
IList<string> values = queryParameters["key"];
// If no query parameter "key" used, value will be ""

// If single value used for a key (...?key=v1), value will be "v1"
// If key has multiple values (...?key=v1&key=v2), value will be "v1,v2"
string value = queryParameters["key"].ToString();
HttpContext.Request.Url and HttpContext.Request.RawUrl translate to:
// using Microsoft.AspNetCore.Http.Extensions;
var url = httpContext.Request.GetDisplayUrl();
HttpContext.Request.IsSecureConnection translates to:
var isSecureConnection = httpContext.Request.IsHttps;
HttpContext.Request.UserHostAddress translates to:
var userHostAddress = httpContext.Connection.RemoteIpAddress?.ToString();
HttpContext.Request.Cookies translates to:
IRequestCookieCollection cookies = httpContext.Request.Cookies;

string unknownCookieValue = cookies["unknownCookie"]; // will be null (no exception)
string knownCookieValue = cookies["cookie1name"]; // will be actual value
HttpContext.Request.RequestContext.RouteData translates to:
var routeValue = httpContext.GetRouteValue("key");
HttpContext.Request.Headers translates to:
// using Microsoft.AspNetCore.Http.Headers;
// using Microsoft.Net.Http.Headers;
IHeaderDictionary headersDictionary = httpContext.Request.Headers;
// GetTypedHeaders extension method provides strongly typed access to many headers

var requestHeaders = httpContext.Request.GetTypedHeaders();
CacheControlHeaderValue cacheControlHeaderValue = requestHeaders.CacheControl;
// For unknown header, unknownheaderValues has zero items and unknownheaderValue is ""
IList<string> unknownheaderValues = headersDictionary["unknownheader"];
string unknownheaderValue = headersDictionary["unknownheader"].ToString();
// For known header, knownheaderValues has 1 item and knownheaderValue is the value
IList<string> knownheaderValues = headersDictionary[HeaderNames.AcceptLanguage];
string knownheaderValue = headersDictionary[HeaderNames.AcceptLanguage].ToString();
HttpContext.Request.UserAgent translates to:

string userAgent = headersDictionary[HeaderNames.UserAgent].ToString();
HttpContext.Request.UrlReferrer translates to:
string urlReferrer = headersDictionary[HeaderNames.Referer].ToString();
HttpContext.Request.ContentType translates to:
MediaTypeHeaderValue mediaHeaderValue = requestHeaders.ContentType;

string contentType = mediaHeaderValue?.MediaType.ToString(); // ex. application/x-www-form-urlencoded
string contentMainType = mediaHeaderValue?.Type.ToString(); // ex. application
string contentSubType = mediaHeaderValue?.SubType.ToString(); // ex. x-www-form-urlencoded
System.Text.Encoding requestEncoding = mediaHeaderValue?.Encoding;
HttpContext.Request.Form translates to:
if (httpContext.Request.HasFormContentType)
{
IFormCollection form;
form = httpContext.Request.Form; // sync

// Or
form = await httpContext.Request.ReadFormAsync(); // async
string firstName = form["firstname"];

string lastName = form["lastname"];
}
WARNING
Read form values only if the content sub type is x-www-form-urlencoded or form-data.
HttpContext.Request.InputStream translates to:
string inputBody;
using (var reader = new System.IO.StreamReader(
httpContext.Request.Body, System.Text.Encoding.UTF8))
{
inputBody = reader.ReadToEnd();
}
WARNING
Use this code only in a handler type middleware, at the end of a pipeline.
You can read the raw body as shown above only once per request. Middleware trying to read the body after the first read
will read an empty body.
This doesn't apply to reading a form as shown earlier, because that's done from a buffer.
HttpContext.Response
HttpContext.Response.Status and HttpContext.Response.StatusDescription translate to:
httpContext.Response.StatusCode = StatusCodes.Status200OK;
HttpContext.Response.ContentEncoding and HttpContext.Response.ContentType translate to:
var mediaType = new MediaTypeHeaderValue("application/json");
mediaType.Encoding = System.Text.Encoding.UTF8;
httpContext.Response.ContentType = mediaType.ToString();
HttpContext.Response.ContentType on its own also translates to:
httpContext.Response.ContentType = "text/html";
HttpContext.Response.Output translates to:
string responseContent = GetResponseContent();

await httpContext.Response.WriteAsync(responseContent);
HttpContext.Response.TransmitFile
Serving up a file is discussed here.
HttpContext.Response.Headers
Sending response headers is complicated by the fact that if you set them after anything has been written to the
response body, they will not be sent.
The solution is to set a callback method that will be called right before writing to the response starts. This is best
done at the start of the Invoke method in your middleware. It's this callback method that sets your response
headers.
The following code sets a callback method called SetHeaders :

{
// ...
httpContext.Response.OnStarting(SetHeaders, state: httpContext);
The SetHeaders callback method would look like this:

// using Microsoft.AspNet.Http.Headers;
private Task SetHeaders(object context)

{
var httpContext = (HttpContext)context;
// Set header with single value

httpContext.Response.Headers["ResponseHeaderName"] = "headerValue";
// Set header with multiple values

string[] responseHeaderValues = new string[] { "headerValue1", "headerValue1" };
httpContext.Response.Headers["ResponseHeaderName"] = responseHeaderValues;
// Translating ASP.NET 4's HttpContext.Response.RedirectLocation

httpContext.Response.Headers[HeaderNames.Location] = "http://www.example.com";
// Or
httpContext.Response.Redirect("http://www.example.com");
// GetTypedHeaders extension method provides strongly typed access to many headers

var responseHeaders = httpContext.Response.GetTypedHeaders();
// Translating ASP.NET 4's HttpContext.Response.CacheControl

responseHeaders.CacheControl = new CacheControlHeaderValue
{
MaxAge = new System.TimeSpan(365, 0, 0, 0)
// Many more properties available
};
// If you use .Net 4.6+, Task.CompletedTask will be a bit faster

}
HttpContext.Response.Cookies
Cookies travel to the browser in a Set-Cookie response header. As a result, sending cookies requires the same
callback as used for sending response headers:

{
// ...
httpContext.Response.OnStarting(SetCookies, state: httpContext);
httpContext.Response.OnStarting(SetHeaders, state: httpContext);
The SetCookies callback method would look like the following:
private Task SetCookies(object context)

{
var httpContext = (HttpContext)context;
IResponseCookies responseCookies = httpContext.Response.Cookies;
responseCookies.Append("cookie1name", "cookie1value");
responseCookies.Append("cookie2name", "cookie2value",
new CookieOptions { Expires = System.DateTime.Now.AddDays(5), HttpOnly = true });
// If you use .Net 4.6+, Task.CompletedTask will be a bit faster

}
HTTP Handlers and HTTP Modules Overview
Configuration
Application Startup
Middleware
Migrate from ASP.NET Core 1.x to 2.0
By Scott Addie
In this article, we walk you through updating an existing ASP.NET Core 1.x project to ASP.NET Core 2.0.
Migrating your application to ASP.NET Core 2.0 enables you to take advantage of many new features and
performance improvements.
Existing ASP.NET Core 1.x applications are based off of version-specific project templates. As the ASP.NET Core
framework evolves, so do the project templates and the starter code contained within them. In addition to
updating the ASP.NET Core framework, you need to update the code for your application.
Prerequisites
See Get Started with ASP.NET Core.
Update Target Framework Moniker (TFM)

Projects targeting .NET Core should use the TFM of a version greater than or equal to .NET Core 2.0. Search for
the <TargetFramework> node in the .csproj file, and replace its inner text with netcoreapp2.0 :
Projects targeting .NET Framework should use the TFM of a version greater than or equal to .NET Framework
4.6.1. Search for the <TargetFramework> node in the .csproj file, and replace its inner text with net461 :
<TargetFramework>net461</TargetFramework>
NOTE
.NET Core 2.0 offers a much larger surface area than .NET Core 1.x. If you're targeting .NET Framework solely because of
missing APIs in .NET Core 1.x, targeting .NET Core 2.0 is likely to work.
Update .NET Core SDK version in global.json

If your solution relies upon a global.json file to target a specific .NET Core SDK version, update its version
property to use the 2.0 version installed on your machine:
{
"sdk": {
"version": "2.0.0"
}
}
Update package references

The .csproj file in a 1.x project lists each NuGet package used by the project.
In an ASP.NET Core 2.0 project targeting .NET Core 2.0, a single metapackage reference in the .csproj file replaces
the collection of packages:
<ItemGroup>
</ItemGroup>
All the features of ASP.NET Core 2.0 and Entity Framework Core 2.0 are included in the metapackage.
ASP.NET Core 2.0 projects targeting .NET Framework should continue to reference individual NuGet packages.
Update the Version attribute of each <PackageReference /> node to 2.0.0.
For example, here's the list of <PackageReference /> nodes used in a typical ASP.NET Core 2.0 project targeting
.NET Framework:
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore" Version="2.0.0" />
<PackageReference Include="Microsoft.AspNetCore.Authentication.Cookies" Version="2.0.0" />
<PackageReference Include="Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore" Version="2.0.0" />
<PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="2.0.0" />
<PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.ViewCompilation" Version="2.0.0"
<PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="2.0.0" PrivateAssets="All" />
<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="2.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="2.0.0" PrivateAssets="All" />
<PackageReference Include="Microsoft.VisualStudio.Web.BrowserLink" Version="2.0.0" />
</ItemGroup>
Update .NET Core CLI tools

In the .csproj file, update the Version attribute of each <DotNetCliToolReference /> node to 2.0.0.
For example, here's the list of CLI tools used in a typical ASP.NET Core 2.0 project targeting .NET Core 2.0:
<ItemGroup>
<DotNetCliToolReference Include="Microsoft.Extensions.SecretManager.Tools" Version="2.0.0" />
</ItemGroup>
Rename Package Target Fallback property

The .csproj file of a 1.x project used a PackageTargetFallback node and variable:
<PackageTargetFallback>$(PackageTargetFallback);portable-net45+win8+wp8+wpa81;</PackageTargetFallback>
Rename both the node and variable to AssetTargetFallback :
<AssetTargetFallback>$(AssetTargetFallback);portable-net45+win8+wp8+wpa81;</AssetTargetFallback>
Update Main method in Program.cs
In 1.x projects, the Main method of Program.cs looked like this:
using System.IO;
namespace AspNetCoreDotNetCore1App
{
{
{
.UseKestrel()
.UseApplicationInsights()
.Build();
host.Run();
}
}
}
In 2.0 projects, the Main method of Program.cs has been simplified:
namespace AspNetCoreDotNetCore2App
{
{
{
}

.Build();
}
}
The adoption of this new 2.0 pattern is highly recommended and is required for product features like Entity
Framework (EF ) Core Migrations to work. For example, running Update-Database from the Package Manager
Console window or dotnet ef database update from the command line (on projects converted to ASP.NET Core
2.0) generates the following error:
Unable to create an object of type '<Context>'. Add an implementation of

'IDesignTimeDbContextFactory<Context>' to the project, or see https://go.microsoft.com/fwlink/?linkid=851728
for additional patterns supported at design time.
Add configuration providers

In 1.x projects, adding configuration providers to an app was accomplished via the Startup constructor. The steps
involved creating an instance of ConfigurationBuilder , loading applicable providers (environment variables, app
settings, etc.), and initializing a member of IConfigurationRoot .

{
.AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
.AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true);
{
}
}
The preceding example loads the Configuration member with configuration settings from appsettings.json as well
as any appsettings.<EnvironmentName>.json file matching the IHostingEnvironment.EnvironmentName property.
The location of these files is at the same path as Startup.cs.
In 2.0 projects, the boilerplate configuration code inherent to 1.x projects runs behind-the-scenes. For example,
environment variables and app settings are loaded at startup. The equivalent Startup.cs code is reduced to
IConfiguration initialization with the injected instance:

{
}
To remove the default providers added by WebHostBuilder.CreateDefaultBuilder , invoke the Clear method on the
IConfigurationBuilder.Sources property inside of ConfigureAppConfiguration . To add providers back, utilize the
ConfigureAppConfiguration method in Program.cs:

{
}

.ConfigureAppConfiguration((hostContext, config) =>
{
// delete all default configuration providers
config.Sources.Clear();
config.AddJsonFile("myconfig.json", optional: true);
})
.Build();
The configuration used by the CreateDefaultBuilder method in the preceding code snippet can be seen here.
For more information, see Configuration in ASP.NET Core.
Move database initialization code
In 1.x projects using EF Core 1.x, a command such as dotnet ef migrations add does the following:
1. Instantiates a Startup instance
2. Invokes the ConfigureServices method to register all services with dependency injection (including DbContext
types)
3. Performs its requisite tasks
In 2.0 projects using EF Core 2.0, Program.BuildWebHost is invoked to obtain the application services. Unlike 1.x,
this has the additional side effect of invoking Startup.Configure . If your 1.x app invoked database initialization
code in its Configure method, unexpected problems can occur. For example, if the database doesn't yet exist, the
seeding code runs before the EF Core Migrations command execution. This problem causes a
dotnet ef migrations list command to fail if the database doesn't yet exist.
Consider the following 1.x seed initialization code in the Configure method of Startup.cs:
{
routes.MapRoute(
name: "default",
});
SeedData.Initialize(app.ApplicationServices);
In 2.0 projects, move the SeedData.Initialize call to the Main method of Program.cs:

{
try
{
}
{
}
}
host.Run();
As of 2.0, it's bad practice to do anything in BuildWebHost except build and configure the web host. Anything that's
about running the application should be handled outside of BuildWebHost — typically in the Main method of
Program.cs.
Review Razor view compilation setting

Faster application startup time and smaller published bundles are of utmost importance to you. For these reasons,
Razor view compilation is enabled by default in ASP.NET Core 2.0.
Setting the MvcRazorCompileOnPublish property to true is no longer required. Unless you're disabling view
compilation, the property may be removed from the .csproj file.
When targeting .NET Framework, you still need to explicitly reference the
Microsoft.AspNetCore.Mvc.Razor.ViewCompilation NuGet package in your .csproj file:
<PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.ViewCompilation" Version="2.0.0" PrivateAssets="All"

/>
Rely on Application Insights "light-up" features

Effortless setup of application performance instrumentation is important. You can now rely on the new Application
Insights "light-up" features available in the Visual Studio 2017 tooling.
ASP.NET Core 1.1 projects created in Visual Studio 2017 added Application Insights by default. If you're not using
the Application Insights SDK directly, outside of Program.cs and Startup.cs, follow these steps:
1. If targeting .NET Core, remove the following <PackageReference /> node from the .csproj file:
<PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.0.0" />
2. If targeting .NET Core, remove the UseApplicationInsights extension method invocation from Program.cs:

{
.UseKestrel()
.UseApplicationInsights()
.Build();
host.Run();
}
3. Remove the Application Insights client-side API call from _Layout.cshtml. It comprises the following two
lines of code:

If you are using the Application Insights SDK directly, continue to do so. The 2.0 metapackage includes the latest
version of Application Insights, so a package downgrade error appears if you're referencing an older version.
Adopt authentication/Identity improvements

ASP.NET Core 2.0 has a new authentication model and a number of significant changes to ASP.NET Core
Identity. If you created your project with Individual User Accounts enabled, or if you have manually added
authentication or Identity, see Migrate Authentication and Identity to ASP.NET Core 2.0.
Breaking Changes in ASP.NET Core 2.0
Migrate authentication and Identity to ASP.NET Core
2.0
By Scott Addie and Hao Kung

ASP.NET Core 2.0 has a new model for authentication and Identity which simplifies configuration by using
services. ASP.NET Core 1.x applications that use authentication or Identity can be updated to use the new model
as outlined below.
Authentication Middleware and services

In 1.x projects, authentication is configured via middleware. A middleware method is invoked for each
authentication scheme you want to support.
The following 1.x example configures Facebook authentication with Identity in Startup.cs:

{
}
public void Configure(IApplicationBuilder app, ILoggerFactory loggerfactory)

{
app.UseIdentity();
app.UseFacebookAuthentication(new FacebookOptions {
AppId = Configuration["auth:facebook:appid"],
AppSecret = Configuration["auth:facebook:appsecret"]
});
}
In 2.0 projects, authentication is configured via services. Each authentication scheme is registered in the
ConfigureServices method of Startup.cs. The UseIdentity method is replaced with UseAuthentication .
The following 2.0 example configures Facebook authentication with Identity in Startup.cs:

{
// If you want to tweak Identity cookies, they're no longer part of IdentityOptions.

services.ConfigureApplicationCookie(options => options.LoginPath = "/Account/LogIn");
.AddFacebook(options =>
{
options.AppId = Configuration["auth:facebook:appid"];
options.AppSecret = Configuration["auth:facebook:appsecret"];
});
}
public void Configure(IApplicationBuilder app, ILoggerFactory loggerfactory) {

}
The UseAuthentication method adds a single authentication middleware component which is responsible for
automatic authentication and the handling of remote authentication requests. It replaces all of the individual
middleware components with a single, common middleware component.
Below are 2.0 migration instructions for each major authentication scheme.
Cookie -based authentication
Select one of the two options below, and make the necessary changes in Startup.cs:
1. Use cookies with Identity
Replace UseIdentity with UseAuthentication in the Configure method:
Invoke the AddIdentity method in the ConfigureServices method to add the cookie authentication
services.
Optionally, invoke the ConfigureApplicationCookie or ConfigureExternalCookie method in the
ConfigureServices method to tweak the Identity cookie settings.
services.ConfigureApplicationCookie(options => options.LoginPath = "/Account/LogIn");
2. Use cookies without Identity

Replace the UseCookieAuthentication method call in the Configure method with UseAuthentication :
Invoke the AddAuthentication and AddCookie methods in the ConfigureServices method:
// If you don't want the cookie to be automatically authenticated and assigned to

HttpContext.User,
// remove the CookieAuthenticationDefaults.AuthenticationScheme parameter passed to
AddAuthentication.
{
options.LoginPath = "/Account/LogIn";
options.LogoutPath = "/Account/LogOff";
});
JWT Bearer Authentication

Make the following changes in Startup.cs:
Replace the UseJwtBearerAuthentication method call in the Configure method with UseAuthentication :
Invoke the AddJwtBearer method in the ConfigureServices method:

services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
.AddJwtBearer(options =>
{
options.Audience = "http://localhost:5001/";
options.Authority = "http://localhost:5000/";
});
This code snippet doesn't use Identity, so the default scheme should be set by passing
JwtBearerDefaults.AuthenticationScheme to the AddAuthentication method.
OpenID Connect (OIDC ) authentication

Replace the UseOpenIdConnectAuthentication method call in the Configure method with UseAuthentication :
Invoke the AddOpenIdConnect method in the ConfigureServices method:
{
options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
})
.AddCookie()
.AddOpenIdConnect(options =>
{
options.Authority = Configuration["auth:oidc:authority"];
options.ClientId = Configuration["auth:oidc:clientid"];
});
Replace the UseFacebookAuthentication method call in the Configure method with UseAuthentication :
Invoke the AddFacebook method in the ConfigureServices method:
.AddFacebook(options =>
{
options.AppId = Configuration["auth:facebook:appid"];
options.AppSecret = Configuration["auth:facebook:appsecret"];
});
Replace the UseGoogleAuthentication method call in the Configure method with UseAuthentication :
Invoke the AddGoogle method in the ConfigureServices method:

.AddGoogle(options =>
{
options.ClientId = Configuration["auth:google:clientid"];
options.ClientSecret = Configuration["auth:google:clientsecret"];
});
Microsoft Account authentication

Replace the UseMicrosoftAccountAuthentication method call in the Configure method with
UseAuthentication :
Invoke the AddMicrosoftAccount method in the ConfigureServices method:
.AddMicrosoftAccount(options =>
{
options.ClientId = Configuration["auth:microsoft:clientid"];
options.ClientSecret = Configuration["auth:microsoft:clientsecret"];
});
Replace the UseTwitterAuthentication method call in the Configure method with UseAuthentication :
Invoke the AddTwitter method in the ConfigureServices method:
.AddTwitter(options =>
{
options.ConsumerKey = Configuration["auth:twitter:consumerkey"];
options.ConsumerSecret = Configuration["auth:twitter:consumersecret"];
});
Setting default authentication schemes

In 1.x, the AutomaticAuthenticate and AutomaticChallenge properties of the AuthenticationOptions base class
were intended to be set on a single authentication scheme. There was no good way to enforce this.
In 2.0, these two properties have been removed as properties on the individual AuthenticationOptions instance.
They can be configured in the AddAuthentication method call within the ConfigureServices method of Startup.cs:
services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme);
In the preceding code snippet, the default scheme is set to CookieAuthenticationDefaults.AuthenticationScheme

("Cookies").
Alternatively, use an overloaded version of the AddAuthentication method to set more than one property. In the
following overloaded method example, the default scheme is set to
CookieAuthenticationDefaults.AuthenticationScheme . The authentication scheme may alternatively be specified
within your individual [Authorize] attributes or authorization policies.
{
options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
});
Define a default scheme in 2.0 if one of the following conditions is true:

You want the user to be automatically signed in
You use the [Authorize] attribute or authorization policies without specifying schemes
An exception to this rule is the AddIdentity method. This method adds cookies for you and sets the default
authenticate and challenge schemes to the application cookie IdentityConstants.ApplicationScheme . Additionally, it
sets the default sign-in scheme to the external cookie IdentityConstants.ExternalScheme .
Use HttpContext authentication extensions

The IAuthenticationManager interface is the main entry point into the 1.x authentication system. It has been
replaced with a new set of HttpContext extension methods in the Microsoft.AspNetCore.Authentication
namespace.
For example, 1.x projects reference an Authentication property:
// Clear the existing external cookie to ensure a clean login process

await HttpContext.Authentication.SignOutAsync(_externalCookieScheme);
In 2.0 projects, import the Microsoft.AspNetCore.Authentication namespace, and delete the Authentication
property references:

await HttpContext.SignOutAsync(IdentityConstants.ExternalScheme);
Windows Authentication (HTTP.sys / IISIntegration)

There are two variations of Windows authentication:
1. The host only allows authenticated users
2. The host allows both anonymous and authenticated users
The first variation described above is unaffected by the 2.0 changes.
The second variation described above is affected by the 2.0 changes. As an example, you may be allowing
anonymous users into your application at the IIS or HTTP.sys layer but authorizing users at the Controller level. In
this scenario, set the default scheme to IISDefaults.AuthenticationScheme in the ConfigureServices method of
Startup.cs:
services.AddAuthentication(IISDefaults.AuthenticationScheme);
Failure to set the default scheme accordingly prevents the authorize request to challenge from working.
IdentityCookieOptions instances
A side effect of the 2.0 changes is the switch to using named options instead of cookie options instances. The
ability to customize the Identity cookie scheme names is removed.
For example, 1.x projects use constructor injection to pass an IdentityCookieOptions parameter into
AccountController.cs. The external cookie authentication scheme is accessed from the provided instance:
public AccountController(
UserManager<ApplicationUser> userManager,
SignInManager<ApplicationUser> signInManager,
IOptions<IdentityCookieOptions> identityCookieOptions,
IEmailSender emailSender,
ISmsSender smsSender,
{
_externalCookieScheme = identityCookieOptions.Value.ExternalCookieAuthenticationScheme;
_smsSender = smsSender;
_logger = loggerFactory.CreateLogger<AccountController>();
}
The aforementioned constructor injection becomes unnecessary in 2.0 projects, and the _externalCookieScheme
field can be deleted:
public AccountController(
UserManager<ApplicationUser> userManager,
SignInManager<ApplicationUser> signInManager,
IEmailSender emailSender,
ISmsSender smsSender,
{
_smsSender = smsSender;
_logger = loggerFactory.CreateLogger<AccountController>();
}
The IdentityConstants.ExternalScheme constant can be used directly:

await HttpContext.SignOutAsync(IdentityConstants.ExternalScheme);
Add IdentityUser POCO navigation properties

The Entity Framework (EF ) Core navigation properties of the base IdentityUser POCO (Plain Old CLR Object)
have been removed. If your 1.x project used these properties, manually add them back to the 2.0 project:
/// <summary>
/// Navigation property for the roles this user belongs to.
/// </summary>
public virtual ICollection<IdentityUserRole<int>> Roles { get; } = new List<IdentityUserRole<int>>();
/// <summary>
/// Navigation property for the claims this user possesses.
/// </summary>
public virtual ICollection<IdentityUserClaim<int>> Claims { get; } = new List<IdentityUserClaim<int>>();
/// <summary>
/// Navigation property for this users login accounts.
/// </summary>
public virtual ICollection<IdentityUserLogin<int>> Logins { get; } = new List<IdentityUserLogin<int>>();
To prevent duplicate foreign keys when running EF Core Migrations, add the following to your IdentityDbContext
class' OnModelCreating method (after the base.OnModelCreating(); call):
protected override void OnModelCreating(ModelBuilder builder)

{
base.OnModelCreating(builder);
// Customize the ASP.NET Core Identity model and override the defaults if needed.
// For example, you can rename the ASP.NET Core Identity table names and more.
// Add your customizations after calling base.OnModelCreating(builder);
builder.Entity<ApplicationUser>()
.HasMany(e => e.Claims)
.WithOne()
.HasForeignKey(e => e.UserId)
.IsRequired()
.OnDelete(DeleteBehavior.Cascade);
.HasMany(e => e.Logins)
.WithOne()
.IsRequired()
.HasMany(e => e.Roles)
.WithOne()
.IsRequired()
}
Replace GetExternalAuthenticationSchemes
The synchronous method GetExternalAuthenticationSchemes was removed in favor of an asynchronous version.
1.x projects have the following code in ManageController.cs:
var otherLogins = _signInManager.GetExternalAuthenticationSchemes().Where(auth => userLogins.All(ul =>

auth.AuthenticationScheme != ul.LoginProvider)).ToList();
This method appears in Login.cshtml too:

var loginProviders = SignInManager.GetExternalAuthenticationSchemes().ToList();
<div>
<p>
@foreach (var provider in loginProviders)
{
<button type="submit" class="btn btn-default" name="provider"
value="@provider.AuthenticationScheme" title="Log in using your @provider.DisplayName
account">@provider.AuthenticationScheme</button>
}
</p>
</div>
</form>
}
In 2.0 projects, use the GetExternalAuthenticationSchemesAsync method:
var schemes = await _signInManager.GetExternalAuthenticationSchemesAsync();

var otherLogins = schemes.Where(auth => userLogins.All(ul => auth.Name != ul.LoginProvider)).ToList();
In Login.cshtml, the AuthenticationScheme property accessed in the foreach loop changes to Name :
var loginProviders = (await SignInManager.GetExternalAuthenticationSchemesAsync()).ToList();

<div>
<p>
@foreach (var provider in loginProviders)
{
<button type="submit" class="btn btn-default" name="provider" value="@provider.Name"
title="Log in using your @provider.DisplayName account">@provider.DisplayName</button>
}
</p>
</div>
</form>
}
ManageLoginsViewModel property change

A ManageLoginsViewModel object is used in the ManageLogins action of ManageController.cs. In 1.x projects, the
object's OtherLogins property return type is IList<AuthenticationDescription> . This return type requires an
import of Microsoft.AspNetCore.Http.Authentication :
using Microsoft.AspNetCore.Http.Authentication;
namespace AspNetCoreDotNetCore1App.Models.ManageViewModels
{
public class ManageLoginsViewModel
{
public IList<UserLoginInfo> CurrentLogins { get; set; }
public IList<AuthenticationDescription> OtherLogins { get; set; }

}
}
In 2.0 projects, the return type changes to IList<AuthenticationScheme> . This new return type requires replacing
the Microsoft.AspNetCore.Http.Authentication import with a Microsoft.AspNetCore.Authentication import.
using Microsoft.AspNetCore.Authentication;
namespace AspNetCoreDotNetCore2App.Models.ManageViewModels
{
public class ManageLoginsViewModel
{
public IList<UserLoginInfo> CurrentLogins { get; set; }
public IList<AuthenticationScheme> OtherLogins { get; set; }

}
}
For additional details and discussion, see the Discussion for Auth 2.0 issue on GitHub.

Core

Uploaded by

Document Informationclick to expand document informationIt is all about .net core

Document Informationclick to expand document information

Copyright:

Available Formats

Core

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Core

Uploaded by

Copyright:

Available Formats

Contents

By Daniel Roth, Rick Anderson, and Shaun Luttin

Why use ASP.NET Core?

Build web APIs and web UI using ASP.NET Core MVC

ASP.NET Core targeting .NET Framework

Razor class libraries

Identity UI library & scaffolding

public BasicTests(WebApplicationFactory<RazorPagesProject.Startup> factory)

For more information, see the Integration tests topic.

Kestrel transport configuration

Generic host builder

Updated SPA templates

Razor Pages search for Razor assets

Razor Pages in an area

MVC compatibility version

Migrate from 2.0 to 2.1

ASP.NET Core metapackage

.NET Standard 2.0

WebListener renamed to HTTP.sys

Enhanced HTTP header support

var data = Encoding.UTF8.GetBytes("This is a sample text from a binary array");

Hosting startup and Application Insights

Automatic use of anti-forgery tokens

Razor support for C# 7.1

ASP.NET Core 1.1 includes the following new features:

Choosing between versions 1.0 and 1.1 of ASP.NET Core

1. Install the .NET Core 2.1 SDK or later.

dotnet new webapp -o aspnetcoreapp

3. Trust the HTTPS development certificate:

The preceding command displays the following dialog:

Select Yes if you agree to trust the development certificate.

<p>Hello, world! The time on the server is @DateTime.Now</p>

7. Browse to http://localhost:5001/About and verify the changes are displayed.

dotnet new razor -o aspnetcoreapp

3. Run the app with the following commands:

<p>Hello, world! The time on the server is @DateTime.Now</p>

6. Browse to http://localhost:5000/About and verify the changes.

4. Create a new ASP.NET Core project.

dotnet new web

5. Restore the packages.

6. Run the app.

The dotnet run command builds the app first, if needed.

By Rick Anderson and Ryan Nowak

Creating a Razor Pages project

public void Configure(IApplicationBuilder app)

Consider a basic page:

<h2>Separate page model</h2>

The Pages/Index2.cshtml.cs page model:

public void OnGet()

FILE NAME AND PATH MATCHING URL

/Pages/Store/Index.cshtml /Store or /Store/Index

Writing a basic form

public void ConfigureServices(IServiceCollection services)

public void Configure(IApplicationBuilder app)

The data model:

public DbSet<Customer> Customers { get; set; }

The Pages/Create.cshtml view file:

<button type="submit" formaction="/?id=1&handler=delete">delete</button>