Contents

ASP.NET Core documentation

Overview
About ASP.NET Core
Compare ASP.NET Core and ASP.NET
Compare .NET Core and .NET Framework
Get started
What's new
What's new in 2.2
What's new in 2.1
What's new in 2.0
What's new in 1.1
Tutorials
Web apps
Razor Pages
Overview
Get started
Add a model
Scaffolding
Work with a database
Update the pages
Add search
Add a new field
Add validation
MVC
Overview
Get started
Add a controller
Add a view
Add a model
 Work with a database
Controller actions and views
Add search
Add a new field
Add validation
Examine the Details and Delete methods
Blazor
Web API apps
Create a web API
Web API with MongoDB
Web API with jQuery
Backend for mobile
Real-time web apps
SignalR with JavaScript
SignalR with TypeScript
Remote Procedure Call apps
Get started with gRPC service
Data access
EF Core with Razor Pages
Get started
Create, Read, Update, and Delete
Sort, filter, page, and group
Migrations
Create a complex data model
Read related data
Update related data
Handle concurrency conflicts
EF Core with MVC, existing database
EF Core with MVC, new database
EF Core with MVC, 10 tutorials
Overview
Get started
 Create, Read, Update, and Delete
Sort, filter, page, and group
Migrations
Create a complex data model
Read related data
Update related data
Handle concurrency conflicts
Inheritance
Advanced topics
Tutorials (Microsoft Learn)
Web API apps
Data access
Fundamentals
Overview
The Startup class
Dependency injection (services)
Middleware
Host
Generic Host
Web Host
Servers
Configuration
Options
Environments (dev, stage, prod)
Logging
Routing
Handle errors
Make HTTP requests
Static files
Web apps
Razor Pages
Introduction
 Tutorial
Overview
Get started
Add a model
Scaffolding
Work with a database
Update the pages
Add search
Add a new field
Add validation
Filters
Route and app conventions
Upload files
Razor SDK
MVC
Overview
Tutorial
Overview
Get started
Add a controller
Add a view
Add a model
Work with a database
Controller actions and views
Add search
Add a new field
Add validation
Examine the Details and Delete methods
Views
Partial views
Controllers
Routing
 File uploads
Dependency injection - controllers
Dependency injection - views
Unit test
Blazor
Overview
Supported platforms
Get started
Hosting models
Build your first app
Components
Forms and validation
Component libraries
Layouts
Dependency injection
Routing
JavaScript interop
Security and Identity
State management
Handle errors
Debug
Call a web API
Hosting and deployment
Overview
Client-side
Server-side
Configure the Linker
Client-side development
Single Page Apps
Angular
React
React with Redux
 JavaScript Services
LibMan
Overview
CLI
Visual Studio
Grunt
Bower
Bundle and minify
Browser Link
Session and app state
Layout
Razor syntax
Razor class libraries
Tag Helpers
Overview
Create Tag Helpers
Use Tag Helpers in forms
Tag Helper Components
Built-in Tag Helpers
Anchor
Cache
Distributed Cache
Environment
Form
Image
Input
Label
Partial
Select
Textarea
Validation Message
Validation Summary
 Advanced
View components
View compilation
App model
Filters
Areas
App parts
aspnet-codegenerator
Web API apps
Overview
Tutorials
Create a web API
Web API with MongoDB
Swagger / OpenAPI
Overview
Get started with Swashbuckle
Get started with NSwag
Action return types
Format response data
Custom formatters
Analyzers
Conventions
Test APIs with HTTP REPL
Real-time apps
SignalR overview
Supported platforms
Tutorials
SignalR with JavaScript
SignalR with TypeScript
Samples
Server concepts
Hubs
 Send from outside a hub
Users and groups
API design considerations
Clients
.NET client
.NET API reference
Java client
Java API reference
JavaScript client
JavaScript API reference
Hosting and scaling
Overview
Azure App Service
Redis backplane
SignalR with background services
Configuration
Authentication and authorization
Security considerations
MessagePack Hub Protocol
Streaming
Compare SignalR and SignalR Core
WebSockets without SignalR
Logging and diagnostics
Remote Procedure Call apps
Introduction to gRPC services
gRPC services with C#
gRPC services with ASP.NET Core
Configuration
Authentication and authorization
Security considerations
Migrating gRPC services from C Core to ASP.NET Core
Comparing gRPC services with HTTP APIs
Test, debug, and troubleshoot
Unit testing
Razor Pages unit tests
Test controllers
Remote debugging
Snapshot debugging
Snapshot debugging in Visual Studio
Integration tests
Load and stress testing
Troubleshoot
Logging
Troubleshoot Azure and IIS
Azure and IIS errors reference
Data access
Tutorials
EF Core with Razor Pages
Get started
Create, Read, Update, and Delete
Sort, filter, page, and group
Migrations
Create a complex data model
Read related data
Update related data
Handle concurrency conflicts
EF Core with MVC, new database
EF Core with MVC, existing database
EF Core with MVC, 10 tutorials
Overview
Get started
Create, Read, Update, and Delete
Sort, filter, page, and group
Migrations
 Create a complex data model
Read related data
Update related data
Handle concurrency conflicts
Inheritance
Advanced topics
EF 6 with ASP.NET Core
Azure Storage with Visual Studio
Connected Services
Blob storage
Queue storage
Table storage
Hosting and deployment
Overview
Host on Azure App Service
Overview
Publish with Visual Studio
Publish with Visual Studio for Mac
Publish with CLI tools
Publish with Visual Studio and Git
Continuous deployment with Azure Pipelines
ASP.NET Core Module
Troubleshoot
Errors reference
DevOps
Overview
Tools and downloads
Deploy to App Service
Continuous integration and deployment
Monitor and troubleshoot
Next steps
Host on Windows with IIS
 Overview
Publish to IIS tutorial
ASP.NET Core Module
IIS support in Visual Studio
IIS Modules
Troubleshoot
Errors reference
Transform web.config
Kestrel
HTTP.sys
Host in a Windows service
Host on Linux with Nginx
Host on Linux with Apache
Host in Docker
Overview
Build Docker images
Visual Studio Tools
Publish to a Docker image
Sample Docker images
Proxy and load balancer configuration
Host in a web farm
Visual Studio publish profiles
Visual Studio for Mac publish to folder
Directory structure
Health checks
Blazor
Overview
Client-side
Server-side
Configure the Linker
Security and Identity
Overview
Authentication
Introduction to Identity
Identity with SPA
Scaffold Identity
Add custom user data to Identity
Authentication samples
Customize Identity
Community OSS authentication options
Configure Identity
Configure Windows Authentication
Custom storage providers for Identity
Google, Facebook ...
Overview
Google authentication
Facebook authentication
Microsoft authentication
Twitter authentication
Other providers
Additional claims
Policy schemes
WS-Federation authentication
Account confirmation and password recovery
Enable QR code generation in Identity
Two-factor authentication with SMS
Use cookie authentication without Identity
Use social authentication without Identity
Azure Active Directory
Overview
Integrate Azure AD into a web app
Integrate Azure AD B2C into a web app
Integrate Azure AD B2C into a web API
Call a web API from WPF
 Call a web API in a 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
Configure certificate authentication
Authorization
Overview
Create a web app with authorization
Razor Pages authorization conventions
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
Overview
Data protection 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
Overview
Configure data protection
Default settings
 Machine-wide policy
Non-DI aware scenarios
Extensibility APIs
Overview
Core cryptography extensibility
Key management extensibility
Miscellaneous APIs
Implementation
Overview
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
Overview
Replace machineKey in ASP.NET
Secrets management
Protect secrets in development
Azure Key Vault Configuration Provider
Enforce HTTPS
EU General Data Protection Regulation (GDPR) support
Anti-request forgery
Prevent open redirect attacks
Prevent Cross-Site Scripting
Enable Cross-Origin Requests (CORS)
Share cookies among apps
IP safelist
 Application security - OWASP
Blazor
Performance
Overview
Response caching
Overview
In-memory cache
Distributed caching
Response caching middleware
Object reuse with ObjectPool
Response compression
Diagnostic tools
Load and stress testing
Globalization and localization
Overview
Portable Object localization
Extensibility
Troubleshoot
Advanced
Model binding
Custom model binding
Model validation
Compatibility version
Write middleware
Request and response operations
URL rewriting
File providers
Request-feature interfaces
Access HttpContext
Change tokens
Open Web Interface for .NET (OWIN)
Background tasks with hosted services
 Hosting startup assemblies
Microsoft.AspNetCore.App metapackage
Microsoft.AspNetCore.All metapackage
Logging with LoggerMessage
Use a file watcher
Factory-based middleware
Factory-based middleware with third-party container
Migration
2.2 to 3.0
2.1 to 2.2
2.0 to 2.1
1.x to 2.0
Overview
Authentication and Identity
ASP.NET to ASP.NET Core
Overview
MVC
Web API
Configuration
Authentication and Identity
ClaimsPrincipal.Current
Membership to Identity
HTTP modules to middleware
Logging (not ASP.NET Core)
API reference
Contribute
 Introduction to ASP.NET Core
6/26/2019 • 5 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 choose 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.
Architected for testability.
Razor Pages makes coding page-focused scenarios easier and more productive.
Blazor lets you use C# in the browser alongside JavaScript. Share server-side and client-side app logic all
written with .NET.
Ability to develop and run on Windows, macOS, and Linux.
Open-source and community-focused.
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.

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 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.
Client-side development
ASP.NET Core integrates seamlessly with popular client-side frameworks and libraries, including Blazor, Angular,
React, and Bootstrap. For more information, see Introduction to Blazor in ASP.NET Core and related topics under
Client-side development.

ASP.NET Core targeting .NET Framework

ASP.NET Core 2.x can target .NET Core or .NET Framework. ASP.NET Core apps targeting .NET Framework
aren't cross-platform—they run on Windows only. Generally, ASP.NET Core 2.x is made up of .NET Standard
libraries. Libraries written with .NET Standard 2.0 run on any .NET platform that implements .NET Standard 2.0.
ASP.NET Core 2.x is supported on .NET Framework versions that implement .NET Standard 2.0:
.NET Framework latest version is strongly recommended.
.NET Framework 4.6.1 and later.
ASP.NET Core 3.0 and later will only run on .NET Core. For more details regarding this change, see A first look at
changes coming in ASP.NET Core 3.0.
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.

Recommended learning path

We recommend the following sequence of tutorials and articles for an introduction to developing ASP.NET Core
apps:
1. Follow a tutorial for the type of app you want to develop or maintain:

APP TYPE SCENARIO TUTORIAL

Web app For new development Get started with Razor Pages

Web app For maintaining an MVC app Get started with MVC

Web API Create a web API*

Real-time app Get started with SignalR

2. Follow a tutorial that shows how to do basic data access:

SCENARIO TUTORIAL

For new development Razor Pages with Entity Framework Core

 SCENARIO TUTORIAL

For maintaining an MVC app MVC with Entity Framework Core

3. Read an overview of ASP.NET Core features that apply to all app types:
Fundamentals
4. Browse the Table of Contents for other topics of interest.
* There is a new web API tutorial that you follow entirely in the browser, no local IDE installation required. The
code runs in an Azure Cloud Shell, and curl is used for testing.

How to download a sample

Many of the articles and tutorials include links to sample code.
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.
Preprocessor directives in sample code
To demonstrate multiple scenarios, sample apps use the #define and #if-#else/#elif-#endif C# statements to
selectively compile and run different sections of sample code. For those samples that make use of this approach,
set the #define statement at the top of the C# files to the symbol associated with the scenario that you want to
run. Some samples require setting the symbol at the top of multiple files in order to run a scenario.
For example, the following #define symbol list indicates that four scenarios are available (one scenario per
symbol). The current sample configuration runs the TemplateCode scenario:

#define TemplateCode // or LogFromMain or ExpandDefault or FilterInCode

To change the sample to run the ExpandDefault scenario, define the ExpandDefault symbol and leave the
remaining symbols commented-out:

#define ExpandDefault // TemplateCode or LogFromMain or FilterInCode

For more information on using C# preprocessor directives to selectively compile sections of code, see #define (C#
Reference) and #if (C# Reference).
Regions in sample code
Some sample apps contain sections of code surrounded by #region and #endregion C# statements. The
documentation build system injects these regions into the rendered documentation topics.
Region names usually contain the word "snippet." The following example shows a region named
snippet_FilterInCode :

#region snippet_FilterInCode
WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureLogging(logging =>
logging.AddFilter("System", LogLevel.Debug)
.AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Trace))
.Build();
#endregion
The preceding C# code snippet is referenced in the topic's markdown file with the following line:

[!code-csharp[](sample/SampleApp/Program.cs?name=snippet_FilterInCode)]

You may safely ignore (or remove) the #region and #endregion statements that surround the code. Don't alter
the code within these statements if you plan to run the sample scenarios described in the topic. Feel free to alter
the code when experimenting with other scenarios.
For more information, see Contribute to the ASP.NET documentation: Code snippets.

Next steps
For more information, see the following resources:
Get started with ASP.NET Core
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.
 Choose between ASP.NET 4.x and ASP.NET Core
7/16/2019 • 2 minutes to read • Edit Online

ASP.NET Core is a redesign of ASP.NET 4.x. This article lists the differences between them.

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 Core provides the following benefits:
A unified story for building web UI and web APIs.
Architected for testability.
Razor Pages makes coding page-focused scenarios easier and more productive.
Blazor lets you use C# in the browser alongside JavaScript. Share server-side and client-side app logic all
written with .NET.
Ability to develop and run on Windows, macOS, and Linux.
Open-source and community-focused.
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.

ASP.NET 4.x
ASP.NET 4.x is a mature framework that provides the services needed to build enterprise-grade, server-based web
apps on Windows.

Framework selection
The following table compares ASP.NET Core to ASP.NET 4.x.

ASP.NET CORE ASP.NET 4.X

Build for Windows, macOS, or Linux Build for Windows

Razor Pages is the recommended approach to create a Web UI Use Web Forms, SignalR, MVC, Web API, WebHooks, or Web
as of ASP.NET Core 2.x. See also MVC, Web API, and SignalR. Pages

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 4.x Good performance

 ASP.NET CORE ASP.NET 4.X

Use .NET Core runtime Use .NET Framework runtime

See ASP.NET Core targeting .NET Framework for information on ASP.NET Core 2.x support on .NET Framework.

ASP.NET Core scenarios

Websites
APIs
Real-time
Deploy an ASP.NET Core app to Azure

ASP.NET 4.x scenarios

Websites
APIs
Real-time
Create an ASP.NET 4.x web app in Azure

Additional resources
Introduction to ASP.NET
Introduction to ASP.NET Core
Deploy ASP.NET Core apps to Azure App Service
 Tutorial: Get started with ASP.NET Core
7/11/2019 • 2 minutes to read • Edit Online

This tutorial shows how to use the .NET Core command-line interface to create and run an ASP.NET Core web
app.
You'll learn how to:
Create a web app project.
Trust the development certificate.
Run the app.
Edit a Razor page.
At the end, you'll have a working web app running on your local machine.

Prerequisites
.NET Core 2.2 SDK

Create a web app project

Open a command shell, and enter the following command:

dotnet new webapp -o aspnetcoreapp

Trust the development certificate

Trust the HTTPS development certificate:
Windows
macOS
Linux

dotnet dev-certs https --trust

The preceding command displays the following dialog:

Select Yes if you agree to trust the development certificate.

For more information, see Trust the ASP.NET Core HTTPS development certificate

Run the app

Run the following commands:

cd aspnetcoreapp
dotnet run

After the command shell indicates that the app has started, browse to https://localhost:5001. Click Accept to
accept the privacy and cookie policy. This app doesn't keep personal information.

Edit a Razor page

Open Pages/Index.cshtml and modify the page with the following highlighted markup:

@page
@model IndexModel
@{
ViewData["Title"] = "Home page";
}

<div class="text-center">
<h1 class="display-4">Welcome</h1>
<p>Hello, world! The time on the server is @DateTime.Now</p>
</div>

Browse to https://localhost:5001, and verify the changes are displayed.

Next steps
In this tutorial, you learned how to:
Create a web app project.
Trust the development certificate.
 Run the project.
Make a change.
To learn more about ASP.NET Core, see the recommended learning path in the introduction:
Introduction to ASP.NET Core
 What's new in ASP.NET Core 2.2
6/21/2019 • 5 minutes to read • Edit Online

This article highlights the most significant changes in ASP.NET Core 2.2, with links to relevant documentation.

OpenAPI Analyzers & Conventions

OpenAPI (formerly known as Swagger) is a language-agnostic specification for describing REST APIs. The
OpenAPI ecosystem has tools that allow for discovering, testing, and producing client code using the specification.
Support for generating and visualizing OpenAPI documents in ASP.NET Core MVC is provided via community
driven projects such as NSwag and Swashbuckle.AspNetCore. ASP.NET Core 2.2 provides improved tooling and
runtime experiences for creating OpenAPI documents.
For more information, see the following resources:
Use web API analyzers
Use web API conventions
ASP.NET Core 2.2.0-preview1: OpenAPI Analyzers & Conventions

Problem details support

ASP.NET Core 2.1 introduced ProblemDetails , based on the RFC 7807 specification for carrying details of an error
with an HTTP Response. In 2.2, ProblemDetails is the standard response for client error codes in controllers
attributed with ApiControllerAttribute . An IActionResult returning a client error status code (4xx) now returns a
ProblemDetails body. The result also includes a correlation ID that can be used to correlate the error using request
logs. For client errors, ProducesResponseType defaults to using ProblemDetails as the response type. This is
documented in OpenAPI / Swagger output generated using NSwag or Swashbuckle.AspNetCore.

Endpoint Routing
ASP.NET Core 2.2 uses a new endpoint routing system for improved dispatching of requests. The changes include
new link generation API members and route parameter transformers.
For more information, see the following resources:
Endpoint routing in 2.2
Route parameter transformers (see Routing section)
Differences between IRouter- and endpoint-based routing

Health checks
A new health checks service makes it easier to use ASP.NET Core in environments that require health checks, such
as Kubernetes. Health checks includes middleware and a set of libraries that define an IHealthCheck abstraction
and service.
Health checks are used by a container orchestrator or load balancer to quickly determine if a system is responding
to requests normally. A container orchestrator might respond to a failing health check by halting a rolling
deployment or restarting a container. A load balancer might respond to a health check by routing traffic away from
the failing instance of the service.
Health checks are exposed by an application as an HTTP endpoint used by monitoring systems. Health checks can
be configured for a variety of real-time monitoring scenarios and monitoring systems. The health checks service
integrates with the BeatPulse project. which makes it easier to add checks for dozens of popular systems and
dependencies.
For more information, see Health checks in ASP.NET Core.

HTTP/2 in Kestrel
ASP.NET Core 2.2 adds support for HTTP/2.
HTTP/2 is a major revision of the HTTP protocol. Some of the notable features of HTTP/2 are support for header
compression and fully multiplexed streams over a single connection. While HTTP/2 preserves HTTP’s semantics
(HTTP headers, methods, etc) it's a breaking change from HTTP/1.x on how this data is framed and sent over the
wire.
As a consequence of this change in framing, servers and clients need to negotiate the protocol version used.
Application-Layer Protocol Negotiation (ALPN ) is a TLS extension that allows the server and client to negotiate the
protocol version used as part of their TLS handshake. While it is possible to have prior knowledge between the
server and the client on the protocol, all major browsers support ALPN as the only way to establish an HTTP/2
connection.
For more information, see HTTP/2 support.

Kestrel configuration
In earlier versions of ASP.NET Core, Kestrel options are configured by calling UseKestrel . In 2.2, Kestrel options
are configured by calling ConfigureKestrel on the host builder. This change resolves an issue with the order of
IServer registrations for in-process hosting. For more information, see the following resources:

Mitigate UseIIS conflict

Configure Kestrel server options with ConfigureKestrel

IIS in-process hosting

In earlier versions of ASP.NET Core, IIS serves as a reverse proxy. In 2.2, the ASP.NET Core Module can boot the
CoreCLR and host an app inside the IIS worker process (w3wp.exe). In-process hosting provides performance and
diagnostic gains when running with IIS.
For more information, see in-process hosting for IIS.

SignalR Java client

ASP.NET Core 2.2 introduces a Java Client for SignalR. This client supports connecting to an ASP.NET Core
SignalR Server from Java code, including Android apps.
For more information, see ASP.NET Core SignalR Java client.

CORS improvements
In earlier versions of ASP.NET Core, CORS Middleware allows Accept , Accept-Language , Content-Language , and
Origin headers to be sent regardless of the values configured in CorsPolicy.Headers . In 2.2, a CORS Middleware
policy match is only possible when the headers sent in Access-Control-Request-Headers exactly match the headers
stated in WithHeaders .
For more information, see CORS Middleware.
Response compression
ASP.NET Core 2.2 can compress responses with the Brotli compression format.
For more information, see Response Compression Middleware supports Brotli compression.

Project templates
ASP.NET Core web project templates were updated to Bootstrap 4 and Angular 6. The new look is visually simpler
and makes it easier to see the important structures of the app.

Validation performance
MVC’s validation system is designed to be extensible and flexible, allowing you to determine on a per request basis
which validators apply to a given model. This is great for authoring complex validation providers. However, in the
most common case an application only uses the built-in validators and don’t require this extra flexibility. Built-in
validators include DataAnnotations such as [Required] and [StringLength], and IValidatableObject .
In ASP.NET Core 2.2, MVC can short-circuit validation if it determines that a given model graph doesn't require
validation. Skipping validation results in significant improvements when validating models that can't or don't have
any validators. This includes objects such as collections of primitives (such as byte[] , string[] ,
Dictionary<string, string> ), or complex object graphs without many validators.

HTTP Client performance

In ASP.NET Core 2.2, the performance of SocketsHttpHandler was improved by reducing connection pool locking
contention. For apps that make many outgoing HTTP requests, such as some microservices architectures,
throughput is improved. Under load, HttpClient throughput can be improved by up to 60% on Linux and 20% on
Windows.
For more information, see the pull request that made this improvement.

Additional information
For the complete list of changes, see the ASP.NET Core 2.2 Release Notes.
 What's new in ASP.NET Core 2.1
5/6/2019 • 6 minutes to read • Edit Online

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 Angular project template with ASP.NET Core
Use the React project template with ASP.NET Core
Use the React-with-Redux project template 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.
 What's new in ASP.NET Core 2.0
6/13/2019 • 5 minutes to read • Edit Online

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
Get started with 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.
For information about the status of planned documentation, see the GitHub issue.

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 JavaScript Services to Create Single Page Applications in
ASP.NET Core.

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.
For information about the status of planned documentation, see the GitHub issue.

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.
 What's new in ASP.NET Core 1.1
6/12/2019 • 2 minutes to read • Edit Online

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 Key Vault configuration 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.
 Tutorial: Create a Razor Pages web app with ASP.NET
Core
8/13/2019 • 2 minutes to read • Edit Online

This series of tutorials explains the basics of building a Razor Pages web app.
For a more advanced introduction aimed at experienced developers, see Introduction to Razor Pages.
This series includes the following tutorials:
1. Create a Razor Pages web app
2. Add a model to a Razor Pages app
3. Scaffold (generate) Razor pages
4. Work with a database
5. Update Razor pages
6. Add search
7. Add a new field
8. Add validation
At the end, you'll have an app that can display and manage a database of movies.

Additional resources
Youtube version of this tutorial
 Tutorial: Get started with Razor Pages in ASP.NET
Core
7/31/2019 • 10 minutes to read • Edit Online

By Rick Anderson
This is the first tutorial of a series that teaches the basics of building an ASP.NET Core Razor Pages web app.
For a more advanced introduction aimed at experienced developers, see Introduction to Razor Pages.
At the end of the series, you'll have an app that manages a database of movies.
View or download sample code (how to download).
View or download sample code (how to download).
In this tutorial, you:
Create a Razor Pages web app.
Run the app.
Examine the project files.
At the end of this tutorial, you'll have a working Razor Pages web app that you'll build on in later tutorials.

Prerequisites
Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 3.0 Preview

Create a Razor Pages web app

Visual Studio
Visual Studio Code
Visual Studio for Mac
From the Visual Studio File menu, select New > Project.
Create a new ASP.NET Core Web Application and select Next.

Name the project RazorPagesMovie. It's important to name the project RazorPagesMovie so the
namespaces will match when you copy and paste code.
 Select ASP.NET Core 3.0 in the dropdown, Web Application, and then select Create.

The following starter project is created:

Run the app

Visual Studio
Visual Studio Code
Visual Studio for Mac
Press Ctrl+F5 to run without the debugger.
Visual Studio displays the following dialog:
 Select Yes if you trust the IIS Express SSL certificate.
The following dialog is displayed:

Select Yes if you agree to trust the development certificate.

See Trust the ASP.NET Core HTTPS development certificate for more information.
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 the 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.

Examine the project files

Here's an overview of the main project folders and files that you'll work with in later tutorials.
Pages folder
Contains Razor pages and supporting files. Each Razor page is a pair of files:
A .cshtml file that contains HTML markup with C# code using Razor syntax.
A .cshtml.cs file that contains C# code that handles page events.
Supporting files have names that begin with an underscore. For example, the _Layout.cshtml file configures UI
elements common to all pages. This file sets up the navigation menu at the top of the page and the copyright notice
at the bottom of the page. For more information, see Layout in ASP.NET Core.
wwwroot folder
Contains static files, such as HTML files, JavaScript files, and CSS files. For more information, see Static files in
ASP.NET Core.
appSettings.json
Contains configuration data, such as connection strings. For more information, see Configuration in ASP.NET Core.
Program.cs
Contains the entry point for the program. For more information, see .NET Generic Host.
Startup.cs
Contains code that configures app behavior. For more information, see App startup in ASP.NET Core.

Next steps
Advance to the next tutorial in the series:

ADD A
M ODEL

This is the first tutorial of a series. The series teaches the basics of building an ASP.NET Core Razor Pages web app.
For a more advanced introduction aimed at experienced developers, see Introduction to Razor Pages.
At the end of the series, you'll have an app that manages a database of movies.
View or download sample code (how to download).
View or download sample code (how to download).
In this tutorial, you:
Create a Razor Pages web app.
Run the app.
Examine the project files.
At the end of this tutorial, you'll have a working Razor Pages web app that you'll build on in later tutorials.

Prerequisites
 Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 2.2 or later

WARNING
If you use Visual Studio 2017, see dotnet/sdk issue #3124 for information about .NET Core SDK versions that don't work with
Visual Studio.

Create a Razor Pages web app

Visual Studio
Visual Studio Code
Visual Studio for Mac
From the Visual Studio File menu, select New > Project.
Create a new ASP.NET Core Web Application and select Next.

Name the project RazorPagesMovie. It's important to name the project RazorPagesMovie so the
namespaces will match when you copy and paste code.
 Select ASP.NET Core 2.2 in the dropdown, Web Application, and then select Create.

The following starter project is created:

Run the app
Visual Studio
Visual Studio Code
Visual Studio for Mac
Press Ctrl+F5 to run without the debugger.
Visual Studio displays the following dialog:

Select Yes if you trust the IIS Express SSL certificate.

The following dialog is displayed:
Select Yes if you agree to trust the development certificate.
See Trust the ASP.NET Core HTTPS development certificate for more information.
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 the 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.
On the app's home page, select Accept to consent to tracking.
This app doesn't track personal information, but the project template includes the consent feature in case
you need it to comply with the European Union's General Data Protection Regulation (GDPR ).

The following image shows the app after you give consent to tracking:
Examine the project files
Here's an overview of the main project folders and files that you'll work with in later tutorials.
Pages folder
Contains Razor pages and supporting files. Each Razor page is a pair of files:
A .cshtml file that contains HTML markup with C# code using Razor syntax.
A .cshtml.cs file that contains C# code that handles page events.
Supporting files have names that begin with an underscore. For example, the _Layout.cshtml file configures UI
elements common to all pages. This file sets up the navigation menu at the top of the page and the copyright notice
at the bottom of the page. For more information, see Layout in ASP.NET Core.
wwwroot folder
Contains static files, such as HTML files, JavaScript files, and CSS files. For more information, see Static files in
ASP.NET Core.
appSettings.json
Contains configuration data, such as connection strings. For more information, see Configuration in ASP.NET Core.
Program.cs
Contains the entry point for the program. For more information, see .NET Generic Host.
Startup.cs
Contains code that configures app behavior, such as whether it requires consent for cookies. For more information,
see App startup in ASP.NET Core.

Additional resources
Youtube version of this tutorial

Next steps
Advance to the next tutorial in the series:
ADD A
M ODEL
 Add a model to a Razor Pages app in ASP.NET Core
8/7/2019 • 25 minutes to read • Edit Online

By Rick Anderson
In this section, classes are added for managing movies in a database. These classes are used with Entity Framework
Core (EF Core) to work with a database. EF Core is an object-relational mapping (ORM ) framework that simplifies
data access.
The model classes 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.
View or download sample code (how to download).
View or download sample code (how to download).

Add a data model

Visual Studio
Visual Studio Code
Visual Studio for Mac
Right-click the RazorPagesMovie project > Add > New Folder. Name the folder Models.
Right click the Models folder. Select Add > Class. Name the class Movie.
Add the following properties to the Movie class:

using System;
using System.ComponentModel.DataAnnotations;

namespace RazorPagesMovie.Models
{
public class Movie
{
public int ID { get; set; }
public string Title { get; set; }

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }
public string Genre { get; set; }
public decimal Price { get; set; }
}
}

The Movie class contains:

The ID field is required by the database for the primary key.
[DataType(DataType.Date)] : The DataType attribute specifies the type of the data (Date). With this attribute:
The user is not required to enter time information in the date field.
Only the date is displayed, not time information.
DataAnnotations are covered in a later tutorial.
Build the project to verify there are no compilation errors.

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.
Visual Studio
Visual Studio Code
Visual Studio for Mac
Create a Pages/Movies folder:
Right click on the Pages folder > Add > New Folder.
Name the folder Movies
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 change the generated name from
RazorPagesMovie.Models.RazorPagesMovieContext to RazorPagesMovie.Data.RazorPagesMovieContext. This
change is not required. It creates the database context class with the correct namespace.
Select Add.

The appsettings.json file is updated with the connection string used to connect to a local database.
Files created
Visual Studio
Visual Studio Code / Visual Studio for Mac
The scaffold process creates and updates the following files:
 Pages/Movies: Create, Delete, Details, Edit, and Index.
Data/RazorPagesMovieContext.cs
Updated
Startup.cs
The created and updated files are explained in the next section.

Initial migration
Visual Studio
Visual Studio Code
Visual Studio for Mac
In this section, the Package Manager Console (PMC ) is used 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 InitialCreate
Update-Database

The preceding commands generate the following warning: "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 'HasColumnType()'."
You can ignore that warning, it will be fixed in a later tutorial.
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 RazorPagesMovieContext.cs file). The InitialCreate
argument is used to name the migrations. Any name can be used, but by convention a name is selected that
describes the migration.
The ef database update command runs the Up method in the Migrations/<time-stamp>_InitialCreate.cs file. The
Up method creates the database.
Visual Studio
Visual Studio Code
Visual Studio for Mac
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:

public void ConfigureServices(IServiceCollection services)

{
services.AddRazorPages();

services.AddDbContext<RazorPagesMovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("RazorPagesMovieContext")));
}

The RazorPagesMovieContext coordinates EF Core functionality (Create, Read, Update, Delete, etc.) for the Movie
model. The data context ( RazorPagesMovieContext ) is derived from Microsoft.EntityFrameworkCore.DbContext. The
data context specifies which entities are included in the data model.

using Microsoft.EntityFrameworkCore;

namespace RazorPagesMovie.Models
{
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.
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. Any name can be used, but by convention a name that describes the
migration is used. For more information, see Tutorial: Using the migrations feature - ASP.NET MVC with EF Core.
The Update-Database command runs the Up method in the Migrations/{time-stamp }_InitialCreate.cs file, which
creates the database.
Test the app
 Run the app and append /Movies to the URL in the browser ( http://localhost:port/movies ).
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.

Test the Create link.

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 for non US-English date formats, the app must be globalized.
For globalization instructions, see this GitHub issue.

Test the Edit, Details, and Delete links.

The next tutorial explains the files created by scaffolding.

Additional resources

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
In this section, classes are added for managing movies in a database. These classes are used with Entity Framework
Core (EF Core) to work with a database. EF Core is an object-relational mapping (ORM ) framework that simplifies
data access code.
The model classes 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.
View or download sample code (how to download).
View or download sample code (how to download).

Add a data model

Visual Studio
Visual Studio Code
Visual Studio for Mac
Right-click the RazorPagesMovie project > Add > New Folder. Name the folder Models.
Right click the Models folder. Select Add > Class. Name the class Movie.
Add the following properties to the Movie class:

using System;
using System.ComponentModel.DataAnnotations;

namespace RazorPagesMovie.Models
{
public class Movie
{
public int ID { get; set; }
public string Title { get; set; }

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }
public string Genre { get; set; }
public decimal Price { get; set; }
}
}

The Movie class contains:

The ID field is required by the database for the primary key.
[DataType(DataType.Date)] : The DataType attribute specifies the type of the data (Date). With this attribute:
The user is not required to enter time information in the date field.
Only the date is displayed, not time information.
DataAnnotations are covered in a later tutorial.
Build the project to verify there are no compilation errors.

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.
Visual Studio
 Visual Studio Code
Visual Studio for Mac
Create a Pages/Movies folder:
Right click on the Pages folder > Add > New Folder.
Name the folder Movies
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.
Select Add.

The appsettings.json file is updated with the connection string used to connect to a local database.
The scaffold process creates and updates the following files:
Files created
Pages/Movies: Create, Delete, Details, Edit, and Index.
Data/RazorPagesMovieContext.cs
File updated
Startup.cs
The created and updated files are explained in the next section.
Initial migration
Visual Studio
Visual Studio Code
Visual Studio for Mac
In this section, the Package Manager Console (PMC ) is used 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

The preceding commands generate the following warning: "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 'HasColumnType()'."
You can ignore that warning, it will be fixed in a later tutorial.
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 RazorPagesMovieContext.cs file). The InitialCreate
argument is used to name the migrations. Any name can be used, but by convention a name is selected that
describes the migration.
The ef database update command runs the Up method in the Migrations/<time-stamp>_InitialCreate.cs file. The
Up method creates the database.
Visual Studio
Visual Studio Code
Visual Studio for Mac
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:

// This method gets called by the runtime.

// Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
services.Configure<CookiePolicyOptions>(options =>
{
// This lambda determines whether user consent for non-essential cookies is
// needed for a given request.
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

services.AddDbContext<RazorPagesMovieContext>(options =>
options.UseSqlServer(
Configuration.GetConnectionString("RazorPagesMovieContext")));
}

The RazorPagesMovieContext coordinates EF Core functionality (Create, Read, Update, Delete, etc.) for the Movie
model. The data context ( RazorPagesMovieContext ) is derived from Microsoft.EntityFrameworkCore.DbContext. The
data context specifies which entities are included in the data model.

using Microsoft.EntityFrameworkCore;

namespace RazorPagesMovie.Models
{
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.
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. Any name can be used, but by convention a name that describes the
migration is used. For more information, see Tutorial: Using the migrations feature - ASP.NET MVC with EF Core.
The Update-Database command runs the Up method in the Migrations/{time-stamp }_InitialCreate.cs file, which
creates the database.
Test the app
Run the app and append /Movies to the URL in the browser ( http://localhost:port/movies ).
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.

Test the Create link.

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 for non US-English date formats, the app must be globalized.
For globalization instructions, see this GitHub issue.

Test the Edit, Details, and Delete links.

The next tutorial explains the files created by scaffolding.

Additional resources
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
7/22/2019 • 16 minutes to read • Edit Online

By Rick Anderson
This tutorial examines the Razor Pages created by scaffolding in the previous tutorial.
View or download sample code (how to download).
View or download sample code (how to download).

The Create, Delete, Details, and Edit pages

Examine the Pages/Movies/Index.cshtml.cs Page Model:

// Unused usings removed.

using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using RazorPagesMovie.Models;
using System.Collections.Generic;
using System.Threading.Tasks;

namespace RazorPagesMovie.Pages.Movies
{
public class IndexModel : PageModel
{
private readonly RazorPagesMovie.Data.RazorPagesMovieContext _context;

public IndexModel(RazorPagesMovie.Data.RazorPagesMovieContext context)

{
_context = context;
}

public IList<Movie> Movie { get;set; }

public async Task OnGetAsync()

{
Movie = await _context.Movie.ToListAsync();
}
}
}

Razor Pages are derived from PageModel . By convention, the PageModel -derived class is called <PageName>Model .
The constructor uses dependency injection to add the RazorPagesMovieContext 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 OnGetreturns 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:
 public async Task<IActionResult> OnPostAsync()
{
if (!ModelState.IsValid)
{
return Page();
}

_context.Movie.Add(Movie);
await _context.SaveChangesAsync();

return RedirectToPage("./Index");
}
}

Examine the Pages/Movies/Index.cshtml Razor Page:

 @page
@model RazorPagesMovie.Pages.Movies.IndexModel

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-page="Create">Create New</a>
</p>
<table class="table">
<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
@model RazorPagesMovie.Pages.Movies.IndexModel

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.DisplayFor HTML Helpers on the page.

The layout page

Select the menu links (RazorPagesMovie, Home, and Privacy). Each page shows the same menu layout. The
menu layout is implemented in the Pages/Shared/_Layout.cshtml file. Open the Pages/Shared/_Layout.cshtml file.
Layout templates allow the HTML container layout to be:
Specified in one place.
Applied in multiple pages in the site.
Find the @RenderBody() line. RenderBody is a placeholder where all the page-specific views show up, wrapped in
the layout page. For example, select the Privacy link and the Pages/Privacy.cshtml view is rendered inside the
RenderBody method.

ViewData and layout

Consider the following markup from the Pages/Movies/Index.cshtml file:

@page
@model RazorPagesMovie.Pages.Movies.IndexModel

@{
ViewData["Title"] = "Index";
}

The preceding highlighted markup is an example of Razor transitioning into C#. The { and } characters enclose
a block of C# code.
The PageModel base class contains a ViewData dictionary property that can be used to add data that and pass it to
a View. Objects are added to 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 _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.
Update the layout
Change the <title> element in the Pages/Shared/_Layout.cshtml file to display Movie rather than
RazorPagesMovie.

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@ViewData["Title"] - Movie</title>

Find the following anchor element in the Pages/Shared/_Layout.cshtml file.

<a class="navbar-brand" asp-area="" asp-page="/Index">RazorPagesMovie</a>

Replace the preceding element with the following markup:

<a class="navbar-brand" asp-page="/Movies/Index">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. The
asp-area attribute value is empty, so the area isn't used in the link. See Areas for more information.

Save your changes, and test the app by clicking on the RpMovie link. See the _Layout.cshtml file in GitHub if you
have any problems.
Test the other links (Home, RpMovie, 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.

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. See 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.
The Create page model
Examine the Pages/Movies/Create.cshtml.cs page model:

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using RazorPagesMovie.Models;
using System;
using System.Threading.Tasks;

namespace RazorPagesMovie.Pages.Movies
{
public class CreateModel : PageModel
{
private readonly RazorPagesMovie.Data.RazorPagesMovieContext _context;

public CreateModel(RazorPagesMovie.Data.RazorPagesMovieContext context)

{
_context = context;
}

public IActionResult OnGet()

{
return Page();
}

[BindProperty]
public Movie Movie { get; set; }

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

_context.Movie.Add(Movie);
await _context.SaveChangesAsync();

return RedirectToPage("./Index");
}
}
}

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, an example of OnGet initializing state is shown. 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:
 public async Task<IActionResult> OnPostAsync()
{
if (!ModelState.IsValid)
{
return Page();
}

_context.Movie.Add(Movie);
await _context.SaveChangesAsync();

return RedirectToPage("./Index");
}

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. Client-side validation and model validation are discussed 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";
}

<h1>Create</h1>

<h4>Movie</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<input type="submit" value="Create" class="btn btn-primary" />
</div>
</form>
</div>
</div>

<div>
<a asp-page="Index">Back to List</a>
</div>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio displays the following tags in a distinctive bold font used for Tag Helpers:
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<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>
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 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>

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.
For more information on Tag Helpers such as <form method="post"> , see Tag Helpers in ASP.NET Core.

Additional resources

P R E V IO U S : A D D IN G A N E X T:
M ODEL D A TA B A SE
By Rick Anderson
This tutorial examines the Razor Pages created by scaffolding in the previous tutorial.
View or download sample.

The Create, Delete, Details, and Edit pages

Examine the Pages/Movies/Index.cshtml.cs Page Model:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using RazorPagesMovie.Models;

namespace RazorPagesMovie.Pages.Movies
{
public class IndexModel : PageModel
{
private readonly RazorPagesMovie.Models.RazorPagesMovieContext _context;

public IndexModel(RazorPagesMovie.Models.RazorPagesMovieContext context)

{
_context = context;
}

public IList<Movie> Movie { get;set; }

public async Task OnGetAsync()

{
Movie = await _context.Movie.ToListAsync();
}
}
}

Razor Pages are derived from PageModel . By convention, the PageModel -derived class is called <PageName>Model .
The constructor uses dependency injection to add the RazorPagesMovieContext 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:
 public async Task<IActionResult> OnPostAsync()
{
if (!ModelState.IsValid)
{
return Page();
}

_context.Movie.Add(Movie);
await _context.SaveChangesAsync();

return RedirectToPage("./Index");
}

Examine the Pages/Movies/Index.cshtml Razor Page:

 @page
@model RazorPagesMovie.Pages.Movies.IndexModel

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-page="Create">Create New</a>
</p>
<table class="table">
<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
@model RazorPagesMovie.Pages.Movies.IndexModel

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.DisplayFor HTML Helpers on the page.

The layout page

Select the menu links (RazorPagesMovie, Home, and Privacy). Each page shows the same menu layout. The
menu layout is implemented in the Pages/Shared/_Layout.cshtml file. Open the Pages/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 page-specific
views you create show up, wrapped in the layout page. For example, if you select the Privacy link, the
Pages/Privacy.cshtml view is rendered inside the RenderBody method.
ViewData and layout
Consider the following code from the Pages/Movies/Index.cshtml file:

@page
@model RazorPagesMovie.Pages.Movies.IndexModel

@{
ViewData["Title"] = "Index";
}

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 _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 which doesn't appear in your layout file. Unlike
HTML comments ( <!-- --> ), Razor comments are not sent to the client.
Update the layout
Change the <title> element in the Pages/Shared/_Layout.cshtml file to display Movie rather than
RazorPagesMovie.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@ViewData["Title"] - Movie</title>

Find the following anchor element in the Pages/Shared/_Layout.cshtml file.

<a class="navbar-brand" asp-area="" asp-page="/Index">RazorPagesMovie</a>

Replace the preceding element with the following markup.

<a class="navbar-brand" asp-page="/Movies/Index">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. The
asp-area attribute value is empty, so the area isn't used in the link. See Areas for more information.

Save your changes, and test the app by clicking on the RpMovie link. See the _Layout.cshtml file in GitHub if you
have any problems.
Test the other links (Home, RpMovie, 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.

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.
The Create page model
Examine the Pages/Movies/Create.cshtml.cs page model:
 // Unused usings removed.
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using RazorPagesMovie.Models;
using System;
using System.Threading.Tasks;

namespace RazorPagesMovie.Pages.Movies
{
public class CreateModel : PageModel
{
private readonly RazorPagesMovie.Models.RazorPagesMovieContext _context;

public CreateModel(RazorPagesMovie.Models.RazorPagesMovieContext context)

{
_context = context;
}

public IActionResult OnGet()

{
return Page();
}

[BindProperty]
public Movie Movie { get; set; }

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

_context.Movie.Add(Movie);
await _context.SaveChangesAsync();

return RedirectToPage("./Index");
}
}
}

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:

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

_context.Movie.Add(Movie);
await _context.SaveChangesAsync();

return RedirectToPage("./Index");
}
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. Client-side validation and model validation are discussed 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";
}

<h1>Create</h1>

<h4>Movie</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<input type="submit" value="Create" class="btn btn-primary" />
</div>
</form>
</div>
</div>

<div>
<a asp-page="Index">Back to List</a>
</div>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio displays the <form method="post"> tag in a distinctive bold 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 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>

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.

Additional resources
YouTube version of this tutorial
P R E V IO U S : A D D IN G A N E X T:
M ODEL D A TA B A SE
 Work with a database and ASP.NET Core
7/24/2019 • 12 minutes to read • Edit Online

By Rick Anderson and Joe Audette

View or download sample code (how to download).
View or download sample code (how to download).
The RazorPagesMovieContext 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 Startup.cs:

Visual Studio
Visual Studio Code / Visual Studio for Mac

public void ConfigureServices(IServiceCollection services)

{
services.AddRazorPages();

services.AddDbContext<RazorPagesMovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("RazorPagesMovieContext")));
}

The ASP.NET Core Configuration system reads the ConnectionString . For local development, it gets the
connection string from the appsettings.json file.
Visual Studio
Visual Studio Code / Visual Studio for Mac
The name value for the database ( Database={Database name} ) will be different for your generated code. The name
value is arbitrary.

{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*",
"ConnectionStrings": {
"RazorPagesMovieContext": "Server=(localdb)\\mssqllocaldb;Database=RazorPagesMovieContext-
bc;Trusted_Connection=True;MultipleActiveResultSets=true"
}
}

When the app is deployed to a test or production server, an environment variable can be used to set the connection
string to a real database server. See Configuration for more information.
Visual Studio
Visual Studio Code / Visual Studio for Mac
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 with the following code:
 using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using RazorPagesMovie.Data;
using System;
using System.Linq;

namespace RazorPagesMovie.Models
{
public static class SeedData
{
public static void Initialize(IServiceProvider serviceProvider)
{
using (var context = new RazorPagesMovieContext(
serviceProvider.GetRequiredService<
DbContextOptions<RazorPagesMovieContext>>()))
{
// 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 ",
ReleaseDate = DateTime.Parse("1984-3-13"),
Genre = "Comedy",
Price = 8.99M
},

new Movie
{
Title = "Ghostbusters 2",
ReleaseDate = DateTime.Parse("1986-2-23"),
Genre = "Comedy",
Price = 9.99M
},

new Movie
{
Title = "Rio Bravo",
ReleaseDate = DateTime.Parse("1959-4-15"),
Genre = "Western",
Price = 3.99M
}
);
context.SaveChanges();
}
}
}
}

If there are any movies in the DB, the seed initializer returns and no movies are added.
 if (context.Movie.Any())
{
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.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using RazorPagesMovie.Data;
using RazorPagesMovie.Models;
using System;

namespace RazorPagesMovie
{
public class Program
{
public static void Main(string[] args)
{
var host = CreateHostBuilder(args).Build();

using (var scope = host.Services.CreateScope())

{
var services = scope.ServiceProvider;

try
{
var context = services.
GetRequiredService<RazorPagesMovieContext>();
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 IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
// webBuilder.UseStartup<Startup>();
webBuilder.UseStartup<StartupVal>();

});
}
}

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
Visual Studio
Visual Studio Code / Visual Studio for Mac
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 next tutorial will improve the presentation of the data.

Additional resources

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

View or download sample code (how to download).

View or download sample code (how to download).
The RazorPagesMovieContext 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 Startup.cs:

Visual Studio
Visual Studio Code / Visual Studio for Mac
 // This method gets called by the runtime.
// Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
services.Configure<CookiePolicyOptions>(options =>
{
// This lambda determines whether user consent for non-essential cookies is
// needed for a given request.
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

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.
Visual Studio
Visual Studio Code
Visual Studio for Mac
The name value for the database ( Database={Database name} ) will be different for your generated code. The name
value is arbitrary.

{
"Logging": {
"LogLevel": {
"Default": "Warning"
}
},
"AllowedHosts": "*",
"ConnectionStrings": {
"RazorPagesMovieContext": "Server=(localdb)\\mssqllocaldb;Database=RazorPagesMovieContext-
1234;Trusted_Connection=True;MultipleActiveResultSets=true"
}
}

When the app is deployed to a test or production server, an environment variable can be used to set the connection
string to a real database server. See Configuration for more information.
Visual Studio
Visual Studio Code
Visual Studio for Mac

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 with the following code:
 using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using System;
using System.Linq;

namespace RazorPagesMovie.Models
{
public static class SeedData
{
public static void Initialize(IServiceProvider serviceProvider)
{
using (var context = new RazorPagesMovieContext(
serviceProvider.GetRequiredService<
DbContextOptions<RazorPagesMovieContext>>()))
{
// 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 ",
ReleaseDate = DateTime.Parse("1984-3-13"),
Genre = "Comedy",
Price = 8.99M
},

new Movie
{
Title = "Ghostbusters 2",
ReleaseDate = DateTime.Parse("1986-2-23"),
Genre = "Comedy",
Price = 9.99M
},

new Movie
{
Title = "Rio Bravo",
ReleaseDate = DateTime.Parse("1959-4-15"),
Genre = "Western",
Price = 3.99M
}
);
context.SaveChanges();
}
}
}
}

If there are any movies in the DB, the seed initializer returns and no movies are added.
 if (context.Movie.Any())
{
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.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using RazorPagesMovie.Models;
using System;
using Microsoft.EntityFrameworkCore;

namespace RazorPagesMovie
{
public class Program
{
public static void Main(string[] args)
{
var host = CreateWebHostBuilder(args).Build();

using (var scope = host.Services.CreateScope())

{
var services = scope.ServiceProvider;

try
{
var context=services.
GetRequiredService<RazorPagesMovieContext>();
context.Database.Migrate();
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 IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(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
Visual Studio
Visual Studio Code
Visual Studio for Mac
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.

Additional resources
YouTube version of this tutorial

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
7/24/2019 • 9 minutes to read • Edit Online

By Rick Anderson
The scaffolded movie app has a good start, but the presentation isn't ideal. 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;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace RazorPagesMovie.Models
{
public class Movie
{
public int ID { get; set; }
public string Title { get; set; }

[Display(Name = "Release Date")]

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }
public string Genre { get; set; }

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

public decimal Price { get; set; }
}
}
The [Column(TypeName = "decimal(18, 2)")] data annotation enables Entity Framework Core to correctly map
Price to currency in the database. For more information, see Data Types.
DataAnnotations is covered 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.

@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>
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, the ?id=1 in
https://localhost:5001/Movies/Details?id=1 ).

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?}"

To test the behavior of @page "{id:int?}" :

Set the page directive in Pages/Movies/Details.cshtml to @page "{id:int?}" .
Set a break point in public async Task<IActionResult> OnGetAsync(int? id) (in Pages/Movies/Details.cshtml.cs).
Navigate to https://localhost:5001/Movies/Details/ .

With the @page "{id:int}" directive, the break point is never hit. The routing engine returns HTTP 404. Using
@page "{id:int?}" , the OnGetAsync method returns NotFound ( HTTP 404 ).

Review concurrency exception handling

Review the OnPostAsync method in the Pages/Movies/Edit.cshtml.cs file:
 public async Task<IActionResult> OnPostAsync()
{
if (!ModelState.IsValid)
{
return Page();
}

_context.Attach(Movie).State = EntityState.Modified;

try
{
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!MovieExists(Movie.ID))
{
return NotFound();
}
else
{
throw;
}
}

return RedirectToPage("./Index");
}

private bool MovieExists(int id)

{
return _context.Movie.Any(e => e.ID == id);
}

The previous code detects concurrency exceptions when the one client deletes the movie and the other client posts
changes to the movie.
To test the catch block:
Set a breakpoint on catch (DbUpdateConcurrencyException)
Select Edit for a movie, make changes, but don't enter Save.
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 may want to detect concurrency conflicts. See Handle concurrency conflicts for more information.
Posting and binding review
Examine the Pages/Movies/Edit.cshtml.cs file:
 public class EditModel : PageModel
{
private readonly RazorPagesMovie.Data.RazorPagesMovieContext _context;

public EditModel(RazorPagesMovie.Data.RazorPagesMovieContext context)

{
_context = context;
}

[BindProperty]
public Movie Movie { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Movie = await _context.Movie.FirstOrDefaultAsync(m => m.ID == id);

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

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

_context.Attach(Movie).State = EntityState.Modified;

try
{
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!MovieExists(Movie.ID))
{
return NotFound();
}
else
{
throw;
}
}

return RedirectToPage("./Index");
}

private bool MovieExists(int id)

{
return _context.Movie.Any(e => e.ID == id);
}

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]
public Movie Movie { get; set; }

If there are errors in the model state (for example, ReleaseDate cannot be converted to a date), the form is
redisplayed 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.

Additional resources

P R E V IO U S : W O R K IN G W IT H A N E X T: A D D
D A TA B A SE SE A RCH

The scaffolded movie app has a good start, but the presentation isn't ideal. 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;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace RazorPagesMovie.Models
{
public class Movie
{
public int ID { get; set; }
public string Title { get; set; }

[Display(Name = "Release Date")]

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }
public string Genre { get; set; }

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

public decimal Price { get; set; }
}
}

The [Column(TypeName = "decimal(18, 2)")] data annotation enables Entity Framework Core to correctly map
Price to currency in the database. For more information, see Data Types.
DataAnnotations is covered 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.
 @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>

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, the ?id=1 in
https://localhost:5001/Movies/Details?id=1 ).

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?}"

To test the behavior of @page "{id:int?}" :

 Set the page directive in Pages/Movies/Details.cshtml to @page "{id:int?}" .
Set a break point in public async Task<IActionResult> OnGetAsync(int? id) (in Pages/Movies/Details.cshtml.cs).
Navigate to https://localhost:5001/Movies/Details/ .

With the @page "{id:int}" directive, the break point is never hit. The routing engine returns HTTP 404. Using
@page "{id:int?}" , the OnGetAsync method returns NotFound ( HTTP 404 ).

Review concurrency exception handling

Review the OnPostAsync method in the Pages/Movies/Edit.cshtml.cs file:

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

_context.Attach(Movie).State = EntityState.Modified;

try
{
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!MovieExists(Movie.ID))
{
return NotFound();
}
else
{
throw;
}
}

return RedirectToPage("./Index");
}

private bool MovieExists(int id)

{
return _context.Movie.Any(e => e.ID == id);
}

The previous code detects concurrency exceptions when the one client deletes the movie and the other client posts
changes to the movie.
To test the catch block:
Set a breakpoint on catch (DbUpdateConcurrencyException)
Select Edit for a movie, make changes, but don't enter Save.
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 may want to detect concurrency conflicts. See Handle concurrency conflicts for more information.
Posting and binding review
Examine the Pages/Movies/Edit.cshtml.cs file:
 public class EditModel : PageModel
{
private readonly RazorPagesMovieContext _context;

public EditModel(RazorPagesMovieContext context)

{
_context = context;
}

[BindProperty]
public Movie Movie { get; set; }

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();
}

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

_context.Attach(Movie).State = EntityState.Modified;

try
{
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!_context.Movie.Any(e => e.ID == Movie.ID))
{
return NotFound();
}
else
{
throw;
}
}

return RedirectToPage("./Index");
}
}

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]
public Movie Movie { get; set; }

If there are errors in the model state (for example, ReleaseDate cannot be converted to a date), the form is
displayed 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.

Additional resources
YouTube version of this tutorial

P R E V IO U S : W O R K IN G W IT H A N E X T: A D D
D A TA B A SE SE A RCH
 Add search to ASP.NET Core Razor Pages
7/24/2019 • 9 minutes to read • Edit Online

By Rick Anderson
View or download sample code (how to download).
View or download sample code (how to download).
In the following sections, searching movies by genre or name is added.
Add the following highlighted properties to Pages/Movies/Index.cshtml.cs:

public class IndexModel : PageModel

{
private readonly RazorPagesMovie.Data.RazorPagesMovieContext _context;

public IndexModel(RazorPagesMovie.Data.RazorPagesMovieContext context)

{
_context = context;
}

public IList<Movie> Movie { get; set; }

[BindProperty(SupportsGet = true)]
public string SearchString { get; set; }
// Requires using Microsoft.AspNetCore.Mvc.Rendering;
public SelectList Genres { get; set; }
[BindProperty(SupportsGet = true)]
public string MovieGenre { get; set; }

SearchString : contains the text users enter in the search text box. SearchString is decorated with the
[BindProperty] attribute. [BindProperty] binds form values and query strings with the same name as the
property. (SupportsGet = true) is required for binding on GET requests.
Genres : contains the list of genres. Genres allows the user to select a genre from the list. SelectList requires
using Microsoft.AspNetCore.Mvc.Rendering;
MovieGenre : contains the specific genre the user selects (for example, "Western").
Genres and MovieGenre are used later in this tutorial.

WARNING
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 GET binding 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)]

Update the Index page's OnGetAsync method with the following code:
 public async Task OnGetAsync()
{
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:

// using System.Linq;
var movies = from m in _context.Movie
select m;

The query is only defined at this point, it has not been run against the database.
If the SearchString property is not null or empty, the movies query is modified to filter on the search string:

if (!string.IsNullOrEmpty(SearchString))
{
movies = movies.Where(s => s.Title.Contains(SearchString));
}

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,
https://localhost:5001/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, https://localhost:5001/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.

The ASP.NET Core runtime uses model binding to set the value of the SearchString property from the query
string ( ?searchString=Ghost ) or route data ( https://localhost:5001/Movies/Ghost ). Model binding is not case
sensitive.
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
@model RazorPagesMovie.Pages.Movies.IndexModel

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-page="Create">Create New</a>
</p>

<form>
<p>
Title: <input type="text" asp-for="SearchString" />
<input type="submit" value="Filter" />
</p>
</form>

<table class="table">
@*Markup removed for brevity.*@

The HTML <form> tag uses the following Tag Helpers:

Form Tag Helper. When the form is submitted, the filter string is sent to the Pages/Movies/Index page via query
string.
Input Tag Helper
Save the changes and test the filter.
Search by genre
Update the OnGetAsync method with the following code:

public async Task OnGetAsync()

{
// Use LINQ to get list of genres.
IQueryable<string> genreQuery = from m in _context.Movie
orderby m.Genre
select m.Genre;

var movies = from m in _context.Movie

select m;

if (!string.IsNullOrEmpty(SearchString))
{
movies = movies.Where(s => s.Title.Contains(SearchString));
}

if (!string.IsNullOrEmpty(MovieGenre))
{
movies = movies.Where(x => x.Genre == MovieGenre);
}
Genres = new SelectList(await genreQuery.Distinct().ToListAsync());
Movie = await movies.ToListAsync();
}

The following code is a LINQ query that retrieves all the genres from the database.

// Use LINQ to get list of genres.

IQueryable<string> genreQuery = from m in _context.Movie
orderby m.Genre
select m.Genre;
The SelectList of genres is created by projecting the distinct genres.

Genres = new SelectList(await genreQuery.Distinct().ToListAsync());

Add search by genre to the Razor Page

Update Index.cshtml as follows:

@page
@model RazorPagesMovie.Pages.Movies.IndexModel

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-page="Create">Create New</a>
</p>

<form>
<p>
<select asp-for="MovieGenre" asp-items="Model.Genres">
<option value="">All</option>
</select>
Title: <input type="text" asp-for="SearchString" />
<input type="submit" value="Filter" />
</p>
</form>

<table class="table">
@*Markup removed for brevity.*@

Test the app by searching by genre, by movie title, and by both.

Additional resources
YouTube version of this tutorial

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

View or download sample code (how to download).

View or download sample code (how to download).
In the following sections, searching movies by genre or name is added.
Add the following highlighted properties to Pages/Movies/Index.cshtml.cs:
 public class IndexModel : PageModel
{
private readonly RazorPagesMovie.Models.RazorPagesMovieContext _context;

public IndexModel(RazorPagesMovie.Models.RazorPagesMovieContext context)

{
_context = context;
}

public IList<Movie> Movie { get; set; }

[BindProperty(SupportsGet = true)]
public string SearchString { get; set; }
// Requires using Microsoft.AspNetCore.Mvc.Rendering;
public SelectList Genres { get; set; }
[BindProperty(SupportsGet = true)]
public string MovieGenre { get; set; }

SearchString : contains the text users enter in the search text box. SearchString is decorated with the
[BindProperty] attribute. [BindProperty] binds form values and query strings with the same name as the
property. (SupportsGet = true) is required for binding on GET requests.
Genres : contains the list of genres. Genres allows the user to select a genre from the list. SelectList requires
using Microsoft.AspNetCore.Mvc.Rendering;
MovieGenre : contains the specific genre the user selects (for example, "Western").
Genres and MovieGenre are used later in this tutorial.

WARNING
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 GET binding 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)]

Update the Index page's OnGetAsync method with the following code:

public async Task OnGetAsync()

{
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:

// using System.Linq;
var movies = from m in _context.Movie
select m;

The query is only defined at this point, it has not been run against the database.
If the SearchString property is not null or empty, the movies query is modified to filter on the search string:
 if (!string.IsNullOrEmpty(SearchString))
{
movies = movies.Where(s => s.Title.Contains(SearchString));
}

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,
https://localhost:5001/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, https://localhost:5001/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.
The ASP.NET Core runtime uses model binding to set the value of the SearchString property from the query
string ( ?searchString=Ghost ) or route data ( https://localhost:5001/Movies/Ghost ). Model binding is not case
sensitive.
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
@model RazorPagesMovie.Pages.Movies.IndexModel

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-page="Create">Create New</a>
</p>

<form>
<p>
Title: <input type="text" asp-for="SearchString" />
<input type="submit" value="Filter" />
</p>
</form>

<table class="table">
@*Markup removed for brevity.*@

The HTML <form> tag uses the following Tag Helpers:

Form Tag Helper. When the form is submitted, the filter string is sent to the Pages/Movies/Index page via query
string.
 Input Tag Helper
Save the changes and test the filter.

Search by genre
Update the OnGetAsync method with the following code:

public async Task OnGetAsync()

{
// Use LINQ to get list of genres.
IQueryable<string> genreQuery = from m in _context.Movie
orderby m.Genre
select m.Genre;

var movies = from m in _context.Movie

select m;

if (!string.IsNullOrEmpty(SearchString))
{
movies = movies.Where(s => s.Title.Contains(SearchString));
}

if (!string.IsNullOrEmpty(MovieGenre))
{
movies = movies.Where(x => x.Genre == MovieGenre);
}
Genres = new SelectList(await genreQuery.Distinct().ToListAsync());
Movie = await movies.ToListAsync();
}

The following code is a LINQ query that retrieves all the genres from the database.
 // Use LINQ to get list of genres.
IQueryable<string> genreQuery = from m in _context.Movie
orderby m.Genre
select m.Genre;

The SelectList of genres is created by projecting the distinct genres.

Genres = new SelectList(await genreQuery.Distinct().ToListAsync());

Add search by genre to the Razor Page

Update Index.cshtml as follows:

@page
@model RazorPagesMovie.Pages.Movies.IndexModel

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-page="Create">Create New</a>
</p>

<form>
<p>
<select asp-for="MovieGenre" asp-items="Model.Genres">
<option value="">All</option>
</select>
Title: <input type="text" asp-for="SearchString" />
<input type="submit" value="Filter" />
</p>
</form>

<table class="table">
@*Markup removed for brevity.*@

Test the app by searching by genre, by movie title, and by both.

Additional resources
YouTube version of this tutorial

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
7/31/2019 • 10 minutes to read • Edit Online

By Rick Anderson
View or download sample code (how to download).
View or download sample code (how to download).
In this section Entity Framework Code First Migrations is used to:
Add a new field to the model.
Migrate the new field schema 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 int ID { get; set; }
public string Title { get; set; }

[Display(Name = "Release Date")]

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }
public string Genre { get; set; }

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

public decimal Price { get; set; }
public string Rating { get; set; }
}

Build the app.

Edit Pages/Movies/Index.cshtml, and add a Rating field:

@page
@model RazorPagesMovie.Pages.Movies.IndexModel

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-page="Create">Create New</a>
</p>
 <form>
<p>
<select asp-for="MovieGenre" asp-items="Model.Genres">
<option value="">All</option>
</select>
Title: <input type="text" asp-for="SearchString" />
<input type="submit" value="Filter" />
</p>
</form>

<table class="table">

<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>
@Html.DisplayNameFor(model => model.Movie[0].Rating)
</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>
@Html.DisplayFor(modelItem => item.Rating)
</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>

Update the following pages:

Add the Rating field to the Delete and Details pages.
Update Create.cshtml with a Rating field.
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. Don't 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.

context.Movie.AddRange(
new Movie
{
Title = "When Harry Met Sally",
ReleaseDate = DateTime.Parse("1989-2-12"),
Genre = "Romantic Comedy",
Price = 7.99M,
Rating = "R"
},

See the completed SeedData.cs file.

Build the solution.
Visual Studio
Visual Studio Code / Visual Studio for Mac
Add a migration for the rating field
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.
The Update-Database command tells the framework to apply the schema changes to the database.
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).
Another option is to delete the database and use migrations to re-create the database. To delete the database in
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, set a
break point in the SeedData.Initialize method.

Additional resources
YouTube version of this tutorial

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

View or download sample code (how to download).

View or download sample code (how to download).
In this section Entity Framework Code First Migrations is used to:
Add a new field to the model.
Migrate the new field schema 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 int ID { get; set; }
public string Title { get; set; }

[Display(Name = "Release Date")]

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }
public string Genre { get; set; }

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

public decimal Price { get; set; }
public string Rating { get; set; }
}

Build the app.

Edit Pages/Movies/Index.cshtml, and add a Rating field:

@page
@model RazorPagesMovie.Pages.Movies.IndexModel

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-page="Create">Create New</a>
</p>

<form>
<p>
<select asp-for="MovieGenre" asp-items="Model.Genres">
<option value="">All</option>
</select>
Title: <input type="text" asp-for="SearchString" />
<input type="submit" value="Filter" />
</p>
</form>

<table class="table">

<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>
@Html.DisplayNameFor(model => model.Movie[0].Rating)
</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>
@Html.DisplayFor(modelItem => item.Rating)
</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>

Update the following pages:

Add the Rating field to the Delete and Details pages.
Update Create.cshtml with a Rating field.
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. Don't 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.
 context.Movie.AddRange(
new Movie
{
Title = "When Harry Met Sally",
ReleaseDate = DateTime.Parse("1989-2-12"),
Genre = "Romantic Comedy",
Price = 7.99M,
Rating = "R"
},

See the completed SeedData.cs file.

Build the solution.
Visual Studio
Visual Studio Code / Visual Studio for Mac
Add a migration for the rating field
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.
The Update-Database command tells the framework to apply the schema changes to the database.
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).
Another option is to delete the database and use migrations to re-create the database. To delete the database in
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, set a
break point in the SeedData.Initialize method.

Additional resources
YouTube version of this tutorial

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
7/24/2019 • 9 minutes to read • Edit Online

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.
Make 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.

Add validation rules to the movie model

The DataAnnotations namespace provides a set of built-in 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 any validation.
Update the Movie class to take advantage of the built-in Required , StringLength , RegularExpression , and Range
validation attributes.
 public class Movie
{
public int Id { get; set; }

[StringLength(60, MinimumLength = 3)]

[Required]
public string Title { get; set; }

[Display(Name = "Release Date")]

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }

[Range(1, 100)]
[DataType(DataType.Currency)]
[Column(TypeName = "decimal(18, 2)")]
public decimal Price { get; set; }

[RegularExpression(@"^[A-Z]+[a-zA-Z""'\s-]*$")]
[Required]
[StringLength(30)]
public string Genre { get; set; }

[RegularExpression(@"^[A-Z]+[a-zA-Z0-9""'\s-]*$")]
[StringLength(5)]
[Required]
public string Rating { get; set; }
}

The validation attributes specify behavior that you want to enforce on the model properties they're applied to:
The Required and MinimumLength attributes indicate 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 preceding code,
"Genre":
Must only use letters.
The first letter is required to be uppercase. White space, numbers, and special characters are not allowed.
The RegularExpression "Rating":
Requires that the first character be an uppercase letter.
Allows special characters and numbers in subsequent spaces. "PG -13" is valid for a rating, but fails for a
"Genre".
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 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 commas in decimal fields. 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.

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. You can disable JavaScript using browser's developer tools. 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 invalid data.
Verify the model state is invalid:

if (!ModelState.IsValid)
{
return Page();
}

The following code shows a portion of the Create.cshtml page 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.

<form method="post">
<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>

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.

[Display(Name = "Release Date")]

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }

[Range(1, 100)]
[DataType(DataType.Currency)]
public decimal Price { get; set; }
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 [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 DisplayFormat attribute is used to explicitly specify the date format:

[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]

public DateTime ReleaseDate { get; set; }

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
{
public int ID { get; set; }

[StringLength(60, MinimumLength = 3)]

public string Title { get; set; }

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

public DateTime ReleaseDate { get; set; }

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

public string Genre { get; set; }

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

[Column(TypeName = "decimal(18, 2)")]
public decimal Price { get; set; }

[RegularExpression(@"^[A-Z]+[a-zA-Z0-9""'\s-]*$"), StringLength(5)]
public string Rating { get; set; }
}

Get started with Razor Pages and EF Core shows advanced EF Core operations with Razor Pages.
Apply migrations
The DataAnnotations applied to the class change the schema. For example, the DataAnnotations applied to the
Title field:

[StringLength(60, MinimumLength = 3)]

[Required]
public string Title { get; set; }

Limits the characters to 60.

Doesn't allow a null value.

Visual Studio
Visual Studio Code / Visual Studio for Mac
The Movie table currently has the following schema:

CREATE TABLE [dbo].[Movie] (

[ID] INT IDENTITY (1, 1) NOT NULL,
[Title] NVARCHAR (MAX) NULL,
[ReleaseDate] DATETIME2 (7) NOT NULL,
[Genre] NVARCHAR (MAX) NULL,
[Price] DECIMAL (18, 2) NOT NULL,
[Rating] NVARCHAR (MAX) NULL,
CONSTRAINT [PK_Movie] PRIMARY KEY CLUSTERED ([ID] ASC)
);

The preceding schema changes don't cause EF to throw an exception. However, create a migration so the schema is
consistent with the model.
From the Tools menu, select NuGet Package Manager > Package Manager Console. In the PMC, enter the
following commands:

Add-Migration New_DataAnnotations
Update-Database
Update-Database runs the Up methods of the New_DataAnnotations class. Examine the Up method:

public partial class New_DataAnnotations : Migration

{
protected override void Up(MigrationBuilder migrationBuilder)
{
migrationBuilder.AlterColumn<string>(
name: "Title",
table: "Movie",
maxLength: 60,
nullable: false,
oldClrType: typeof(string),
oldNullable: true);

migrationBuilder.AlterColumn<string>(
name: "Rating",
table: "Movie",
maxLength: 5,
nullable: false,
oldClrType: typeof(string),
oldNullable: true);

migrationBuilder.AlterColumn<string>(
name: "Genre",
table: "Movie",
maxLength: 30,
nullable: false,
oldClrType: typeof(string),
oldNullable: true);
}

The updated Movie table has the following schema:

CREATE TABLE [dbo].[Movie] (

[ID] INT IDENTITY (1, 1) NOT NULL,
[Title] NVARCHAR (60) NOT NULL,
[ReleaseDate] DATETIME2 (7) NOT NULL,
[Genre] NVARCHAR (30) NOT NULL,
[Price] DECIMAL (18, 2) NOT NULL,
[Rating] NVARCHAR (5) NOT NULL,
CONSTRAINT [PK_Movie] PRIMARY KEY CLUSTERED ([ID] ASC)
);

Publish to Azure
For information on deploying to Azure, see Tutorial: Build an ASP.NET Core app in Azure with SQL Database.
Thanks for completing this introduction to Razor Pages. Get started with Razor Pages and EF Core is an excellent
follow up to this tutorial.

Additional resources
Tag Helpers in forms in ASP.NET Core
Globalization and localization in ASP.NET Core
Tag Helpers in ASP.NET Core
Author Tag Helpers in ASP.NET Core
YouTube version of this tutorial
P R E V IO U S : A D D IN G A N E W
F IE L D
 Create a web app with ASP.NET Core MVC
4/26/2019 • 2 minutes to read • Edit Online

This tutorial teaches ASP.NET Core MVC web development with controllers and views. If you're new to ASP.NET
Core web development, consider the Razor Pages version of this tutorial, which provides an easier starting point.
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
8/6/2019 • 11 minutes to read • Edit Online

By Rick Anderson
This tutorial teaches ASP.NET Core MVC web development with controllers and views. If you're new to ASP.NET
Core web development, consider the Razor Pages version of this tutorial, which provides an easier starting point.
This tutorial teaches the basics of building an ASP.NET Core MVC web app.
The app manages a database of movie titles. You learn how to:
Create a web app.
Add and scaffold a model.
Work with a database.
Add search and validation.
At the end, you have an app that can manage and display movie data.
View or download sample code (how to download).

Prerequisites
Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 3.0 Preview

Create a web app

Visual Studio
Visual Studio Code
Visual Studio for Mac
From the Visual Studio select Create a new project.
Select ASP.NET Core Web Application and then select Next.
Name the project MvcMovie and select Create. It's important to name the project MvcMovie so when
you copy code, the namespace will match.

Select Web Application(Model-View-Controller), and then select Create.

Visual Studio used the 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.
Run the app
Visual Studio
Visual Studio Code
Visual Studio for Mac
Select Ctrl-F5 to run the app in non-debug mode.
Visual Studio displays the following dialog:

Select Yes if you trust the IIS Express SSL certificate.

The following dialog is displayed:
Select Yes if you agree to trust the development certificate.
See Trust the ASP.NET Core HTTPS development certificate for more information.
Visual Studio starts IIS Express and runs the 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.
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.
You can launch the app in debug or non-debug mode from the Debug menu item:

You can debug the app by selecting the IIS Express button
 The following image shows the app:

Visual Studio
Visual Studio Code
Visual Studio for Mac

Visual Studio help

Learn to debug C# code using Visual Studio
Introduction to the Visual Studio IDE
In the next part of this tutorial, you learn about MVC and start writing some code.

NEXT

This tutorial teaches ASP.NET Core MVC web development with controllers and views. If you're new to ASP.NET
Core web development, consider the Razor Pages version of this tutorial, which provides an easier starting point.
This tutorial teaches the basics of building an ASP.NET Core MVC web app.
The app manages a database of movie titles. You learn how to:
Create a web app.
Add and scaffold a model.
Work with a database.
Add search and validation.
At the end, you have an app that can manage and display movie data.
View or download sample code (how to download).
Prerequisites
Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 2.2 or later

WARNING
If you use Visual Studio 2017, see dotnet/sdk issue #3124 for information about .NET Core SDK versions that don't work with
Visual Studio.

Create a web app

Visual Studio
Visual Studio Code
Visual Studio for Mac
From the Visual Studio select Create a new project.
Selecct ASP.NET Core Web Application and then select Next.

Name the project MvcMovie and select Create. It's important to name the project MvcMovie so when
you copy code, the namespace will match.
 Select Web Application(Model-View-Controller), and then select Create.

Visual Studio used the 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.
Run the app
Visual Studio
Visual Studio Code
Visual Studio for Mac
Select Ctrl-F5 to run the app in non-debug mode.
Visual Studio displays the following dialog:

Select Yes if you trust the IIS Express SSL certificate.

The following dialog is displayed:

Select Yes if you agree to trust the development certificate.

See Trust the ASP.NET Core HTTPS development certificate for more information.
Visual Studio starts IIS Express and runs the 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.
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.
You can launch the app in debug or non-debug mode from the Debug menu item:
You can debug the app by selecting the IIS Express button

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
Visual Studio Code
Visual Studio for Mac

Visual Studio help

Learn to debug C# code using Visual Studio
Introduction to the Visual Studio IDE
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
8/6/2019 • 12 minutes to read • Edit Online

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,
https://localhost:5001/Home/Privacy has route data of Home (the controller ) and Privacy (the action
method to call on the home controller). https://localhost:5001/Movies/Edit/5 is a request to edit the movie
with ID=5 using the movie controller. Route data is explained 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.

Add a controller
Visual Studio
Visual Studio Code
Visual Studio for Mac
In Solution Explorer, right-click Controllers > Add > Controller
 In the Add Scaffold dialog box, select MVC Controller - Empty

In the Add Empty MVC Controller dialog, enter HelloWorldController and select ADD.
Replace the contents of Controllers/HelloWorldController.cs with the following:
 using Microsoft.AspNetCore.Mvc;
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 https://localhost:5001/HelloWorld , and
combines the protocol used: HTTPS , the network location of the web server (including the TCP port):
localhost:5001 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 the scaffolding engine is used to generate HTTP POST methods which update data.
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]

The routing format is set in the Configure method in Startup.cs file.

app.UseEndpoints(endpoints =>
{
endpoints.MapControllerRoute(
name: "default",
pattern: "{controller=Home}/{action=Index}/{id?}");
endpoints.MapRazorPages();
});

When you browse to 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:{PORT}/HelloWorld maps to the
HelloWorldController class. The second part of the URL segment determines the action method on the class. So
localhost:{PORT}/HelloWorld/Index would cause the Index method of the HelloWorldController class to run.
Notice that you only had to browse to localhost:{PORT}/HelloWorld and the Index method was called by default.
That's 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. Route data is explained later in the tutorial.
Browse to https://localhost:{PORT}/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.
 // GET: /HelloWorld/Welcome/
// 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 in $"Hello {name}, NumTimes is: {numTimes}" .

Run the app and browse to:

https://localhost:{PORT}/HelloWorld/Welcome?name=Rick&numtimes=4

(Replace {PORT} 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: https://localhost:{PORT}/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 MapControllerRoute method. The trailing ? (in id? ) indicates the id
parameter is optional.
 app.UseEndpoints(endpoints =>
{
endpoints.MapControllerRoute(
name: "default",
pattern: "{controller=Home}/{action=Index}/{id?}");
endpoints.MapRazorPages();
});

In these examples the controller has been doing the "VC" portion of MVC - that is, the View and the 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 generate the HTML response. You do that in the next tutorial.

P R E V IO U S NEXT

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,
https://localhost:5001/Home/About has route data of Home (the controller ) and About (the action method to
call on the home controller). https://localhost:5001/Movies/Edit/5 is a request to edit the movie with ID=5
using the movie controller. Route data is explained 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.

Add a controller
Visual Studio
Visual Studio Code
Visual Studio for Mac
In Solution Explorer, right-click Controllers > Add > Controller
 In the Add Scaffold dialog box, select MVC Controller - Empty

In the Add Empty MVC Controller dialog, enter HelloWorldController and select ADD.
Replace the contents of Controllers/HelloWorldController.cs with the following:
 using Microsoft.AspNetCore.Mvc;
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 https://localhost:5001/HelloWorld , and
combines the protocol used: HTTPS , the network location of the web server (including the TCP port):
localhost:5001 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 the scaffolding engine is used to generate HTTP POST methods which update data.
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]

The routing format is set in the Configure method in Startup.cs file.

app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});

When you browse to 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:{PORT}/HelloWorld maps to the
HelloWorldController class. The second part of the URL segment determines the action method on the class. So
localhost:{PORT}/HelloWorld/Index would cause the Index method of the HelloWorldController class to run.
Notice that you only had to browse to localhost:{PORT}/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. Route data is explained later in the tutorial.
Browse to https://localhost:{PORT}/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.
 // GET: /HelloWorld/Welcome/
// 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 in $"Hello {name}, NumTimes is: {numTimes}" .

Run the app and browse to:

https://localhost:{PORT}/HelloWorld/Welcome?name=Rick&numtimes=4

(Replace {PORT} 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: https://localhost:{PORT}/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.
 app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});

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.

P R E V IO U S NEXT
 Add a view to an ASP.NET Core MVC app
8/6/2019 • 16 minutes to read • Edit Online

By Rick Anderson
In this section you modify the HelloWorldController class to use Razor view 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 with 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 calls the controller's View method. It uses a view template to generate an HTML response.
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 .

Add a view
Visual Studio
Visual Studio Code
Visual Studio for Mac
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
Select Razor View
Keep the Name box value, Index.cshtml.
Select Add
Replace the contents of the Views/HelloWorld/Index.cshtml Razor view file with the following:

@{
ViewData["Title"] = "Index";
}

<h2>Index</h2>

<p>Hello from our View Template!</p>

Navigate to https://localhost:{PORT}/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 a view template file name wasn't specified, MVC defaulted to using the default
view file. The default view file has the same name as the method ( Index ), so in the
/Views/HelloWorld/Index.cshtml is used. The image below shows the string "Hello from our View Template!" hard-
coded in the view.
Change views and layout pages
Select the menu links (MvcMovie, Home, and Privacy). 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 Privacy link, the
Views/Home/Privacy.cshtml view is rendered inside the RenderBody method.

Change the title, footer, and menu link in the layout file
Replace the content of the Views\Shared_Layout.cshtml file with the following markup. The changes are
highlighted:
 <!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@ViewData["Title"] - Movie App</title>
<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
<link rel="stylesheet" href="~/css/site.css" />
</head>
<body>
<header>
<nav class="navbar navbar-expand-sm navbar-toggleable-sm navbar-light bg-white border-bottom box-shadow
mb-3">
<div class="container">
<a class="navbar-brand" asp-controller="Movies" asp-action="Index">Movie App</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target=".navbar-
collapse" aria-controls="navbarSupportedContent"
aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="navbar-collapse collapse d-sm-inline-flex flex-sm-row-reverse">
<ul class="navbar-nav flex-grow-1">
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-
action="Index">Home</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-
action="Privacy">Privacy</a>
</li>
</ul>
</div>
</div>
</nav>
</header>
<div class="container">
<main role="main" class="pb-3">
@RenderBody()
</main>
</div>

<footer class="border-top footer text-muted">

<div class="container">
&copy; 2019 - Movie App - <a asp-area="" asp-controller="Home" asp-action="Privacy">Privacy</a>
</div>
</footer>
<script src="~/lib/jquery/dist/jquery.js"></script>
<script src="~/lib/bootstrap/dist/js/bootstrap.bundle.js"></script>
<script src="~/js/site.js" asp-append-version="true"></script>
@RenderSection("Scripts", required: false)
</body>
</html>

The preceding markup made the following changes:

3 occurrences of MvcMovie to Movie App .
The anchor element <a class="navbar-brand" asp-area="" asp-controller="Home" asp-action="Index">MvcMovie</a>
to <a class="navbar-brand" asp-controller="Movies" asp-action="Index">Movie App</a> .
In the preceding markup, the asp-area="" anchor Tag Helper attribute and attribute value was omitted because this
app is not using Areas.
Note: The Movies controller has not been implemented. At this point, the Movie App link is not functional.
Save your changes and select the Privacy link. Notice how the title on the browser tab displays Privacy Policy -
Movie App instead of Privacy Policy - Mvc Movie:

Select the Home 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. The Layout property
can be used to set a different layout view, or set it to null so no layout file will be used.
Change the title and <h2> element of the Views/HelloWorld/Index.cshtml view file:

@{
ViewData["Title"] = "Movie List";
}

<h2>My Movie List</h2>

<p>Hello from our View Template!</p>

The title and <h2> element are slightly different so you can see which bit of code changes the display.
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:

<title>@ViewData["Title"] - Movie App</title>

Save the change and navigate to https://localhost:{PORT}/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.
The content in the Index.cshtml view template is merged with the Views/Shared/_Layout.cshtml view template. A
single HTML response is sent to the browser. Layout templates make it easy to make changes that apply across all
of the pages in an app. 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 the code is
written 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 the 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.
In HelloWorldController.cs, change the Welcome method to add a Message and NumTimes value to the ViewData
dictionary. The ViewData dictionary is a dynamic object, which means any type can be used; 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:
 using Microsoft.AspNetCore.Mvc;
using System.Text.Encodings.Web;

namespace MvcMovie.Controllers
{
public class HelloWorldController : Controller
{
public IActionResult Index()
{
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:

https://localhost:{PORT}/HelloWorld/Welcome?name=Rick&numtimes=4

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, the ViewData dictionary was used to pass data from the controller to a view. Later in the
tutorial, a view model is used 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 When to use ViewBag, ViewData, or
TempData for more information.
In the next tutorial, a database of movies is created.

P R E V IO U S NEXT

In this section you modify the HelloWorldController class to use Razor view 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 with 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 calls the controller's View method. It uses a view template to generate an HTML response.
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 .

Add a view
Visual Studio
Visual Studio Code
Visual Studio for Mac
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
Select Razor View
Keep the Name box value, Index.cshtml.
Select Add

Replace the contents of the Views/HelloWorld/Index.cshtml Razor view file with the following:

@{
ViewData["Title"] = "Index";
}

<h2>Index</h2>

<p>Hello from our View Template!</p>

Navigate to https://localhost:{PORT}/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 a view template file name wasn't specified, MVC defaulted to using the default
view file. The default view file has the same name as the method ( Index ), so in the
/Views/HelloWorld/Index.cshtml is used. The image below shows the string "Hello from our View Template!" hard-
coded in the view.
Change views and layout pages
Select the menu links (MvcMovie, Home, and Privacy). 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 Privacy link, the
Views/Home/Privacy.cshtml view is rendered inside the RenderBody method.

Change the title, footer, and menu link in the layout file
In the title and footer elements, change MvcMovie to Movie App .
Change the anchor element
<a class="navbar-brand" asp-area="" asp-controller="Home" asp-action="Index">MvcMovie</a> to
<a class="navbar-brand" asp-controller="Movies" asp-action="Index">Movie App</a> .

The following markup shows the highlighted changes:

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@ViewData["Title"] - Movie App</title>

<environment include="Development">
<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
</environment>
<environment exclude="Development">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-
bootstrap/4.1.3/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"
crossorigin="anonymous"
integrity="sha256-eSi1q2PG6J7g7ib17yAaWMcrr5GrtohYChqibrV7PBE="/>
</environment>
<link rel="stylesheet" href="~/css/site.css" />
</head>
<body>
 <body>
<header>
<nav class="navbar navbar-expand-sm navbar-toggleable-sm navbar-light bg-white border-bottom box-shadow
mb-3">
<div class="container">
<a class="navbar-brand" asp-controller="Movies" asp-action="Index">Movie App</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target=".navbar-
collapse" aria-controls="navbarSupportedContent"
aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="navbar-collapse collapse d-sm-inline-flex flex-sm-row-reverse">
<ul class="navbar-nav flex-grow-1">
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-
action="Index">Home</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-
action="Privacy">Privacy</a>
</li>
</ul>
</div>
</div>
</nav>
</header>
<div class="container">
<partial name="_CookieConsentPartial" />
<main role="main" class="pb-3">
@RenderBody()
</main>
</div>

<footer class="border-top footer text-muted">

<div class="container">
&copy; 2019 - Movie App - <a asp-area="" asp-controller="Home" asp-action="Privacy">Privacy</a>
</div>
</footer>

<environment include="Development">
<script src="~/lib/jquery/dist/jquery.js"></script>
<script src="~/lib/bootstrap/dist/js/bootstrap.bundle.js"></script>
</environment>
<environment exclude="Development">
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js"
asp-fallback-src="~/lib/jquery/dist/jquery.min.js"
asp-fallback-test="window.jQuery"
crossorigin="anonymous"
integrity="sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8=">
</script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.1.3/js/bootstrap.bundle.min.js"
asp-fallback-src="~/lib/bootstrap/dist/js/bootstrap.bundle.min.js"
asp-fallback-test="window.jQuery && window.jQuery.fn && window.jQuery.fn.modal"
crossorigin="anonymous"
integrity="sha256-E/V4cWE4qvAeO5MOhjtGtqDzPndRO1LBk8lJ/PR7CA4=">
</script>
</environment>
<script src="~/js/site.js" asp-append-version="true"></script>

@RenderSection("Scripts", required: false)

</body>
</html>

In the preceding markup, the asp-area anchor Tag Helper attribute was omitted because this app is not using
Areas.
Note: The Movies controller has not been implemented. At this point, the Movie App link is not functional.
Save your changes and select the Privacy link. Notice how the title on the browser tab displays Privacy Policy -
Movie App instead of Privacy Policy - Mvc Movie:

Select the Home 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. The Layout property
can be used to set a different layout view, or set it to null so no layout file will be used.
Change the title and <h2> element of the Views/HelloWorld/Index.cshtml view file:

@{
ViewData["Title"] = "Movie List";
}

<h2>My Movie List</h2>

<p>Hello from our View Template!</p>

The title and <h2> element are slightly different so you can see which bit of code changes the display.
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:

<title>@ViewData["Title"] - Movie App</title>

Save the change and navigate to https://localhost:{PORT}/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 the code is
written 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 the 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.
In HelloWorldController.cs, change the Welcome method to add a Message and NumTimes value to the ViewData
dictionary. The ViewData dictionary is a dynamic object, which means any type can be used; 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:
 using Microsoft.AspNetCore.Mvc;
using System.Text.Encodings.Web;

namespace MvcMovie.Controllers
{
public class HelloWorldController : Controller
{
public IActionResult Index()
{
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:

https://localhost:{PORT}/HelloWorld/Welcome?name=Rick&numtimes=4

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, the ViewData dictionary was used to pass data from the controller to a view. Later in the
tutorial, a view model is used 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 When to use ViewBag, ViewData, or
TempData for more information.
In the next tutorial, a database of movies is created.

P R E V IO U S NEXT
 Add a model to an ASP.NET Core MVC app
6/11/2019 • 12 minutes to read • Edit Online

By Rick Anderson and Tom Dykstra

In this section, you add 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.
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 just define the properties of the data that will be 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. For information about that approach, see
ASP.NET Core - Existing Database.

Add a data model class

Visual Studio
Visual Studio Code / Visual Studio for Mac
Right-click the Models folder > Add > Class. Name the class Movie.
Add the following properties to the Movie class:

using System;
using System.ComponentModel.DataAnnotations;

namespace MvcMovie.Models
{
public class Movie
{
public int Id { get; set; }
public string Title { get; set; }

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }
public string Genre { get; set; }
public decimal Price { get; set; }
}
}

The Movie class contains:

The Id field which is required by the database for the primary key.
[DataType(DataType.Date)] : The DataType attribute specifies the type of the data ( Date ). With this attribute:
The user is not required to enter time information in the date field.
Only the date is displayed, not time information.
DataAnnotations are covered in a later tutorial.
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.
Visual Studio
Visual Studio Code
Visual Studio for Mac
In Solution Explorer, right-click the Controllers folder > Add > New Scaffolded Item.

In the Add Scaffold dialog, select 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
Select 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.
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 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.

Initial migration
In this section, the following tasks are completed:
Add an initial migration.
Update the database with the initial migration.
Visual Studio
Visual Studio Code / Visual Studio for Mac
1. From the Tools menu, select NuGet Package Manager > Package Manager Console (PMC ).

2. In the PMC, enter the following commands:

Add-Migration Initial
Update-Database

The Add-Migration command generates code to create the initial database schema.
The database schema is based on the model specified in the MvcMovieContext class. The Initial argument
is the migration name. Any name can be used, but by convention, a name that describes the migration is
used. For more information, see Tutorial: Using the migrations feature - ASP.NET MVC with EF Core.
The Update-Database command runs the Up method in the Migrations/{time-stamp }_InitialCreate.cs file,
which creates the database.

Examine the context registered with dependency injection

ASP.NET Core is built with dependency injection (DI). Services (such as the EF Core DB context) are registered with
DI 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.
Visual Studio
Visual Studio Code / Visual Studio for Mac
The scaffolding tool automatically created a DB context and registered it with the DI container.
Examine the following Startup.ConfigureServices method. The highlighted line was added by the scaffolder:

public void ConfigureServices(IServiceCollection services)

{
services.Configure<CookiePolicyOptions>(options =>
{
// This lambda determines whether user consent for non-essential cookies
// is needed for a given request.
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

services.AddDbContext<MvcMovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("MvcMovieContext")));
}

The MvcMovieContext coordinates EF Core functionality (Create, Read, Update, Delete, etc.) for the Movie model.
The data context ( MvcMovieContext ) is derived from Microsoft.EntityFrameworkCore.DbContext. The data context
specifies which entities are included in the data model:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.EntityFrameworkCore;

namespace MvcMovie.Models
{
public class MvcMovieContext : DbContext
{
public MvcMovieContext (DbContextOptions<MvcMovieContext> options)
: base(options)
{
}

public DbSet<MvcMovie.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.
Test the app
 Run the app and append /Movies to the URL in the browser ( http://localhost:port/movies ).
If you get a database exception similar to the following:

SqlException: Cannot open database "MvcMovieContext-GUID" requested by the login. The login failed.
Login failed for user 'User-name'.

You missed the migrations step.

Test the Create link. Enter and submit data.

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 for non US-English date formats, the app must be globalized.
For globalization instructions, see this GitHub issue.

Test the Edit, Details, and Delete links.

Examine the Startup class:

public void ConfigureServices(IServiceCollection services)

{
services.Configure<CookiePolicyOptions>(options =>
{
// This lambda determines whether user consent for non-essential cookies
// is needed for a given request.
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

services.AddDbContext<MvcMovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("MvcMovieContext")));
}

The preceding highlighted code shows the movie database context being added to the Dependency Injection
container:
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);
}

The id parameter is generally passed as route data. For example https://localhost:5001/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:
https://localhost:5001/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.

var movie = await _context.Movie

.FirstOrDefaultAsync(m => m.Id == id);

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";
}

<h1>Details</h1>

<div>
<h4>Movie</h4>
<hr />
<dl class="row">
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Title)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Title)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.ReleaseDate)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.ReleaseDate)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Genre)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Genre)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Price)
</dt>
<dd class="col-sm-10">
@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, the following @model statement was automatically included at the top of
the Details.cshtml file:

@model MvcMovie.Models.Movie

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 @model directive 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>

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-action="Create">Create New</a>
</p>
<table class="table">
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.Title)
</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>
@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-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:

Additional resources
Tag Helpers
Globalization and localization
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 in ASP.NET Core
4/26/2019 • 4 minutes to read • Edit Online

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:

Visual Studio
Visual Studio Code / Visual Studio for Mac

public void ConfigureServices(IServiceCollection services)

{
services.Configure<CookiePolicyOptions>(options =>
{
// This lambda determines whether user consent for non-essential cookies
// is needed for a given request.
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

services.AddDbContext<MvcMovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("MvcMovieContext")));
}

The ASP.NET Core Configuration system reads the ConnectionString . For local development, it gets the
connection string from the appsettings.json file:

"ConnectionStrings": {
"MvcMovieContext": "Server=(localdb)\\mssqllocaldb;Database=MvcMovieContext-
2;Trusted_Connection=True;MultipleActiveResultSets=true"
}

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.
Visual Studio
Visual Studio Code / Visual Studio for Mac

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 > 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
Create a new class named SeedData in the Models folder. Replace the generated code with the following:
 using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using System;
using System.Linq;

namespace MvcMovie.Models
{
public static class SeedData
{
public static void Initialize(IServiceProvider serviceProvider)
{
using (var context = new MvcMovieContext(
serviceProvider.GetRequiredService<
DbContextOptions<MvcMovieContext>>()))
{
// 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 ",
ReleaseDate = DateTime.Parse("1984-3-13"),
Genre = "Comedy",
Price = 8.99M
},

new Movie
{
Title = "Ghostbusters 2",
ReleaseDate = DateTime.Parse("1986-2-23"),
Genre = "Comedy",
Price = 9.99M
},

new Movie
{
Title = "Rio Bravo",
ReleaseDate = DateTime.Parse("1959-4-15"),
Genre = "Western",
Price = 3.99M
}
);
context.SaveChanges();
}
}
}
}

If there are any movies in the DB, the seed initializer returns and no movies are added.
 if (context.Movie.Any())
{
return; // DB has been seeded.
}

Add the seed initializer

Replace the contents of Program.cs with the following code:

using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using System;
using Microsoft.EntityFrameworkCore;
using MvcMovie.Models;
using MvcMovie;

namespace MvcMovie
{
public class Program
{
public static void Main(string[] args)
{
var host = CreateWebHostBuilder(args).Build();

using (var scope = host.Services.CreateScope())

{
var services = scope.ServiceProvider;

try
{
var context = services.GetRequiredService<MvcMovieContext>();
context.Database.Migrate();
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 IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>();
}
}

Test the app

Visual Studio
Visual Studio Code / Visual Studio for Mac
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
7/11/2019 • 9 minutes to read • Edit Online

By Rick Anderson
We have a good start to the movie app, but the presentation isn't ideal, for example, ReleaseDate should be two
words.

Open the Models/Movie.cs file and add the highlighted lines shown below:
 using System;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace MvcMovie.Models
{
public class Movie
{
public int Id { get; set; }
public string Title { get; set; }

[Display(Name = "Release Date")]

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }
public string Genre { get; set; }

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

public decimal Price { get; set; }
}
}

We 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.
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.
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.
 <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>

Tag Helpers enable server-side code to participate in creating and rendering HTML elements in Razor files. In the
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:

app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});

ASP.NET Core translates https://localhost:5001/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. For more information, see Additional
resources.
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);
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!MovieExists(movie.ID))
{
return NotFound();
}
else
{
throw;
}
}
return RedirectToAction("Index");
}
return View(movie);
}

// GET: Movies/Edit/5
public async Task<IActionResult> Edit(int? id)
{
if (id == null)
{
return NotFound();
}

var movie = await _context.Movie.SingleOrDefaultAsync(m => m.ID == 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);
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!MovieExists(movie.ID))
{
return NotFound();
}
else
{
throw;
}
}
return RedirectToAction("Index");
}
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. For more information, see Protect your controller from over-posting.
ViewModels provide an alternative approach to prevent over-posting.
Notice the second Edit action method is preceded by the [HttpPost] attribute.
[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);
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!MovieExists(movie.ID))
{
return NotFound();
}
else
{
throw;
}
}
return RedirectToAction(nameof(Index));
}
return View(movie);
}
 // 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);
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!MovieExists(movie.ID))
{
return NotFound();
}
else
{
throw;
}
}
return RedirectToAction("Index");
}
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
FindAsync method, and returns the selected movie to the Edit view. If a movie cannot be found, NotFound ( HTTP
404) is returned.
 // 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);
}

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:
 @model MvcMovie.Models.Movie

@{
ViewData["Title"] = "Edit";
}

<h1>Edit</h1>

<h4>Movie</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form asp-action="Edit">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<input type="hidden" asp-for="Id" />
<div class="form-group">
<label asp-for="Title" class="control-label"></label>
<input asp-for="Title" class="form-control" />
<span asp-validation-for="Title" class="text-danger"></span>
</div>
<div class="form-group">
<label asp-for="ReleaseDate" class="control-label"></label>
<input asp-for="ReleaseDate" class="form-control" />
<span asp-validation-for="ReleaseDate" class="text-danger"></span>
</div>
<div class="form-group">
<label asp-for="Genre" class="control-label"></label>
<input asp-for="Genre" class="form-control" />
<span asp-validation-for="Genre" class="text-danger"></span>
</div>
<div class="form-group">
<label asp-for="Price" class="control-label"></label>
<input asp-for="Price" class="form-control" />
<span asp-validation-for="Price" class="text-danger"></span>
</div>
<div class="form-group">
<input type="submit" value="Save" class="btn btn-primary" />
</div>
</form>
</div>
</div>

<div>
<a asp-action="Index">Back to List</a>
</div>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

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">
<div class="form-horizontal">
<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" />
<div class="form-group">
<label class="control-label col-md-2" for="Genre" />
<div class="col-md-10">
<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>
<div class="form-group">
<label class="control-label col-md-2" for="Price" />
<div class="col-md-10">
<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-
replace="true"></span>
</div>
</div>
<!-- Markup removed for brevity -->
<div class="form-group">
<div class="col-md-offset-2 col-md-10">
<input type="submit" value="Save" class="btn btn-default" />
</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]
[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);
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!MovieExists(movie.ID))
{
return NotFound();
}
else
{
throw;
}
}
return RedirectToAction(nameof(Index));
}
return View(movie);
}
 // 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);
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!MovieExists(movie.ID))
{
return NotFound();
}
else
{
throw;
}
}
return RedirectToAction("Index");
}
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.

Additional resources
Globalization and localization
Introduction to Tag Helpers
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
8/7/2019 • 7 minutes to read • Edit Online

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 found inside Controllers/MoviesController.cs with the following code:

public async Task<IActionResult> Index(string searchString)

{
var movies = from m in _context.Movie
select m;

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

return View(await movies.ToListAsync());

}

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

var movies = from m in _context.Movie

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 value of the search
string:

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

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 SQLite, 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.

app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});

Change the parameter to id and all occurrences of searchString change to id .

The previous Index method:

public async Task<IActionResult> Index(string searchString)

{
var movies = from m in _context.Movie
select m;

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

return View(await movies.ToListAsync());

}

The updated Index method with id parameter:

 public async Task<IActionResult> Index(string id)
{
var movies = from m in _context.Movie
select m;

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

return View(await movies.ToListAsync());

}

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 :

public async Task<IActionResult> Index(string searchString)

{
var movies = from m in _context.Movie
select m;

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

return View(await movies.ToListAsync());

}

Open the Views/Movies/Index.cshtml file, and add the <form> markup highlighted below:
 ViewData["Title"] = "Index";
}

<h2>Index</h2>

<p>
<a asp-action="Create">Create New</a>
</p>

<form asp-controller="Movies" asp-action="Index">

<p>
Title: <input type="text" name="SearchString">
<input type="submit" value="Filter" />
</p>
</form>

<table class="table">
<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:{PORT}/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. Fix this by specifying the request should be HTTP GET found in the
Views/Movies/Index.cshtml file.
 @model IEnumerable<MvcMovie.Models.Movie>

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-action="Create">Create New</a>
</p>
<form asp-controller="Movies" asp-action="Index" method="get">
<p>
Title: <input type="text" name="SearchString">
<input type="submit" value="Filter" />
</p>
</form>

<table class="table">
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.Title)

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">

Add Search by genre

Add the following MovieGenreViewModel class to the Models folder:

using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

namespace MvcMovie.Models
{
public class MovieGenreViewModel
{
public List<Movie> Movies { get; set; }
public SelectList Genres { get; set; }
public string MovieGenre { get; set; }
public string SearchString { get; set; }
}
}

The movie-genre view model will contain:

A list of movies.
A SelectList containing the list of genres. This allows the user to select a genre from the list.
MovieGenre , which contains the selected genre.
SearchString , which contains the text users enter in the search text box.

Replace the Index method in MoviesController.cs with the following code:

// GET: Movies
public async Task<IActionResult> Index(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;

var movies = from m in _context.Movie

select m;

if (!string.IsNullOrEmpty(searchString))
{
movies = movies.Where(s => s.Title.Contains(searchString));
}

if (!string.IsNullOrEmpty(movieGenre))
{
movies = movies.Where(x => x.Genre == movieGenre);
}

var movieGenreVM = new MovieGenreViewModel

{
Genres = new SelectList(await genreQuery.Distinct().ToListAsync()),
Movies = await movies.ToListAsync()
};

return View(movieGenreVM);
}

The following code is a LINQ query that retrieves all the genres from the database.

// Use LINQ to get list of genres.

IQueryable<string> genreQuery = from m in _context.Movie
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).
When the user searches for the item, the search value is retained in the search box.

Add search by genre to the Index view

Update Index.cshtml found in Views/Movies/ as follows:
@model MvcMovie.Models.MovieGenreViewModel

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-action="Create">Create New</a>
</p>
<form asp-controller="Movies" asp-action="Index" method="get">
<p>

<select asp-for="MovieGenre" asp-items="Model.Genres">

<option value="">All</option>
</select>

Title: <input type="text" asp-for="SearchString" />

<input type="submit" value="Filter" />
</p>
</form>

<table class="table">
<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>
@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-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>
Examine the lambda expression used in the following HTML Helper:
@Html.DisplayNameFor(model => model.Movies[0].Title)

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.
Test the app by searching by genre, by movie title, and by both:

P R E V IO U S NEXT
 Add a new field to an ASP.NET Core MVC app
8/2/2019 • 5 minutes to read • Edit Online

By Rick Anderson
In this section Entity Framework Code First Migrations is used to:
Add a new field to the model.
Migrate the new field to the database.
When EF Code First is used to automatically create a database, Code First:
Adds a table to the database to track the schema of the database.
Verifies 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.

Add a Rating Property to the Movie Model

Add a Rating property to Models/Movie.cs:

public class Movie

{
public int Id { get; set; }
public string Title { get; set; }

[Display(Name = "Release Date")]

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }
public string Genre { get; set; }

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

public decimal Price { get; set; }
public string Rating { get; set; }
}

Build the app

Visual Studio
Visual Studio Code
Visual Studio for Mac
Ctrl+Shift+B
Because you've added a new field to the Movie class, you 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")]

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>
@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>
@Html.DisplayNameFor(model => model.Movies[0].Rating)
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Movies)
{
<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>
@Html.DisplayFor(modelItem => item.Rating)
</td>
<td>
<a asp-action="Edit" asp-route-id="@item.Id">Edit</a> |

Update the /Views/Movies/Create.cshtml with a Rating field.

Visual Studio / Visual Studio for Mac
Visual Studio Code
You can copy/paste the previous "form group" and let intelliSense help you update the fields. IntelliSense works
with Tag Helpers.
Update the the remaining templates.
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 .

new Movie
{
Title = "When Harry Met Sally",
ReleaseDate = DateTime.Parse("1989-1-11"),
Genre = "Romantic Comedy",
Rating = "R",
Price = 7.99M
},

The app won't work until the DB is updated to include the new field. If it's run now, the following SqlException is
thrown:
SqlException: Invalid column name 'Rating'.

This error occurs 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.)
There are a few approaches to resolving the error:
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're 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. This is a good approach for early development and when
using SQLite.
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, Code First Migrations is used.
Visual Studio
Visual Studio Code / Visual Studio for Mac
From the Tools menu, select NuGet Package Manager > Package Manager Console.

In the PMC, enter the following commands:

Add-Migration Rating
Update-Database

The command tells the migration framework to examine the current Movie model with the current
Add-Migration
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 all the records in the DB are deleted, the initialize method will seed the DB and include the Rating field.
Run the app and verify you can create/edit/display movies with a Rating field. You should 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
7/11/2019 • 9 minutes to read • Edit Online

By Rick Anderson
In this section:
Validation logic is added to the Movie model.
You 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.

Add validation rules to the movie model

The DataAnnotations namespace provides a set of built-in 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 any validation.
Update the Movie class to take advantage of the built-in Required , StringLength , RegularExpression , and Range
validation attributes.

public class Movie

{
public int Id { get; set; }

[StringLength(60, MinimumLength = 3)]

[Required]
public string Title { get; set; }

[Display(Name = "Release Date")]

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }

[Range(1, 100)]
[DataType(DataType.Currency)]
[Column(TypeName = "decimal(18, 2)")]
public decimal Price { get; set; }

[RegularExpression(@"^[A-Z]+[a-zA-Z""'\s-]*$")]
[Required]
[StringLength(30)]
public string Genre { get; set; }

[RegularExpression(@"^[A-Z]+[a-zA-Z0-9""'\s-]*$")]
[StringLength(5)]
[Required]
public string Rating { get; set; }
}
The validation attributes specify behavior that you want to enforce on the model properties they're applied to:
The Required and MinimumLength attributes indicate 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 preceding code,
"Genre":
Must only use letters.
The first letter is required to be uppercase. White space, numbers, and special characters are not allowed.
The RegularExpression "Rating":
Requires that the first character be an uppercase letter.
Allows special characters and numbers in subsequent spaces. "PG -13" is valid for a rating, but fails for a
"Genre".
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
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
You may not be able to enter decimal commas in decimal fields. 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.
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]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Create(
[Bind("ID,Title,ReleaseDate,Genre,Price, Rating")] Movie movie)
{
if (ModelState.IsValid)
{
_context.Add(movie);
await _context.SaveChangesAsync();
return RedirectToAction("Index");
}
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.
The portion of the Create.cshtml view template is shown in the following markup:

<h4>Movie</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form asp-action="Create">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<div class="form-group">
<label asp-for="Title" class="control-label"></label>
<input asp-for="Title" class="form-control" />
<span asp-validation-for="Title" class="text-danger"></span>
</div>

@*Markup removed for brevity.*@

The preceding markup is used by the action methods to display the initial form and to redisplay it in the event of an
error.
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.
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.

Using DataType Attributes

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.
 [Display(Name = "Release Date")]
[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }

[Range(1, 100)]
[DataType(DataType.Currency)]
public decimal Price { get; set; }

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.
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)]

public DateTime ReleaseDate { get; set; }

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
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 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:
[Range(typeof(DateTime), "1/1/1966", "1/1/2020")]

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.
The following code shows combining attributes on one line:
 public class Movie
{
public int Id { get; set; }

[StringLength(60, MinimumLength = 3)]

public string Title { get; set; }

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

public DateTime ReleaseDate { get; set; }

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

public string Genre { get; set; }

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

[Column(TypeName = "decimal(18, 2)")]
public decimal Price { get; set; }

[RegularExpression(@"^[A-Z]+[a-zA-Z0-9""'\s-]*$"), StringLength(5)]
public string Rating { get; set; }
}

In the next part of the series, we review the app and make some improvements to the automatically generated
Details and Delete methods.

Additional resources
Working with Forms
Globalization and localization
Introduction to Tag Helpers
Author Tag Helpers

P R E V IO U S NEXT
 Examine the Details and Delete methods of an
ASP.NET Core app
8/7/2019 • 3 minutes to read • Edit Online

By Rick Anderson
Open the Movie controller and examine the Details method:

// 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);
}

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.

app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});

EF makes it easy to search for data using the FirstOrDefaultAsync 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:{PORT}/Movies/Details/1 to something like http://localhost:{PORT}/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();
}

var movie = await _context.Movie

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

return View(movie);
}

// POST: Movies/Delete/5
[HttpPost, ActionName("Delete")]
[ValidateAntiForgeryToken]
public async Task<IActionResult> DeleteConfirmed(int id)
{
var movie = await _context.Movie.FindAsync(id);
_context.Movie.Remove(movie);
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}

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:

// GET: Movies/Delete/5
public async Task<IActionResult> Delete(int? id)
{

// POST: Movies/Delete/5
[HttpPost, ActionName("Delete")]
[ValidateAntiForgeryToken]
public async Task<IActionResult> DeleteConfirmed(int id)
{

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:

// POST: Movies/Delete/6
[HttpPost]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Delete(int id, bool notUsed)

Publish to Azure
For information on deploying to Azure, see Tutorial: Build a .NET Core and SQL Database web app in Azure App
Service.

P R E V IO U S
 Build your first Blazor app
8/13/2019 • 8 minutes to read • Edit Online

By Daniel Roth and Luke Latham

This tutorial shows you how to build and modify a Blazor app.
Follow the guidance in the Get started with ASP.NET Core Blazor article to create a Blazor project for this tutorial.
Name the project ToDoList.

Build components
1. Browse to each of the app's three pages in the Pages folder: Home, Counter, and Fetch data. These pages are
implemented by the Razor component files Index.razor, Counter.razor, and FetchData.razor.
2. On the Counter page, select the Click me button to increment the counter without a page refresh.
Incrementing a counter in a webpage normally requires writing JavaScript, but Blazor provides a better
approach using C#.
3. Examine the implementation of the Counter component in the Counter.razor file.
Pages/Counter.razor:

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
private int currentCount = 0;

private void IncrementCount()

{
currentCount++;
}
}

The UI of the Counter component is defined using HTML. Dynamic rendering logic (for example, loops,
conditionals, expressions) is added using an embedded C# syntax called Razor. The HTML markup and C#
rendering logic are converted into a component class at build time. The name of the generated .NET class
matches the file name.
Members of the component class are defined in an @code block. In the @code block, component state
(properties, fields) and methods are specified for event handling or for defining other component logic.
These members are then used as part of the component's rendering logic and for handling events.
When the Click me button is selected:
The Counter component's registered onclick handler is called (the IncrementCount method).
The Counter component regenerates its render tree.
The new render tree is compared to the previous one.
Only modifications to the Document Object Model (DOM ) are applied. The displayed count is updated.
4. Modify the C# logic of the Counter component to make the count increment by two instead of one.

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
private int currentCount = 0;

private void IncrementCount()

{
currentCount += 2;
}
}

5. Rebuild and run the app to see the changes. Select the Click me button. The counter increments by two.

Use components
Include a component in another component using an HTML syntax.
1. Add the Counter component to the app's Index component by adding a <Counter /> element to the
Index component ( Index.razor).

If you're using Blazor client-side for this experience, a SurveyPrompt component is used by the Index
component. Replace the <SurveyPrompt> element with a <Counter /> element. If you're using a Blazor
server-side app for this experience, add the <Counter /> element to the Index component:
Pages/Index.razor:

@page "/"

<h1>Hello, world!</h1>

Welcome to your new app.

<Counter />

2. Rebuild and run the app. The Index component has its own counter.

Component parameters
Components can also have parameters. Component parameters are defined using public properties on the
component class decorated with [Parameter] . Use attributes to specify arguments for a component in markup.
1. Update the component's @code C# code:
Add a IncrementAmount property decorated with the [Parameter] attribute.
Change the IncrementCount method to use the IncrementAmount when increasing the value of
currentCount .
Pages/Counter.razor:
 @page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
private int currentCount = 0;

[Parameter]
public int IncrementAmount { get; set; } = 1;

private void IncrementCount()

{
currentCount += IncrementAmount;
}
}

1. Specify an IncrementAmount parameter in the Index component's <Counter> element using an attribute. Set
the value to increment the counter by ten.
Pages/Index.razor:

@page "/"

<h1>Hello, world!</h1>

Welcome to your new app.

<Counter IncrementAmount="10" />

2. Reload the Index component. The counter increments by ten each time the Click me button is selected. The
counter in the Counter component continues to increment by one.

Route to components
The @page directive at the top of the Counter.razor file specifies that the Counter component is a routing endpoint.
The Counter component handles requests sent to /counter . Without the @page directive, a component doesn't
handle routed requests, but the component can still be used by other components.

Dependency injection
Services registered in the app's service container are available to components via dependency injection (DI). Inject
services into a component using the @inject directive.
Examine the directives of the FetchData component.
If working with a Blazor server-side app, the WeatherForecastService service is registered as a singleton, so one
instance of the service is available throughout the app. The @inject directive is used to inject the instance of the
WeatherForecastService service into the component.

Pages/FetchData.razor:

@page "/fetchdata"
@using ToDoList.App.Services
@inject WeatherForecastService ForecastService
The FetchData component uses the injected service, as ForecastService , to retrieve an array of WeatherForecast
objects:

@code {
private WeatherForecast[] forecasts;

protected override async Task OnInitAsync()

{
forecasts = await ForecastService.GetForecastAsync(DateTime.Now);
}
}

If working with a Blazor client-side app, HttpClient is injected to obtain weather forecast data from the
weather.json file in the wwwroot/sample-data folder:
Pages/FetchData.razor:

@inject HttpClient Http

...

protected override async Task OnInitAsync()

{
forecasts =
await Http.GetJsonAsync<WeatherForecast[]>("sample-data/weather.json");
}

A @foreach loop is used to render each forecast instance as a row in the table of weather data:

<table class="table">
<thead>
<tr>
<th>Date</th>
<th>Temp. (C)</th>
<th>Temp. (F)</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
@foreach (var forecast in forecasts)
{
<tr>
<td>@forecast.Date.ToShortDateString()</td>
<td>@forecast.TemperatureC</td>
<td>@forecast.TemperatureF</td>
<td>@forecast.Summary</td>
</tr>
}
</tbody>
</table>

Build a todo list

Add a new component to the app that implements a simple todo list.
1. Add an empty file named Todo.razor to the app in the Pages folder:
2. Provide the initial markup for the component:
 @page "/todo"

<h1>Todo</h1>

3. Add the Todo component to the navigation bar.

The NavMenu component (Shared/NavMenu.razor) is used in the app's layout. Layouts are components that
allow you to avoid duplication of content in the app.
Add a <NavLink> element for the Todo component by adding the following list item markup below the
existing list items in the Shared/NavMenu.razor file:

<li class="nav-item px-3">

<NavLink class="nav-link" href="todo">
<span class="oi oi-list-rich" aria-hidden="true"></span> Todo
</NavLink>
</li>

4. Rebuild and run the app. Visit the new Todo page to confirm that the link to the Todo component works.
5. Add a TodoItem.cs file to the root of the project to hold a class that represents a todo item. Use the following
C# code for the TodoItem class:

public class TodoItem

{
public string Title { get; set; }
public bool IsDone { get; set; }
}

6. Return to the Todo component (Pages/Todo.razor):

Add a field for the todo items in an @code block. The Todo component uses this field to maintain the
state of the todo list.
Add unordered list markup and a foreach loop to render each todo item as a list item ( <li> ).

@page "/todo"

<h1>Todo</h1>

<ul>
@foreach (var todo in todos)
{
<li>@todo.Title</li>
}
</ul>

@code {
private IList<TodoItem> todos = new List<TodoItem>();
}

7. The app requires UI elements for adding todo items to the list. Add a text input ( <input> ) and a button (
<button> ) below the unordered list ( <ul>...</ul> ):
 @page "/todo"

<h1>Todo</h1>

<ul>
@foreach (var todo in todos)
{
<li>@todo.Title</li>
}
</ul>

<input placeholder="Something todo" />

<button>Add todo</button>

@code {
private IList<TodoItem> todos = new List<TodoItem>();
}

8. Rebuild and run the app. When the Add todo button is selected, nothing happens because an event handler
isn't wired up to the button.
9. Add an AddTodo method to the Todo component and register it for button selections using the @onclick
attribute. The AddTodo C# method is called when the button is selected:

<input placeholder="Something todo" />

<button @onclick="AddTodo">Add todo</button>

@code {
private IList<TodoItem> todos = new List<TodoItem>();

private void AddTodo()

{
// Todo: Add the todo
}
}

10. To get the title of the new todo item, add a newTodo string field at the top of the @code block and bind it to
the value of the text input using the bind attribute in the <input> element:

private IList<TodoItem> todos = new List<TodoItem>();

private string newTodo;

<input placeholder="Something todo" @bind="@newTodo" />

11. Update the AddTodo method to add the TodoItem with the specified title to the list. Clear the value of the
text input by setting newTodo to an empty string:
 @page "/todo"

<h1>Todo</h1>

<ul>
@foreach (var todo in todos)
{
<li>@todo.Title</li>
}
</ul>

<input placeholder="Something todo" @bind="@newTodo" />

<button @onclick="AddTodo">Add todo</button>

@code {
private IList<TodoItem> todos = new List<TodoItem>();
private string newTodo;

private void AddTodo()

{
if (!string.IsNullOrWhiteSpace(newTodo))
{
todos.Add(new TodoItem { Title = newTodo });
newTodo = string.Empty;
}
}
}

12. Rebuild and run the app. Add some todo items to the todo list to test the new code.
13. The title text for each todo item can be made editable, and a check box can help the user keep track of
completed items. Add a check box input for each todo item and bind its value to the IsDone property.
Change @todo.Title to an <input> element bound to @todo.Title :

<ul>
@foreach (var todo in todos)
{
<li>
<input type="checkbox" @bind="@todo.IsDone" />
<input @bind="@todo.Title" />
</li>
}
</ul>

14. To verify that these values are bound, update the <h1> header to show a count of the number of todo items
that aren't complete ( IsDone is false ).

<h1>Todo (@todos.Count(todo => !todo.IsDone))</h1>

15. The completed Todo component (Pages/Todo.razor):

 @page "/todo"

<h1>Todo (@todos.Count(todo => !todo.IsDone))</h1>

<ul>
@foreach (var todo in todos)
{
<li>
<input type="checkbox" @bind="@todo.IsDone" />
<input @bind="@todo.Title" />
</li>
}
</ul>

<input placeholder="Something todo" @bind="@newTodo" />

<button @onclick="AddTodo">Add todo</button>

@code {
private IList<TodoItem> todos = new List<TodoItem>();
private string newTodo;

private void AddTodo()

{
if (!string.IsNullOrWhiteSpace(newTodo))
{
todos.Add(new TodoItem { Title = newTodo });
newTodo = string.Empty;
}
}
}

16. Rebuild and run the app. Add todo items to test the new code.
Create and use ASP.NET Core Razor components
 Tutorial: Create a web API with ASP.NET Core
8/9/2019 • 28 minutes to read • Edit Online

By Rick Anderson and Mike Wasson

This tutorial teaches the basics of building a web API with ASP.NET Core.
In this tutorial, you learn how to:
Create a web API project.
Add a model class and a database context.
Scaffold a controller with CRUD methods.
Configure routing, URL paths, and return values.
Call the web API with Postman.
At the end, you have a web API that can manage "to-do" items stored in a database.

Overview
This tutorial creates the following API:

API DESCRIPTION REQUEST BODY RESPONSE BODY

GET /api/TodoItems Get all to-do items None Array of to-do items

GET /api/TodoItems/{id} Get an item by ID None To-do item

POST /api/TodoItems Add a new item To-do item To-do item

PUT /api/TodoItems/{id} Update an existing item To-do item None

DELETE /api/TodoItems/{id} Delete an item None None

The following diagram shows the design of the app.

Prerequisites
Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 3.0 Preview

Create a web project

Visual Studio
Visual Studio Code
Visual Studio for Mac
From the File menu, select New > Project.
Select the ASP.NET Core Web Application template and click Next.
Name the project TodoApi and click Create.
In the Create a new ASP.NET Core Web Application dialog, confirm that .NET Core and ASP.NET Core 3.0
are selected. Select the API template and click Create. Don't select Enable Docker Support.

Test the API

The project template creates a WeatherForecast API. Call the Get method from a browser to test the app.
Visual Studio
Visual Studio Code
Visual Studio for Mac
Press Ctrl+F5 to run the app. Visual Studio launches a browser and navigates to
https://localhost:<port>/WeatherForecast , where <port> is a randomly chosen port number.
If you get a dialog box that asks if you should trust the IIS Express certificate, select Yes. In the Security Warning
dialog that appears next, select Yes.
JSON similar to the following is returned:

[
{
"date": "2019-07-16T19:04:05.7257911-06:00",
"temperatureC": 52,
"temperatureF": 125,
"summary": "Mild"
},
{
"date": "2019-07-17T19:04:05.7258461-06:00",
"temperatureC": 36,
"temperatureF": 96,
"summary": "Warm"
},
{
"date": "2019-07-18T19:04:05.7258467-06:00",
"temperatureC": 39,
"temperatureF": 102,
"summary": "Cool"
},
{
"date": "2019-07-19T19:04:05.7258471-06:00",
"temperatureC": 10,
"temperatureF": 49,
"summary": "Bracing"
},
{
"date": "2019-07-20T19:04:05.7258474-06:00",
"temperatureC": -1,
"temperatureF": 31,
"summary": "Chilly"
}
]

Add a model class

A model is a set of classes that represent the data that the app manages. The model for this app is a single
TodoItem class.

Visual Studio
Visual Studio Code
Visual Studio for Mac
In Solution Explorer, right-click the project. Select Add > New Folder. Name the folder Models.
Right-click the Models folder and select Add > Class. Name the class TodoItem and select Add.
Replace the template code with the following code:
 namespace TodoApi.Models
{
public class TodoItem
{
public long Id { get; set; }
public string Name { get; set; }
public bool IsComplete { get; set; }
}
}

The Id property functions as the unique key in a relational database.

Model classes can go anywhere in the project, but the Models folder is used by convention.

Add a database context

The database context is the main class that coordinates Entity Framework functionality for a data model. This class
is created by deriving from the Microsoft.EntityFrameworkCore.DbContext class.
Visual Studio
Visual Studio Code / Visual Studio for Mac
Add Microsoft.EntityFrameworkCore.SqlServer
From the Tools menu, select NuGet Package Manager > Manage NuGet Packages for Solution.
Select the Include prerelease checkbox.
Select the Browse tab, and then enter Microsoft.EntityFrameworkCore.SqlServer in the search box.
Select Microsoft.EntityFrameworkCore.SqlServer V3.0.0-preview in the left pane.
Select the Project check box in the right pane and then select Install.
Use the preceding instructions to add the Microsoft.EntityFrameworkCore.InMemory NuGet package.
Add the TodoContext database context
Right-click the Models folder and select Add > Class. Name the class TodoContext and click Add.
Enter the following code:

using Microsoft.EntityFrameworkCore;

namespace TodoApi.Models
{
public class TodoContext : DbContext
{
public TodoContext(DbContextOptions<TodoContext> options)
: base(options)
{
}

public DbSet<TodoItem> TodoItems { get; set; }

}
}

Register the database context

In ASP.NET Core, services such as the DB context must be registered with the dependency injection (DI) container.
The container provides the service to controllers.
Update Startup.cs with the following highlighted code:

// Unused usings removed

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi
{
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}

public IConfiguration Configuration { get; }

public void ConfigureServices(IServiceCollection services)

{
services.AddDbContext<TodoContext>(opt =>
opt.UseInMemoryDatabase("TodoList"));
services.AddControllers();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)

{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}

app.UseHttpsRedirection();

app.UseRouting();

app.UseAuthorization();

app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
}
}
}

The preceding code:

Removes unused using declarations.
Adds the database context to the DI container.
Specifies that the database context will use an in-memory database.

Scaffold a controller
Visual Studio
Visual Studio Code / Visual Studio for Mac
Right-click the Controllers folder.
Select Add > New Scaffolded Item.
 Select API Controller with actions, using Entity Framework, and then select Add.
In the Add API Controller with actions, using Entity Framework dialog:
Select TodoItem (TodoAPI.Models) in the Model class.
Select TodoContext (TodoAPI.Models) in the Data context class.
Select Add
The generated code:
Defines an API controller class without methods.
Decorates the class with the [ApiController] attribute. This attribute indicates that the controller responds to web
API requests. For information about specific behaviors that the attribute enables, see Create web APIs with
ASP.NET Core.
Uses DI to inject the database context ( TodoContext ) into the controller. The database context is used in each of
the CRUD methods in the controller.

Examine the PostTodoItem create method

Replace the return statement in the PostTodoItem to use the nameof operator:

// POST: api/TodoItems
[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
_context.TodoItems.Add(todoItem);
await _context.SaveChangesAsync();

//return CreatedAtAction("GetTodoItem", new { id = todoItem.Id }, todoItem);

return CreatedAtAction(nameof(GetTodoItem), new { id = todoItem.Id }, todoItem);
}

The preceding code is an HTTP POST method, as indicated by the [HttpPost] attribute. The method gets the value
of the to-do item from the body of the HTTP request.
The CreatedAtAction method:
Returns an HTTP 201 status code if successful. 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.
For more information, see 10.2.2 201 Created.
References the GetTodoItem action to create the Location header's URI. The C# nameof keyword is used to
avoid hard-coding the action name in the CreatedAtAction call.
Install Postman
This tutorial uses Postman to test the web API.
Install Postman
Start the web app.
Start Postman.
Disable SSL certificate verification
From File > Settings (*General tab), disable SSL certificate verification.
 WARNING
Re-enable SSL certificate verification after testing the controller.

Test PostTodoItem with Postman

Create a new request.
Set the HTTP method to POST .
Select the Body tab.
Select the raw radio button.
Set the type to JSON (application/json).
In the request body enter JSON for a to-do item:

{
"name":"walk dog",
"isComplete":true
}

Select Send.

Test the location header URI

Select the Headers tab in the Response pane.
Copy the Location header value:
 Set the method to GET.
Paste the URI (for example, https://localhost:5001/api/TodoItems/1 )
Select Send.

Examine the GET methods

These methods implement two GET endpoints:
GET /api/TodoItems
GET /api/TodoItems/{id}

Test the app by calling the two endpoints from a browser or Postman. For example:
https://localhost:5001/api/TodoItems
https://localhost:5001/api/TodoItems/1
A response similar to the following is produced by the call to GetTodoItems :

[
{
"id": 1,
"name": "Item1",
"isComplete": false
}
]

Test Get with Postman

Create a new request.
Set the HTTP method to GET.
Set the request URL to https://localhost:<port>/api/TodoItems . For example,
https://localhost:5001/api/TodoItems .
Set Two pane view in Postman.
Select Send.
This app uses an in-memory database. If the app is stopped and started, the preceding GET request will not return
any data. If no data is returned, POST data to the app.

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:
Start with the template string in the controller's Route attribute:

[Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase
{
private readonly TodoContext _context;

public TodoItemsController(TodoContext context)

{
_context = context;
}

Replace [controller] with the name of the controller, which by convention is the controller class name
minus the "Controller" suffix. For this sample, the controller class name is TodoItemsController, so the
controller name is "TodoItems". ASP.NET Core routing is case insensitive.
If the [HttpGet] attribute has a route template (for example, [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 GetTodoItem method, "{id}" is a placeholder variable for the unique identifier of the to-do item.
When GetTodoItem is invoked, the value of "{id}" in the URL is provided to the method in its id parameter.

// GET: api/TodoItems/5
[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
var todoItem = await _context.TodoItems.FindAsync(id);

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

return todoItem;
}

Return values
The return type of the GetTodoItems and GetTodoItem methods is ActionResult<T> type. ASP.NET Core
automatically serializes the object to JSON and writes the JSON into the body of the response message. The
response code for this return type is 200, assuming there are no unhandled exceptions. Unhandled exceptions are
translated into 5xx errors.
ActionResult return types can represent a wide range of HTTP status codes. For example, GetTodoItem can return
two different status values:
If no item matches the requested ID, the method returns a 404 NotFound error code.
Otherwise, the method returns 200 with a JSON response body. Returning item results in an HTTP 200
 response.

The PutTodoItem method

Examine the PutTodoItem method:

// PUT: api/TodoItems/5
[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
if (id != todoItem.Id)
{
return BadRequest();
}

_context.Entry(todoItem).State = EntityState.Modified;

try
{
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!TodoItemExists(id))
{
return NotFound();
}
else
{
throw;
}
}

return NoContent();
}

PutTodoItem is similar to PostTodoItem , 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 changes. To
support partial updates, use HTTP PATCH.
If you get an error calling PutTodoItem , call GET to ensure there's an item in the database.
Test the PutTodoItem method
This sample uses an in-memory database that must be initialed each time the app is started. There must be an item
in the database before you make a PUT call. Call GET to insure there's an item in the database before making a PUT
call.
Update the to-do item that has ID = 1 and set its name to "feed fish":

{
"ID":1,
"name":"feed fish",
"isComplete":true
}

The following image shows the Postman update:

The DeleteTodoItem method
Examine the DeleteTodoItem method:

// DELETE: api/TodoItems/5
[HttpDelete("{id}")]
public async Task<ActionResult<TodoItem>> DeleteTodoItem(long id)
{
var todoItem = await _context.TodoItems.FindAsync(id);
if (todoItem == null)
{
return NotFound();
}

_context.TodoItems.Remove(todoItem);
await _context.SaveChangesAsync();

return todoItem;
}

The DeleteTodoItem response is 204 (No Content).

Test the DeleteTodoItem method
Use Postman to delete a to-do item:
Set the method to DELETE .
Set the URI of the object to delete, for example https://localhost:5001/api/TodoItems/1
Select Send

Call the API from jQuery

See Tutorial: Call an ASP.NET Core web API with jQuery.
In this tutorial, you learn how to:
 Create a web API project.
Add a model class and a database context.
Add a controller.
Add CRUD methods.
Configure routing and URL paths.
Specify return values.
Call the web API with Postman.
Call the web API with jQuery.
At the end, you have a web API that can manage "to-do" items stored in a relational database.

Overview
This tutorial creates the following API:

API DESCRIPTION REQUEST BODY RESPONSE BODY

GET /api/TodoItems Get all to-do items None Array of to-do items

GET /api/TodoItems/{id} Get an item by ID None To-do item

POST /api/TodoItems Add a new item To-do item To-do item

PUT /api/TodoItems/{id} Update an existing item To-do item None

DELETE /api/TodoItems/{id} Delete an item None None

The following diagram shows the design of the app.

Prerequisites
Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 2.2 or later
 WARNING
If you use Visual Studio 2017, see dotnet/sdk issue #3124 for information about .NET Core SDK versions that don't work with
Visual Studio.

Create a web project

Visual Studio
Visual Studio Code
Visual Studio for Mac
From the File menu, select New > Project.
Select the ASP.NET Core Web Application template and click Next.
Name the project TodoApi and click Create.
In the Create a new ASP.NET Core Web Application dialog, confirm that .NET Core and ASP.NET Core 2.2
are selected. Select the API template and click Create. Don't select Enable Docker Support.

Test the API

The project template creates a values API. Call the Get method from a browser to test the app.
Visual Studio
Visual Studio Code
Visual Studio for Mac
Press Ctrl+F5 to run the app. Visual Studio launches a browser and navigates to
https://localhost:<port>/api/values , where <port> is a randomly chosen port number.

If you get a dialog box that asks if you should trust the IIS Express certificate, select Yes. In the Security Warning
dialog that appears next, select Yes.
The following JSON is returned:

["value1","value2"]

Add a model class

A model is a set of classes that represent the data that the app manages. The model for this app is a single
TodoItem class.

Visual Studio
Visual Studio Code
Visual Studio for Mac
In Solution Explorer, right-click the project. Select Add > New Folder. Name the folder Models.
Right-click the Models folder and select Add > Class. Name the class TodoItem and select Add.
Replace the template code with the following code:

namespace TodoApi.Models
{
public class TodoItem
{
public long Id { get; set; }
public string Name { get; set; }
public bool IsComplete { get; set; }
}
}

The Id property functions as the unique key in a relational database.

Model classes can go anywhere in the project, but the Models folder is used by convention.

Add a database context

The database context is the main class that coordinates Entity Framework functionality for a data model. This class
is created by deriving from the Microsoft.EntityFrameworkCore.DbContext class.
Visual Studio
Visual Studio Code / Visual Studio for Mac
Right-click the Models folder and select Add > Class. Name the class TodoContext and click Add.
Replace the template code with the following code:
 using Microsoft.EntityFrameworkCore;

namespace TodoApi.Models
{
public class TodoContext : DbContext
{
public TodoContext(DbContextOptions<TodoContext> options)
: base(options)
{
}

public DbSet<TodoItem> TodoItems { get; set; }

}
}

Register the database context

In ASP.NET Core, services such as the DB context must be registered with the dependency injection (DI) container.
The container provides the service to controllers.
Update Startup.cs with the following highlighted code:
 // Unused usings removed
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using TodoApi.Models;

namespace TodoApi
{
public class Startup
{
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.
public void ConfigureServices(IServiceCollection services)
{
services.AddDbContext<TodoContext>(opt =>
opt.UseInMemoryDatabase("TodoList"));
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}

// 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
{
// The default HSTS value is 30 days. You may want to change this for
// production scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}

app.UseHttpsRedirection();
app.UseMvc();
}
}
}

The preceding code:

Removes unused using declarations.
Adds the database context to the DI container.
Specifies that the database context will use an in-memory database.

Add a controller
Visual Studio
Visual Studio Code / Visual Studio for Mac
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 select Add.

Replace the template code with the following code:

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using TodoApi.Models;

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

public TodoController(TodoContext context)

{
_context = context;

if (_context.TodoItems.Count() == 0)
{
// Create a new TodoItem if collection is empty,
// which means you can't delete all TodoItems.
_context.TodoItems.Add(new TodoItem { Name = "Item1" });
_context.SaveChanges();
}
}
}
}

The preceding code:

 Defines an API controller class without methods.
Decorates the class with the [ApiController] attribute. This attribute indicates that the controller responds to web
API requests. For information about specific behaviors that the attribute enables, see Create web APIs with
ASP.NET Core.
Uses DI to inject the database context ( TodoContext ) into the controller. The database context is used in each of
the CRUD methods in the controller.
Adds an item named Item1 to the database if the database is empty. This code is in the constructor, so it runs
every time there's a new HTTP request. If you delete all items, the constructor creates Item1 again the next time
an API method is called. So it may look like the deletion didn't work when it actually did work.

Add Get methods

To provide an API that retrieves to-do items, add the following methods to the TodoController class:

// GET: api/Todo
[HttpGet]
public async Task<ActionResult<IEnumerable<TodoItem>>> GetTodoItems()
{
return await _context.TodoItems.ToListAsync();
}

// GET: api/Todo/5
[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
var todoItem = await _context.TodoItems.FindAsync(id);

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

return todoItem;
}

These methods implement two GET endpoints:

GET /api/todo
GET /api/todo/{id}

Stop the app if it's still running. Then run it again to include the latest changes.
Test the app by calling the two endpoints from a browser. For example:
https://localhost:<port>/api/todo
https://localhost:<port>/api/todo/1

The following HTTP response is produced by the call to GetTodoItems :

[
{
"id": 1,
"name": "Item1",
"isComplete": false
}
]
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:
Start with the template string in the controller's Route attribute:

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

Replace [controller] with the name of the controller, which by convention is the controller class name
minus the "Controller" suffix. For this sample, the controller class name is TodoController, so the controller
name is "todo". ASP.NET Core routing is case insensitive.
If the [HttpGet] attribute has a route template (for example, [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 GetTodoItem method, "{id}" is a placeholder variable for the unique identifier of the to-do item.
When GetTodoItem is invoked, the value of "{id}" in the URL is provided to the method in its id parameter.

// GET: api/Todo/5
[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
var todoItem = await _context.TodoItems.FindAsync(id);

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

return todoItem;
}

Return values
The return type of the GetTodoItems and GetTodoItem methods is ActionResult<T> type. ASP.NET Core
automatically serializes the object to JSON and writes the JSON into the body of the response message. The
response code for this return type is 200, assuming there are no unhandled exceptions. Unhandled exceptions are
translated into 5xx errors.
ActionResult return types can represent a wide range of HTTP status codes. For example, GetTodoItem can return
two different status values:
If no item matches the requested ID, the method returns a 404 NotFound error code.
Otherwise, the method returns 200 with a JSON response body. Returning item results in an HTTP 200
response.

Test the GetTodoItems method

This tutorial uses Postman to test the web API.
 Install Postman
Start the web app.
Start Postman.
Disable SSL certificate verification
Visual Studio
Visual Studio Code / Visual Studio for Mac
From File > Settings (General tab), disable SSL certificate verification.

WARNING
Re-enable SSL certificate verification after testing the controller.

Create a new request.

Set the HTTP method to GET.
Set the request URL to https://localhost:<port>/api/todo . For example,
https://localhost:5001/api/todo .
Set Two pane view in Postman.
Select Send.

Add a Create method

Add the following PostTodoItem method inside of Controllers/TodoController.cs:
 // POST: api/Todo
[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem item)
{
_context.TodoItems.Add(item);
await _context.SaveChangesAsync();

return CreatedAtAction(nameof(GetTodoItem), new { id = item.Id }, item);

}

The preceding code is an HTTP POST method, as indicated by the [HttpPost] attribute. The method gets the value
of the to-do item from the body of the HTTP request.
The CreatedAtAction method:
Returns an HTTP 201 status code, if successful. 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. For more information, see 10.2.2 201 Created.
References the GetTodoItem action to create the Location header's URI. The C# nameof keyword is used to
avoid hard-coding the action name in the CreatedAtAction call.

// GET: api/Todo/5
[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
var todoItem = await _context.TodoItems.FindAsync(id);

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

return todoItem;
}

Test the PostTodoItem method

Build the project.
In Postman, set the HTTP method to POST .
Select the Body tab.
Select the raw radio button.
Set the type to JSON (application/json).
In the request body enter JSON for a to-do item:

{
"name":"walk dog",
"isComplete":true
}

Select Send.
 If you get a 405 Method Not Allowed error, it's probably the result of not compiling the project after adding
the PostTodoItem method.
Test the location header URI
Select the Headers tab in the Response pane.
Copy the Location header value:

Set the method to GET.

Paste the URI (for example, https://localhost:5001/api/Todo/2 )
Select Send.

Add a PutTodoItem method

Add the following PutTodoItem method:

// PUT: api/Todo/5
[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem item)
{
if (id != item.Id)
{
return BadRequest();
}

_context.Entry(item).State = EntityState.Modified;
await _context.SaveChangesAsync();

return NoContent();
}

PutTodoItem is similar to PostTodoItem , 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 changes. To
support partial updates, use HTTP PATCH.
If you get an error calling PutTodoItem , call GET to ensure there's an item in the database.
Test the PutTodoItem method
This sample uses an in-memory database that must be initialed each time the app is started. There must be an item
in the database before you make a PUT call. Call GET to insure there's an item in the database before making a PUT
call.
Update the to-do item that has id = 1 and set its name to "feed fish":

{
"ID":1,
"name":"feed fish",
"isComplete":true
}

The following image shows the Postman update:

Add a DeleteTodoItem method
Add the following DeleteTodoItem method:

// DELETE: api/Todo/5
[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
var todoItem = await _context.TodoItems.FindAsync(id);

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

_context.TodoItems.Remove(todoItem);
await _context.SaveChangesAsync();

return NoContent();
}

The DeleteTodoItem response is 204 (No Content).

Test the DeleteTodoItem method
Use Postman to delete a to-do item:
Set the method to DELETE .
Set the URI of the object to delete, for example https://localhost:5001/api/todo/1
Select Send
The sample app allows you to delete all the items. However, when the last item is deleted, a new one is created by
the model class constructor the next time the API is called.

Call the 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 app to serve static files and enable default file mapping by updating Startup.cs with the following
highlighted code:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
// The default HSTS value is 30 days. You may want to change this for
// production scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}

app.UseDefaultFiles();
app.UseStaticFiles();
app.UseHttpsRedirection();
app.UseMvc();
}
Create a wwwroot folder in the project directory.
Add an HTML file named index.html to the 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="Save">
<a onclick="closeInput()" aria-label="Close">&#10006;</a>
</form>
</div>

<p id="counter"></p>

<table>
<tr>
<th>Is Complete</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="
 integrity="sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8="
crossorigin="anonymous"></script>
<script src="site.js"></script>
</body>
</html>

Add a JavaScript file named site.js to the 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.text("No " + name);
}
}

$(document).ready(function() {
getData();
});

function getData() {
$.ajax({
type: "GET",
url: uri,
cache: false,
success: function(data) {
const tBody = $("#todos");

$(tBody).empty();

getCount(data.length);

$.each(data, function(key, item) {

const tr = $("<tr></tr>")
.append(
$("<td></td>").append(
$("<input/>", {
type: "checkbox",
disabled: true,
checked: item.isComplete
})
)
)
.append($("<td></td>").text(item.name))
.append(
$("<td></td>").append(
$("<button>Edit</button>").on("click", function() {
editItem(item.id);
})
)
)
.append(
$("<td></td>").append(
$("<button>Delete</button>").on("click", function() {
deleteItem(item.id);
})
)
);

tr.appendTo(tBody);
});
 });

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("Something went wrong!");
},
success: function(result) {
getData();
$("#add-name").val("");
}
});
}

function deleteItem(id) {
$.ajax({
url: uri + "/" + id,
type: "DELETE",
success: function(result) {
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",
accepts: "application/json",
contentType: "application/json",
data: JSON.stringify(item),
success: function(result) {
getData();
}
});

closeInput();
return false;
 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 Properties\launchSettings.json.
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 calls all of the CRUD methods of the API. Following are explanations of the calls to the API.
Get a list of to -do items
The jQuery ajax function sends a GET request to the API, which returns JSON representing an array of to-do
items. The success callback function is invoked if the request succeeds. In the callback, the DOM is updated with
the to-do information.
 $(document).ready(function() {
getData();
});

function getData() {
$.ajax({
type: "GET",
url: uri,
cache: false,
success: function(data) {
const tBody = $("#todos");

$(tBody).empty();

getCount(data.length);

$.each(data, function(key, item) {

const tr = $("<tr></tr>")
.append(
$("<td></td>").append(
$("<input/>", {
type: "checkbox",
disabled: true,
checked: item.isComplete
})
)
)
.append($("<td></td>").text(item.name))
.append(
$("<td></td>").append(
$("<button>Edit</button>").on("click", function() {
editItem(item.id);
})
)
)
.append(
$("<td></td>").append(
$("<button>Delete</button>").on("click", function() {
deleteItem(item.id);
})
)
);

tr.appendTo(tBody);
});

todos = data;
}
});
}

Add a to -do item

The ajax function sends a POST request with the to-do item in the request body. The accepts and contentType
options are set to application/json to specify the media type being received and sent. The to-do item is converted
to JSON by using JSON.stringify. When the API returns a successful status code, the getData function is invoked
to update the HTML table.
 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("Something went wrong!");
},
success: function(result) {
getData();
$("#add-name").val("");
}
});
}

Update a to -do item

Updating a to-do item is similar to adding one. The url changes to add the unique identifier of the item, and the
type is PUT .

$.ajax({
url: uri + "/" + $("#edit-id").val(),
type: "PUT",
accepts: "application/json",
contentType: "application/json",
data: JSON.stringify(item),
success: function(result) {
getData();
}
});

Delete a to -do item

Deleting a to-do item is accomplished by setting the type on the AJAX call to DELETE and specifying the item's
unique identifier in the URL.

$.ajax({
url: uri + "/" + id,
type: "DELETE",
success: function(result) {
getData();
}
});

Additional resources
View or download sample code for this tutorial. See how to download.
For more information, see the following resources:
Create web APIs with ASP.NET Core
ASP.NET Core Web API help pages with Swagger / OpenAPI
<xref:data/ef-rp/index>
Routing to controller actions in ASP.NET Core
Controller action return types in ASP.NET Core Web API
Deploy ASP.NET Core apps to Azure App Service
Host and deploy ASP.NET Core
YouTube version of this tutorial
 Create a web API with ASP.NET Core and MongoDB
7/11/2019 • 10 minutes to read • Edit Online

By Pratik Khandelwal and Scott Addie

This tutorial creates a web API that performs Create, Read, Update, and Delete (CRUD ) operations on a MongoDB
NoSQL database.
In this tutorial, you learn how to:
Configure MongoDB
Create a MongoDB database
Define a MongoDB collection and schema
Perform MongoDB CRUD operations from a web API
Customize JSON serialization
View or download sample code (how to download)

Prerequisites
Visual Studio
Visual Studio Code
Visual Studio for Mac
.NET Core SDK 2.2 or later
Visual Studio 2019 with the ASP.NET and web development workload
MongoDB

Configure MongoDB
If using Windows, MongoDB is installed at C:\Program Files\MongoDB by default. Add C:\Program
Files\MongoDB\Server\<version_number>\bin to the Path environment variable. This change enables MongoDB
access from anywhere on your development machine.
Use the mongo Shell in the following steps to create a database, make collections, and store documents. For more
information on mongo Shell commands, see Working with the mongo Shell.
1. Choose a directory on your development machine for storing the data. For example, C:\BooksData on
Windows. Create the directory if it doesn't exist. The mongo Shell doesn't create new directories.
2. Open a command shell. Run the following command to connect to MongoDB on default port 27017.
Remember to replace <data_directory_path> with the directory you chose in the previous step.

mongod --dbpath <data_directory_path>

3. Open another command shell instance. Connect to the default test database by running the following
command:

mongo
4. Run the following in a command shell:

use BookstoreDb

If it doesn't already exist, a database named BookstoreDb is created. If the database does exist, its connection
is opened for transactions.
5. Create a Books collection using following command:

db.createCollection('Books')

The following result is displayed:

{ "ok" : 1 }

6. Define a schema for the Books collection and insert two documents using the following command:

db.Books.insertMany([{'Name':'Design Patterns','Price':54.93,'Category':'Computers','Author':'Ralph
Johnson'}, {'Name':'Clean Code','Price':43.15,'Category':'Computers','Author':'Robert C. Martin'}])

The following result is displayed:

{
"acknowledged" : true,
"insertedIds" : [
ObjectId("5bfd996f7b8e48dc15ff215d"),
ObjectId("5bfd996f7b8e48dc15ff215e")
]
}

NOTE
The ID's shown in this article will not match the IDs when you run this sample.

1. View the documents in the database using the following command:

db.Books.find({}).pretty()

The following result is displayed:

 {
"_id" : ObjectId("5bfd996f7b8e48dc15ff215d"),
"Name" : "Design Patterns",
"Price" : 54.93,
"Category" : "Computers",
"Author" : "Ralph Johnson"
}
{
"_id" : ObjectId("5bfd996f7b8e48dc15ff215e"),
"Name" : "Clean Code",
"Price" : 43.15,
"Category" : "Computers",
"Author" : "Robert C. Martin"
}

The schema adds an autogenerated _id property of type ObjectId for each document.
The database is ready. You can start creating the ASP.NET Core web API.

Create the ASP.NET Core web API project

Visual Studio
Visual Studio Code
Visual Studio for Mac
1. Go to File > New > Project.
2. Select the ASP.NET Core Web Application project type, and select Next.
3. Name the project BooksApi, and select Create.
4. Select the .NET Core target framework and ASP.NET Core 2.2. Select the API project template, and select
Create.
5. Visit the NuGet Gallery: MongoDB.Driver to determine the latest stable version of the .NET driver for
MongoDB. In the Package Manager Console window, navigate to the project root. Run the following
command to install the .NET driver for MongoDB:

Install-Package MongoDB.Driver -Version {VERSION}

Add an entity model

1. Add a Models directory to the project root.
2. Add a Book class to the Models directory with the following code:
 using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;

namespace BooksApi.Models
{
public class Book
{
[BsonId]
[BsonRepresentation(BsonType.ObjectId)]
public string Id { get; set; }

[BsonElement("Name")]
public string BookName { get; set; }

public decimal Price { get; set; }

public string Category { get; set; }

public string Author { get; set; }

}
}

In the preceding class, the Id property:

Is required for mapping the Common Language Runtime (CLR ) object to the MongoDB collection.
Is annotated with [BsonId] to designate this property as the document's primary key.
Is annotated with [BsonRepresentation(BsonType.ObjectId)] to allow passing the parameter as type
string instead of an ObjectId structure. Mongo handles the conversion from string to ObjectId .
The BookName property is annotated with the [BsonElement] attribute. The attribute's value of Name
represents the property name in the MongoDB collection.

Add a configuration model

1. Add the following database configuration values to appsettings.json:

{
"BookstoreDatabaseSettings": {
"BooksCollectionName": "Books",
"ConnectionString": "mongodb://localhost:27017",
"DatabaseName": "BookstoreDb"
},
"Logging": {
"IncludeScopes": false,
"Debug": {
"LogLevel": {
"Default": "Warning"
}
},
"Console": {
"LogLevel": {
"Default": "Warning"
}
}
}
}

2. Add a BookstoreDatabaseSettings.cs file to the Models directory with the following code:
 namespace BooksApi.Models
{
public class BookstoreDatabaseSettings : IBookstoreDatabaseSettings
{
public string BooksCollectionName { get; set; }
public string ConnectionString { get; set; }
public string DatabaseName { get; set; }
}

public interface IBookstoreDatabaseSettings

{
string BooksCollectionName { get; set; }
string ConnectionString { get; set; }
string DatabaseName { get; set; }
}
}

The preceding BookstoreDatabaseSettings class is used to store the appsettings.json file's

BookstoreDatabaseSettings property values. The JSON and C# property names are named identically to
ease the mapping process.
3. Add the following highlighted code to Startup.ConfigureServices :

public void ConfigureServices(IServiceCollection services)

{
services.Configure<BookstoreDatabaseSettings>(
Configuration.GetSection(nameof(BookstoreDatabaseSettings)));

services.AddSingleton<IBookstoreDatabaseSettings>(sp =>
sp.GetRequiredService<IOptions<BookstoreDatabaseSettings>>().Value);

services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}

In the preceding code:

The configuration instance to which the appsettings.json file's BookstoreDatabaseSettings section binds is
registered in the Dependency Injection (DI) container. For example, a BookstoreDatabaseSettings object's
ConnectionString property is populated with the BookstoreDatabaseSettings:ConnectionString property in
appsettings.json.
The IBookstoreDatabaseSettings interface is registered in DI with a singleton service lifetime. When
injected, the interface instance resolves to a BookstoreDatabaseSettings object.
4. Add the following code to the top of Startup.cs to resolve the BookstoreDatabaseSettings and
IBookstoreDatabaseSettings references:

using BooksApi.Models;

Add a CRUD operations service

1. Add a Services directory to the project root.
2. Add a BookService class to the Services directory with the following code:
 using BooksApi.Models;
using MongoDB.Driver;
using System.Collections.Generic;
using System.Linq;

namespace BooksApi.Services
{
public class BookService
{
private readonly IMongoCollection<Book> _books;

public BookService(IBookstoreDatabaseSettings settings)

{
var client = new MongoClient(settings.ConnectionString);
var database = client.GetDatabase(settings.DatabaseName);

_books = database.GetCollection<Book>(settings.BooksCollectionName);
}

public List<Book> Get() =>

_books.Find(book => true).ToList();

public Book Get(string id) =>

_books.Find<Book>(book => book.Id == id).FirstOrDefault();

public Book Create(Book book)

{
_books.InsertOne(book);
return book;
}

public void Update(string id, Book bookIn) =>

_books.ReplaceOne(book => book.Id == id, bookIn);

public void Remove(Book bookIn) =>

_books.DeleteOne(book => book.Id == bookIn.Id);

public void Remove(string id) =>

_books.DeleteOne(book => book.Id == id);
}
}

In the preceding code, an IBookstoreDatabaseSettings instance is retrieved from DI via constructor injection.
This technique provides access to the appsettings.json configuration values that were added in the Add a
configuration model section.
3. Add the following highlighted code to Startup.ConfigureServices :

public void ConfigureServices(IServiceCollection services)

{
services.Configure<BookstoreDatabaseSettings>(
Configuration.GetSection(nameof(BookstoreDatabaseSettings)));

services.AddSingleton<IBookstoreDatabaseSettings>(sp =>
sp.GetRequiredService<IOptions<BookstoreDatabaseSettings>>().Value);

services.AddSingleton<BookService>();

services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}

In the preceding code, the BookService class is registered with DI to support constructor injection in
 consuming classes. The singleton service lifetime is most appropriate because BookService takes a direct
dependency on MongoClient . Per the official Mongo Client reuse guidelines, MongoClient should be
registered in DI with a singleton service lifetime.
4. Add the following code to the top of Startup.cs to resolve the BookService reference:

using BooksApi.Services;

The BookService class uses the following MongoDB.Driver members to perform CRUD operations against the
database:
MongoClient – Reads the server instance for performing database operations. The constructor of this class is
provided the MongoDB connection string:

public BookService(IBookstoreDatabaseSettings settings)

{
var client = new MongoClient(settings.ConnectionString);
var database = client.GetDatabase(settings.DatabaseName);

_books = database.GetCollection<Book>(settings.BooksCollectionName);
}

IMongoDatabase – Represents the Mongo database for performing operations. This tutorial uses the generic
GetCollection<TDocument>(collection) method on the interface to gain access to data in a specific
collection. Perform CRUD operations against the collection after this method is called. In the
GetCollection<TDocument>(collection) method call:

collection represents the collection name.

TDocument represents the CLR object type stored in the collection.

GetCollection<TDocument>(collection) returns a MongoCollection object representing the collection. In this tutorial,

the following methods are invoked on the collection:
DeleteOne – Deletes a single document matching the provided search criteria.
Find<TDocument> – Returns all documents in the collection matching the provided search criteria.
InsertOne – Inserts the provided object as a new document in the collection.
ReplaceOne – Replaces the single document matching the provided search criteria with the provided object.

Add a controller
Add a BooksController class to the Controllers directory with the following code:

using BooksApi.Models;
using BooksApi.Services;
using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;

namespace BooksApi.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class BooksController : ControllerBase
{
private readonly BookService _bookService;

public BooksController(BookService bookService)

{
_bookService = bookService;
 _bookService = bookService;
}

[HttpGet]
public ActionResult<List<Book>> Get() =>
_bookService.Get();

[HttpGet("{id:length(24)}", Name = "GetBook")]

public ActionResult<Book> Get(string id)
{
var book = _bookService.Get(id);

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

return book;
}

[HttpPost]
public ActionResult<Book> Create(Book book)
{
_bookService.Create(book);

return CreatedAtRoute("GetBook", new { id = book.Id.ToString() }, book);

}

[HttpPut("{id:length(24)}")]
public IActionResult Update(string id, Book bookIn)
{
var book = _bookService.Get(id);

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

_bookService.Update(id, bookIn);

return NoContent();
}

[HttpDelete("{id:length(24)}")]
public IActionResult Delete(string id)
{
var book = _bookService.Get(id);

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

_bookService.Remove(book.Id);

return NoContent();
}
}
}

The preceding web API controller:

Uses the BookService class to perform CRUD operations.
Contains action methods to support GET, POST, PUT, and DELETE HTTP requests.
Calls CreatedAtRoute in the Create action method to return an HTTP 201 response. Status code 201 is 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 book.

Test the web API

1. Build and run the app.
2. Navigate to http://localhost:<port>/api/books to test the controller's parameterless Get action method.
The following JSON response is displayed:

[
{
"id":"5bfd996f7b8e48dc15ff215d",
"bookName":"Design Patterns",
"price":54.93,
"category":"Computers",
"author":"Ralph Johnson"
},
{
"id":"5bfd996f7b8e48dc15ff215e",
"bookName":"Clean Code",
"price":43.15,
"category":"Computers",
"author":"Robert C. Martin"
}
]

3. Navigate to http://localhost:<port>/api/books/{id here} to test the controller's overloaded Get action

method. The following JSON response is displayed:

{
"id":"{ID}",
"bookName":"Clean Code",
"price":43.15,
"category":"Computers",
"author":"Robert C. Martin"
}

Configure JSON serialization options

There are two details to change about the JSON responses returned in the Test the web API section:
The property names' default camel casing should be changed to match the Pascal casing of the CLR object's
property names.
The bookName property should be returned as Name .

To satisfy the preceding requirements, make the following changes:

1. In Startup.ConfigureServices , chain the following highlighted code on to the AddMvc method call:
 public void ConfigureServices(IServiceCollection services)
{
services.Configure<BookstoreDatabaseSettings>(
Configuration.GetSection(nameof(BookstoreDatabaseSettings)));

services.AddSingleton<IBookstoreDatabaseSettings>(sp =>
sp.GetRequiredService<IOptions<BookstoreDatabaseSettings>>().Value);

services.AddSingleton<BookService>();

services.AddMvc()
.AddJsonOptions(options => options.UseMemberCasing())
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}

With the preceding change, property names in the web API's serialized JSON response match their
corresponding property names in the CLR object type. For example, the Book class's Author property
serializes as Author .
2. In Models/Book.cs, annotate the BookName property with the following [JsonProperty] attribute:

[BsonElement("Name")]
[JsonProperty("Name")]
public string BookName { get; set; }

The [JsonProperty] attribute's value of Name represents the property name in the web API's serialized
JSON response.
3. Add the following code to the top of Models/Book.cs to resolve the [JsonProperty] attribute reference:

using Newtonsoft.Json;

4. Repeat the steps defined in the Test the web API section. Notice the difference in JSON property names.

Next steps
For more information on building ASP.NET Core web APIs, see the following resources:
YouTube version of this article
Create web APIs with ASP.NET Core
Controller action return types in ASP.NET Core Web API
 Tutorial: Call an ASP.NET Core web API with jQuery
7/29/2019 • 4 minutes to read • Edit Online

By Rick Anderson
This tutorial shows how to call an ASP.NET Core web API with jQuery
For ASP.NET Core 2.2, see the 2.2 version of Call the Web API with jQuery.

Prerequisites
Complete Tutorial: Create a web API

Call the 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 app to serve static files and enable default file mapping by updating Startup.cs with the following
highlighted code:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)

{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}

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

app.UseHttpsRedirection();

app.UseRouting();

app.UseAuthorization();

app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
}

Create a wwwroot folder in the project directory.

Add an HTML file named index.html to the 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 {
 #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="Save">
<a onclick="closeInput()" aria-label="Close">&#10006;</a>
</form>
</div>

<p id="counter"></p>

<table>
<tr>
<th>Is Complete</th>
<th>Name</th>
<th></th>
<th></th>
</tr>
<tbody id="todos"></tbody>
</table>

<script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-3.4.1.js"
integrity="sha384-mlceH9HlqLp7GMKHrj5Ara1+LvdTZVMx4S1U43/NxCvAkzIo8WJ0FE7duLel3wVo"
crossorigin="anonymous"></script>
<script src="site.js"></script>
</body>
</html>

Add a JavaScript file named site.js to the wwwroot directory. Replace its contents with the following code:

const uri = 'api/TodoItems';

let todos = null;
function getCount(data) {
const el = $('#counter');
let name = 'to-do';
if (data) {
if (data > 1) {
 if (data > 1) {
name = 'to-dos';
}
el.text(data + ' ' + name);
} else {
el.text('No ' + name);
}
}

$(document).ready(function() {
getData();
});

function getData() {
$.ajax({
type: 'GET',
url: uri,
cache: false,
success: function(data) {
const tBody = $('#todos');

$(tBody).empty();

getCount(data.length);

$.each(data, function(key, item) {

const tr = $('<tr></tr>')
.append(
$('<td></td>').append(
$('<input/>', {
type: 'checkbox',
disabled: true,
checked: item.isComplete
})
)
)
.append($('<td></td>').text(item.name))
.append(
$('<td></td>').append(
$('<button>Edit</button>').on('click', function() {
editItem(item.id);
})
)
)
.append(
$('<td></td>').append(
$('<button>Delete</button>').on('click', function() {
deleteItem(item.id);
})
)
);

tr.appendTo(tBody);
});

todos = data;
}
});
}

function addItem() {
const item = {
name: $('#add-name').val(),
isComplete: false
};

$.ajax({
type: 'POST',
accepts: 'application/json',
url: uri,
 url: uri,
contentType: 'application/json',
data: JSON.stringify(item),
error: function(jqXHR, textStatus, errorThrown) {
alert('Something went wrong!');
},
success: function(result) {
getData();
$('#add-name').val('');
}
});
}

function deleteItem(id) {
$.ajax({
url: uri + '/' + id,
type: 'DELETE',
success: function(result) {
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: parseInt($('#edit-id').val(), 10)
};

$.ajax({
url: uri + '/' + $('#edit-id').val(),
type: 'PUT',
accepts: 'application/json',
contentType: 'application/json',
data: JSON.stringify(item),
success: function(result) {
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 Properties\launchSettings.json.
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 calls all of the CRUD methods of the API. Following are explanations of the calls to the API.
Get a list of to -do items
The jQuery ajax function sends a GET request to the API, which returns JSON representing an array of to-do
items. The success callback function is invoked if the request succeeds. In the callback, the DOM is updated with
the to-do information.

$(document).ready(function() {
getData();
});

function getData() {
$.ajax({
type: 'GET',
url: uri,
cache: false,
success: function(data) {
const tBody = $('#todos');

$(tBody).empty();

getCount(data.length);

$.each(data, function(key, item) {

const tr = $('<tr></tr>')
.append(
$('<td></td>').append(
$('<input/>', {
type: 'checkbox',
disabled: true,
checked: item.isComplete
})
)
)
.append($('<td></td>').text(item.name))
.append(
$('<td></td>').append(
$('<button>Edit</button>').on('click', function() {
editItem(item.id);
})
)
)
.append(
$('<td></td>').append(
$('<button>Delete</button>').on('click', function() {
deleteItem(item.id);
})
)
);

tr.appendTo(tBody);
});

todos = data;
}
});
}

Add a to -do item

The ajax function sends a POST request with the to-do item in the request body. The accepts and contentType
options are set to application/json to specify the media type being received and sent. The to-do item is converted
to JSON by using JSON.stringify. When the API returns a successful status code, the getData function is invoked
to update the HTML table.
 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('Something went wrong!');
},
success: function(result) {
getData();
$('#add-name').val('');
}
});
}

Update a to -do item

Updating a to-do item is similar to adding one. The url changes to add the unique identifier of the item, and the
type is PUT .

$.ajax({
url: uri + '/' + $('#edit-id').val(),
type: 'PUT',
accepts: 'application/json',
contentType: 'application/json',
data: JSON.stringify(item),
success: function(result) {
getData();
}
});

Delete a to -do item

Deleting a to-do item is accomplished by setting the type on the AJAX call to DELETE and specifying the item's
unique identifier in the URL.

$.ajax({
url: uri + '/' + id,
type: 'DELETE',
success: function(result) {
getData();
}
});

Advance to the next tutorial to learn how to generate API help pages:
Get started with Swashbuckle and ASP.NET Core
 Create backend services for native mobile apps with
ASP.NET Core
4/26/2019 • 8 minutes to read • Edit Online

By Steve Smith
Mobile apps can communicate with ASP.NET Core backend services. For instructions on connecting local web
services from iOS simulators and Android emulators, see Connect to Local Web Services from iOS Simulators and
Android Emulators.
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()
.UseStartup<Startup>()
.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:
 using System.ComponentModel.DataAnnotations;

namespace ToDoApi.Models
{
public class ToDoItem
{
[Required]
public string ID { get; set; }

[Required]
public string Name { get; set; }

[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 System.Collections.Generic;
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.Collections.Generic;
using System.Linq;
using ToDoApi.Interfaces;
using ToDoApi.Models;

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);
 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
};

var todoItem2 = new ToDoItem

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

var todoItem3 = new ToDoItem

{
ID = "ecfa6f80-3671-4911-aabe-63cc442c1ecf",
Name = "Publish apps",
Notes = "All app stores",
Done = false,
};

_toDoList.Add(todoItem1);
_toDoList.Add(todoItem2);
_toDoList.Add(todoItem3);
}
}
}

Configure the implementation in Startup.cs:

 public void ConfigureServices(IServiceCollection services)
{
// Add framework services.
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;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using ToDoApi.Interfaces;
using ToDoApi.Models;

namespace ToDoApi.Controllers
{
[Route("api/[controller]")]
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
{
if (item == null || !ModelState.IsValid)
{
return BadRequest(ErrorCode.TodoItemNameAndNotesRequired.ToString());
}
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.

[HttpDelete("{id}")]
public IActionResult Delete(string id)
{
try
{
var item = _toDoRepository.Find(id);
if (item == null)
{
return NotFound(ErrorCode.RecordNotFound.ToString());
}
_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.

Additional resources
Authentication and Authorization
 Tutorial: Get started with ASP.NET Core SignalR
7/15/2019 • 13 minutes to read • Edit Online

This tutorial teaches the basics of building a real-time app using SignalR. You learn how to:
Create a web project.
Add the SignalR client library.
Create a SignalR hub.
Configure the project to use SignalR.
Add code that sends messages from any client to all connected clients.
At the end, you'll have a working chat app:

Prerequisites
Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 3.0 Preview

Create a web app project

Visual Studio
Visual Studio Code
Visual Studio for Mac
From the menu, select File > New Project.
In the Create a new project dialog, select ASP.NET Core Web Application, and then select Next.
In the Configure your new project dialog, name the project SignalRChat, and then select Create.
 In the Create a new ASP.NET Core Web Application dialog, select .NET Core and ASP.NET Core 3.0.
Select Web Application to create a project that uses Razor Pages, and then select Create.

Add the SignalR client library

The SignalR server library is included in the ASP.NET Core 3.0 shared framework. 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 (CDN )) that can deliver anything found in npm, the
Node.js package manager.
Visual Studio
Visual Studio Code
Visual Studio for Mac
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@next .
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 a 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;
using System.Threading.Tasks;

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 a connected client to send a message to all clients. JavaScript
client code that calls the method is shown later in the tutorial. SignalR code is asynchronous to provide
maximum scalability.

Configure 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.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using SignalRChat.Hubs;

namespace SignalRChat
{
public class Startup
{
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.
public void ConfigureServices(IServiceCollection services)
{
services.Configure<CookiePolicyOptions>(options =>
{
// This lambda determines whether user consent for non-essential cookies is needed for a
given request.
options.CheckConsentNeeded = context => true;
});

services.AddRazorPages();
services.AddSignalR();
}

// This method gets called by the runtime. Use this method to configure the HTTP request
pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
// The default HSTS value is 30 days. You may want to change this for production
scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}

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

app.UseCookiePolicy();
app.UseRouting();

app.UseAuthorization();

app.UseEndpoints(endpoints =>
{
endpoints.MapRazorPages();
endpoints.MapHub<ChatHub>("/chatHub");
});
}
}
}
 These changes add SignalR to the ASP.NET Core dependency injection and routing systems.

Add SignalR client code

Replace the content in Pages\Index.cshtml with the following code:

@page
<div class="container">
<div class="row">&nbsp;</div>
<div class="row">
<div class="col-2">User</div>
<div class="col-4"><input type="text" id="userInput" /></div>
</div>
<div class="row">
<div class="col-2">Message</div>
<div class="col-4"><input type="text" id="messageInput" /></div>
</div>
<div class="row">&nbsp;</div>
<div class="row">
<div class="col-6">
<input type="button" id="sendButton" value="Send Message" />
</div>
</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();

//Disable send button until connection is established

document.getElementById("sendButton").disabled = true;

connection.on("ReceiveMessage", function (user, message) {

var msg = message.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
var encodedMsg = user + " says " + msg;
var li = document.createElement("li");
li.textContent = encodedMsg;
document.getElementById("messagesList").appendChild(li);
});

connection.start().then(function () {
document.getElementById("sendButton").disabled = false;
}).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) {
return console.error(err.toString());
});
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
Visual Studio for Mac
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 Message 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.

If you get the error ERR_SPDY_INADEQUATE_TRANSPORT_SECURITY in Chrome or

NS_ERROR_NET_INADEQUATE_SECURITY in Firefox, run these commands to update your development certificate:

dotnet dev-certs https --clean

dotnet dev-certs https --trust

Next steps
To learn more about SignalR, see the introduction:
Introduction to ASP.NET Core SignalR
This tutorial teaches the basics of building a real-time app using SignalR. You learn how to:
Create a web project.
Add the SignalR client library.
Create a SignalR hub.
Configure the project to use SignalR.
Add code that sends messages from any client to all connected clients.
At the end, you'll have a working chat app:
Prerequisites
Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio 2017 version 15.9 or later with the ASP.NET and web development workload. You can use
Visual Studio 2019, but some project creation steps differ from what's shown in the tutorial.
.NET Core SDK 2.2 or later

WARNING
If you use Visual Studio 2017, see dotnet/sdk issue #3124 for information about .NET Core SDK versions that don't work with
Visual Studio.

Create a web project

Visual Studio
Visual Studio Code
Visual Studio for Mac
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.2, 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 (CDN )) that can deliver anything found in npm, the
Node.js package manager.
Visual Studio
Visual Studio Code
Visual Studio for Mac
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 a 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;
using System.Threading.Tasks;

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 a connected client to send a message to all clients. JavaScript
client code that calls the method is shown later in the tutorial. SignalR code is asynchronous to provide
maximum scalability.

Configure 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.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using SignalRChat.Hubs;

namespace SignalRChat
{
public class Startup
{
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.
public void ConfigureServices(IServiceCollection services)
{
services.Configure<CookiePolicyOptions>(options =>
{
// This lambda determines whether user consent for non-essential cookies is needed for a
given request.
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

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.UseStaticFiles();
app.UseCookiePolicy();
app.UseSignalR(routes =>
{
routes.MapHub<ChatHub>("/chatHub");
});
app.UseMvc();
}
}
}

These changes add SignalR to the ASP.NET Core dependency injection system and the middleware pipeline.

Add SignalR client code

Replace the content in Pages\Index.cshtml with the following code:

@page
<div class="container">
<div class="row">&nbsp;</div>
<div class="row">
<div class="col-6">&nbsp;</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">&nbsp;</div>
<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();

//Disable send button until connection is established

document.getElementById("sendButton").disabled = true;

connection.on("ReceiveMessage", function (user, message) {

var msg = message.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
var encodedMsg = user + " says " + msg;
var li = document.createElement("li");
li.textContent = encodedMsg;
document.getElementById("messagesList").appendChild(li);
});

connection.start().then(function(){
document.getElementById("sendButton").disabled = false;
}).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) {
return console.error(err.toString());
});
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
Visual Studio for Mac
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 Message 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
In this tutorial, you learned how to:
Create a web app project.
Add the SignalR client library.
Create a SignalR hub.
Configure the project to use SignalR.
Add code that uses the hub to send messages from any client to all connected clients.
To learn more about SignalR, see the introduction:
Introduction to ASP.NET Core SignalR
 Use ASP.NET Core SignalR with TypeScript and
Webpack
5/14/2019 • 10 minutes to read • Edit Online

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
View or download sample code (how to download)

Prerequisites
Visual Studio
Visual Studio Code
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 2.2 or later
Node.js with npm

Create the ASP.NET Core web app

Visual Studio
Visual Studio Code
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.
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 select OK.
3. Select .NET Core from the target framework drop-down, and select ASP.NET Core 2.2 from the framework
selector drop-down. Select the Empty template, and select OK.

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.29.3" is used instead of "webpack": "^4.29.3" . 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>
<meta charset="utf-8" />
<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.

app.UseDefaultFiles();
app.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.

services.AddSignalR();

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:
 using Microsoft.AspNetCore.SignalR;
using System.Threading.Tasks;

namespace SignalRWebPack.Hubs
{
public class ChatHub : Hub
{
}
}

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 "./css/main.css";
import * as signalR from "@aspnet/signalr";

const divMessages: HTMLDivElement = document.querySelector("#divMessages");

const tbMessage: HTMLInputElement = document.querySelector("#tbMessage");
const btnSend: HTMLButtonElement = document.querySelector("#btnSend");
const username = new Date().getTime();

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;
});

tbMessage.addEventListener("keyup", (e: KeyboardEvent) => {

if (e.keyCode === 13) {
send();
}
});

btnSend.addEventListener("click", 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:
 import "./css/main.css";
import * as signalR from "@aspnet/signalr";

const divMessages: HTMLDivElement = document.querySelector("#divMessages");

const tbMessage: HTMLInputElement = document.querySelector("#tbMessage");
const btnSend: HTMLButtonElement = document.querySelector("#btnSend");
const username = new Date().getTime();

const connection = new signalR.HubConnectionBuilder()

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

connection.start().catch(err => document.write(err));

connection.on("messageReceived", (username: string, message: string) => {

let messageContainer = document.createElement("div");

messageContainer.innerHTML =
`<div class="message-author">${username}</div><div>${message}</div>`;

divMessages.appendChild(messageContainer);
divMessages.scrollTop = divMessages.scrollHeight;
});

tbMessage.addEventListener("keyup", (e: KeyboardEvent) => {

if (e.keyCode === 13) {
send();
}
});

btnSend.addEventListener("click", 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:

using Microsoft.AspNetCore.SignalR;
using System.Threading.Tasks;

namespace SignalRWebPack.Hubs
{
public class ChatHub : Hub
{
public async Task NewMessage(long 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
Visual Studio Code
1. Run Webpack in release mode. Using the Package Manager Console window, execute the following
command in the project root. If you are not in the project root, enter cd SignalRWebPack before entering the
command.

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.
Additional resources
ASP.NET Core SignalR JavaScript client
Use hubs in ASP.NET Core SignalR
 Tutorial: Create a gRPC client and server in ASP.NET
Core
8/7/2019 • 7 minutes to read • Edit Online

By John Luo
This tutorial shows how to create a .NET Core gRPC client and an ASP.NET Core gRPC Server.
At the end, you'll have a gRPC client that communicates with the gRPC Greeter service.
View or download sample code (how to download).
In this tutorial, you:
Create a gRPC Server.
Create a gRPC client.
Test the gRPC client service with the gRPC Greeter service.

Prerequisites
Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 3.0 Preview

Create a gRPC service

Visual Studio
Visual Studio Code
Visual Studio for Mac
From the Visual Studio File menu, select New > Project.
In the Create a new project dialog, select ASP.NET Core Web Application.
Select Next
Name the project GrpcGreeter. It's important to name the project GrpcGreeter so the namespaces will match
when you copy and paste code.
Select Create
In the Create a new ASP.NET Core Web Application dialog:
Select .NET Core and ASP.NET Core 3.0 in the dropdown menus.
Select the gRPC Service template.
Select Create
Run the service
Visual Studio
Visual Studio Code / Visual Studio for Mac
Press Ctrl+F5 to run the gRPC service without the debugger.
 Visual Studio runs the service in a command prompt.
The logs show the service listening on https://localhost:5001 .

info: Microsoft.Hosting.Lifetime[0]
Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[0]
Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]

NOTE
The gRPC template is configured to use Transport Layer Security (TLS). gRPC clients need to use HTTPS to call the server.
macOS doesn't support ASP.NET Core gRPC with TLS. Additional configuration is required to successfully run gRPC services
on macOS. For more information, see gRPC and ASP.NET Core on macOS.

Examine the project files

GrpcGreeter project files:
greet.proto: The Protos/greet.proto file defines the Greeter gRPC and is used to generate the gRPC server
assets. For more information, see Introduction to gRPC.
Services folder: Contains the implementation of the Greeter service.
appSettings.json: Contains configuration data, such as protocol used by Kestrel. For more information, see
Configuration in ASP.NET Core.
Program.cs: Contains the entry point for the gRPC service. For more information, see .NET Generic Host.
Startup.cs: Contains code that configures app behavior. For more information, see App startup.

Create the gRPC client in a .NET console app

Visual Studio
Visual Studio Code
Visual Studio for Mac
Open a second instance of Visual Studio.
Select File > New > Project from the menu bar.
In the Create a new project dialog, select Console App (.NET Core).
Select Next
In the Name text box, enter "GrpcGreeterClient".
Select Create.
Add required packages
The gRPC client project requires the following packages:
Grpc.Net.Client, which contains the .NET Core client.
Google.Protobuf, which contains protobuf message APIs for C#.
Grpc.Tools, which contains C# tooling support for protobuf files. The tooling package isn't required at runtime,
so the dependency is marked with PrivateAssets="All" .

Visual Studio
Visual Studio Code
 Visual Studio for Mac
Install the packages using either the Package Manager Console (PMC ) or Manage NuGet Packages.
PMC option to install packages
From Visual Studio, select Tools > NuGet Package Manager > Package Manager Console
From the Package Manager Console window, navigate to the directory in which the
GrpcGreeterClient.csproj file exists.
Run the following commands:

Install-Package Grpc.Net.Client
Install-Package Google.Protobuf
Install-Package Grpc.Tools

Manage NuGet Packages option to install packages

Right-click the project in Solution Explorer > Manage NuGet Packages
Select the Browse tab.
Enter Grpc.Net.Client in the search box.
Select the Grpc.Net.Client package from the Browse tab and select Install.
Repeat for Google.Protobuf and Grpc.Tools .
Add greet.proto
Create a Protos folder in the gRPC client project.
Copy the Protos\greet.proto file from the gRPC Greeter service to the gRPC client project.
Edit the GrpcGreeterClient.csproj project file:
Visual Studio
Visual Studio Code
Visual Studio for Mac
Right-click the project and select Edit Project File.

Add an item group with a <Protobuf> element that refers to the greet.proto file:

<ItemGroup>
<Protobuf Include="Protos\greet.proto" GrpcServices="Client" />
</ItemGroup>

Create the Greeter client

Build the project to create the types in the GrpcGreeter namespace. The GrpcGreeter types are generated
automatically by the build process.
Update the gRPC client Program.cs file with the following code:
 using System;
using System.Net.Http;
using System.Threading.Tasks;
using GrpcGreeter;
using Grpc.Net.Client;

namespace GrpcGreeterClient
{
class Program
{
static async Task Main(string[] args)
{
var httpClient = new HttpClient();
// The port number(5001) must match the port of the gRPC server.
httpClient.BaseAddress = new Uri("https://localhost:5001");
var client = GrpcClient.Create<Greeter.GreeterClient>(httpClient);
var reply = await client.SayHelloAsync(
new HelloRequest { Name = "GreeterClient" });
Console.WriteLine("Greeting: " + reply.Message);
Console.WriteLine("Press any key to exit...");
Console.ReadKey();
}
}
}

Program.cs contains the entry point and logic for the gRPC client.
The Greeter client is created by:
Instantiating an HttpClient containing the information for creating the connection to the gRPC service.
Using the HttpClient to construct the Greeter client:

static async Task Main(string[] args)

{
var httpClient = new HttpClient();
// The port number(5001) must match the port of the gRPC server.
httpClient.BaseAddress = new Uri("https://localhost:5001");
var client = GrpcClient.Create<Greeter.GreeterClient>(httpClient);
var reply = await client.SayHelloAsync(
new HelloRequest { Name = "GreeterClient" });
Console.WriteLine("Greeting: " + reply.Message);
Console.WriteLine("Press any key to exit...");
Console.ReadKey();
}

The Greeter client calls the asynchronous SayHello method. The result of the SayHello call is displayed:

static async Task Main(string[] args)

{
var httpClient = new HttpClient();
// The port number(5001) must match the port of the gRPC server.
httpClient.BaseAddress = new Uri("https://localhost:5001");
var client = GrpcClient.Create<Greeter.GreeterClient>(httpClient);
var reply = await client.SayHelloAsync(
new HelloRequest { Name = "GreeterClient" });
Console.WriteLine("Greeting: " + reply.Message);
Console.WriteLine("Press any key to exit...");
Console.ReadKey();
}

Test the gRPC client with the gRPC Greeter service

 Visual Studio
Visual Studio Code / Visual Studio for Mac
In the Greeter service, press Ctrl+F5 to start the server without the debugger.
In the GrpcGreeterClient project, press Ctrl+F5 to start the client without the debugger.

The client sends a greeting to the service with a message containing its name "GreeterClient". The service sends
the message "Hello GreeterClient" as a response. The "Hello GreeterClient" response is displayed in the command
prompt:

Greeting: Hello GreeterClient

Press any key to exit...

The gRPC service records the details of the successful call in the logs written to the command prompt.

info: Microsoft.Hosting.Lifetime[0]
Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[0]
Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
Content root path: C:\GH\aspnet\docs\4\Docs\aspnetcore\tutorials\grpc\grpc-start\sample\GrpcGreeter
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
Request starting HTTP/2 POST https://localhost:5001/Greet.Greeter/SayHello application/grpc
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
Executing endpoint 'gRPC - /Greet.Greeter/SayHello'
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
Executed endpoint 'gRPC - /Greet.Greeter/SayHello'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
Request finished in 78.32260000000001ms 200 application/grpc

Next steps
Introduction to gRPC on ASP.NET Core
gRPC services with C#
Migrating gRPC services from C -core to ASP.NET Core
 Razor Pages with Entity Framework Core in ASP.NET
Core - Tutorial 1 of 8
8/9/2019 • 32 minutes to read • Edit Online

By Tom Dykstra and Rick Anderson

This is the first in a series of tutorials that show how to use Entity Framework (EF ) Core in an ASP.NET Core Razor
Pages app. The tutorials build a web site for a fictional Contoso University. The site includes functionality such as
student admission, course creation, and instructor assignments.
Download or view the completed app. Download instructions.

Prerequisites
If you're new to Razor Pages, go through the Get started with Razor Pages tutorial series before starting this
one.
Visual Studio
Visual Studio Code
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 3.0 Preview

Database engines
The Visual Studio instructions use SQL Server LocalDB, a version of SQL Server Express that runs only on
Windows.
The Visual Studio Code instructions use SQLite, a cross-platform database engine.
If you choose to use SQLite, download and install a third-party tool for managing and viewing a SQLite database,
such as DB Browser for SQLite.

Troubleshooting
If you run into a problem you can't resolve, compare your code to the completed project. A good way to get help is
by posting a question to StackOverflow.com, using the ASP.NET Core tag or the EF Core tag.

The sample 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 based on the built-in project templates. The tutorial's focus is on how to use EF Core, not
how to customize the UI.
Follow the link at the top of the page to get the source code for the completed project. The cu30 folder has the code
for the ASP.NET Core 3.0 version of the tutorial. Files that reflect the state of the code for tutorials 1-7 can be found
in the cu30snapshots folder.
Visual Studio
Visual Studio Code
To run the app after downloading the completed project:
 Delete three files and one folder that have SQLite in the name.
Build the project.
In Package Manager Console (PMC ) run the following command:

Update-Database

Run the project to seed the database.

Create the web app project

Visual Studio
Visual Studio Code
From the Visual Studio File menu, select New > Project.
Select ASP.NET Core Web Application.
Name the project ContosoUniversity. It's important to use this exact name including capitalization, so the
namespaces match when code is copied and pasted.
Select .NET Core and ASP.NET Core 3.0 in the dropdowns, and then select Web Application.

Set up the site style

Set up the site header, footer, and menu by updatingPages/Shared/_Layout.cshtml:
Change each occurrence of "ContosoUniversity" to "Contoso University". There are three occurrences.
Delete the Home and Privacy menu entries, and add entries for About, Students, Courses, Instructors,
and Departments.
The changes are highlighted.
 <!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@ViewData["Title"] - Contoso University</title>
<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
<link rel="stylesheet" href="~/css/site.css" />
</head>
<body>
<header>
<nav class="navbar navbar-expand-sm navbar-toggleable-sm navbar-light bg-white border-bottom box-shadow
mb-3">
<div class="container">
<a class="navbar-brand" asp-area="" asp-page="/Index">Contoso University</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target=".navbar-
collapse" aria-controls="navbarSupportedContent"
aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="navbar-collapse collapse d-sm-inline-flex flex-sm-row-reverse">
<ul class="navbar-nav flex-grow-1">
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-page="/About">About</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-page="/Students/Index">Students</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-page="/Courses/Index">Courses</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-
page="/Instructors/Index">Instructors</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-
page="/Departments/Index">Departments</a>
</li>
</ul>
</div>
</div>
</nav>
</header>
<div class="container">
<main role="main" class="pb-3">
@RenderBody()
</main>
</div>

<footer class="border-top footer text-muted">

<div class="container">
&copy; 2019 - Contoso University - <a asp-area="" asp-page="/Privacy">Privacy</a>
</div>
</footer>

<script src="~/lib/jquery/dist/jquery.js"></script>
<script src="~/lib/bootstrap/dist/js/bootstrap.bundle.js"></script>
<script src="~/js/site.js" asp-append-version="true"></script>

@RenderSection("Scripts", required: false)

</body>
</html>

In Pages/Index.cshtml, replace the contents of the file with the following code to replace the text about ASP.NET
Core with text about this app:
 @page
@model IndexModel
@{
ViewData["Title"] = "Home page";
}

<div class="row mb-auto">

<div class="col-md-4">
<div class="row no-gutters border mb-4">
<div class="col p-4 mb-4 ">
<p class="card-text">
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>
</div>
</div>
<div class="col-md-4">
<div class="row no-gutters border mb-4">
<div class="col p-4 d-flex flex-column position-static">
<p class="card-text mb-auto">
You can build the application by following the steps in a series of tutorials.
</p>
<p>
<a href="https://docs.microsoft.com/aspnet/core/data/ef-rp/intro" class="stretched-
link">See the tutorial</a>
</p>
</div>
</div>
</div>
<div class="col-md-4">
<div class="row no-gutters border mb-4">
<div class="col p-4 d-flex flex-column">
<p class="card-text mb-auto">
You can download the completed project from GitHub.
</p>
<p>
<a href="https://github.com/aspnet/AspNetCore.Docs/tree/master/aspnetcore/data/ef-
rp/intro/samples" class="stretched-link">See project source code</a>
</p>
</div>
</div>
</div>
</div>

Run the app to verify that the home page appears.

The data model

The following sections create a data model:
A student can enroll in any number of courses, and a course can have any number of students enrolled in it.

The Student entity

Create a Models folder in the project folder.

Create Models/Student.cs with the following code:

using System;
using System.Collections.Generic;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
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 table that corresponds to this class. By default,
EF Core interprets a property that's named ID or classnameID as the primary key. So the alternative automatically
recognized name for the Student class primary key is StudentID .
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 holds all of the Enrollment entities that are
related to that Student. For example, if a Student row in the database has two related Enrollment rows, the
Enrollments navigation property contains those two Enrollment entities.

In the database, an Enrollment row is related to a Student row if its StudentID column contains the student's ID
value. For example, suppose a Student row has ID=1. Related Enrollment rows will have StudentID = 1. StudentID
is a foreign key in the Enrollment table.
The Enrollments property is defined as ICollection<Enrollment> because there may be multiple related
Enrollment entities. You can use other collection types, such as List<Enrollment> or HashSet<Enrollment> . When
ICollection<Enrollment> is used, EF Core creates a HashSet<Enrollment> collection by default.

The Enrollment entity

Create Models/Enrollment.cs with the following code:

namespace ContosoUniversity.Models
{
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 EnrollmentID property is the primary key; this entity uses the classnameID pattern instead of ID by itself. For
a production data model, choose one pattern and use it consistently. This tutorial uses both just to illustrate that
both work. Using ID without classname makes it easier to implement some kinds of data model changes.
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 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 is the foreign key 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

Create Models/Course.cs with the following code:

using System.Collections.Generic;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Course
{
[DatabaseGenerated(DatabaseGeneratedOption.None)]
public int CourseID { get; set; }
public string Title { get; set; }
public int Credits { get; set; }

public ICollection<Enrollment> Enrollments { 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 database
generate it.
Build the project to validate that there are no compiler errors.

Scaffold Student pages

In this section, you use the ASP.NET Core scaffolding tool to generate:
An EF Core context class. The context is the main class that coordinates Entity Framework functionality for a
given data model. It derives from the Microsoft.EntityFrameworkCore.DbContext class.
Razor pages that handle Create, Read, Update, and Delete (CRUD ) operations for the Student entity.

Visual Studio
Visual Studio Code
Create a Students folder in the Pages folder.
In Solution Explorer, right-click the Pages/Students folder and select Add > New Scaffolded Item.
In the Add Scaffold dialog, select Razor Pages using Entity Framework (CRUD ) > ADD.
In the Add Razor Pages using Entity Framework (CRUD ) dialog:
In the Model class drop-down, select Student (ContosoUniversity.Models).
In the Data context class row, select the + (plus) sign.
Change the data context name from ContosoUniversity.Models.ContosoUniversityContext to
ContosoUniversity.Data.SchoolContext.
Select Add.
The following packages are automatically installed:
 Microsoft.VisualStudio.Web.CodeGeneration.Design
Microsoft.EntityFrameworkCore.SqlServer
Microsoft.Extensions.Logging.Debug
Microsoft.EntityFrameworkCore.Tools

If you have a problem with the preceding step, build the project and retry the scaffold step.
The scaffolding process:
Creates Razor pages in the Pages/Students folder:
Create.cshtml and Create.cshtml.cs
Delete.cshtml and Delete.cshtml.cs
Details.cshtml and Details.cshtml.cs
Edit.cshtml and Edit.cshtml.cs
Index.cshtml and Index.cshtml.cs
Creates Data/SchoolContext.cs.
Adds the context to dependency injection in Startup.cs.
Adds a database connection string to appsettings.json.

Database connection string

Visual Studio
Visual Studio Code
The connection string specifies SQL Server LocalDB.

{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*",
"ConnectionStrings": {
"SchoolContext": "Server=
(localdb)\\mssqllocaldb;Database=SchoolContext;Trusted_Connection=True;MultipleActiveResultSets=true"
}
}

LocalDB is a lightweight version of the SQL Server Express Database Engine and is intended for app development,
not production use. By default, LocalDB creates .mdf files in the C:/Users/<user> directory.

Update the database context class

The main class that coordinates EF Core functionality for a given data model is the database context class. The
context is derived from Microsoft.EntityFrameworkCore.DbContext. The 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:
 using Microsoft.EntityFrameworkCore;
using ContosoUniversity.Models;

namespace ContosoUniversity.Data
{
public class SchoolContext : DbContext
{
public SchoolContext (DbContextOptions<SchoolContext> options)
: base(options)
{
}

public DbSet<Student> Students { get; set; }

public DbSet<Enrollment> Enrollments { get; set; }
public DbSet<Course> Courses { get; set; }

protected override void OnModelCreating(ModelBuilder modelBuilder)

{
modelBuilder.Entity<Course>().ToTable("Course");
modelBuilder.Entity<Enrollment>().ToTable("Enrollment");
modelBuilder.Entity<Student>().ToTable("Student");
}
}
}

The highlighted code creates a DbSet<TEntity> property for each entity set. In EF Core terminology:
An entity set typically corresponds to a database table.
An entity corresponds to a row in the table.
Since an entity set contains multiple entities, the DBSet properties should be plural names. Since the scaffolding
tool created a Student DBSet, this step changes it to plural Students .
To make the Razor Pages code match the new DBSet name, make a global change across the whole project of
_context.Student to _context.Students . There are 8 occurrences.

Build the project to verify there are no compiler errors.

Startup.cs
ASP.NET Core is built with dependency injection. Services (such as the EF Core database 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 database context
instance is shown later in the tutorial.
The scaffolding tool automatically registered the context class with the dependency injection container.
Visual Studio
Visual Studio Code
In ConfigureServices , the highlighted lines were added by the scaffolder:

public void ConfigureServices(IServiceCollection services)

{
services.AddRazorPages();

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
appsettings.json file.

Create the database

Update Program.cs to create the database if it doesn't exist:

using ContosoUniversity.Data;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using System;

namespace ContosoUniversity
{
public class Program
{
public static void Main(string[] args)
{
var host = CreateHostBuilder(args).Build();

CreateDbIfNotExists(host);

host.Run();
}

private static void CreateDbIfNotExists(IHost host)

{
using (var scope = host.Services.CreateScope())
{
var services = scope.ServiceProvider;

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

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
}

The EnsureCreated method takes no action if a database for the context exists. If no database exists, it creates the
database and schema. EnsureCreated enables the following workflow for handling data model changes:
Delete the database. Any existing data is lost.
Change the data model. For example, add an EmailAddress field.
Run the app.
EnsureCreated creates a database with the new schema.
This workflow works well early in development when the schema is rapidly evolving, as long as you don't need to
preserve data. The situation is different when data that has been entered into the database needs to be preserved.
When that is the case, use migrations.
Later in the tutorial series, you delete the database that was created by EnsureCreated and use migrations instead.
A database that is created by EnsureCreated can't be updated by using migrations.
Test the app
Run the app.
Select the Students link and then Create New.
Test the Edit, Details, and Delete links.

Seed the database

The EnsureCreated method creates an empty database. This section adds code that populates the database with
test data.
Create Data/DbInitializer.cs with the following code:

using ContosoUniversity.Data;
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.Students.Any())
{
return; // DB has been seeded
}

var students = new Student[]

{
new Student{FirstMidName="Carson",LastName="Alexander",EnrollmentDate=DateTime.Parse("2019-09-
01")},
new Student{FirstMidName="Meredith",LastName="Alonso",EnrollmentDate=DateTime.Parse("2017-09-
01")},
new Student{FirstMidName="Arturo",LastName="Anand",EnrollmentDate=DateTime.Parse("2018-09-
01")},
new Student{FirstMidName="Gytis",LastName="Barzdukas",EnrollmentDate=DateTime.Parse("2017-09-
01")},
new Student{FirstMidName="Yan",LastName="Li",EnrollmentDate=DateTime.Parse("2017-09-01")},
new Student{FirstMidName="Peggy",LastName="Justice",EnrollmentDate=DateTime.Parse("2016-09-
01")},
new Student{FirstMidName="Laura",LastName="Norman",EnrollmentDate=DateTime.Parse("2018-09-
01")},
new Student{FirstMidName="Nino",LastName="Olivetto",EnrollmentDate=DateTime.Parse("2019-09-
01")}
};
foreach (Student s in students)
{
context.Students.Add(s);
}
context.SaveChanges();

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.Courses.Add(c);
}
context.SaveChanges();

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=1045,Grade=Grade.B},
new Enrollment{StudentID=2,CourseID=3141,Grade=Grade.F},
new Enrollment{StudentID=2,CourseID=2021,Grade=Grade.F},
new Enrollment{StudentID=3,CourseID=1050},
new Enrollment{StudentID=4,CourseID=1050},
new Enrollment{StudentID=4,CourseID=4022,Grade=Grade.F},
new Enrollment{StudentID=5,CourseID=4041,Grade=Grade.C},
new Enrollment{StudentID=6,CourseID=1045},
new Enrollment{StudentID=7,CourseID=3141,Grade=Grade.A},
};
foreach (Enrollment e in enrollments)
{
context.Enrollments.Add(e);
}
context.SaveChanges();
}
}
}

The code checks if there are any students in the database. If there are no students, it adds test data to the database.
It creates the test data in arrays rather than List<T> collections to optimize performance.
In Program.cs, replace the EnsureCreated call with a DbInitializer.Initialize call:

// context.Database.EnsureCreated();
DbInitializer.Initialize(context);

Visual Studio
Visual Studio Code
Run the app, delete any student records you created earlier, and stop the app.
Restart the app.
Select the Students page to see the seeded data.

View the database

Visual Studio
Visual Studio Code
Open SQL Server Object Explorer (SSOX) from the View menu in Visual Studio.
In SSOX, select (localdb)\MSSQLLocalDB > Databases > SchoolContext-{GUID }. The database name is
 generated from the context name you provided earlier plus a dash and a GUID.
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.
Right-click the Student table and click View Code to see how the Student model maps to the Student table
schema.

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 can 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.

public async Task OnGetAsync()

{
Students = await _context.Students.ToListAsync();
}

The async keyword tells the compiler to:

Generate callbacks for parts of the method body.
Create the Task object that's returned.
The Task<T> return type 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 database 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 database.
For more information about asynchronous programming in .NET, see Async Overview and Asynchronous
programming with async and await.

Next steps
 NEXT
T U T O R IA L

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
Visual Studio Code
Visual Studio 2019 with the following workloads:
ASP.NET and web development
.NET Core cross-platform development
.NET Core 2.1 SDK or later
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
Visual Studio Code
From the Visual Studio File menu, select New > Project.
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.
Select ASP.NET Core 2.1 in the dropdown, and then select Web Application.
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>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@ViewData["Title"] : Contoso University</title>

<environment include="Development">
<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
<link rel="stylesheet" href="~/css/site.css" />
</environment>
<environment exclude="Development">
<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>
</head>
<body>
<nav class="navbar navbar-inverse navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-
collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a asp-page="/Index" class="navbar-brand">Contoso University</a>
</div>
<div class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<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" />

<div class="container body-content">

@RenderBody()
<hr />
<footer>
<p>&copy; 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">
<div class="col-md-4">
<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>
<div class="col-md-4">
<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 &raquo;
</a>
</p>
</div>
<div class="col-md-4">
<h2>Download it</h2>
<p>You can download the completed project from GitHub.</p>
<p>
<a class="btn btn-default"
href="https://github.com/aspnet/AspNetCore.Docs/tree/master/aspnetcore/data/ef-
rp/intro/samples/cu-final">
See project source code &raquo;
</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;
using System.Collections.Generic;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
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:

 namespace ContosoUniversity.Models
{
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:

 using System.Collections.Generic;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Course
{
[DatabaseGenerated(DatabaseGeneratedOption.None)]
public int CourseID { get; set; }
public string Title { get; set; }
public int Credits { get; set; }

public ICollection<Enrollment> Enrollments { 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
Visual Studio Code
In Solution Explorer, right click on the Pages/Students 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 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.
The scaffold process created and changed the following files:
Files created
Pages/Students Create, Delete, Details, Edit, Index.
Data/SchoolContext.cs
File 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 ConfigureServices method in Startup.cs. The highlighted line was added by the scaffolder:
 public void ConfigureServices(IServiceCollection services)
{
services.Configure<CookiePolicyOptions>(options =>
{
// This lambda determines whether user consent for
//non -essential cookies is needed for a given request.
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

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
appsettings.json file.

Update main
In Program.cs, modify the Main method to do the following:
Get a DB context instance from the dependency injection container.
Call the EnsureCreated.
Dispose the context when the EnsureCreated method completes.
The following code shows the updated Program.cs file.
 using ContosoUniversity.Models; // SchoolContext
using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection; // CreateScope
using Microsoft.Extensions.Logging;
using System;

namespace ContosoUniversity
{
public class Program
{
public static void Main(string[] args)
{
var host = CreateWebHostBuilder(args).Build();

using (var scope = host.Services.CreateScope())

{
var services = scope.ServiceProvider;

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

host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>();
}
}

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.
Test the Edit, Details, and Delete links.
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:

using Microsoft.EntityFrameworkCore;

namespace ContosoUniversity.Models
{
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 .
SQL Server Express LocalDB
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.Models
{
public static class DbInitializer
{
public static void Initialize(SchoolContext context)
{
// context.Database.EnsureCreated();

// Look for any students.

if (context.Student.Any())
{
 {
return; // DB has been seeded
}

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);
}
context.SaveChanges();

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);
}
context.SaveChanges();

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=1045,Grade=Grade.B},
new Enrollment{StudentID=2,CourseID=3141,Grade=Grade.F},
new Enrollment{StudentID=2,CourseID=2021,Grade=Grade.F},
new Enrollment{StudentID=3,CourseID=1050},
new Enrollment{StudentID=4,CourseID=1050},
new Enrollment{StudentID=4,CourseID=4022,Grade=Grade.F},
new Enrollment{StudentID=5,CourseID=4041,Grade=Grade.C},
new Enrollment{StudentID=6,CourseID=1045},
new Enrollment{StudentID=7,CourseID=3141,Grade=Grade.A},
};
foreach (Enrollment e in enrollments)
{
context.Enrollment.Add(e);
}
context.SaveChanges();
}
}
}

Note: The preceding code uses Models for the namespace ( namespace ContosoUniversity.Models ) rather than Data .
Models is consistent with the scaffolder -generated code. For more information, see this GitHub scaffolding issue.

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 :

public class Program

{
public static void Main(string[] args)
{
var host = CreateWebHostBuilder(args).Build();

using (var scope = host.Services.CreateScope())

{
var services = scope.ServiceProvider;

try
{
var context = services.GetRequiredService<SchoolContext>();
// using ContosoUniversity.Data;
DbInitializer.Initialize(context);
}
catch (Exception ex)
{
var logger = services.GetRequiredService<ILogger<Program>>();
logger.LogError(ex, "An error occurred creating the DB.");
}
}

host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>();
}

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
The database name is generated from the context name you provided earlier plus a dash and a GUID. Thus, the
database name will be "SchoolContext-{GUID }". The GUID will be different for each user. Open SQL Server
Object Explorer (SSOX) from the View menu in Visual Studio. In SSOX, click (localdb)\MSSQLLocalDB >
Databases > SchoolContext-{GUID }.
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.

public async Task OnGetAsync()

{
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.

Additional resources
YouTube version of this tutorial

NEXT
 Razor Pages with EF Core in ASP.NET Core - CRUD -
2 of 8
8/9/2019 • 22 minutes to read • Edit Online

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.
If you run into problems you can't solve, download the completed app and compare that code to what you created
by following the tutorial.
In this tutorial, the scaffolded CRUD (create, read, update, delete) code is reviewed and customized.

No repository
Some developers use a service layer or repository pattern to create an abstraction layer between the UI (Razor
Pages) and the data access layer. This tutorial doesn't do that. To minimize complexity and keep the tutorial focused
on EF Core, EF Core code is added directly to the page model classes.

Update the Details page

The scaffolded code for the Students pages doesn't include enrollment data. In this section, you add enrollments to
the Details page.
Read enrollments
To display a student's enrollment data on the page, you need to read it. The scaffolded code in
Pages/Students/Details.cshtml.cs reads only the Student data, without the Enrollment data:

public async Task<IActionResult> OnGetAsync(int? id)

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

Student = await _context.Students.FirstOrDefaultAsync(m => m.ID == id);

if (Student == null)
{
return NotFound();
}
return Page();
}

Replace the OnGetAsync method with the following code to read enrollment data for the selected student. The
changes are highlighted.
 public async Task<IActionResult> OnGetAsync(int? id)
{
if (id == null)
{
return NotFound();
}

Student = await _context.Students

.Include(s => s.Enrollments)
.ThenInclude(e => e.Course)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.ID == id);

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 where the entities returned are not updated in the
current context. AsNoTracking is discussed later in this tutorial.
Display enrollments
Replace the code in Pages/Students/Details.cshtml with the following code to display a list of enrollments. The
changes are highlighted.
 @page
@model ContosoUniversity.Pages.Students.DetailsModel

@{
ViewData["Title"] = "Details";
}

<h1>Details</h1>

<div>
<h4>Student</h4>
<hr />
<dl class="row">
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Student.LastName)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Student.LastName)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Student.FirstMidName)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Student.FirstMidName)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Student.EnrollmentDate)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Student.EnrollmentDate)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Student.Enrollments)
</dt>
<dd class="col-sm-10">
<table class="table">
<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>

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.
Ways to read one entity
The generated code uses FirstOrDefaultAsync to read one entity. This method returns null if nothing is found;
otherwise, it returns the first row found that satisfies the query filter criteria. FirstOrDefaultAsync is generally a
better choice than the following alternatives:
SingleOrDefaultAsync - Throws an exception if there's more than one entity that satisfies the query filter. To
determine if more than one row could be returned by the query, SingleOrDefaultAsync tries to fetch multiple
rows. This extra work is unnecessary if the query can only return one entity, as when it searches on a unique key.
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 database. This method is optimized to look up a single entity, but you can't call
Include with FindAsync . So if related data is needed, FirstOrDefaultAsync is the better choice.

Route data vs. query string

The URL for the Details page is https://localhost:<port>/Students/Details?id=1 . The entity's primary key value is
in the query string. Some developers prefer to pass the key value in route data:
https://localhost:<port>/Students/Details/1 . For more information, see Update the generated code.

Update the Create page

The scaffolded OnPostAsync code for the Create page is vulnerable to overposting. Replace the OnPostAsync
method in Pages/Students/Create.cshtml.cs with the following code.

public async Task<IActionResult> OnPostAsync()

{
var emptyStudent = new Student();

if (await TryUpdateModelAsync<Student>(
emptyStudent,
"student", // Prefix for form value.
s => s.FirstMidName, s => s.LastName, s => s.EnrollmentDate))
{
_context.Students.Add(emptyStudent);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}

return Page();
}

TryUpdateModelAsync
The preceding code creates a Student object and then uses posted form fields to update the Student object's
properties. The TryUpdateModelAsync method:
Uses the posted form values from the PageContext property in the PageModel.
Updates only the properties listed ( s => s.FirstMidName, s => s.LastName, s => s.EnrollmentDate ).
Looks for form fields with a "student" prefix. For example, Student.FirstMidName . It's not case sensitive.
Uses the model binding system to convert form values from strings to the types in the Student model. For
example, EnrollmentDate has to be converted to DateTime.
Run the app, and create a student entity to test the Create page.

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 class Student

{
public int ID { get; set; }
public string LastName { get; set; }
public string FirstMidName { get; set; }
public DateTime EnrollmentDate { get; set; }
public string Secret { get; set; }
}

Even if the app doesn't have a Secret field on the create or 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 database. 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. That happens even though
the app designer never intended the Secret property to be set with the Create page.
View model
View models provide an alternative way to prevent overposting.
The application model is often called the domain model. The domain model typically contains all the properties
required by the corresponding entity in the database. The view model contains only the properties needed for the
UI that it is used for (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;

namespace ContosoUniversity.Models
{
public class StudentVM
{
public int ID { get; set; }
public string LastName { get; set; }
public string FirstMidName { get; set; }
public DateTime EnrollmentDate { get; set; }
}
}

The following code uses the StudentVM view model to create a new student:

[BindProperty]
public StudentVM StudentVM { get; set; }

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

var entry = _context.Add(new Student());

entry.CurrentValues.SetValues(StudentVM);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}

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 Create.cshtml be updated to use StudentVM rather than Student .

Update the Edit page

In Pages/Students/Edit.cshtml.cs, replace the OnGetAsync and OnPostAsync methods with the following code.
 public async Task<IActionResult> OnGetAsync(int? id)
{
if (id == null)
{
return NotFound();
}

Student = await _context.Students.FindAsync(id);

if (Student == null)
{
return NotFound();
}
return Page();
}

public async Task<IActionResult> OnPostAsync(int id)

{
var studentToUpdate = await _context.Students.FindAsync(id);

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

if (await TryUpdateModelAsync<Student>(
studentToUpdate,
"student",
s => s.FirstMidName, s => s.LastName, s => s.EnrollmentDate))
{
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}

return Page();
}

The code changes are similar to the Create page with a few exceptions:
FirstOrDefaultAsync has been replaced with FindAsync. When you don't have to include related data,
FindAsync is more efficient.
OnPostAsync has an id parameter.
The current student is fetched from the database, rather than creating an empty student.
Run the app, and test it by creating and editing a student.

Entity States
The database context keeps track of whether entities in memory are in sync with their corresponding rows in the
database. This tracking 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 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 : No changes need to be saved with this entity. An entity has this status when it's read from the
database.
: 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 app, state changes are typically set automatically. An entity is read, changes are made, and the entity
state is automatically 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 .
Rereading the entity in that new context simulates desktop processing.

Update the Delete page

In this section, you implement a custom error message when the call to SaveChanges fails.
Replace the code in Pages/Students/Delete.cshtml.cs with the following code. The changes are highlighted (other
than cleanup of using statements).

using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Students
{
public class DeleteModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public DeleteModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Student Student { get; set; }
public string ErrorMessage { get; set; }

public async Task<IActionResult> OnGetAsync(int? id, bool? saveChangesError = false)

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

Student = await _context.Students

.AsNoTracking()
.FirstOrDefaultAsync(m => m.ID == id);

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

if (saveChangesError.GetValueOrDefault())
{
ErrorMessage = "Delete failed. Try again";
}

return Page();
}

public async Task<IActionResult> OnPostAsync(int? id)

 public async Task<IActionResult> OnPostAsync(int? id)
{
if (id == null)
{
return NotFound();
}

var student = await _context.Students.FindAsync(id);

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

try
{
_context.Students.Remove(student);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
catch (DbUpdateException /* ex */)
{
//Log the error (uncomment ex variable name and write a log.)
return RedirectToAction("./Delete",
new { id, saveChangesError = true });
}
}
}
}

The preceding code adds the optional parameter saveChangesError to the OnGetAsync method signature.
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 when the
database is in the cloud. The saveChangesError parameter 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 method retrieves the selected entity, then calls the Remove method to set the entity's status to
OnPostAsync
Deleted . When SaveChanges is called, a SQL DELETE command is generated. If Remove fails:

The database exception is caught.

The Delete pages OnGetAsync method is called with saveChangesError=true .

Add an error message to the Delete Razor Page (Pages/Students/Delete.cshtml):

 @page
@model ContosoUniversity.Pages.Students.DeleteModel

@{
ViewData["Title"] = "Delete";
}

<h1>Delete</h1>

<p class="text-danger">@Model.ErrorMessage</p>

<h3>Are you sure you want to delete this?</h3>

<div>
<h4>Student</h4>
<hr />
<dl class="row">
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Student.LastName)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Student.LastName)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Student.FirstMidName)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Student.FirstMidName)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Student.EnrollmentDate)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Student.EnrollmentDate)
</dd>
</dl>

<form method="post">
<input type="hidden" asp-for="Student.ID" />
<input type="submit" value="Delete" class="btn btn-danger" /> |
<a asp-page="./Index">Back to List</a>
</form>
</div>

Run the app and delete a student to test the Delete page.

Next steps

P R E V IO U S NEXT
T U T O R IA L T U T O R IA L

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 Students 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 that 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>
<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>

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:

public async Task<IActionResult> OnGetAsync(int? id)

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

Student = await _context.Student

.Include(s => s.Enrollments)
.ThenInclude(e => e.Course)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.ID == id);

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

@{
ViewData["Title"] = "Details";
}

<h2>Details</h2>

<div>
<h4>Student</h4>
<hr />
<dl class="dl-horizontal">
<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>
<table class="table">
<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:

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
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);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}

return null;
}

TryUpdateModelAsync
Examine the TryUpdateModelAsync code:

var emptyStudent = new Student();

if (await TryUpdateModelAsync<Student>(
emptyStudent,
"student", // Prefix for form value.
s => s.FirstMidName, s => s.LastName, s => s.EnrollmentDate))
{

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 class Student
{
public int ID { get; set; }
public string LastName { get; set; }
public string FirstMidName { get; set; }
public DateTime EnrollmentDate { get; set; }
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;

namespace ContosoUniversity.Models
{
public class StudentVM
{
public int ID { get; set; }
public string LastName { get; set; }
public string FirstMidName { get; set; }
public DateTime EnrollmentDate { get; set; }
}
}

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; }

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

var entry = _context.Add(new Student());

entry.CurrentValues.SetValues(StudentVM);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}

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:
 public class EditModel : PageModel
{
private readonly SchoolContext _context;

public EditModel(SchoolContext context)

{
_context = context;
}

[BindProperty]
public Student Student { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Student = await _context.Student.FindAsync(id);

if (Student == null)
{
return NotFound();
}
return Page();
}

public async Task<IActionResult> OnPostAsync(int? id)

{
if (!ModelState.IsValid)
{
return Page();
}

var studentToUpdate = await _context.Student.FindAsync(id);

if (await TryUpdateModelAsync<Student>(
studentToUpdate,
"student",
s => s.FirstMidName, s => s.LastName, s => s.EnrollmentDate))
{
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}

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

{
private readonly SchoolContext _context;

public DeleteModel(SchoolContext context)

{
_context = context;
}

[BindProperty]
public Student Student { get; set; }
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()
.FirstOrDefaultAsync(m => m.ID == id);

if (Student == null)
{
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:

public async Task<IActionResult> OnPostAsync(int? id)

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

var student = await _context.Student

.AsNoTracking()
.FirstOrDefaultAsync(m => m.ID == id);

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

try
{
_context.Student.Remove(student);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
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
Students/Index or other links don't work:
Verify the Razor Page contains the correct @page directive. For example, The Students/Index Razor Page should
not contain a route template:

@page "{id:int}"

Each Razor Page must include the @page directive.

Additional resources
YouTube version of this tutorial

P R E V IO U S NEXT
 Razor Pages with EF Core in ASP.NET Core - Sort,
Filter, Paging - 3 of 8
8/9/2019 • 29 minutes to read • Edit Online

By Tom Dykstra, Rick Anderson, and Jon P Smith

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.
If you run into problems you can't solve, download the completed app and compare that code to what you created
by following the tutorial.
This tutorial adds sorting, filtering, and paging functionality to the Students pages.
The following illustration shows a completed page. The column headings are clickable links to sort the column.
Click a column heading repeatedly to switch between ascending and descending sort order.

Add sorting
Replace the code in Pages/Students/Index.cshtml.cs with the following code to add sorting.
 using ContosoUniversity.Data;
using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Students
{
public class IndexModel : PageModel
{
private readonly SchoolContext _context;

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; }

public IList<Student> Students { get; set; }

public async Task OnGetAsync(string sortOrder)

{
NameSort = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";
DateSort = sortOrder == "Date" ? "date_desc" : "Date";

IQueryable<Student> studentsIQ = from s in _context.Students

select s;

switch (sortOrder)
{
case "name_desc":
studentsIQ = studentsIQ.OrderByDescending(s => s.LastName);
break;
case "Date":
studentsIQ = studentsIQ.OrderBy(s => s.EnrollmentDate);
break;
case "date_desc":
studentsIQ = studentsIQ.OrderByDescending(s => s.EnrollmentDate);
break;
default:
studentsIQ = studentsIQ.OrderBy(s => s.LastName);
break;
}

Students = await studentsIQ.AsNoTracking().ToListAsync();

}
}
}

The preceding code:

Adds properties to contain the sorting parameters.
Changes the name of the Student property to Students .
Replaces the code in the OnGetAsync method.

The OnGetAsync method 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:

NameSort = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";

DateSort = sortOrder == "Date" ? "date_desc" : "Date";

The code uses the C# conditional operator ?:. The ?: operator is a ternary operator (it takes three operands). 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.
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:

IQueryable<Student> studentsIQ = from s in _context.Students

select s;

switch (sortOrder)
{
case "name_desc":
studentsIQ = studentsIQ.OrderByDescending(s => s.LastName);
break;
case "Date":
studentsIQ = studentsIQ.OrderBy(s => s.EnrollmentDate);
break;
case "date_desc":
studentsIQ = studentsIQ.OrderByDescending(s => s.EnrollmentDate);
break;
default:
studentsIQ = studentsIQ.OrderBy(s => s.LastName);
break;
}

Students = await studentsIQ.AsNoTracking().ToListAsync();

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:

Students = await studentsIQ.AsNoTracking().ToListAsync();

OnGetAsync could get verbose with a large number of sortable columns. For information about an alternative way
to code this functionality, see Use dynamic LINQ to simplify code in the MVC version of this tutorial series.
Add column heading hyperlinks to the Student Index page
Replace the code in Students/Index.cshtml, with the following code. The changes are highlighted.

@page
@model ContosoUniversity.Pages.Students.IndexModel

@{
ViewData["Title"] = "Students";
}

<h2>Students</h2>
<p>
<a asp-page="Create">Create New</a>
</p>

<table class="table">
<thead>
<tr>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.NameSort">
@Html.DisplayNameFor(model => model.Students[0].LastName)
</a>
</th>
<th>
@Html.DisplayNameFor(model => model.Students[0].FirstMidName)
</th>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.DateSort">
@Html.DisplayNameFor(model => model.Students[0].EnrollmentDate)
</a>
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Students)
{
<tr>
<td>
@Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
@Html.DisplayFor(modelItem => item.FirstMidName)
</td>
<td>
@Html.DisplayFor(modelItem => item.EnrollmentDate)
</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>
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.
Changes the page heading from Index to Students.
Changes Model.Student to Model.Students .

To verify that sorting works:

Run the app and select the Students tab.
Click the column headings.

Add filtering
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.
Update the OnGetAsync method
Replace the code in Students/Index.cshtml.cs with the following code to add filtering:
 using ContosoUniversity.Data;
using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Students
{
public class IndexModel : PageModel
{
private readonly SchoolContext _context;

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; }

public IList<Student> Students { get; set; }

public async Task OnGetAsync(string sortOrder, string searchString)

{
NameSort = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";
DateSort = sortOrder == "Date" ? "date_desc" : "Date";

CurrentFilter = searchString;

IQueryable<Student> studentsIQ = from s in _context.Students

select s;
if (!String.IsNullOrEmpty(searchString))
{
studentsIQ = studentsIQ.Where(s => s.LastName.Contains(searchString)
|| s.FirstMidName.Contains(searchString));
}

switch (sortOrder)
{
case "name_desc":
studentsIQ = studentsIQ.OrderByDescending(s => s.LastName);
break;
case "Date":
studentsIQ = studentsIQ.OrderBy(s => s.EnrollmentDate);
break;
case "date_desc":
studentsIQ = studentsIQ.OrderByDescending(s => s.EnrollmentDate);
break;
default:
studentsIQ = studentsIQ.OrderBy(s => s.LastName);
break;
}

Students = await studentsIQ.AsNoTracking().ToListAsync();

}
}
}

The preceding code:

Adds the searchString parameter to the OnGetAsync method, and saves the parameter value in the
 CurrentFilter property. The search string value is received from a text box that's added in the next section.
Adds 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.
IQueryable vs. IEnumerable
The 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. SQLite defaults to case-sensitive. 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 the filter is case-insensitive even if the Where method is called on an
IEnumerable or runs on SQLite.

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.
Calling Contains on an IQueryable is usually preferable for performance reasons. With IQueryable , the filtering is
done by the database server. If an IEnumerable is created first, all the rows have to be returned from the database
server.
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.
For more information, see How to use case-insensitive query with Sqlite provider.
Update the Razor page
Replace the code in Pages/Students/Index.cshtml to create a Search button and assorted chrome.
@page
@model ContosoUniversity.Pages.Students.IndexModel

@{
ViewData["Title"] = "Students";
}

<h2>Students</h2>

<p>
<a asp-page="Create">Create New</a>
</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-primary" /> |
<a asp-page="./Index">Back to full List</a>
</p>
</div>
</form>

<table class="table">
<thead>
<tr>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.NameSort">
@Html.DisplayNameFor(model => model.Students[0].LastName)
</a>
</th>
<th>
@Html.DisplayNameFor(model => model.Students[0].FirstMidName)
</th>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.DateSort">
@Html.DisplayNameFor(model => model.Students[0].EnrollmentDate)
</a>
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Students)
{
<tr>
<td>
@Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
@Html.DisplayFor(modelItem => item.FirstMidName)
</td>
<td>
@Html.DisplayFor(modelItem => item.EnrollmentDate)
</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>
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. If you're using SQLite, the filter is case-insensitive only if
you implemented the optional ToUpper code shown earlier.
Select Search.
Notice that the URL contains the search string. For example:

https://localhost:<port>/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
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.

Create the PaginatedList class

In the project folder, create PaginatedList.cs with the following code:
 using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.EntityFrameworkCore;

namespace ContosoUniversity
{
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 to the PageModel class
Replace the code in Students/Index.cshtml.cs to add paging.

using ContosoUniversity.Data;
using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Students
{
public class IndexModel : PageModel
{
private readonly SchoolContext _context;

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; }

public PaginatedList<Student> Students { get; set; }

public async Task OnGetAsync(string sortOrder,

string currentFilter, string searchString, int? pageIndex)
{
CurrentSort = sortOrder;
NameSort = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";
DateSort = sortOrder == "Date" ? "date_desc" : "Date";
if (searchString != null)
{
pageIndex = 1;
}
else
{
searchString = currentFilter;
}

CurrentFilter = searchString;

IQueryable<Student> studentsIQ = from s in _context.Students

select s;
if (!String.IsNullOrEmpty(searchString))
{
studentsIQ = studentsIQ.Where(s => s.LastName.Contains(searchString)
|| s.FirstMidName.Contains(searchString));
}
switch (sortOrder)
{
case "name_desc":
studentsIQ = studentsIQ.OrderByDescending(s => s.LastName);
break;
case "Date":
studentsIQ = studentsIQ.OrderBy(s => s.EnrollmentDate);
break;
case "date_desc":
studentsIQ = studentsIQ.OrderByDescending(s => s.EnrollmentDate);
break;
default:
studentsIQ = studentsIQ.OrderBy(s => s.LastName);
break;
}

int pageSize = 3;
Students = await PaginatedList<Student>.CreateAsync(
studentsIQ.AsNoTracking(), pageIndex ?? 1, pageSize);
}
}
}
 }

The preceding code:

Changes the type of the Students property from IList<Student> to PaginatedList<Student> .
Adds the page index, the current sortOrder , and the currentFilter to the OnGetAsync method signature.
Saves the sort order in the CurrentSort property.
Resets page index to 1 when there's a new search string.
Uses the PaginatedList class to get Student entities.

All the parameters that OnGetAsync receives 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.
The CurrentSort property 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.
The CurrentFilter property 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.

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.
The two question marks after pageIndex in the PaginatedList.CreateAsync call 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 Razor Page
Replace the code in Students/Index.cshtml with the following code. The changes are highlighted:

@page
@model ContosoUniversity.Pages.Students.IndexModel

@{
ViewData["Title"] = "Students";
}

<h2>Students</h2>

<p>
<a asp-page="Create">Create New</a>
</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-primary" /> |
<a asp-page="./Index">Back to full List</a>
 <a asp-page="./Index">Back to full List</a>
</p>
</div>
</form>

<table class="table">
<thead>
<tr>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.NameSort"
asp-route-currentFilter="@Model.CurrentFilter">
@Html.DisplayNameFor(model => model.Students[0].LastName)
</a>
</th>
<th>
@Html.DisplayNameFor(model => model.Students[0].FirstMidName)
</th>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.DateSort"
asp-route-currentFilter="@Model.CurrentFilter">
@Html.DisplayNameFor(model => model.Students[0].EnrollmentDate)
</a>
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Students)
{
<tr>
<td>
@Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
@Html.DisplayFor(modelItem => item.FirstMidName)
</td>
<td>
@Html.DisplayFor(modelItem => item.EnrollmentDate)
</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>

@{
var prevDisabled = !Model.Students.HasPreviousPage ? "disabled" : "";
var nextDisabled = !Model.Students.HasNextPage ? "disabled" : "";
}

<a asp-page="./Index"
asp-route-sortOrder="@Model.CurrentSort"
asp-route-pageIndex="@(Model.Students.PageIndex - 1)"
asp-route-currentFilter="@Model.CurrentFilter"
class="btn btn-primary @prevDisabled">
Previous
</a>
<a asp-page="./Index"
asp-route-sortOrder="@Model.CurrentSort"
asp-route-pageIndex="@(Model.Students.PageIndex + 1)"
asp-route-currentFilter="@Model.CurrentFilter"
class="btn btn-primary @nextDisabled">
Next
</a>
The column header links use the query string to pass the current search string to the OnGetAsync method:

<a asp-page="./Index" asp-route-sortOrder="@Model.NameSort"

asp-route-currentFilter="@Model.CurrentFilter">
@Html.DisplayNameFor(model => model.Students[0].LastName)
</a>

The paging buttons are displayed by tag helpers:

<a asp-page="./Index"
asp-route-sortOrder="@Model.CurrentSort"
asp-route-pageIndex="@(Model.Students.PageIndex - 1)"
asp-route-currentFilter="@Model.CurrentFilter"
class="btn btn-primary @prevDisabled">
Previous
</a>
<a asp-page="./Index"
asp-route-sortOrder="@Model.CurrentSort"
asp-route-pageIndex="@(Model.Students.PageIndex + 1)"
asp-route-currentFilter="@Model.CurrentFilter"
class="btn btn-primary @nextDisabled">
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.

Add grouping
This section creates an About page that displays 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 Models/SchoolViewModels folder.
Create SchoolViewModels/EnrollmentDateGroup.cs with the following code:

using System;
using System.ComponentModel.DataAnnotations;

namespace ContosoUniversity.Models.SchoolViewModels
{
public class EnrollmentDateGroup
{
[DataType(DataType.Date)]
public DateTime? EnrollmentDate { get; set; }

public int StudentCount { get; set; }

}
}

Create the Razor Page

Create a 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>

@foreach (var item in Model.Students)

{
<tr>
<td>
@Html.DisplayFor(modelItem => item.EnrollmentDate)
</td>
<td>
@item.StudentCount
</td>
</tr>
}
</table>

Create the page model

Create a Pages/About.cshtml.cs file with the following code:
 using ContosoUniversity.Models.SchoolViewModels;
using ContosoUniversity.Data;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using ContosoUniversity.Models;

namespace ContosoUniversity.Pages
{
public class AboutModel : PageModel
{
private readonly SchoolContext _context;

public AboutModel(SchoolContext context)

{
_context = context;
}

public IList<EnrollmentDateGroup> Students { get; set; }

public async Task OnGetAsync()

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

Students = 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.
Run the app and navigate to the About page. The count of students for each enrollment date is displayed in a table.
Next steps
In the next tutorial, the app uses migrations to update the data model.

P R E V IO U S NEXT
T U T O R IA L T U T O R IA L

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 class IndexModel : PageModel

{
private readonly SchoolContext _context;

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:
 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 following code contains the C# conditional ?: operator:

NameSort = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";

DateSort = sortOrder == "Date" ? "date_desc" : "Date";

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:
 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();

}

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:

Student = await studentIQ.AsNoTracking().ToListAsync();

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

@{
ViewData["Title"] = "Index";
}

<h2>Index</h2>
<p>
<a asp-page="Create">Create New</a>
</p>

<table class="table">
<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>
<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>

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 Students/Index.cshtml.cs, set a breakpoint on switch (sortOrder) .
Add a watch for NameSort and DateSort .
In Students/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
Update the Students/Index.cshtml.cs OnGetAsync with the following code:

public async Task OnGetAsync(string sortOrder, string searchString)

{
NameSort = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";
DateSort = sortOrder == "Date" ? "date_desc" : "Date";
CurrentFilter = searchString;

IQueryable<Student> studentIQ = from s in _context.Student

select s;
if (!String.IsNullOrEmpty(searchString))
{
studentIQ = studentIQ.Where(s => s.LastName.Contains(searchString)
|| s.FirstMidName.Contains(searchString));
}

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:

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 penalty:
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
@model ContosoUniversity.Pages.Students.IndexModel

@{
ViewData["Title"] = "Index";
}

<h2>Index</h2>

<p>
<a asp-page="Create">Create New</a>
</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>

<table class="table">

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.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.EntityFrameworkCore;

namespace ContosoUniversity
{
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; }

Update the Students/Index.cshtml.cs OnGetAsync with the following code:

public async Task OnGetAsync(string sortOrder,

string currentFilter, string searchString, int? pageIndex)
{
CurrentSort = sortOrder;
NameSort = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";
DateSort = sortOrder == "Date" ? "date_desc" : "Date";
if (searchString != null)
{
pageIndex = 1;
}
else
{
searchString = currentFilter;
}

CurrentFilter = searchString;

IQueryable<Student> studentIQ = from s in _context.Student

select s;
if (!String.IsNullOrEmpty(searchString))
{
studentIQ = studentIQ.Where(s => s.LastName.Contains(searchString)
|| s.FirstMidName.Contains(searchString));
}
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;
}

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.

if (searchString != null)
{
pageIndex = 1;
}
else
{
searchString = currentFilter;
}

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
@model ContosoUniversity.Pages.Students.IndexModel

@{
ViewData["Title"] = "Index";
}

<h2>Index</h2>

<p>
<a asp-page="Create">Create New</a>
</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>

<table class="table">
<thead>
<tr>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.NameSort"
asp-route-currentFilter="@Model.CurrentFilter">
 asp-route-currentFilter="@Model.CurrentFilter">
@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"
asp-route-currentFilter="@Model.CurrentFilter">
@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>
<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>

@{
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>
<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 @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"

asp-route-currentFilter="@Model.CurrentFilter">
@Html.DisplayNameFor(model => model.Student[0].LastName)
</a>
The paging buttons are displayed by tag helpers:

<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>
<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 @nextDisabled">
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 Students/Index.cshtml.cs, set a breakpoint on switch (sortOrder) .
Add a watch for NameSort , DateSort , CurrentSort , and Model.Student.PageIndex .
In Students/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;
using System.ComponentModel.DataAnnotations;

namespace ContosoUniversity.Models.SchoolViewModels
{
public class EnrollmentDateGroup
{
[DataType(DataType.Date)]
public DateTime? EnrollmentDate { get; set; }

public int StudentCount { get; set; }

}
}

Update the About page model

The web templates in ASP.NET Core 2.2 do not include the About page. If you are using ASP.NET Core 2.2, create
the About Razor Page.
Update the Pages/About.cshtml.cs file with the following code:
 using ContosoUniversity.Models.SchoolViewModels;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using ContosoUniversity.Models;

namespace ContosoUniversity.Pages
{
public class AboutModel : PageModel
{
private readonly SchoolContext _context;

public AboutModel(SchoolContext context)

{
_context = context;
}

public IList<EnrollmentDateGroup> Student { get; set; }

public async Task OnGetAsync()

{
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>

@foreach (var item in Model.Student)

{
<tr>
<td>
@Html.DisplayFor(modelItem => item.EnrollmentDate)
</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.

Additional resources
Debugging ASP.NET Core 2.x source
YouTube version of this tutorial
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
8/9/2019 • 11 minutes to read • Edit Online

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.
If you run into problems you can't solve, download the completed app and compare that code to what you created
by following the tutorial.
This tutorial introduces the EF Core migrations feature for managing data model changes.
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 series started by configuring the Entity Framework to create the
database if it doesn't exist. Each time the data model changes, you have to drop the database. The next time the app
runs, the call to EnsureCreated re-creates the database to match the new data model. The DbInitializer class then
runs to seed the new database.
This approach to keeping the database 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 database 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 database schema instead of creating a new database.
Rather than dropping and recreating the database when the data model changes, migrations updates the schema
and retains existing data.

NOTE
SQLite limitations
This tutorial uses the Entity Framework Core migrations feature where possible. Migrations updates the database schema to
match changes in the data model. However, migrations only does the kinds of changes that the database engine supports,
and SQLite's schema change capabilities are limited. For example, adding a column is supported, but removing a column is
not supported. If a migration is created to remove a column, the ef migrations add command succeeds but the
ef database update command fails.

The workaround for the SQLite limitations is to manually write migrations code to perform a table rebuild when something in
the table changes. The code would go in the Up and Down methods for a migration and would involve:
Creating a new table.
Copying data from the old table to the new table.
Dropping the old table.
Renaming the new table.
Writing database-specific code of this type is outside the scope of this tutorial. Instead, this tutorial drops and re-creates the
database whenever an attempt to apply a migration would fail. For more information, see the following resources:
SQLite EF Core Database Provider Limitations
Customize migration code
Data seeding
SQLite ALTER TABLE statement
Drop the database
Visual Studio
Visual Studio Code
Use SQL Server Object Explorer (SSOX) to delete the database, or run the following command in the Package
Manager Console (PMC ):

Drop-Database

Create an initial migration

Visual Studio
Visual Studio Code
Run the following commands in the PMC:

Add-Migration InitialCreate
Update-Database

Up and Down methods

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

using System;
using Microsoft.EntityFrameworkCore.Metadata;
using Microsoft.EntityFrameworkCore.Migrations;

namespace ContosoUniversity.Migrations
{
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);
});

migrationBuilder.CreateTable(
name: "Student",
columns: table => new
{
ID = table.Column<int>(nullable: false)
.Annotation("SqlServer:ValueGenerationStrategy",
SqlServerValueGenerationStrategy.IdentityColumn),
LastName = table.Column<string>(nullable: true),
FirstMidName = table.Column<string>(nullable: true),
 EnrollmentDate = table.Column<DateTime>(nullable: false)
},
constraints: table =>
{
table.PrimaryKey("PK_Student", x => x.ID);
});

migrationBuilder.CreateTable(
name: "Enrollment",
columns: table => new
{
EnrollmentID = table.Column<int>(nullable: false)
.Annotation("SqlServer:ValueGenerationStrategy",
SqlServerValueGenerationStrategy.IdentityColumn),
CourseID = table.Column<int>(nullable: false),
StudentID = table.Column<int>(nullable: false),
Grade = table.Column<int>(nullable: true)
},
constraints: table =>
{
table.PrimaryKey("PK_Enrollment", x => x.EnrollmentID);
table.ForeignKey(
name: "FK_Enrollment_Course_CourseID",
column: x => x.CourseID,
principalTable: "Course",
principalColumn: "CourseID",
onDelete: ReferentialAction.Cascade);
table.ForeignKey(
name: "FK_Enrollment_Student_StudentID",
column: x => x.StudentID,
principalTable: "Student",
principalColumn: "ID",
onDelete: ReferentialAction.Cascade);
});

migrationBuilder.CreateIndex(
name: "IX_Enrollment_CourseID",
table: "Enrollment",
column: "CourseID");

migrationBuilder.CreateIndex(
name: "IX_Enrollment_StudentID",
table: "Enrollment",
column: "StudentID");
}

protected override void Down(MigrationBuilder migrationBuilder)

{
migrationBuilder.DropTable(
name: "Enrollment");

migrationBuilder.DropTable(
name: "Course");

migrationBuilder.DropTable(
name: "Student");
}
}
}

The preceding code is for the initial migration. The code:

Was generated by the migrations add InitialCreate command.
Is executed by the database update command.
Creates a database for the data model specified by the database context class.
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."

The migrations history table

Use SSOX or your SQLite tool to inspect the database.
Notice the addition of an __EFMigrationsHistory table. The __EFMigrationsHistory table keeps track of which
migrations have been applied to the database.
View the data in the __EFMigrationsHistory table. It shows one row for the first migration.

The data model snapshot

Migrations creates a snapshot of the current data model in Migrations/SchoolContextModelSnapshot.cs. When you
add a migration, EF determines what changed by comparing the current data model to the snapshot file.
Because the snapshot file tracks the state of the data model, you can't delete a migration by deleting the
<timestamp>_<migrationname>.cs file. To back out the most recent migration, you have to use the migrations remove
command. That command deletes the migration and ensures the snapshot is correctly reset. For more information,
see dotnet ef migrations remove.

Remove EnsureCreated
This tutorial series started by using EnsureCreated . EnsureCreated doesn't create a migrations history table and so
can't be used with migrations. It's designed for testing or rapid prototyping where the database is dropped and re-
created frequently.
From this point forward, the tutorials will use migrations.
In Data/DBInitializer.cs, comment out the following line:

context.Database.EnsureCreated();

Run the app and verify that the database is seeded.

Applying migrations in production

We recommend that production apps not call Database.Migrate at application startup. Migrate shouldn't be called
from an app that is deployed to a server farm. If the app is scaled out to multiple server instances, it's hard to
ensure database schema updates don't happen from multiple servers or conflict with read/write access.
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.

Troubleshooting
If the app uses SQL Server LocalDB and displays the following exception:

SqlException: Cannot open database "ContosoUniversity" requested by the login.

The login failed.
Login failed for user 'user name'.
The solution may be to run dotnet ef database update at a command prompt.
Additional resources
EF Core CLI.
Package Manager Console (Visual Studio)

Next steps
The next tutorial builds out the data model, adding entity properties and new entities.

P R E V IO U S NEXT
T U T O R IA L T U T O R IA L

In this tutorial, the EF Core migrations feature for managing data model changes is used.
If you run into problems you can't solve, download the completed app.
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
Visual Studio Code
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
Visual Studio Code
 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);
});

migrationBuilder.CreateTable(
protected override void Down(MigrationBuilder migrationBuilder)
{
migrationBuilder.DropTable(
name: "Enrollment");

migrationBuilder.DropTable(
name: "Course");

migrationBuilder.DropTable(
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
Visual Studio Code
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 EnsureCreated :

context.Database.EnsureCreated();

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.
Login failed for user 'user name'.

Solution: Run dotnet ef database update

Additional resources
YouTube version of this tutorial
.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
8/9/2019 • 56 minutes to read • Edit Online

By Tom Dykstra 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.
If you run into problems you can't solve, download the completed app and compare that code to what you created
by following the tutorial.
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 completed data model is shown in the following illustration:
The Student entity

Replace the code in Models/Student.cs with the following code:

using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
[Required]
[StringLength(50)]
[Display(Name = "Last Name")]
public string LastName { get; set; }
[Required]
[StringLength(50, ErrorMessage = "First name cannot be longer than 50 characters.")]
[Column("FirstName")]
[Display(Name = "First Name")]
public string FirstMidName { get; set; }
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Enrollment Date")]
public DateTime EnrollmentDate { get; set; }
[Display(Name = "Full Name")]
public string FullName
{
get
{
return LastName + ", " + FirstMidName;
}
}

public ICollection<Enrollment> Enrollments { get; set; }

}
}

The preceding code adds a FullName property and adds the following attributes to existing properties:
[DataType]
[DisplayFormat]
[StringLength]
[Column]
[Required]
[Display]

The FullName calculated property

FullName is a calculated property that returns a value that's created by concatenating two other properties.
FullName can't be set, so it has only a get accessor. No FullName column is created in the database.
The DataType attribute

[DataType(DataType.Date)]

For student enrollment dates, all of the pages currently display the time of day along with the date, although only
the date is relevant. By using data annotation attributes, you can make one code change that will fix the display
format in every page that shows the data.
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. The DataType attributes don't
provide validation.
The DisplayFormat attribute

[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]

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 DisplayFormat attribute is used to explicitly specify the date format. 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 DisplayFormat attribute 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, and client-side input validation.
By default, the browser renders data using the correct format based on the locale.
For more information, see the <input> Tag Helper documentation.
The StringLength attribute

[StringLength(50, ErrorMessage = "First name cannot be longer than 50 characters.")]

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 code shown limits
names to no more than 50 characters. An example that sets the minimum string length is shown later.
The StringLength attribute also provides client-side and server-side validation. The minimum value has no impact
on the database schema.
The StringLength attribute doesn't prevent a user from entering white space for a name. The RegularExpression
attribute can be 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:
 [RegularExpression(@"^[A-Z]+[a-zA-Z""'\s-]*$")]

Visual Studio
Visual Studio Code
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) . When a
migration is created and applied later in this tutorial, the name fields become nvarchar(50) as a result of the string
length attributes.
The Column attribute

[Column("FirstName")]
public string FirstMidName { get; set; }

Attributes can control how classes and properties are mapped to the database. In the Student model, the Column
attribute is used to map the name of the FirstMidName property to "FirstName" in the database.
When the database 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.
With the [Column] attribute, Student.FirstMidName in the data model 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. That discrepancy will be resolved by adding a
migration later in this tutorial.
The Required attribute

[Required]

The Required attribute makes the name properties required fields. The Required attribute isn't needed for non-
nullable types such as value types (for example, DateTime , int , and double ). 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:
 [Display(Name = "Last Name")]
[StringLength(50, MinimumLength=1)]
public string LastName { get; set; }

The Display attribute

[Display(Name = "Last Name")]

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."
Create a migration
Run the app and go to the Students page. An exception is thrown. The [Column] attribute causes EF to expect to
find a column named FirstName , but the column name in the database is still FirstMidName .
Visual Studio
Visual Studio Code
The error message is similar to the following example:

SqlException: Invalid column name 'FirstName'.

In the PMC, enter the following commands to create a new migration and update the database:

Add-Migration ColumnFirstName
Update-Database

The first of these commands 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
database had more than 50 characters, the 51 to last character would be lost.
Open the Student table in SSOX:
 Before the 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 .

Run the app and go to the Students page.

Notice that times are not input or displayed along with dates.
Select Create New, and try to enter a name longer than 50 characters.

NOTE
In the following sections, building the app at some stages generates compiler errors. The instructions specify when to build
the app.

The Instructor Entity

Create Models/Instructor.cs with the following code:

 using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Instructor
{
public int ID { get; set; }

[Required]
[Display(Name = "Last Name")]
[StringLength(50)]
public string LastName { get; set; }

[Required]
[Column("FirstName")]
[Display(Name = "First Name")]
[StringLength(50)]
public string FirstMidName { get; set; }

[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Hire Date")]
public DateTime HireDate { get; set; }

[Display(Name = "Full Name")]

public string FullName
{
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)]

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.

public ICollection<CourseAssignment> CourseAssignments { get; set; }

An instructor can have at most one office, so the OfficeAssignment property holds a single OfficeAssignment entity.
OfficeAssignment is null if no office is assigned.

public OfficeAssignment OfficeAssignment { get; set; }

The OfficeAssignment entity

Create Models/OfficeAssignment.cs with the following code:

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
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]
public int InstructorID { get; set; }

By default, EF Core treats the key as non-database-generated because the column is for an identifying relationship.
The Instructor navigation property
The Instructor.OfficeAssignment navigation property can be null because there might not be an OfficeAssignment
row for a given instructor. An instructor might not have an office assignment.
The OfficeAssignment.Instructor navigation property will always have an instructor entity because the foreign key
InstructorID -
type is int , a non nullable value type. 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 Course Entity

Update Models/Course.cs with the following code:

using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Course
{
[DatabaseGenerated(DatabaseGeneratedOption.None)]
[Display(Name = "Number")]
public int CourseID { get; set; }

[StringLength(50, MinimumLength = 3)]

public string Title { get; set; }

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

public int DepartmentID { get; set; }

public Department Department { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }
public ICollection<CourseAssignment> CourseAssignments { 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 foreign key 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. However, explicitly including 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 property 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.
 [DatabaseGenerated(DatabaseGeneratedOption.None)]
[Display(Name = "Number")]
public int CourseID { get; set; }

By default, EF Core assumes that PK values are generated by the database. Database-generated 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 database 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.

public int DepartmentID { get; set; }

public Department Department { get; set; }

A course can have any number of students enrolled in it, so the Enrollments navigation property is a collection:

public ICollection<Enrollment> Enrollments { get; set; }

A course may be taught by multiple instructors, so the CourseAssignments navigation property is a collection:

public ICollection<CourseAssignment> CourseAssignments { get; set; }

CourseAssignment is explained later.

The Department entity

Create Models/Department.cs with the following code:

 using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Department
{
public int DepartmentID { get; set; }

[StringLength(50, MinimumLength = 3)]

public string Name { get; set; }

[DataType(DataType.Currency)]
[Column(TypeName = "money")]
public decimal Budget { get; set; }

[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[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; }
}
}

The Column attribute

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 database:

[Column(TypeName="money")]
public decimal Budget { get; set; }

Column mapping is generally not required. EF Core 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.
Foreign key and navigation properties
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:

public int? InstructorID { get; set; }

public Instructor Administrator { get; set; }

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:
 public ICollection<Course> Courses { get; set; }

By convention, EF Core enables cascade delete for non-nullable FKs and for many-to-many relationships. This
default behavior can result in circular cascade delete rules. Circular cascade delete rules cause an exception when a
migration is added.
For example, if the Department.InstructorID property was defined as non-nullable, EF Core would configure a
cascade delete rule. In that case, the department would be deleted when the instructor assigned as its administrator
is deleted. In this scenario, a restrict rule would make more sense. The following fluent API would set a restrict rule
and disable cascade delete.

modelBuilder.Entity<Department>()
.HasOne(d => d.Administrator)
.WithMany()
.OnDelete(DeleteBehavior.Restrict)

The Enrollment entity

An enrollment record is for one course taken by one student.

Update Models/Enrollment.cs with the following code:

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
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; }
[DisplayFormat(NullDisplayText = "No grade")]
public Grade? Grade { get; set; }

public Course Course { get; set; }

public Student Student { get; set; }
}
}

Foreign key and navigation properties

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:

public int CourseID { get; set; }

public Course Course { get; set; }

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

public int StudentID { get; set; }

public Student Student { get; set; }

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:

namespace ContosoUniversity.Models
{
public class CourseAssignment
{
public int InstructorID { get; set; }
public int CourseID { get; set; }
public Instructor Instructor { get; set; }
public Course Course { get; set; }
}
}

The Instructor-to-Courses many-to-many relationship requires a join table, and the entity for that join table is
CourseAssignment.

It's common to name a join entity EntityName1EntityName2 . For example, the Instructor-to-Courses join table using
this pattern would be CourseInstructor . However, we recommend using a name that describes the relationship.
Data models start out simple and grow. Join tables without payload (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
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 that:
Multiple rows are allowed for one course.
Multiple rows are allowed for one instructor.
Multiple rows aren't allowed for the same instructor and course.
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 database context

Update Data/SchoolContext.cs with the following code:

using ContosoUniversity.Models;
using Microsoft.EntityFrameworkCore;

namespace ContosoUniversity.Data
{
public class SchoolContext : DbContext
{
public SchoolContext(DbContextOptions<SchoolContext> options) : base(options)
{
}

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

public DbSet<Enrollment> Enrollments { get; set; }
public DbSet<Student> Students { 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:

protected override void OnModelCreating(ModelBuilder modelBuilder)

{
modelBuilder.Entity<Blog>()
.Property(b => b.Url)
.IsRequired();
}

In this tutorial, the fluent API is used only for database 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 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
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 database

Update the code in Data/DbInitializer.cs:

using System;
using System.Linq;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using ContosoUniversity.Models;

namespace ContosoUniversity.Data
{
public static class DbInitializer
{
public static void Initialize(SchoolContext context)
{
//context.Database.EnsureCreated();
// Look for any students.
if (context.Students.Any())
{
return; // DB has been seeded
}

var students = new Student[]

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

foreach (Student s in students)

{
context.Students.Add(s);
}
context.SaveChanges();

var instructors = new Instructor[]

{
new Instructor { FirstMidName = "Kim", LastName = "Abercrombie",
HireDate = DateTime.Parse("1995-03-11") },
new Instructor { FirstMidName = "Fadi", LastName = "Fakhouri",
HireDate = DateTime.Parse("2002-07-06") },
new Instructor { FirstMidName = "Roger", LastName = "Harui",
HireDate = DateTime.Parse("1998-07-01") },
new Instructor { FirstMidName = "Candace", LastName = "Kapoor",
HireDate = DateTime.Parse("2001-01-15") },
new Instructor { FirstMidName = "Roger", LastName = "Zheng",
HireDate = DateTime.Parse("2004-02-12") }
};

foreach (Instructor i in instructors)

{
context.Instructors.Add(i);
}
context.SaveChanges();

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,
StartDate = DateTime.Parse("2007-09-01"),
InstructorID = instructors.Single( i => i.LastName == "Fakhouri").ID },
new Department { Name = "Engineering", Budget = 350000,
StartDate = DateTime.Parse("2007-09-01"),
InstructorID = instructors.Single( i => i.LastName == "Harui").ID },
new Department { Name = "Economics", Budget = 100000,
StartDate = DateTime.Parse("2007-09-01"),
InstructorID = instructors.Single( i => i.LastName == "Kapoor").ID }
};

foreach (Department d in departments)

foreach (Department d in departments)
{
context.Departments.Add(d);
}
context.SaveChanges();

var courses = new Course[]

{
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,
DepartmentID = departments.Single( s => s.Name == "Economics").DepartmentID
},
new Course {CourseID = 1045, Title = "Calculus", Credits = 4,
DepartmentID = departments.Single( s => s.Name == "Mathematics").DepartmentID
},
new Course {CourseID = 3141, Title = "Trigonometry", Credits = 4,
DepartmentID = departments.Single( s => s.Name == "Mathematics").DepartmentID
},
new Course {CourseID = 2021, Title = "Composition", Credits = 3,
DepartmentID = departments.Single( s => s.Name == "English").DepartmentID
},
new Course {CourseID = 2042, Title = "Literature", Credits = 4,
DepartmentID = departments.Single( s => s.Name == "English").DepartmentID
},
};

foreach (Course c in courses)

{
context.Courses.Add(c);
}
context.SaveChanges();

var officeAssignments = new OfficeAssignment[]

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

foreach (OfficeAssignment o in officeAssignments)

{
context.OfficeAssignments.Add(o);
}
context.SaveChanges();

var courseInstructors = new CourseAssignment[]

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

foreach (CourseAssignment ci in courseInstructors)

{
context.CourseAssignments.Add(ci);
}
context.SaveChanges();

var enrollments = new Enrollment[]

{
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alexander").ID,
CourseID = courses.Single(c => c.Title == "Chemistry" ).CourseID,
Grade = Grade.A
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alexander").ID,
CourseID = courses.Single(c => c.Title == "Microeconomics" ).CourseID,
Grade = Grade.C
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alexander").ID,
CourseID = courses.Single(c => c.Title == "Macroeconomics" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alonso").ID,
CourseID = courses.Single(c => c.Title == "Calculus" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alonso").ID,
CourseID = courses.Single(c => c.Title == "Trigonometry" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alonso").ID,
CourseID = courses.Single(c => c.Title == "Composition" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Anand").ID,
CourseID = courses.Single(c => c.Title == "Chemistry" ).CourseID
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Anand").ID,
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
}
};

foreach (Enrollment e in enrollments)

{
var enrollmentInDataBase = context.Enrollments.Where(
s =>
s.Student.ID == e.StudentID &&
s.Course.CourseID == e.CourseID).SingleOrDefault();
if (enrollmentInDataBase == null)
{
context.Enrollments.Add(e);
}
}
context.SaveChanges();
}
}
}

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. See Enrollments and CourseAssignments for examples of how
many-to-many join tables can be seeded.

Add a migration
Build the project.
Visual Studio
Visual Studio Code
In PMC, run the following command.

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.
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'.
In the next section, you see what to do about this error.

Apply the migration or drop and re-create

Now that you have an existing database, you need to think about how to apply changes to it. This tutorial shows
two alternatives:
Drop and re-create the database. Choose this section if you're using SQLite.
Apply the migration to the existing database. The instructions in this section work for SQL Server only, not for
SQLite.
Either choice works for SQL Server. While the apply-migration method is more complex and time-consuming, it's
the preferred approach for real-world, production environments.

Drop and re-create the database

Skip this section if you're using SQL Server and want to do the apply-migration approach in the following section.
To force EF Core to create a new database, drop and update the database:
Visual Studio
Visual Studio Code
In the Package Manager Console (PMC ), run the following command:

Drop-Database

Delete the Migrations folder, then run the following command:

Add-Migration InitialCreate
Update-Database

Run the app. Running the app runs the DbInitializer.Initialize method. The DbInitializer.Initialize
populates the new database.
Visual Studio
Visual Studio Code
Open the database 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.

Apply the migration

This section is optional. These steps work only for SQL Server LocalDB and only if you skipped the preceding Drop
and re-create the database section.
When migrations are run with existing data, there may be FK constraints that are not satisfied with the existing
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 preceding Drop and re-create the database section.
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 database 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
In the ComplexDataModel migration class, update the 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:
[!code-csharp[](intro/samples/cu30snapshots/5-complex/Migrations/ ComplexDataModel.cs?
name=snippet_CreateDefaultValue&highlight=23-31)]
With the preceding changes, existing Course rows will be related to the "Temp" department after the
ComplexDataModel.Up method runs.

The way of handling the situation shown here is simplified for this tutorial. 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 .

Visual Studio
Visual Studio Code
In the Package Manager Console (PMC ), run the following command:

Update-Database

Because the DbInitializer.Initialize method is designed to work only with an empty database, use SSOX to
delete all the rows in the Student and Course tables. (Cascade delete will take care of the Enrollment table.)
Run the app. Running the app runs the DbInitializer.Initialize method. The DbInitializer.Initialize
populates the new database.

Next steps
The next two tutorials show how to read and update related data.
 P R E V IO U S NEXT
T U T O R IA L T U T O R IA L

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 are shown in the following illustration:

If you run into problems you can't solve, download the completed app.

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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
public string LastName { get; set; }
public string FirstMidName { get; set; }
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
public DateTime EnrollmentDate { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }

}
}

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 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 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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
[StringLength(50)]
public string LastName { get; set; }
[StringLength(50, ErrorMessage = "First name cannot be longer than 50 characters.")]
public string FirstMidName { get; set; }
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
public DateTime EnrollmentDate { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }

}
}

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:
 [RegularExpression(@"^[A-Z]+[a-zA-Z""'\s-]*$")]

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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
[StringLength(50)]
public string LastName { get; set; }
[StringLength(50, ErrorMessage = "First name cannot be longer than 50 characters.")]
[Column("FirstName")]
public string FirstMidName { get; set; }
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
public DateTime EnrollmentDate { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }

}
}

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
Visual Studio Code

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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
[Required]
[StringLength(50)]
[Display(Name = "Last Name")]
public string LastName { get; set; }
[Required]
[StringLength(50, ErrorMessage = "First name cannot be longer than 50 characters.")]
[Column("FirstName")]
[Display(Name = "First Name")]
public string FirstMidName { get; set; }
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Enrollment Date")]
public DateTime EnrollmentDate { get; set; }
[Display(Name = "Full Name")]
public string FullName
{
get
{
return LastName + ", " + FirstMidName;
}
}

public ICollection<Enrollment> Enrollments { get; set; }

}
}

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:

[Display(Name = "Last Name")]

[StringLength(50, MinimumLength=1)]
public string LastName { get; set; }

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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Instructor
{
public int ID { get; set; }

[Required]
[Display(Name = "Last Name")]
[StringLength(50)]
public string LastName { get; set; }

[Required]
[Column("FirstName")]
[Display(Name = "First Name")]
[StringLength(50)]
public string FirstMidName { get; set; }

[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Hire Date")]
public DateTime HireDate { get; set; }

[Display(Name = "Full Name")]

public string FullName
{
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.
 public ICollection<CourseAssignment> CourseAssignments { get; set; }

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.

public OfficeAssignment OfficeAssignment { get; set; }

Create the OfficeAssignment entity

Create Models/OfficeAssignment.cs with the following code:

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
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]
public int InstructorID { get; set; }

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]
public Instructor Instructor { get; set; }

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:

 using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Course
{
[DatabaseGenerated(DatabaseGeneratedOption.None)]
[Display(Name = "Number")]
public int CourseID { get; set; }

[StringLength(50, MinimumLength = 3)]

public string Title { get; set; }

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

public int DepartmentID { get; set; }

public Department Department { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }
public ICollection<CourseAssignment> CourseAssignments { 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.

[DatabaseGenerated(DatabaseGeneratedOption.None)]
[Display(Name = "Number")]
public int CourseID { get; set; }

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.

public int DepartmentID { get; set; }

public Department Department { get; set; }

A course can have any number of students enrolled in it, so the Enrollments navigation property is a collection:

public ICollection<Enrollment> Enrollments { get; set; }

A course may be taught by multiple instructors, so the CourseAssignments navigation property is a collection:

public ICollection<CourseAssignment> CourseAssignments { get; set; }

CourseAssignment is explained later.

Create the Department entity

Create Models/Department.cs with the following code:

 using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Department
{
public int DepartmentID { get; set; }

[StringLength(50, MinimumLength = 3)]

public string Name { get; set; }

[DataType(DataType.Currency)]
[Column(TypeName = "money")]
public decimal Budget { get; set; }

[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[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; }
}
}

The Column attribute

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")]
public decimal Budget { get; set; }

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.
Foreign key and navigation properties
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:

public int? InstructorID { get; set; }

public Instructor Administrator { get; set; }

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:
 public ICollection<Course> Courses { get; set; }

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 was defined as non-nullable:
EF Core configures a cascade delete rule to delete the department when the instructor is deleted.
Deleting the department when the instructor is deleted isn't the intended behavior.
The following fluent API would set a restrict rule instead of cascade.

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:

 using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
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; }
[DisplayFormat(NullDisplayText = "No grade")]
public Grade? Grade { get; set; }

public Course Course { get; set; }

public Student Student { get; set; }
}
}

Foreign key and navigation properties

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:

public int CourseID { get; set; }

public Course Course { get; set; }

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

public int StudentID { get; set; }

public Student Student { get; set; }

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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class CourseAssignment
{
public int InstructorID { get; set; }
public int CourseID { get; set; }
public Instructor Instructor { get; set; }
public Course Course { get; set; }
}
}

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:

using ContosoUniversity.Models;
using Microsoft.EntityFrameworkCore;

namespace ContosoUniversity.Models
{
public class SchoolContext : DbContext
{
public SchoolContext(DbContextOptions<SchoolContext> options) : base(options)
{
}

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

public DbSet<Enrollment> Enrollment { get; set; }
public DbSet<Student> Student { 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:

protected override void OnModelCreating(ModelBuilder modelBuilder)

{
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;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using ContosoUniversity.Models;

namespace ContosoUniversity.Data
{
public static class DbInitializer
{
public static void Initialize(SchoolContext context)
{
//context.Database.EnsureCreated();
// Look for any students.
if (context.Student.Any())
{
return; // DB has been seeded
}

var students = new Student[]

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

foreach (Student s in students)

{
context.Student.Add(s);
}
context.SaveChanges();

var instructors = new Instructor[]

{
new Instructor { FirstMidName = "Kim", LastName = "Abercrombie",
HireDate = DateTime.Parse("1995-03-11") },
new Instructor { FirstMidName = "Fadi", LastName = "Fakhouri",
HireDate = DateTime.Parse("2002-07-06") },
new Instructor { FirstMidName = "Roger", LastName = "Harui",
HireDate = DateTime.Parse("1998-07-01") },
new Instructor { FirstMidName = "Candace", LastName = "Kapoor",
HireDate = DateTime.Parse("2001-01-15") },
new Instructor { FirstMidName = "Roger", LastName = "Zheng",
HireDate = DateTime.Parse("2004-02-12") }
};

foreach (Instructor i in instructors)

{
context.Instructors.Add(i);
}
context.SaveChanges();

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,
StartDate = DateTime.Parse("2007-09-01"),
InstructorID = instructors.Single( i => i.LastName == "Fakhouri").ID },
new Department { Name = "Engineering", Budget = 350000,
StartDate = DateTime.Parse("2007-09-01"),
InstructorID = instructors.Single( i => i.LastName == "Harui").ID },
new Department { Name = "Economics", Budget = 100000,
StartDate = DateTime.Parse("2007-09-01"),
InstructorID = instructors.Single( i => i.LastName == "Kapoor").ID }
};

foreach (Department d in departments)

foreach (Department d in departments)
{
context.Departments.Add(d);
}
context.SaveChanges();

var courses = new Course[]

{
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,
DepartmentID = departments.Single( s => s.Name == "Economics").DepartmentID
},
new Course {CourseID = 1045, Title = "Calculus", Credits = 4,
DepartmentID = departments.Single( s => s.Name == "Mathematics").DepartmentID
},
new Course {CourseID = 3141, Title = "Trigonometry", Credits = 4,
DepartmentID = departments.Single( s => s.Name == "Mathematics").DepartmentID
},
new Course {CourseID = 2021, Title = "Composition", Credits = 3,
DepartmentID = departments.Single( s => s.Name == "English").DepartmentID
},
new Course {CourseID = 2042, Title = "Literature", Credits = 4,
DepartmentID = departments.Single( s => s.Name == "English").DepartmentID
},
};

foreach (Course c in courses)

{
context.Courses.Add(c);
}
context.SaveChanges();

var officeAssignments = new OfficeAssignment[]

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

foreach (OfficeAssignment o in officeAssignments)

{
context.OfficeAssignments.Add(o);
}
context.SaveChanges();

var courseInstructors = new CourseAssignment[]

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

foreach (CourseAssignment ci in courseInstructors)

{
context.CourseAssignments.Add(ci);
}
context.SaveChanges();

var enrollments = new Enrollment[]

{
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alexander").ID,
CourseID = courses.Single(c => c.Title == "Chemistry" ).CourseID,
Grade = Grade.A
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alexander").ID,
CourseID = courses.Single(c => c.Title == "Microeconomics" ).CourseID,
Grade = Grade.C
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alexander").ID,
CourseID = courses.Single(c => c.Title == "Macroeconomics" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alonso").ID,
CourseID = courses.Single(c => c.Title == "Calculus" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alonso").ID,
CourseID = courses.Single(c => c.Title == "Trigonometry" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alonso").ID,
CourseID = courses.Single(c => c.Title == "Composition" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Anand").ID,
CourseID = courses.Single(c => c.Title == "Chemistry" ).CourseID
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Anand").ID,
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
}
};

foreach (Enrollment e in enrollments)

{
var enrollmentInDataBase = context.Enrollment.Where(
s =>
s.Student.ID == e.StudentID &&
s.Course.CourseID == e.CourseID).SingleOrDefault();
if (enrollmentInDataBase == null)
{
context.Enrollment.Add(e);
}
}
context.SaveChanges();
}
}
}

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. See Enrollments and CourseAssignments for examples of how
many-to-many join tables can be seeded.

Add a migration
Build the project.
Visual Studio
Visual Studio Code

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'.
Apply the migration
Now that you have an existing database, you need to think about how to apply future changes to it. This tutorial
shows two approaches:
Drop and re-create the database
Apply the migration to the existing database. While this method is more complex and time-consuming, it's the
preferred approach for real-world, production environments. Note: This is an optional section of the tutorial.
You can do the drop and re-create steps and skip this section. If you do want to follow the steps in this section,
don't do the drop and re-create steps.
Drop and re -create 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
Visual Studio Code
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.
Apply the migration to the existing database
This section is optional. These steps work only if you skipped the preceding Drop and re-create the database
section.
When migrations are run with existing data, there may be FK constraints that are not satisfied with the existing
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:

migrationBuilder.CreateTable(
name: "Department",
columns: table => new
{
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)
},
constraints: table =>
{
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.

migrationBuilder.AddColumn<int>(
name: "DepartmentID",
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.

Additional resources
YouTube version of this tutorial(Part 1)
YouTube version of this tutorial(Part 2)
P R E V IO U S NEXT
 Razor Pages with EF Core in ASP.NET Core - Read
Related Data - 6 of 8
8/9/2019 • 28 minutes to read • Edit Online

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.
If you run into problems you can't solve, download the completed app and compare that code to what you created
by following the tutorial.
This tutorial shows how to read and display related data. Related data is data that EF Core loads into navigation
properties.
The following illustrations show the completed pages for this tutorial:
Eager, explicit, and lazy loading
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 an
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 a giant 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 explicit 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
database. With explicit loading, the code specifies the navigation properties to be loaded. Use the Load
method to do explicit loading. For example:

Lazy loading. Lazy loading was added to EF Core in version 2.1. 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 database each time a navigation property is accessed for the
first time.

Create Course pages

The Course entity includes a navigation property that contains the related Department entity.
To display the name of the assigned department for a course:
Load the related Department entity into the Course.Department navigation property.
Get the name from the Department entity's Name property.
Scaffold Course pages
Visual Studio
Visual Studio Code
Follow the instructions in Scaffold Student pages with the following exceptions:
Create a Pages/Courses folder.
Use Course for the model class.
Use the existing context class instead of creating a new one.
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.
Display the department name
Update Pages/Courses/Index.cshtml.cs with the following code:
 using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Collections.Generic;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Courses
{
public class IndexModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public IndexModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

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

public async Task OnGetAsync()

{
Courses = await _context.Courses
.Include(c => c.Department)
.AsNoTracking()
.ToListAsync();
}
}
}

The preceding code changes the Course property to Courses and adds AsNoTracking . AsNoTracking improves
performance because the entities returned are not tracked. The entities don't need to be tracked because they're not
updated in the current context.
Update Pages/Courses/Index.cshtml with the following code.
 @page
@model ContosoUniversity.Pages.Courses.IndexModel

@{
ViewData["Title"] = "Courses";
}

<h1>Courses</h1>

<p>
<a asp-page="Create">Create New</a>
</p>
<table class="table">
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.Courses[0].CourseID)
</th>
<th>
@Html.DisplayNameFor(model => model.Courses[0].Title)
</th>
<th>
@Html.DisplayNameFor(model => model.Courses[0].Credits)
</th>
<th>
@Html.DisplayNameFor(model => model.Courses[0].Department)
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Courses)
{
<tr>
<td>
@Html.DisplayFor(modelItem => item.CourseID)
</td>
<td>
@Html.DisplayFor(modelItem => item.Title)
</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 Course property name 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:

@Html.DisplayFor(modelItem => item.Department.Name)

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. The Select method is an alternative that
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; }

public async Task OnGetAsync()

{
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 int CourseID { get; set; }
public string Title { get; set; }
public int Credits { get; set; }
public string DepartmentName { get; set; }
}

See IndexSelect.cshtml and IndexSelect.cshtml.cs for a complete example.

Create Instructor pages

This section scaffolds Instructor pages and adds related Courses and Enrollments to the Instructors Index page.

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, 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, 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
The instructors page shows data from three different tables. A view model is needed that includes three properties
representing the three tables.
Create SchoolViewModels/InstructorIndexData.cs with the following code:
 using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Models.SchoolViewModels
{
public class InstructorIndexData
{
public IEnumerable<Instructor> Instructors { get; set; }
public IEnumerable<Course> Courses { get; set; }
public IEnumerable<Enrollment> Enrollments { get; set; }
}
}

Scaffold Instructor pages

Visual Studio
Visual Studio Code
Follow the instructions in Scaffold the student pages with the following exceptions:
Create a Pages/Instructors folder.
Use Instructor for the model class.
Use the existing context class instead of creating a new one.
To see what the scaffolded page looks like before you update it, run the app and navigate to the Instructors page.
Update Pages/Instructors/Index.cshtml.cs with the following code:
 using ContosoUniversity.Models;
using ContosoUniversity.Models.SchoolViewModels; // Add VM
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Instructors
{
public class IndexModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public IndexModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

public InstructorIndexData InstructorData { get; set; }

public int InstructorID { get; set; }
public int CourseID { get; set; }

public async Task OnGetAsync(int? id, int? courseID)

{
InstructorData = new InstructorIndexData();
InstructorData.Instructors = await _context.Instructors
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.AsNoTracking()
.OrderBy(i => i.LastName)
.ToListAsync();

if (id != null)
{
InstructorID = id.Value;
Instructor instructor = InstructorData.Instructors
.Where(i => i.ID == id.Value).Single();
InstructorData.Courses = instructor.CourseAssignments.Select(s => s.Course);
}

if (courseID != null)
{
CourseID = courseID.Value;
var selectedCourse = InstructorData.Courses
.Where(x => x.CourseID == courseID).Single();
InstructorData.Enrollments = selectedCourse.Enrollments;
}
}
}
}

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:
 InstructorData.Instructors = await _context.Instructors
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.AsNoTracking()
.OrderBy(i => i.LastName)
.ToListAsync();

The code specifies eager loading for the following navigation properties:
Instructor.OfficeAssignment
Instructor.CourseAssignments
CourseAssignments.Course
Course.Department
Course.Enrollments
Enrollment.Student

Notice the repetition of Include and ThenInclude methods for CourseAssignments and Course . This repetition is
necessary to specify eager loading for two navigation properties of the Course entity.
The following code executes when an instructor is selected ( id != null ).

if (id != null)
{
InstructorID = id.Value;
Instructor instructor = InstructorData.Instructors
.Where(i => i.ID == id.Value).Single();
InstructorData.Courses = instructor.CourseAssignments.Select(s => s.Course);
}

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.
The Where method returns a collection. But in this case, the filter will select a single entity. so the Single method is
called to convert 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.
The following code populates the view model's Enrollments property when a course is selected:

if (courseID != null)
{
CourseID = courseID.Value;
var selectedCourse = InstructorData.Courses
.Where(x => x.CourseID == courseID).Single();
InstructorData.Enrollments = selectedCourse.Enrollments;
}

Update the instructors Index page

Update Pages/Instructors/Index.cshtml with the following code.

@page "{id:int?}"
@model ContosoUniversity.Pages.Instructors.IndexModel

@{
ViewData["Title"] = "Instructors";
}

<h2>Instructors</h2>

<p>
<a asp-page="Create">Create New</a>
</p>
<table class="table">
<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.InstructorData.Instructors)
{
string selectedRow = "";
if (item.ID == Model.InstructorID)
{
selectedRow = "table-success";
}
<tr class="@selectedRow">
<td>
@Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
@Html.DisplayFor(modelItem => item.FirstMidName)
</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> |
<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>

@if (Model.InstructorData.Courses != null)

{
<h3>Courses Taught by Selected Instructor</h3>
<table class="table">
<tr>
<th></th>
<th>Number</th>
<th>Title</th>
<th>Department</th>
</tr>

@foreach (var item in Model.InstructorData.Courses)

{
string selectedRow = "";
if (item.CourseID == Model.CourseID)
{
selectedRow = "table-success";
}
<tr class="@selectedRow">
<td>
 <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>
}

@if (Model.InstructorData.Enrollments != null)

{
<h3>
Students Enrolled in Selected Course
</h3>
<table class="table">
<tr>
<th>Name</th>
<th>Grade</th>
</tr>
@foreach (var item in Model.InstructorData.Enrollments)
{
<tr>
<td>
@item.Student.FullName
</td>
<td>
@Html.DisplayFor(modelItem => item.Grade)
</td>
</tr>
}
</table>
}

The preceding code 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:
https://localhost:5001/Instructors?id=2

When the page directive is @page "{id:int?}" , the URL is:

https://localhost:5001/Instructors/2

Adds 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.

@if (item.OfficeAssignment != null)

{
@item.OfficeAssignment.Location
}

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

string selectedRow = "";

if (item.CourseID == Model.CourseID)
{
selectedRow = "success";
}
<tr class="@selectedRow">

Adds 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> |

Adds a table of courses for the selected Instructor.

Adds a table of student enrollments for the selected course.
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 for an instructor. The row style changes and courses assigned to that instructor are
displayed.
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:
 public async Task OnGetAsync(int? id, int? courseID)
{
Instructor = new InstructorIndexData();

Instructor.Instructors = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.AsNoTracking()
.OrderBy(i => i.LastName)
.ToListAsync();

if (id != null)
{
InstructorID = id.Value;
Instructor instructor = Instructor.Instructors.Single(
i => i.ID == id.Value);
InstructorData.Courses = instructor.CourseAssignments.Select(
s => s.Course);
}

if (courseID != null)
{
CourseID = courseID.Value;
Instructor.Enrollments = InstructorData.Courses.Single(
x => x.CourseID == courseID).Enrollments;
}
}

Use of Single with a Where condition is a matter of personal preference. It provides no benefits over using the
Where method.

Explicit loading
The current code specifies eager loading for Enrollments and Students :

InstructorData.Instructors = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.AsNoTracking()
.OrderBy(i => i.LastName)
.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 Pages/Instructors/Index.cshtml.cs with the following code.
 using ContosoUniversity.Models;
using ContosoUniversity.Models.SchoolViewModels; // Add VM
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Instructors
{
public class IndexModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public IndexModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

public InstructorIndexData InstructorData { get; set; }

public int InstructorID { get; set; }
public int CourseID { get; set; }

public async Task OnGetAsync(int? id, int? courseID)

{
InstructorData = new InstructorIndexData();
InstructorData.Instructors = await _context.Instructors
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
//.Include(i => i.CourseAssignments)
// .ThenInclude(i => i.Course)
// .ThenInclude(i => i.Enrollments)
// .ThenInclude(i => i.Student)
//.AsNoTracking()
.OrderBy(i => i.LastName)
.ToListAsync();

if (id != null)
{
InstructorID = id.Value;
Instructor instructor = InstructorData.Instructors
.Where(i => i.ID == id.Value).Single();
InstructorData.Courses = instructor.CourseAssignments.Select(s => s.Course);
}

if (courseID != null)
{
CourseID = courseID.Value;
var selectedCourse = InstructorData.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();
}
InstructorData.Enrollments = selectedCourse.Enrollments;
}
}
}
}

The preceding code drops the ThenInclude method calls for enrollment and student data. If a course is selected, the
explicit loading code retrieves:
The Enrollment entities for the selected course.
 The Student entities for each Enrollment .
Notice that the preceding code comments out .AsNoTracking() . Navigation properties can only be explicitly loaded
for tracked entities.
Test the app. From a user's perspective, the app behaves identically to the previous version.

Next steps
The next tutorial shows how to update related data.

P R E V IO U S NEXT
T U T O R IA L T U T O R IA L

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 explicit 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. Lazy loading was added to EF Core in version 2.1. 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 Course 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
Visual Studio Code
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.
Update the OnGetAsync method with the following code:

public async Task OnGetAsync()

{
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="Create">Create New</a>
</p>
<table class="table">
<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>
@Html.DisplayFor(modelItem => item.Title)
</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:
 @Html.DisplayFor(modelItem => item.Department.Name)

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:

public async Task OnGetAsync()

{
Course = await _context.Courses
.Include(c => c.Department)
.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; }

public async Task OnGetAsync()

{
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 int CourseID { get; set; }
public string Title { get; set; }
public int Credits { get; set; }
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.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Models.SchoolViewModels
{
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
Visual Studio Code
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;
using ContosoUniversity.Models.SchoolViewModels; // Add VM
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Instructors
{
public class IndexModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public IndexModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

public InstructorIndexData Instructor { get; set; }

public int InstructorID { 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:

Instructor.Instructors = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.AsNoTracking()
.OrderBy(i => i.LastName)
.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>
<a asp-page="Create">Create New</a>
</p>
<table class="table">
<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>
@Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
@Html.DisplayFor(modelItem => item.FirstMidName)
</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> |
<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>
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.

@if (item.OfficeAssignment != null)

{
@item.OfficeAssignment.Location
}

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.

string selectedRow = "";

if (item.CourseID == Model.CourseID)
{
selectedRow = "success";
}
<tr class="@selectedRow">

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)
{
Instructor = new InstructorIndexData();
Instructor.Instructors = await _context.Instructors
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.AsNoTracking()
.OrderBy(i => i.LastName)
.ToListAsync();

if (id != null)
{
InstructorID = id.Value;
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 class IndexModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public IndexModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

public InstructorIndexData Instructor { get; set; }

public int InstructorID { get; set; }
public int CourseID { get; set; }

public async Task OnGetAsync(int? id, int? courseID)

{
Instructor = new InstructorIndexData();
Instructor.Instructors = await _context.Instructors
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.AsNoTracking()
.OrderBy(i => i.LastName)
.ToListAsync();

if (id != null)
{
InstructorID = id.Value;
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;
}
}

Examine the updated query:

Instructor.Instructors = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.AsNoTracking()
.OrderBy(i => i.LastName)
.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)
{
InstructorID = id.Value;
Instructor instructor = Instructor.Instructors.Where(
i => i.ID == id.Value).Single();
Instructor.Courses = instructor.CourseAssignments.Select(s => s.Course);
}

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:

if (courseID != null)
{
CourseID = courseID.Value;
Instructor.Enrollments = Instructor.Courses.Where(
x => x.CourseID == courseID).Single().Enrollments;
}

Add the following markup to the end of the Pages/Instructors/Index.cshtml Razor Page:
 <a asp-page="./Delete" asp-route-id="@item.ID">Delete</a>
</td>
</tr>
}
</tbody>
</table>

@if (Model.Instructor.Courses != null)

{
<h3>Courses Taught by Selected Instructor</h3>
<table class="table">
<tr>
<th></th>
<th>Number</th>
<th>Title</th>
<th>Department</th>
</tr>

@foreach (var item in Model.Instructor.Courses)

{
string selectedRow = "";
if (item.CourseID == Model.CourseID)
{
selectedRow = "success";
}
<tr class="@selectedRow">
<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:
 Instructor.Instructors = await _context.Instructors
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.AsNoTracking()
.OrderBy(i => i.LastName)
.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>
<table class="table">
<tr>
<th>Name</th>
<th>Grade</th>
</tr>
@foreach (var item in Model.Instructor.Enrollments)
{
<tr>
<td>
@item.Student.FullName
</td>
<td>
@Html.DisplayFor(modelItem => item.Grade)
</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:
 public async Task OnGetAsync(int? id, int? courseID)
{
Instructor = new InstructorIndexData();

Instructor.Instructors = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.AsNoTracking()
.OrderBy(i => i.LastName)
.ToListAsync();

if (id != null)
{
InstructorID = id.Value;
Instructor instructor = Instructor.Instructors.Single(
i => i.ID == id.Value);
Instructor.Courses = instructor.CourseAssignments.Select(
s => s.Course);
}

if (courseID != null)
{
CourseID = courseID.Value;
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 :

Instructor.Instructors = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.AsNoTracking()
.OrderBy(i => i.LastName)
.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:
 public async Task OnGetAsync(int? id, int? courseID)
{
Instructor = new InstructorIndexData();
Instructor.Instructors = await _context.Instructors
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
//.Include(i => i.CourseAssignments)
// .ThenInclude(i => i.Course)
// .ThenInclude(i => i.Enrollments)
// .ThenInclude(i => i.Student)
// .AsNoTracking()
.OrderBy(i => i.LastName)
.ToListAsync();

if (id != null)
{
InstructorID = id.Value;
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;
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.

Additional resources
YouTube version of this tutorial (part1)
YouTube version of this tutorial (part2)

P R E V IO U S NEXT
 Razor Pages with EF Core in ASP.NET Core - Update
Related Data - 7 of 8
8/13/2019 • 32 minutes to read • Edit Online

By Tom Dykstra, 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.
If you run into problems you can't solve, download the completed app and compare that code to what you created
by following the tutorial.
This tutorial shows how to update related data. The following illustrations show some of the completed pages.
Update the Course Create and Edit pages
The scaffolded code for the Course Create and Edit pages has a Department drop-down list that shows Department
ID (an integer). The drop-down should show the Department name, so both of these pages need a list of
department names. To provide that list, use a base class for the Create and Edit pages.
Create a base class for Course Create and Edit
Create a Pages/Courses/DepartmentNamePageModel.cs file with the following code:
 using ContosoUniversity.Data;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.AspNetCore.Mvc.Rendering;
using Microsoft.EntityFrameworkCore;
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 .
Update the Course Create page model
A Course is assigned to a Department. The base class for the Create and Edit pages provides a SelectList for
selecting the department. The drop-down list that uses the SelectList sets the Course.DepartmentID foreign key
(FK) property. EF Core uses the Course.DepartmentID FK to load the Department navigation property.
Update Pages/Courses/Create.cshtml.cs with the following code:
 using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Courses
{
public class CreateModel : DepartmentNamePageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public CreateModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

public IActionResult OnGet()

{
PopulateDepartmentsDropDownList(_context);
return Page();
}

[BindProperty]
public Course Course { get; set; }

public async Task<IActionResult> OnPostAsync()

{
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);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}

// Select DepartmentID if TryUpdateModelAsync fails.

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

The preceding code:

Derives from DepartmentNamePageModel .
Uses TryUpdateModelAsync to prevent overposting.
Removes ViewData["DepartmentID"] . DepartmentNameSL from the base class is a strongly typed model and will be
used by the Razor page. Strongly typed models are preferred over weakly typed. For more information, see
Weakly typed data (ViewData and ViewBag).
Update the Course Create Razor page
Update Pages/Courses/Create.cshtml with the following code:
 @page
@model ContosoUniversity.Pages.Courses.CreateModel
@{
ViewData["Title"] = "Create Course";
}
<h2>Create</h2>
<h4>Course</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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 class="form-group">
<input type="submit" value="Create" class="btn btn-primary" />
</div>
</form>
</div>
</div>
<div>
<a asp-page="Index">Back to List</a>
</div>
@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

The preceding code makes the following changes:

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" in the drop-down when no
department has been selected yet, rather than the first department.
Adds a validation message when the department isn't selected.
The Razor Page uses the Select Tag Helper:
 <div class="form-group">
<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>

Test the Create page. The Create page displays the department name rather than the department ID.
Update the Course Edit page model
Update Pages/Courses/Edit.cshtml.cs with the following code:

using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Courses
{
public class EditModel : DepartmentNamePageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public EditModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Course Course { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Course = await _context.Courses

.Include(c => c.Department).FirstOrDefaultAsync(m => m.CourseID == id);

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

// Select current DepartmentID.

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

public async Task<IActionResult> OnPostAsync(int? id)

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

var courseToUpdate = await _context.Courses.FindAsync(id);

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

if (await TryUpdateModelAsync<Course>(
courseToUpdate,
"course", // Prefix for form value.
c => c.Credits, c => c.DepartmentID, c => c.Title))
{
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}

// 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 selects that department in the drop-down list.

Update the Course Edit Razor page

Update Pages/Courses/Edit.cshtml with the following code:
 @page
@model ContosoUniversity.Pages.Courses.EditModel

@{
ViewData["Title"] = "Edit";
}

<h2>Edit</h2>

<h4>Course</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<input type="hidden" asp-for="Course.CourseID" />
<div class="form-group">
<label asp-for="Course.CourseID" class="control-label"></label>
<div>@Html.DisplayFor(model => model.Course.CourseID)</div>
</div>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<label asp-for="Course.Department" class="control-label"></label>
<select asp-for="Course.DepartmentID" class="form-control"
asp-items="@Model.DepartmentNameSL"></select>
<span asp-validation-for="Course.DepartmentID" class="text-danger"></span>
</div>
<div class="form-group">
<input type="submit" value="Save" class="btn btn-primary" />
</div>
</form>
</div>
</div>

<div>
<a asp-page="./Index">Back to List</a>
</div>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

The preceding code makes the following changes:

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 for the Department drop-down 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.

Update the Course Details and Delete pages

AsNoTracking can improve performance when tracking isn't required.
Update the Course page models
Update Pages/Courses/Delete.cshtml.cs with the following code to add AsNoTracking :

using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Courses
{
public class DeleteModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public DeleteModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Course Course { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Course = await _context.Courses

.AsNoTracking()
.Include(c => c.Department)
.FirstOrDefaultAsync(m => m.CourseID == id);

if (Course == null)
{
return NotFound();
}
return Page();
}

public async Task<IActionResult> OnPostAsync(int? id)

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

Course = await _context.Courses.FindAsync(id);

if (Course != null)
{
_context.Courses.Remove(Course);
await _context.SaveChangesAsync();
}

return RedirectToPage("./Index");
}
}
}

Make the same change in the Pages/Courses/Details.cshtml.cs file:

 using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Courses
{
public class DetailsModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public DetailsModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

public Course Course { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Course = await _context.Courses

.AsNoTracking()
.Include(c => c.Department)
.FirstOrDefaultAsync(m => m.CourseID == id);

if (Course == null)
{
return NotFound();
}
return Page();
}
#endregion
}
}

Update the Course Razor pages

Update Pages/Courses/Delete.cshtml with the following code:
 @page
@model ContosoUniversity.Pages.Courses.DeleteModel

@{
ViewData["Title"] = "Delete";
}

<h2>Delete</h2>

<h3>Are you sure you want to delete this?</h3>

<div>
<h4>Course</h4>
<hr />
<dl class="row">
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Course.CourseID)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Course.CourseID)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Course.Title)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Course.Title)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Course.Credits)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Course.Credits)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Course.Department)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Course.Department.Name)
</dd>
</dl>

<form method="post">
<input type="hidden" asp-for="Course.CourseID" />
<input type="submit" value="Delete" class="btn btn-danger" /> |
<a asp-page="./Index">Back to List</a>
</form>
</div>

Make the same changes to the Details page.

 @page
@model ContosoUniversity.Pages.Courses.DetailsModel

@{
ViewData["Title"] = "Details";
}

<h2>Details</h2>

<div>
<h4>Course</h4>
<hr />
<dl class="row">
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Course.CourseID)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Course.CourseID)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Course.Title)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Course.Title)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Course.Credits)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Course.Credits)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Course.Department)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Course.Department.Name)
</dd>
</dl>
</div>
<div>
<a asp-page="./Edit" asp-route-id="@Model.Course.CourseID">Edit</a> |
<a asp-page="./Index">Back to List</a>
</div>

Test the Course pages

Test the create, edit, details, and delete pages.

Update the instructor Create and Edit pages

Instructors may teach any number of courses. The following image shows the instructor Edit page with an array of
course checkboxes.
The checkboxes enable changes to courses an instructor is assigned to. A checkbox is displayed for every course in
the database. Courses that the instructor is assigned to are selected. The user can select or clear checkboxes to
change course assignments. If the number of courses were much greater, a different UI might work better. But the
method of managing a many-to-many relationship shown here wouldn't change. To create or delete relationships,
you manipulate a join entity.
Create a class for assigned courses data
Create SchoolViewModels/AssignedCourseData.cs with the following code:

namespace ContosoUniversity.Models.SchoolViewModels
{
public class AssignedCourseData
{
public int CourseID { get; set; }
public string Title { get; set; }
public bool Assigned { get; set; }
}
}

The AssignedCourseData class contains data to create the check boxes for courses assigned to an instructor.
Create an Instructor page model base class
Create the Pages/Instructors/InstructorCoursesPageModel.cs base class:

using ContosoUniversity.Data;
using ContosoUniversity.Models;
using ContosoUniversity.Models.SchoolViewModels;
using Microsoft.AspNetCore.Mvc.RazorPages;
using System.Collections.Generic;
using System.Linq;

namespace ContosoUniversity.Pages.Instructors
{
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);
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 for
efficient lookups.
Since the Razor page 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:

if (selectedCourses == null)
{
instructorToUpdate.CourseAssignments = new List<CourseAssignment>();
return;
}

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 page. 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.

if (selectedCoursesHS.Contains(course.CourseID.ToString()))
{
if (!instructorCourses.Contains(course.CourseID))
{
instructorToUpdate.CourseAssignments.Add(
new CourseAssignment
{
InstructorID = instructorToUpdate.ID,
CourseID = course.CourseID
});
}
}

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.

else
{
if (instructorCourses.Contains(course.CourseID))
{
CourseAssignment courseToRemove
= instructorToUpdate
.CourseAssignments
.SingleOrDefault(i => i.CourseID == course.CourseID);
context.Remove(courseToRemove);
}
}

Handle office location

Another relationship the edit page has to handle is the one-to-zero-or-one relationship that the Instructor entity
has with the OfficeAssignment entity. The instructor edit code must handle the following scenarios:
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 Instructor Edit page model
Update Pages/Instructors/Edit.cshtml.cs with the following code:

using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using System;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Instructors
{
public class EditModel : InstructorCoursesPageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public EditModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Instructor Instructor { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Instructor = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments).ThenInclude(i => i.Course)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.ID == id);

if (Instructor == null)
{
return NotFound();
}
PopulateAssignedCourseData(_context, Instructor);
return Page();
}

public async Task<IActionResult> OnPostAsync(int? id, string[] selectedCourses)

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

var instructorToUpdate = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.FirstOrDefaultAsync(s => s.ID == id);

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

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;
}
UpdateInstructorCourses(_context, selectedCourses, instructorToUpdate);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
UpdateInstructorCourses(_context, selectedCourses, instructorToUpdate);
PopulateAssignedCourseData(_context, instructorToUpdate);
return Page();
}
}
}

The preceding code:

Gets the current Instructor entity from the database using eager loading for the OfficeAssignment ,
CourseAssignment , and CourseAssignment.Course navigation properties.
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.
Calls PopulateAssignedCourseData in OnGetAsync to provide information for the checkboxes using the
AssignedCourseData view model class.
Calls UpdateInstructorCourses in OnPostAsync to apply information from the checkboxes to the Instructor entity
being edited.
Calls PopulateAssignedCourseData and UpdateInstructorCourses in OnPostAsync if TryUpdateModel fails. These
method calls restore the assigned course data entered on the page when it is redisplayed with an error message.
Update the Instructor Edit Razor page
Update Pages/Instructors/Edit.cshtml with the following code:

@page
@model ContosoUniversity.Pages.Instructors.EditModel
@{
ViewData["Title"] = "Edit";
}
<h2>Edit</h2>
<h4>Instructor</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<input type="hidden" asp-for="Instructor.ID" />
<div class="form-group">
<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>
<div class="form-group">
<label asp-for="Instructor.FirstMidName" class="control-label"></label>
 <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>
<div class="form-group">
<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>
<div class="form-group">
<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 class="form-group">
<div class="table">
<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 class="form-group">
<input type="submit" value="Save" class="btn btn-primary" />
</div>
</form>
</div>
</div>

<div>
<a asp-page="./Index">Back to List</a>
</div>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

The preceding code creates an HTML table that has three columns. Each column has a checkbox and a caption
containing the course number and title. The checkboxes 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 checkbox is set to
CourseID . When the page is posted, the model binder passes an array that consists of the CourseID values for only
the checkboxes that are selected.
When the checkboxes are initially rendered, courses assigned to the instructor are selected.
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.
Run the app and test the updated Instructors Edit page. Change some course assignments. The changes are
reflected on the Index page.
Update the Instructor Create page
Update the Instructor Create page model and Razor page with code similar to the Edit page:
using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Instructors
{
public class CreateModel : InstructorCoursesPageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public CreateModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

public IActionResult OnGet()

{
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);
return Page();
}

[BindProperty]
public Instructor Instructor { get; set; }

public async Task<IActionResult> OnPostAsync(string[] selectedCourses)

{
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);
}
}

if (await TryUpdateModelAsync<Instructor>(
newInstructor,
"Instructor",
i => i.FirstMidName, i => i.LastName,
i => i.HireDate, i => i.OfficeAssignment))
{
_context.Instructors.Add(newInstructor);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
PopulateAssignedCourseData(_context, newInstructor);
return Page();
}
}
}

@page
@model ContosoUniversity.Pages.Instructors.CreateModel
@{
ViewData["Title"] = "Create";
}

<h2>Create</h2>

<h4>Instructor</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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 class="form-group">
<div class="table">
<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 class="form-group">
<input type="submit" value="Create" class="btn btn-primary" />
</div>
</form>
</div>
</div>

<div>
<a asp-page="Index">Back to List</a>
</div>
 @section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

Test the instructor Create page.

Update the Instructor Delete page

Update Pages/Instructors/Delete.cshtml.cs with the following code:
using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Instructors
{
public class DeleteModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public DeleteModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Instructor Instructor { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Instructor = await _context.Instructors.FirstOrDefaultAsync(m => m.ID == id);

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

public async Task<IActionResult> OnPostAsync(int? id)

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

Instructor instructor = await _context.Instructors

.Include(i => i.CourseAssignments)
.SingleAsync(i => i.ID == id);

if (instructor == null)
{
return RedirectToPage("./Index");
}

var departments = await _context.Departments

.Where(d => d.InstructorID == id)
.ToListAsync();
departments.ForEach(d => d.InstructorID = null);

_context.Instructors.Remove(instructor);

await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
}
}
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.
Run the app and test the Delete page.

Next steps

P R E V IO U S NEXT
T U T O R IA L T U T O R IA L

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 ContosoUniversity.Data;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.AspNetCore.Mvc.Rendering;
using Microsoft.EntityFrameworkCore;
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:
 using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Courses
{
public class CreateModel : DepartmentNamePageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public CreateModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

public IActionResult OnGet()

{
PopulateDepartmentsDropDownList(_context);
return Page();
}

[BindProperty]
public Course Course { get; set; }

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
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);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}

// 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 code:
 @page
@model ContosoUniversity.Pages.Courses.CreateModel
@{
ViewData["Title"] = "Create Course";
}
<h2>Create</h2>
<h4>Course</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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 class="form-group">
<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");}
}

The preceding markup makes the following changes:

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:
 <div class="form-group">
<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>

Test the Create page. The Create page displays the department name rather than the department ID.
Update the Courses Edit page.
Replace the code in Pages/Courses/Edit.cshtml.cs with the following code:
 using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Courses
{
public class EditModel : DepartmentNamePageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public EditModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Course Course { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Course = await _context.Courses

.Include(c => c.Department).FirstOrDefaultAsync(m => m.CourseID == id);

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

// Select current DepartmentID.

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

public async Task<IActionResult> OnPostAsync(int? id)

{
if (!ModelState.IsValid)
{
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))
{
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}

// 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

@{
ViewData["Title"] = "Edit";
}

<h2>Edit</h2>

<h4>Course</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<input type="hidden" asp-for="Course.CourseID" />
<div class="form-group">
<label asp-for="Course.CourseID" class="control-label"></label>
<div>@Html.DisplayFor(model => model.Course.CourseID)</div>
</div>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<label asp-for="Course.Department" class="control-label"></label>
<select asp-for="Course.DepartmentID" class="form-control"
asp-items="@Model.DepartmentNameSL"></select>
<span asp-validation-for="Course.DepartmentID" class="text-danger"></span>
</div>
<div class="form-group">
<input type="submit" value="Save" class="btn btn-default" />
</div>
</form>
</div>
</div>

<div>
<a asp-page="./Index">Back to List</a>
</div>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

The preceding markup makes the following changes:

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 class DeleteModel : PageModel

{
private readonly ContosoUniversity.Data.SchoolContext _context;

public DeleteModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Course Course { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Course = await _context.Courses

.AsNoTracking()
.Include(c => c.Department)
.FirstOrDefaultAsync(m => m.CourseID == id);

if (Course == null)
{
return NotFound();
}
return Page();
}

public async Task<IActionResult> OnPostAsync(int? id)

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

Course = await _context.Courses

.AsNoTracking()
.FirstOrDefaultAsync(m => m.CourseID == id);

if (Course != null)
{
_context.Courses.Remove(Course);
await _context.SaveChangesAsync();
}

return RedirectToPage("./Index");
}
}

Update the OnGetAsync method in the Pages/Courses/Details.cshtml.cs file:

 public async Task<IActionResult> OnGetAsync(int? id)
{
if (id == null)
{
return NotFound();
}

Course = await _context.Courses

.AsNoTracking()
.Include(c => c.Department)
.FirstOrDefaultAsync(m => m.CourseID == id);

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

@{
ViewData["Title"] = "Delete";
}

<h2>Delete</h2>

<h3>Are you sure you want to delete this?</h3>

<div>
<h4>Course</h4>
<hr />
<dl class="dl-horizontal">
<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>

<form method="post">
<input type="hidden" asp-for="Course.CourseID" />
<input type="submit" value="Delete" class="btn btn-default" /> |
<a asp-page="./Index">Back to List</a>
</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:

public class EditModel : PageModel

{
private readonly ContosoUniversity.Data.SchoolContext _context;

public EditModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Instructor Instructor { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Instructor = await _context.Instructors

.Include(i => i.OfficeAssignment)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.ID == id);

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

public async Task<IActionResult> OnPostAsync(int? id)

{
if (!ModelState.IsValid)
{
return Page();
}

var instructorToUpdate = await _context.Instructors

.Include(i => i.OfficeAssignment)
.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;
}
await _context.SaveChangesAsync();
}
return RedirectToPage("./Index");

}
}

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
@{
ViewData["Title"] = "Edit";
}
<h2>Edit</h2>
<h4>Instructor</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<input type="hidden" asp-for="Instructor.ID" />
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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 class="form-group">
<input type="submit" value="Save" class="btn btn-default" />
</div>
</form>
</div>
</div>

<div>
<a asp-page="./Index">Back to List</a>
</div>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

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:

namespace ContosoUniversity.Models.SchoolViewModels
{
public class AssignedCourseData
{
public int CourseID { get; set; }
public string Title { get; set; }
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 ContosoUniversity.Data;
using ContosoUniversity.Models;
using ContosoUniversity.Models.SchoolViewModels;
using Microsoft.AspNetCore.Mvc.RazorPages;
using System.Collections.Generic;
using System.Linq;

namespace ContosoUniversity.Pages.Instructors
{
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
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public EditModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Instructor Instructor { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Instructor = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments).ThenInclude(i => i.Course)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.ID == id);

if (Instructor == null)
{
return NotFound();
}
PopulateAssignedCourseData(_context, Instructor);
return Page();
}

public async Task<IActionResult> OnPostAsync(int? id, string[] selectedCourses)

{
if (!ModelState.IsValid)
{
return Page();
}

var instructorToUpdate = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.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;
}
UpdateInstructorCourses(_context, selectedCourses, instructorToUpdate);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
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
@{
ViewData["Title"] = "Edit";
}
<h2>Edit</h2>
<h4>Instructor</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<input type="hidden" asp-for="Instructor.ID" />
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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 class="form-group">
<div class="col-md-offset-2 col-md-10">
<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 class="form-group">
<input type="submit" value="Save" class="btn btn-default" />
</div>
</form>
</div>
 </div>
</div>

<div>
<a asp-page="./Index">Back to List</a>
</div>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

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:

using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Instructors
{
public class CreateModel : InstructorCoursesPageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public CreateModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

public IActionResult OnGet()

{
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 Instructor Instructor { get; set; }

public async Task<IActionResult> OnPostAsync(string[] selectedCourses)

{
if (!ModelState.IsValid)
{
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);
}
}

if (await TryUpdateModelAsync<Instructor>(
newInstructor,
"Instructor",
i => i.FirstMidName, i => i.LastName,
i => i.HireDate, i => i.OfficeAssignment))
{
_context.Instructors.Add(newInstructor);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
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

@{
ViewData["Title"] = "Create";
}

<h2>Create</h2>

<h4>Instructor</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<div class="form-group">
<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>
 </div>
<div class="form-group">
<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>
<div class="form-group">
<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>

<div class="form-group">
<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 class="form-group">
<div class="col-md-offset-2 col-md-10">
<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 class="form-group">
<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");}
}

Test the instructor Create page.

Update the Delete page

Update the Delete page model with the following code:
 using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Instructors
{
public class DeleteModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public DeleteModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Instructor Instructor { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Instructor = await _context.Instructors.SingleAsync(m => m.ID == id);

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

public async Task<IActionResult> OnPostAsync(int id)

{
Instructor instructor = await _context.Instructors
.Include(i => i.CourseAssignments)
.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);

await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
}
}

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.
Additional resources
YouTube version of this tutorial (Part 1)
YouTube version of this tutorial (Part 2)

P R E V IO U S NEXT
 Razor Pages with EF Core in ASP.NET Core -
Concurrency - 8 of 8
8/9/2019 • 36 minutes to read • Edit Online

By Rick Anderson, Tom Dykstra, and Jon P Smith

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.
If you run into problems you can't solve, download the completed app and compare that code to what you created
by following the tutorial.
This tutorial shows how to handle conflicts when multiple users update an entity concurrently (at the same time).

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 database.
If concurrency detection isn't enabled, whoever updates the database last overwrites the other user's changes. If
this risk is acceptable, the cost of programming for concurrency might outweigh the benefit.
Pessimistic concurrency (locking)
One way to prevent concurrency conflicts is to use database locks. This is called pessimistic concurrency. Before the
app reads a database row that it intends to update, it requests a lock. Once a row is locked for update access, no
other users are allowed to lock the row until the first lock is released.
Managing locks has disadvantages. It can be complex to program and can cause performance problems as the
number of users increases. Entity Framework Core provides no built-in support for it, and this tutorial doesn't show
how to implement it.
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 take effect, since the browser displays the Index page with zero as the
Budget amount.
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:
You can keep track of which property a user has modified and update only the corresponding columns in the
database.
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 has some
disadvantages:
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 database. 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.

Conflict detection in EF Core

EF Core throws DbConcurrencyException exceptions when it detects conflicts. The data model has to be configured
to enable conflict detection. Options for enabling conflict detection include the following:
Configure EF Core to include the original values of columns configured as concurrency tokens in the Where
clause of Update and Delete commands.
When SaveChanges is called, the Where clause looks for the original values of any properties annotated with
the ConcurrencyCheck attribute. The update statement won't find a row to update if any of the concurrency
token properties changed since the row was first read. EF Core interprets that as a concurrency conflict. For
database tables that have many columns, this approach can result in very large Where clauses, and can
require large amounts of state. Therefore this approach is generally not recommended, and it isn't the
method used in this tutorial.
In the database table, include a tracking column that can be used to determine when a row has been
changed.
In a SQL Server database, the data type of the tracking column is 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 number). If the row
being updated has been changed by another user, the value in the rowversion column is different than the
original value. In that case, the Update or Delete statement can't find the row to update because of the
 Where clause. EF Core throws a concurrency exception when no rows are affected by an Update or Delete
command.

Add a tracking property

In Models/Department.cs, add a tracking property named RowVersion:

using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Department
{
public int DepartmentID { get; set; }

[StringLength(50, MinimumLength = 3)]

public string Name { get; set; }

[DataType(DataType.Currency)]
[Column(TypeName = "money")]
public decimal Budget { get; set; }

[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Start Date")]
public DateTime StartDate { get; set; }

public int? InstructorID { get; set; }

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

public Instructor Administrator { get; set; }

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

The Timestamp attribute is what identifies the column as a concurrency tracking column. The fluent API is an
alternative way to specify the tracking property:

modelBuilder.Entity<Department>()
.Property<byte[]>("RowVersion")
.IsRowVersion();

Visual Studio
Visual Studio Code
For a SQL Server database, the [Timestamp] attribute on an entity property defined as byte array:
Causes the column to be included in DELETE and UPDATE WHERE clauses.
Sets the column type in the database to rowversion.
The database generates a sequential row version number that's incremented each time the row is updated. In an
Update or Delete command, the Where clause includes the fetched row version value. If the row being updated
has changed since it was fetched:
The current row version value doesn't match the fetched value.
 The Update or Delete commands don't find a row because the Where clause looks for the fetched row version
value.
A DbUpdateConcurrencyException is thrown.

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 database 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. If no rows are updated, EF Core
throws a DbUpdateConcurrencyException .
Update the database
Adding the RowVersion property changes the data model, which requires a migration.
Build the project.
Visual Studio
Visual Studio Code
Run the following command in the PMC:

Add-Migration RowVersion

This command:
Creates 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()
.HasAnnotation("SqlServer:ValueGenerationStrategy",
SqlServerValueGenerationStrategy.IdentityColumn);

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");
});

Visual Studio
Visual Studio Code
Run the following command in the PMC:

Update-Database

Scaffold Department pages

Visual Studio
Visual Studio Code
Follow the instructions in Scaffold Student pages with the following exceptions:
Create a Pages/Departments folder.
Use Department for the model class.
Use the existing context class instead of creating a new one.
Build the project.

Update the Index page

The scaffolding tool created a RowVersion column for the Index page, but that field wouldn't be displayed in a
production app. In this tutorial, the last byte of the RowVersion is displayed to help show how concurrency handling
works. The last byte isn't guaranteed to be unique by itself.
Update the Index page:
Replace Index with Departments.
 Change the code containing RowVersion to show just the last byte of the byte array.
Replace FirstMidName with FullName.
The following code shows the updated page:

@page
@model ContosoUniversity.Pages.Departments.IndexModel

@{
ViewData["Title"] = "Departments";
}

<h2>Departments</h2>

<p>
<a asp-page="Create">Create New</a>
</p>
<table class="table">
<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 ContosoUniversity.Data;
using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.AspNetCore.Mvc.Rendering;
using Microsoft.EntityFrameworkCore;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Departments
{
public class EditModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public EditModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

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

public async Task<IActionResult> OnGetAsync(int id)

{
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();
}

public async Task<IActionResult> OnPostAsync(int id)

{
if (!ModelState.IsValid)
{
return Page();
}

var departmentToUpdate = await _context.Departments

.Include(i => i.Administrator)
.FirstOrDefaultAsync(m => m.DepartmentID == id);

if (departmentToUpdate == null)
{
return HandleDeletedDepartment();
}

_context.Entry(departmentToUpdate)
.Property("RowVersion").OriginalValue = Department.RowVersion;

if (await TryUpdateModelAsync<Department>(
 if (await TryUpdateModelAsync<Department>(
departmentToUpdate,
"Department",
s => s.Name, s => s.StartDate, s => s.Budget, s => s.InstructorID))
{
try
{
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
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;
// Clear the model error for the next postback.
ModelState.Remove("Department.RowVersion");
}
}

InstructorNameSL = new SelectList(_context.Instructors,

"ID", "FullName", departmentToUpdate.InstructorID);

return Page();
}

private IActionResult HandleDeletedDepartment()

{
var 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)
 if (dbValues.InstructorID != clientValues.InstructorID)
{
Instructor dbInstructor = await _context.Instructors
.FindAsync(dbValues.InstructorID);
ModelState.AddModelError("Department.InstructorID",
$"Current value: {dbInstructor?.FullName}");
}

ModelState.AddModelError(string.Empty,
"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.");
}
}
}

The OriginalValue is updated with the rowVersion value from the entity when it was fetched in the OnGet method.
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.

public async Task<IActionResult> OnPostAsync(int id)

{
if (!ModelState.IsValid)
{
return Page();
}

var departmentToUpdate = await _context.Departments

.Include(i => i.Administrator)
.FirstOrDefaultAsync(m => m.DepartmentID == id);

if (departmentToUpdate == null)
{
return HandleDeletedDepartment();
}

_context.Entry(departmentToUpdate)
.Property("RowVersion").OriginalValue = Department.RowVersion;

In the preceding highlighted code:

The value in Department.RowVersion is what was in the entity when it was originally fetched in the Get request
for the Edit page. The value is provided to the OnPost method by a hidden field in the Razor page that displays
the entity to be edited. The hidden field value is copied to Department.RowVersion by the model binder.
OriginalValue is what EF Core will use in the Where clause. Before the highlighted line of code executes,
OriginalValue has the value that was in the database when FirstOrDefaultAsync was called in this method,
which might be different from what was displayed on the Edit page.
The highlighted code makes sure that EF Core uses the original RowVersion value from the displayed
Department entity in the SQL UPDATE statement's Where clause.

When a concurrency error happens, the following highlighted code gets the client values (the values posted to this
method) and the database values.
 if (await TryUpdateModelAsync<Department>(
departmentToUpdate,
"Department",
s => s.Name, s => s.StartDate, s => s.Budget, s => s.InstructorID))
{
try
{
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
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;
// Clear the model error for the next postback.
ModelState.Remove("Department.RowVersion");
}

The following code adds a custom error message for each column that has database 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}");
}

ModelState.AddModelError(string.Empty,
"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.");
}

The following highlighted code sets the RowVersion value to the new value retrieved from the database. The next
time the user clicks Save, only concurrency errors that happen since the last display of the Edit page will be caught.
 if (await TryUpdateModelAsync<Department>(
departmentToUpdate,
"Department",
s => s.Name, s => s.StartDate, s => s.Budget, s => s.InstructorID))
{
try
{
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
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;
// Clear the model error for the next postback.
ModelState.Remove("Department.RowVersion");
}

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 the Razor page
Update Pages/Departments/Edit.cshtml with the following code:
 @page "{id:int}"
@model ContosoUniversity.Pages.Departments.EditModel
@{
ViewData["Title"] = "Edit";
}
<h2>Edit</h2>
<h4>Department</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<input type="hidden" asp-for="Department.DepartmentID" />
<input type="hidden" asp-for="Department.RowVersion" />
<div class="form-group">
<label>RowVersion</label>
@Model.Department.RowVersion[7]
</div>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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 class="form-group">
<input type="submit" value="Save" class="btn btn-primary" />
</div>
</form>
</div>
</div>
<div>
<a asp-page="./Index">Back to List</a>
</div>
@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

The preceding code:

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 database 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

Update Pages/Departments/Delete.cshtml.cs with the following code:

using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Departments
{
public class DeleteModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public DeleteModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Department Department { get; set; }
public string ConcurrencyErrorMessage { get; set; }

public async Task<IActionResult> OnGetAsync(int id, bool? concurrencyError)

{
Department = await _context.Departments
.Include(d => d.Administrator)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.DepartmentID == id);

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();
}

public async Task<IActionResult> OnPostAsync(int id)

{
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);
await _context.SaveChangesAsync();
 }
return RedirectToPage("./Index");
}
catch (DbUpdateConcurrencyException)
{
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 database.
A DbUpdateConcurrencyException exception is thrown.
OnGetAsync is called with the concurrencyError .

Update the Delete Razor page

Update Pages/Departments/Delete.cshtml with the following code:
 @page "{id:int}"
@model ContosoUniversity.Pages.Departments.DeleteModel

@{
ViewData["Title"] = "Delete";
}

<h2>Delete</h2>

<p class="text-danger">@Model.ConcurrencyErrorMessage</p>

<h3>Are you sure you want to delete this?</h3>

<div>
<h4>Department</h4>
<hr />
<dl class="dl-horizontal">
<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>

<form method="post">
<input type="hidden" asp-for="Department.DepartmentID" />
<input type="hidden" asp-for="Department.RowVersion" />
<div class="form-actions no-color">
<input type="submit" value="Delete" class="btn btn-danger" /> |
<a asp-page="./Index">Back to List</a>
</div>
</form>
</div>

The preceding code makes the following changes:

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 postgit add back binds the value.
Test concurrency conflicts
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
database. Clicking Delete deletes the entity, unless RowVersion has been updated.department has been deleted.

Additional resources
Concurrency Tokens in EF Core
Handle concurrency in EF Core
Debugging ASP.NET Core 2.x source

Next steps
This is the last tutorial in the series. Additional topics are covered in the MVC version of this tutorial series.

P R E V IO U S
T U T O R IA L

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:
doesn't match the fetched value.
rowversion
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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Department
{
public int DepartmentID { get; set; }

[StringLength(50, MinimumLength = 3)]

public string Name { get; set; }

[DataType(DataType.Currency)]
[Column(TypeName = "money")]
public decimal Budget { get; set; }

[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Start Date")]
public DateTime StartDate { get; set; }

public int? InstructorID { get; set; }

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

public Instructor Administrator { get; set; }

public ICollection<Course> Courses { 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:

modelBuilder.Entity<Department>()
.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

dotnet ef database update

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:

Runs migrations to update the DB.

Scaffold the Departments model

 Visual Studio
Visual Studio Code
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>
<a asp-page="Create">Create New</a>
</p>
<table class="table">
<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 ContosoUniversity.Data;
using ContosoUniversity.Models;
using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.AspNetCore.Mvc.Rendering;
using Microsoft.EntityFrameworkCore;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Departments
{
public class EditModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public EditModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

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

public async Task<IActionResult> OnGetAsync(int id)

{
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();
}

public async Task<IActionResult> OnPostAsync(int id)

{
if (!ModelState.IsValid)
{
return Page();
}

var departmentToUpdate = await _context.Departments

.Include(i => i.Administrator)
.FirstOrDefaultAsync(m => m.DepartmentID == id);

// null means Department was deleted by another user.

if (departmentToUpdate == null)
{
return 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>(
 if (await TryUpdateModelAsync<Department>(
departmentToUpdate,
"Department",
s => s.Name, s => s.StartDate, s => s.Budget, s => s.InstructorID))
{
try
{
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
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 IActionResult HandleDeletedDepartment()

{
var 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}");
}

ModelState.AddModelError(string.Empty,
"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.

public async Task<IActionResult> OnPostAsync(int id)

{
if (!ModelState.IsValid)
{
return Page();
}

var departmentToUpdate = await _context.Departments

.Include(i => i.Administrator)
.FirstOrDefaultAsync(m => m.DepartmentID == id);

// null means Department was deleted by another user.

if (departmentToUpdate == null)
{
return 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
{
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
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");
}

The following 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}");
}

ModelState.AddModelError(string.Empty,
"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.");
}
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
{
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
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");
}

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 the Edit page

Update Pages/Departments/Edit.cshtml with the following markup:
 @page "{id:int}"
@model ContosoUniversity.Pages.Departments.EditModel
@{
ViewData["Title"] = "Edit";
}
<h2>Edit</h2>
<h4>Department</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<input type="hidden" asp-for="Department.DepartmentID" />
<input type="hidden" asp-for="Department.RowVersion" />
<div class="form-group">
<label>RowVersion</label>
@Model.Department.RowVersion[7]
</div>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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 class="form-group">
<input type="submit" value="Save" class="btn btn-default" />
</div>
</form>
</div>
</div>
<div>
<a asp-page="./Index">Back to List</a>
</div>
@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

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

Update the Delete page model with the following code:

using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Departments
{
public class DeleteModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;
 public DeleteModel(ContosoUniversity.Data.SchoolContext context)
{
_context = context;
}

[BindProperty]
public Department Department { get; set; }
public string ConcurrencyErrorMessage { get; set; }

public async Task<IActionResult> OnGetAsync(int id, bool? concurrencyError)

{
Department = await _context.Departments
.Include(d => d.Administrator)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.DepartmentID == id);

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();
}

public async Task<IActionResult> OnPostAsync(int id)

{
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);
await _context.SaveChangesAsync();
}
return RedirectToPage("./Index");
}
catch (DbUpdateConcurrencyException)
{
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 the Delete page
Update Pages/Departments/Delete.cshtml with the following code:

@page "{id:int}"
@model ContosoUniversity.Pages.Departments.DeleteModel

@{
ViewData["Title"] = "Delete";
}

<h2>Delete</h2>

<p class="text-danger">@Model.ConcurrencyErrorMessage</p>

<h3>Are you sure you want to delete this?</h3>

<div>
<h4>Department</h4>
<hr />
<dl class="dl-horizontal">
<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>

<form method="post">
<input type="hidden" asp-for="Department.DepartmentID" />
<input type="hidden" asp-for="Department.RowVersion" />
<div class="form-actions no-color">
<input type="submit" value="Delete" class="btn btn-default" /> |
<a asp-page="./Index">Back to List</a>
</div>
</form>
</div>

The preceding code makes the following changes:

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.
Additional resources
Concurrency Tokens in EF Core
Handle concurrency in EF Core
YouTube version of this tutorial(Handling Concurrency Conflicts)
YouTube version of this tutorial(Part 2)
YouTube version of this tutorial(Part 3)

P R E V IO U S
 ASP.NET Core MVC with EF Core - tutorial series
4/26/2019 • 2 minutes to read • Edit Online

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:
Is easier to follow.
Provides more EF Core best practices.
Uses more efficient queries.
Is more current with the latest API.
Covers more features.
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
9. Inheritance
10. Advanced topics
 Tutorial: Get started with EF Core in an ASP.NET MVC
web app
5/14/2019 • 20 minutes to read • Edit Online

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:
Is easier to follow.
Provides more EF Core best practices.
Uses more efficient queries.
Is more current with the latest API.
Covers more features.
The Contoso University sample web application demonstrates how to create ASP.NET Core 2.2 MVC web
applications using Entity Framework (EF ) Core 2.2 and Visual Studio 2017 or 2019.
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.
In this tutorial, you:
Create an ASP.NET Core MVC web app
Set up the site style
Learn about EF Core NuGet packages
Create the data model
Create the database context
Register the context for dependency injection
Initialize the database with test data
Create a controller and views
View the database

Prerequisites
.NET Core SDK 2.2
Visual Studio 2019 with the following workloads:
ASP.NET and web development workload
.NET Core cross-platform development workload

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.

Contoso University web app

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.
Create web app
Open Visual Studio.
From the File menu, select New > Project.
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 dialog to appear.
Select .NET Core, ASP.NET Core 2.2 and the Web Application (Model-View-Controller) template.
Make sure Authentication is set to No Authentication.
Select OK
Set up the site style
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 About, Students, Courses, Instructors, and Departments, and delete the Privacy
menu entry.
The changes are highlighted.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@ViewData["Title"] - Contoso University</title>

<environment include="Development">
<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
</environment>
<environment exclude="Development">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-
bootstrap/4.1.3/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"
crossorigin="anonymous"
integrity="sha256-eSi1q2PG6J7g7ib17yAaWMcrr5GrtohYChqibrV7PBE="/>
</environment>
<link rel="stylesheet" href="~/css/site.css" />
</head>
<body>
<header>
<nav class="navbar navbar-expand-sm navbar-toggleable-sm navbar-light bg-white border-bottom box-shadow
mb-3">
mb-3">
<div class="container">
<a class="navbar-brand" asp-area="" asp-controller="Home" asp-action="Index">Contoso
University</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target=".navbar-
collapse" aria-controls="navbarSupportedContent"
aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="navbar-collapse collapse d-sm-inline-flex flex-sm-row-reverse">
<ul class="navbar-nav flex-grow-1">
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-
action="Index">Home</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-
action="About">About</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Students" asp-
action="Index">Students</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Courses" asp-
action="Index">Courses</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Instructors" asp-
action="Index">Instructors</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Departments" asp-
action="Index">Departments</a>
</li>
</ul>
</div>
</div>
</nav>
</header>
<div class="container">
<partial name="_CookieConsentPartial" />
<main role="main" class="pb-3">
@RenderBody()
</main>
</div>

<footer class="border-top footer text-muted">

<div class="container">
&copy; 2019 - Contoso University - <a asp-area="" asp-controller="Home" asp-
action="Privacy">Privacy</a>
</div>
</footer>

<environment include="Development">
<script src="~/lib/jquery/dist/jquery.js"></script>
<script src="~/lib/bootstrap/dist/js/bootstrap.bundle.js"></script>
</environment>
<environment exclude="Development">
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js"
asp-fallback-src="~/lib/jquery/dist/jquery.min.js"
asp-fallback-test="window.jQuery"
crossorigin="anonymous"
integrity="sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8=">
</script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.1.3/js/bootstrap.bundle.min.js"
asp-fallback-src="~/lib/bootstrap/dist/js/bootstrap.bundle.min.js"
asp-fallback-test="window.jQuery && window.jQuery.fn && window.jQuery.fn.modal"
crossorigin="anonymous"
integrity="sha256-E/V4cWE4qvAeO5MOhjtGtqDzPndRO1LBk8lJ/PR7CA4=">
 integrity="sha256-E/V4cWE4qvAeO5MOhjtGtqDzPndRO1LBk8lJ/PR7CA4=">
</script>
</environment>
<script src="~/js/site.js" asp-append-version="true"></script>

@RenderSection("Scripts", required: false)

</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 class="jumbotron">
<h1>Contoso University</h1>
</div>
<div class="row">
<div class="col-md-4">
<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 MVC web application.
</p>
</div>
<div class="col-md-4">
<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.asp.net/en/latest/data/ef-mvc/intro.html">See the
tutorial &raquo;</a></p>
</div>
<div class="col-md-4">
<h2>Download it</h2>
<p>You can download the completed project from GitHub.</p>
<p><a class="btn btn-default"
href="https://github.com/aspnet/AspNetCore.Docs/tree/master/aspnetcore/data/ef-mvc/intro/samples/cu-final">See
project source code &raquo;</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.
About EF 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.App metapackage, so you don't need to reference the package.
The EF SQL Server 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.

Create the data model

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;
using System.Collections.Generic;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
public string LastName { get; set; }
public string FirstMidName { get; set; }
public DateTime EnrollmentDate { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }

}
}

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.
The Enrollment entity

In the Models folder, create Enrollment.cs and replace the existing code with the following code:

namespace ContosoUniversity.Models
{
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 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:

using System.Collections.Generic;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Course
{
[DatabaseGenerated(DatabaseGeneratedOption.None)]
public int CourseID { get; set; }
public string Title { get; set; }
public int Credits { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }

}
}

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:
 using ContosoUniversity.Models;
using Microsoft.EntityFrameworkCore;

namespace ContosoUniversity.Data
{
public class SchoolContext : DbContext
{
public SchoolContext(DbContextOptions<SchoolContext> options) : base(options)
{
}

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

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.

using ContosoUniversity.Models;
using Microsoft.EntityFrameworkCore;

namespace ContosoUniversity.Data
{
public class SchoolContext : DbContext
{
public SchoolContext(DbContextOptions<SchoolContext> options) : base(options)
{
}

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

public DbSet<Enrollment> Enrollments { get; set; }
public DbSet<Student> Students { get; set; }

protected override void OnModelCreating(ModelBuilder modelBuilder)

{
modelBuilder.Entity<Course>().ToTable("Course");
modelBuilder.Entity<Enrollment>().ToTable("Enrollment");
modelBuilder.Entity<Student>().ToTable("Student");
}
}
}

Register the SchoolContext

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.

public void ConfigureServices(IServiceCollection services)

{
services.Configure<CookiePolicyOptions>(options =>
{
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddDbContext<SchoolContext>(options =>
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
appsettings.json file.
Add using statements for ContosoUniversity.Data and Microsoft.EntityFrameworkCore namespaces, and then build
the project.

using ContosoUniversity.Data;
using Microsoft.EntityFrameworkCore;
using Microsoft.AspNetCore.Http;

Open the appsettings.json file and add a connection string as shown in the following example.

{
"ConnectionStrings": {
"DefaultConnection": "Server=
(localdb)\\mssqllocaldb;Database=ContosoUniversity1;Trusted_Connection=True;MultipleActiveResultSets=true"
},
"Logging": {
"IncludeScopes": false,
"LogLevel": {
"Default": "Warning"
}
}
}

SQL Server Express LocalDB

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.

Initialize DB 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 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.Students.Any())
{
return; // DB has been seeded
}

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.Students.Add(s);
}
context.SaveChanges();

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.Courses.Add(c);
}
context.SaveChanges();

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=1045,Grade=Grade.B},
new Enrollment{StudentID=2,CourseID=3141,Grade=Grade.F},
new Enrollment{StudentID=2,CourseID=2021,Grade=Grade.F},
new Enrollment{StudentID=3,CourseID=1050},
new Enrollment{StudentID=4,CourseID=1050},
new Enrollment{StudentID=4,CourseID=4022,Grade=Grade.F},
new Enrollment{StudentID=5,CourseID=4041,Grade=Grade.C},
new Enrollment{StudentID=6,CourseID=1045},
 new Enrollment{StudentID=6,CourseID=1045},
new Enrollment{StudentID=7,CourseID=3141,Grade=Grade.A},
};
foreach (Enrollment e in enrollments)
{
context.Enrollments.Add(e);
}
context.SaveChanges();
}
}
}

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.

public static void Main(string[] args)

{
var host = CreateWebHostBuilder(args).Build();

using (var scope = host.Services.CreateScope())

{
var services = scope.ServiceProvider;
try
{
var context = services.GetRequiredService<SchoolContext>();
DbInitializer.Initialize(context);
}
catch (Exception ex)
{
var logger = services.GetRequiredService<ILogger<Program>>();
logger.LogError(ex, "An error occurred while seeding the database.");
}
}

host.Run();
}

Add using statements:

using Microsoft.Extensions.DependencyInjection;
using ContosoUniversity.Data;

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 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.
In the Add Scaffold dialog box:
Select MVC controller with views, using Entity Framework.
Click Add. The Add MVC Controller with views, using Entity Framework dialog box appears.

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
{
private readonly SchoolContext _context;

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:

public async Task<IActionResult> Index()

{
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>

@{
ViewData["Title"] = "Index";
}

<h2>Index</h2>

<p>
<a asp-action="Create">Create New</a>
</p>
<table class="table">
<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>
@foreach (var item in Model) {
<tr>
<td>
@Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
@Html.DisplayFor(modelItem => item.FirstMidName)
</td>
<td>
@Html.DisplayFor(modelItem => item.EnrollmentDate)
</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>

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 Students 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\<yourusername> 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 <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, 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
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, 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.

public async Task<IActionResult> Index()

{
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.
ToListAsync is the asynchronous version of the ToList extension method.
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
var students = context.Students.Where(s => s.LastName == "Davolio") .

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.

Get the code

Download or view the completed application.

Next steps
In this tutorial, you:
Created ASP.NET Core MVC web app
Set up the site style
 Learned about EF Core NuGet packages
Created the data model
Created the database context
Registered the SchoolContext
Initialized DB with test data
Created controller and views
Viewed the database
In the following tutorial, you'll learn how to perform basic CRUD (create, read, update, delete) operations.
Advance to the next tutorial to learn how to perform basic CRUD (create, read, update, delete) operations.
Implement basic CRUD functionality
 Tutorial: Implement CRUD Functionality - ASP.NET
MVC with EF Core
6/6/2019 • 19 minutes to read • Edit Online

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:

Customize the Details page
Update the Create page
Update the Edit page
Update the Delete page
Close database connections

Prerequisites
Get started with EF Core and ASP.NET Core MVC

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.
 public async Task<IActionResult> Details(int? id)
{
if (id == null)
{
return NotFound();
}

var student = await _context.Students

.Include(s => s.Enrollments)
.ThenInclude(e => e.Course)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.ID == id);

if (student == null)
{
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:

app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});

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 class="col-sm-2">
@Html.DisplayNameFor(model => model.LastName)
</dt>
<dd class="col-sm-10">
@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 class="col-sm-2">
@Html.DisplayNameFor(model => model.Enrollments)
</dt>
<dd class="col-sm-10">
<table class="table">
<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>
@Html.DisplayFor(modelItem => item.Grade)
</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]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Create(
[Bind("EnrollmentDate,FirstMidName,LastName")] Student student)
{
try
{
if (ModelState.IsValid)
{
_context.Add(student);
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}
}
catch (DbUpdateException /* ex */)
{
//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.");
}
return View(student);
}

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 class Student

{
public int ID { get; set; }
public string LastName { get; set; }
public string FirstMidName { get; set; }
public DateTime EnrollmentDate { get; 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]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Create(
[Bind("EnrollmentDate,FirstMidName,LastName")] Student student)
{
try
{
if (ModelState.IsValid)
{
_context.Add(student);
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}
}
catch (DbUpdateException /* ex */)
{
//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.");
}
return View(student);
}

Change the date to a valid value and click Create to see the new student appear in the Index page.

Update the Edit 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")]
[ValidateAntiForgeryToken]
public async Task<IActionResult> EditPost(int? id)
{
if (id == null)
{
return NotFound();
}
var studentToUpdate = await _context.Students.FirstOrDefaultAsync(s => s.ID == id);
if (await TryUpdateModelAsync<Student>(
studentToUpdate,
"",
s => s.FirstMidName, s => s.LastName, s => s.EnrollmentDate))
{
try
{
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}
catch (DbUpdateException /* ex */)
{
//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.");
}
}
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();
}
if (ModelState.IsValid)
{
try
{
_context.Update(student);
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}
catch (DbUpdateException /* ex */)
{
//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.");
}
}
return View(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.
Modified . Some or all of the entity's property values have been modified. The 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.

Update the Delete page

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();
}

var student = await _context.Students

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

if (saveChangesError.GetValueOrDefault())
{
ViewData["ErrorMessage"] =
"Delete failed. Try again, and if the problem persists " +
"see your system administrator.";
}

return View(student);
}

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.

[HttpPost, ActionName("Delete")]
[ValidateAntiForgeryToken]
public async Task<IActionResult> DeleteConfirmed(int id)
{
var student = await _context.Students.FindAsync(id);
if (student == null)
{
return RedirectToAction(nameof(Index));
}

try
{
_context.Students.Remove(student);
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}
catch (DbUpdateException /* ex */)
{
//Log the error (uncomment ex variable name and write a log.)
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]
[ValidateAntiForgeryToken]
public async Task<IActionResult> DeleteConfirmed(int id)
{
try
{
Student studentToDelete = new Student() { ID = id };
_context.Entry(studentToDelete).State = EntityState.Deleted;
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}
catch (DbUpdateException /* ex */)
{
//Log the error (uncomment ex variable name and write a log.)
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>
<h3>Are you sure you want to delete this?</h3>

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.)

Close 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.

Handle 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.

Get the code

Download or view the completed application.

Next steps
In this tutorial, you:
Customized the Details page
Updated the Create page
Updated the Edit page
Updated the Delete page
Closed database connections
Advance to the next tutorial to learn how to expand the functionality of the Index page by adding sorting, filtering,
and paging.
Next: Sorting, filtering, and paging
 Tutorial: Add sorting, filtering, and paging - ASP.NET
MVC with EF Core
5/7/2019 • 14 minutes to read • Edit Online

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.

In this tutorial, you:

Add column sort links
Add a Search box
Add paging to Students Index
Add paging to Index method
Add paging links
Create an About page

Prerequisites
Implement CRUD Functionality

Add column sort links

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)
{
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());
}

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>

@{
ViewData["Title"] = "Index";
}

<h2>Index</h2>

<p>
<a asp-action="Create">Create New</a>
</p>
<table class="table">
<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>
@foreach (var item in Model) {
<tr>
<td>
@Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
@Html.DisplayFor(modelItem => item.FirstMidName)
</td>
<td>
@Html.DisplayFor(modelItem => item.EnrollmentDate)
</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>

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 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["NameSortParm"] = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";
ViewData["DateSortParm"] = sortOrder == "Date" ? "date_desc" : "Date";
ViewData["CurrentFilter"] = searchString;

var students = from s in _context.Students

select s;
if (!String.IsNullOrEmpty(searchString))
{
students = students.Where(s => s.LastName.Contains(searchString)
|| s.FirstMidName.Contains(searchString));
}
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());
}
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>
<a asp-action="Create">Create New</a>
</p>

<form asp-action="Index" method="get">

<div class="form-actions no-color">
<p>
Find by name: <input type="text" name="SearchString" value="@ViewData["currentFilter"]" />
<input type="submit" value="Search" class="btn btn-default" /> |
<a asp-action="Index">Back to Full List</a>
</p>
</div>
</form>

<table class="table">

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 to Students Index

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.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.EntityFrameworkCore;

namespace ContosoUniversity
{
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 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 to 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? pageNumber)
{
ViewData["CurrentSort"] = sortOrder;
ViewData["NameSortParm"] = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";
ViewData["DateSortParm"] = sortOrder == "Date" ? "date_desc" : "Date";

if (searchString != null)
{
pageNumber = 1;
}
else
{
searchString = currentFilter;
}

ViewData["CurrentFilter"] = searchString;

var students = from s in _context.Students

select s;
if (!String.IsNullOrEmpty(searchString))
{
students = students.Where(s => s.LastName.Contains(searchString)
|| s.FirstMidName.Contains(searchString));
}
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;
}

int pageSize = 3;
return View(await PaginatedList<Student>.CreateAsync(students.AsNoTracking(), pageNumber ?? 1, pageSize));
}

This code adds a page number parameter, a current sort order parameter, and a current filter parameter to the
method signature.

public async Task<IActionResult> Index(

string sortOrder,
string currentFilter,
string searchString,
int? pageNumber)

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.

if (searchString != null)
{
pageNumber = 1;
}
else
{
searchString = currentFilter;
}

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(), pageNumber ?? 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
(pageNumber ?? 1) means return the value of pageNumber if it has a value, or return 1 if pageNumber is null.

Add paging links

In Views/Students/Index.cshtml, replace the existing code with the following code. The changes are highlighted.

@model PaginatedList<ContosoUniversity.Models.Student>

@{
ViewData["Title"] = "Index";
}

<h2>Index</h2>

<p>
<a asp-action="Create">Create New</a>
</p>

<form asp-action="Index" method="get">

<div class="form-actions no-color">
<p>
Find by name: <input type="text" name="SearchString" value="@ViewData["CurrentFilter"]" />
<input type="submit" value="Search" class="btn btn-default" /> |
<a asp-action="Index">Back to Full List</a>
</p>
</div>
</form>

<table class="table">
<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>
@Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
@Html.DisplayFor(modelItem => item.FirstMidName)
</td>
<td>
@Html.DisplayFor(modelItem => item.EnrollmentDate)
</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>

@{
var prevDisabled = !Model.HasPreviousPage ? "disabled" : "";
var nextDisabled = !Model.HasNextPage ? "disabled" : "";
}

<a asp-action="Index"
asp-route-sortOrder="@ViewData["CurrentSort"]"
asp-route-pageNumber="@(Model.PageIndex - 1)"
asp-route-currentFilter="@ViewData["CurrentFilter"]"
class="btn btn-default @prevDisabled">
Previous
</a>
<a asp-action="Index"
asp-route-sortOrder="@ViewData["CurrentSort"]"
asp-route-pageNumber="@(Model.PageIndex + 1)"
asp-route-currentFilter="@ViewData["CurrentFilter"]"
class="btn btn-default @nextDisabled">
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:

 <a asp-action="Index"
asp-route-sortOrder="@ViewData["CurrentSort"]"
asp-route-pageNumber="@(Model.PageIndex - 1)"
asp-route-currentFilter="@ViewData["CurrentFilter"]"
class="btn btn-default @prevDisabled">
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

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.
Create the About method in the Home controller.
Create 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;
using System.ComponentModel.DataAnnotations;

namespace ContosoUniversity.Models.SchoolViewModels
{
public class EnrollmentDateGroup
{
[DataType(DataType.Date)]
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:

using Microsoft.EntityFrameworkCore;
using ContosoUniversity.Data;
using ContosoUniversity.Models.SchoolViewModels;

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

{
private readonly SchoolContext _context;

public HomeController(SchoolContext context)

{
_context = context;
}

Add an 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.
Create the About View
Add a 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>

@foreach (var item in Model)

{
<tr>
<td>
@Html.DisplayFor(modelItem => item.EnrollmentDate)
</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.

Get the code

Download or view the completed application.

Next steps
In this tutorial, you:
Added column sort links
Added a Search box
Added paging to Students Index
Added paging to Index method
Added paging links
Created an About page
Advance to the next tutorial to learn how to handle data model changes by using migrations.
Next: Handle data model changes
 Tutorial: Using the migrations feature - ASP.NET MVC
with EF Core
7/11/2019 • 6 minutes to read • Edit Online

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.
In this tutorial, you:
Learn about migrations
Change the connection string
Create an initial migration
Examine Up and Down methods
Learn about the data model snapshot
Apply the migration

Prerequisites
Sorting, filtering, and paging

About 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.
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.

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.

{
"ConnectionStrings": {
"DefaultConnection": "Server=
(localdb)\\mssqllocaldb;Database=ContosoUniversity2;Trusted_Connection=True;MultipleActiveResultSets=true"
},

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 Folder 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.EntityFrameworkCore.Infrastructure[10403]
Entity Framework Core 2.2.0-rtm-35687 initialized 'SchoolContext' using provider
'Microsoft.EntityFrameworkCore.SqlServer' with options: None
Done. To undo this action, use 'ef migrations remove'

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 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

{
protected override void Up(MigrationBuilder migrationBuilder)
{
migrationBuilder.CreateTable(
name: "Course",
columns: table => new
{
CourseID = table.Column<int>(nullable: false),
Credits = table.Column<int>(nullable: false),
Title = table.Column<string>(nullable: true)
},
constraints: table =>
{
table.PrimaryKey("PK_Course", x => x.CourseID);
});

// Additional code not shown

}

protected override void Down(MigrationBuilder migrationBuilder)

{
migrationBuilder.DropTable(
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

In the command window, enter the following command to create the database and tables in it.

dotnet ef database update

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 Logging in .NET Core and ASP.NET Core.

info: Microsoft.EntityFrameworkCore.Infrastructure[10403]
Entity Framework Core 2.2.0-rtm-35687 initialized 'SchoolContext' using provider
'Microsoft.EntityFrameworkCore.SqlServer' with options: None
info: Microsoft.EntityFrameworkCore.Database.Command[20101]
Executed DbCommand (274ms) [Parameters=[], CommandType='Text', CommandTimeout='60']
CREATE DATABASE [ContosoUniversity2];
info: Microsoft.EntityFrameworkCore.Database.Command[20101]
Executed DbCommand (60ms) [Parameters=[], CommandType='Text', CommandTimeout='60']
IF SERVERPROPERTY('EngineEdition') <> 5
BEGIN
ALTER DATABASE [ContosoUniversity2] SET READ_COMMITTED_SNAPSHOT ON;
END;
info: Microsoft.EntityFrameworkCore.Database.Command[20101]
Executed DbCommand (15ms) [Parameters=[], CommandType='Text', CommandTimeout='30']
CREATE TABLE [__EFMigrationsHistory] (
[MigrationId] nvarchar(150) NOT NULL,
[ProductVersion] nvarchar(32) NOT NULL,
CONSTRAINT [PK___EFMigrationsHistory] PRIMARY KEY ([MigrationId])
);

<logs omitted for brevity>

info: Microsoft.EntityFrameworkCore.Database.Command[20101]
Executed DbCommand (3ms) [Parameters=[], CommandType='Text', CommandTimeout='30']
INSERT INTO [__EFMigrationsHistory] ([MigrationId], [ProductVersion])
VALUES (N'20190327172701_InitialCreate', N'2.2.0-rtm-35687');
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.

Compare CLI and 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 included in the Microsoft.AspNetCore.App metapackage, so you don't need to add a package reference if your
app has a package reference for Microsoft.AspNetCore.App .
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).

Get the code

Download or view the completed application.

Next step
In this tutorial, you:
Learned about migrations
Learned about NuGet migration packages
Changed the connection string
Created an initial migration
Examined Up and Down methods
 Learned about the data model snapshot
Applied the migration
Advance to the next tutorial to begin looking at more advanced topics about expanding the data model. Along the
way you'll create and apply additional migrations.
Create and apply additional migrations
 Tutorial: Create a complex data model - ASP.NET
MVC with EF Core
7/11/2019 • 30 minutes to read • Edit Online

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:

In this tutorial, you:

Customize the Data model
Make changes to Student entity
Create Instructor entity
Create OfficeAssignment entity
 Modify Course entity
Create Department entity
Modify Enrollment entity
Update the database context
Seed database with test data
Add a migration
Change the connection string
Update the database

Prerequisites
Using EF Core migrations

Customize the Data model

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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
public string LastName { get; set; }
public string FirstMidName { get; set; }
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
public DateTime EnrollmentDate { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }

}
}

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.
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 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 :
The browser can enable HTML5 features (for example to show a calendar control, the locale-appropriate
currency symbol, email links, some client-side input validation, etc.).
By default, the browser will render data using the correct format based on your locale.
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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
[StringLength(50)]
public string LastName { get; set; }
[StringLength(50)]
public string FirstMidName { get; set; }
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
public DateTime EnrollmentDate { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }

}
}

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:

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

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

dotnet ef database update

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 try to enter either name longer than 50 characters.
The application should prevent you from doing this.
The Column attribute
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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
[StringLength(50)]
public string LastName { get; set; }
[StringLength(50)]
[Column("FirstName")]
public string FirstMidName { get; set; }
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
public DateTime EnrollmentDate { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }

}
}

The addition of the Column attribute changes the model backing the SchoolContext , so it won't match the database.
Save your changes and build the project. Then open the command window in the project folder and enter the
following commands to create another migration:

dotnet ef migrations add ColumnFirstName

dotnet ef database update

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.

Changes to Student entity

In Models/Student.cs, replace the code you added earlier with the following code. The changes are highlighted.
 using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
[Required]
[StringLength(50)]
[Display(Name = "Last Name")]
public string LastName { get; set; }
[Required]
[StringLength(50)]
[Column("FirstName")]
[Display(Name = "First Name")]
public string FirstMidName { get; set; }
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Enrollment Date")]
public DateTime EnrollmentDate { get; set; }
[Display(Name = "Full Name")]
public string FullName
{
get
{
return LastName + ", " + FirstMidName;
}
}

public ICollection<Enrollment> Enrollments { get; set; }

}
}

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:

[Display(Name = "Last Name")]

[StringLength(50, MinimumLength=1)]
public string LastName { get; set; }

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 Instructor entity

Create Models/Instructor.cs, replacing the template code with the following code:

using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Instructor
{
public int ID { get; set; }

[Required]
[Display(Name = "Last Name")]
[StringLength(50)]
public string LastName { get; set; }

[Required]
[Column("FirstName")]
[Display(Name = "First Name")]
[StringLength(50)]
public string FirstMidName { get; set; }

[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Hire Date")]
public DateTime HireDate { get; set; }

[Display(Name = "Full Name")]

public string FullName
{
get { return LastName + ", " + FirstMidName; }
}

public ICollection<CourseAssignment> CourseAssignments { get; set; }

public OfficeAssignment OfficeAssignment { get; set; }
}
}

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.

public ICollection<CourseAssignment> CourseAssignments { get; set; }

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).

public OfficeAssignment OfficeAssignment { get; set; }

Create OfficeAssignment entity

Create Models/OfficeAssignment.cs with the following code:

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
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

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]
public int InstructorID { get; set; }
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 Course entity

In Models/Course.cs, replace the code you added earlier with the following code. The changes are highlighted.

using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Course
{
[DatabaseGenerated(DatabaseGeneratedOption.None)]
[Display(Name = "Number")]
public int CourseID { get; set; }

[StringLength(50, MinimumLength = 3)]

public string Title { get; set; }

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

public int DepartmentID { get; set; }

public Department Department { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }
public ICollection<CourseAssignment> CourseAssignments { get; set; }
}
}

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.

[DatabaseGenerated(DatabaseGeneratedOption.None)]
[Display(Name = "Number")]
public int CourseID { get; set; }

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.
Foreign key and navigation 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.

public int DepartmentID { get; set; }

public Department Department { get; set; }

A course can have any number of students enrolled in it, so the Enrollments navigation property is a collection:

public ICollection<Enrollment> Enrollments { get; set; }

A course may be taught by multiple instructors, so the CourseAssignments navigation property is a collection (the
type CourseAssignment is explained later):

public ICollection<CourseAssignment> CourseAssignments { get; set; }

Create Department entity

Create Models/Department.cs with the following code:

using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Department
{
public int DepartmentID { get; set; }

[StringLength(50, MinimumLength = 3)]

public string Name { get; set; }

[DataType(DataType.Currency)]
[Column(TypeName = "money")]
public decimal Budget { get; set; }

[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[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; }
}
}

The Column attribute

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")]
public decimal Budget { get; set; }

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.
Foreign key and navigation properties
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:

public int? InstructorID { get; set; }

public Instructor Administrator { get; set; }

A department may have many courses, so there's a Courses navigation property:

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

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 department when you delete the instructor, 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:

modelBuilder.Entity<Department>()
.HasOne(d => d.Administrator)
.WithMany()
.OnDelete(DeleteBehavior.Restrict)

Modify Enrollment entity

In Models/Enrollment.cs, replace the code you added earlier with the following code:

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
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; }
[DisplayFormat(NullDisplayText = "No grade")]
public Grade? Grade { get; set; }

public Course Course { get; set; }

public Student Student { get; set; }
}
}

Foreign key and navigation properties

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:

public int CourseID { get; set; }

public Course Course { get; set; }

An enrollment record is for a single student, so there's a StudentID foreign key property and a Student navigation
property:

public int StudentID { get; set; }

public Student Student { get; set; }

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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class CourseAssignment
{
public int InstructorID { get; set; }
public int CourseID { get; set; }
public Instructor Instructor { get; set; }
public Course Course { get; set; }
}
}

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:
 using ContosoUniversity.Models;
using Microsoft.EntityFrameworkCore;

namespace ContosoUniversity.Data
{
public class SchoolContext : DbContext
{
public SchoolContext(DbContextOptions<SchoolContext> options) : base(options)
{
}

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

public DbSet<Enrollment> Enrollments { get; set; }
public DbSet<Student> Students { 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 });
}
}
}

This code adds the new entities and configures the CourseAssignment entity's composite primary key.

About a fluent API alternative

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:

protected override void OnModelCreating(ModelBuilder modelBuilder)

{
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 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;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using ContosoUniversity.Models;

namespace ContosoUniversity.Data
{
public static class DbInitializer
{
{
public static void Initialize(SchoolContext context)
{
//context.Database.EnsureCreated();

// Look for any students.

if (context.Students.Any())
{
return; // DB has been seeded
}

var students = new Student[]

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

foreach (Student s in students)

{
context.Students.Add(s);
}
context.SaveChanges();

var instructors = new Instructor[]

{
new Instructor { FirstMidName = "Kim", LastName = "Abercrombie",
HireDate = DateTime.Parse("1995-03-11") },
new Instructor { FirstMidName = "Fadi", LastName = "Fakhouri",
HireDate = DateTime.Parse("2002-07-06") },
new Instructor { FirstMidName = "Roger", LastName = "Harui",
HireDate = DateTime.Parse("1998-07-01") },
new Instructor { FirstMidName = "Candace", LastName = "Kapoor",
HireDate = DateTime.Parse("2001-01-15") },
new Instructor { FirstMidName = "Roger", LastName = "Zheng",
HireDate = DateTime.Parse("2004-02-12") }
};

foreach (Instructor i in instructors)

{
context.Instructors.Add(i);
}
context.SaveChanges();

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,
StartDate = DateTime.Parse("2007-09-01"),
InstructorID = instructors.Single( i => i.LastName == "Fakhouri").ID },
new Department { Name = "Engineering", Budget = 350000,
StartDate = DateTime.Parse("2007-09-01"),
InstructorID = instructors.Single( i => i.LastName == "Harui").ID },
new Department { Name = "Economics", Budget = 100000,
StartDate = DateTime.Parse("2007-09-01"),
 StartDate = DateTime.Parse("2007-09-01"),
InstructorID = instructors.Single( i => i.LastName == "Kapoor").ID }
};

foreach (Department d in departments)

{
context.Departments.Add(d);
}
context.SaveChanges();

var courses = new Course[]

{
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,
DepartmentID = departments.Single( s => s.Name == "Economics").DepartmentID
},
new Course {CourseID = 1045, Title = "Calculus", Credits = 4,
DepartmentID = departments.Single( s => s.Name == "Mathematics").DepartmentID
},
new Course {CourseID = 3141, Title = "Trigonometry", Credits = 4,
DepartmentID = departments.Single( s => s.Name == "Mathematics").DepartmentID
},
new Course {CourseID = 2021, Title = "Composition", Credits = 3,
DepartmentID = departments.Single( s => s.Name == "English").DepartmentID
},
new Course {CourseID = 2042, Title = "Literature", Credits = 4,
DepartmentID = departments.Single( s => s.Name == "English").DepartmentID
},
};

foreach (Course c in courses)

{
context.Courses.Add(c);
}
context.SaveChanges();

var officeAssignments = new OfficeAssignment[]

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

foreach (OfficeAssignment o in officeAssignments)

{
context.OfficeAssignments.Add(o);
}
context.SaveChanges();

var courseInstructors = new CourseAssignment[]

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

foreach (CourseAssignment ci in courseInstructors)

{
context.CourseAssignments.Add(ci);
}
context.SaveChanges();

var enrollments = new Enrollment[]

{
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alexander").ID,
CourseID = courses.Single(c => c.Title == "Chemistry" ).CourseID,
Grade = Grade.A
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alexander").ID,
CourseID = courses.Single(c => c.Title == "Microeconomics" ).CourseID,
Grade = Grade.C
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alexander").ID,
CourseID = courses.Single(c => c.Title == "Macroeconomics" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alonso").ID,
CourseID = courses.Single(c => c.Title == "Calculus" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alonso").ID,
CourseID = courses.Single(c => c.Title == "Trigonometry" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alonso").ID,
CourseID = courses.Single(c => c.Title == "Composition" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Anand").ID,
CourseID = courses.Single(c => c.Title == "Chemistry" ).CourseID
},
 new Enrollment {
StudentID = students.Single(s => s.LastName == "Anand").ID,
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
}
};

foreach (Enrollment e in enrollments)

{
var enrollmentInDataBase = context.Enrollments.Where(
s =>
s.Student.ID == e.StudentID &&
s.Course.CourseID == e.CourseID).SingleOrDefault();
if (enrollmentInDataBase == null)
{
context.Enrollments.Add(e);
}
}
context.SaveChanges();
}
}
}

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
Save your changes and build the project. Then open the command window in the project folder and enter the
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.
Done. To undo this action, use 'ef migrations remove'

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:
 migrationBuilder.CreateTable(
name: "Department",
columns: table => new
{
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)
},
constraints: table =>
{
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.

migrationBuilder.AddColumn<int>(
name: "DepartmentID",
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

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.

{
"ConnectionStrings": {
"DefaultConnection": "Server=
(localdb)\\mssqllocaldb;Database=ContosoUniversity3;Trusted_Connection=True;MultipleActiveResultSets=true"
},

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:

dotnet ef database drop

Update the database

After you have changed the database name or deleted the database, run the database update command in the
command window to execute the migrations.

dotnet ef database update

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.
Get the code
Download or view the completed application.

Next steps
In this tutorial, you:
Customized the Data model
Made changes to Student entity
Created Instructor entity
Created OfficeAssignment entity
Modified Course entity
Created Department entity
Modified Enrollment entity
Updated the database context
Seeded database with test data
Added a migration
Changed the connection string
Updated the database
Advance to the next tutorial to learn more about how to access related data.
Next: Access related data
 Tutorial: Read related data - ASP.NET MVC with EF
Core
8/6/2019 • 14 minutes to read • Edit Online

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.
In this tutorial, you:
Learn how to load related data
Create a Courses page
Create an Instructors page
Learn about explicit loading

Prerequisites
Create a complex data model

Learn how to load 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

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 ):

public async Task<IActionResult> Index()

{
var courses = _context.Courses
.Include(c => c.Department)
.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>
<a asp-action="Create">Create New</a>
</p>
<table class="table">
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.CourseID)
</th>
<th>
@Html.DisplayNameFor(model => model.Title)
</th>
<th>
@Html.DisplayNameFor(model => model.Credits)
</th>
<th>
@Html.DisplayNameFor(model => model.Department)
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model)
{
<tr>
<td>
@Html.DisplayFor(modelItem => item.CourseID)
</td>
<td>
@Html.DisplayFor(modelItem => item.Title)
</td>
<td>
@Html.DisplayFor(modelItem => item.Credits)
</td>
<td>
@Html.DisplayFor(modelItem => item.Department.Name)
</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:
 @Html.DisplayFor(modelItem => item.Department.Name)

Run the app and select the Courses tab to see the list with department names.

Create an Instructors page

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.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Models.SchoolViewModels
{
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:

using ContosoUniversity.Models.SchoolViewModels;

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
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.AsNoTracking()
.OrderBy(i => i.LastName)
.ToListAsync();

if (id != null)
{
ViewData["InstructorID"] = id.Value;
Instructor instructor = viewModel.Instructors.Where(
i => i.ID == id.Value).Single();
viewModel.Courses = instructor.CourseAssignments.Select(s => s.Course);
}

if (courseID != null)
{
ViewData["CourseID"] = courseID.Value;
viewModel.Enrollments = viewModel.Courses.Where(
x => x.CourseID == courseID).Single().Enrollments;
}

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.

viewModel.Instructors = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.AsNoTracking()
.OrderBy(i => i.LastName)
.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 .
 viewModel.Instructors = await _context.Instructors
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.AsNoTracking()
.OrderBy(i => i.LastName)
.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 .

viewModel.Instructors = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.AsNoTracking()
.OrderBy(i => i.LastName)
.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)
{
ViewData["InstructorID"] = id.Value;
Instructor instructor = viewModel.Instructors.Where(
i => i.ID == id.Value).Single();
viewModel.Courses = instructor.CourseAssignments.Select(s => s.Course);
}

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.

if (courseID != null)
{
ViewData["CourseID"] = courseID.Value;
viewModel.Enrollments = viewModel.Courses.Where(
x => x.CourseID == courseID).Single().Enrollments;
}

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>
<a asp-action="Create">Create New</a>
</p>
<table class="table">
<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)
{
string selectedRow = "";
if (item.ID == (int?)ViewData["InstructorID"])
{
selectedRow = "success";
}
<tr class="@selectedRow">
<td>
@Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
@Html.DisplayFor(modelItem => item.FirstMidName)
</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-action="Index" asp-route-id="@item.ID">Select</a> |
<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>

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.)

@if (item.OfficeAssignment != null)

{
@item.OfficeAssignment.Location
}

Added a Courses column that displays courses taught by each instructor. For more information, see the
Explicit line transition with @: section of the Razor syntax article.
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.

string selectedRow = "";

if (item.ID == (int?)ViewData["InstructorID"])
{
selectedRow = "success";
}
<tr class="@selectedRow">

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.

<a asp-action="Index" asp-route-id="@item.ID">Select</a> |

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>
<table class="table">
<tr>
<th></th>
<th>Number</th>
<th>Title</th>
<th>Department</th>
</tr>

@foreach (var item in Model.Courses)

{
string selectedRow = "";
if (item.CourseID == (int?)ViewData["CourseID"])
{
selectedRow = "success";
}
<tr class="@selectedRow">
<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>
<table class="table">
<tr>
<th>Name</th>
<th>Grade</th>
</tr>
@foreach (var item in Model.Enrollments)
{
<tr>
<td>
@item.Student.FullName
</td>
<td>
@Html.DisplayFor(modelItem => item.Grade)
</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.

About 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();
viewModel.Instructors = await _context.Instructors
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.OrderBy(i => i.LastName)
.ToListAsync();

if (id != null)
{
ViewData["InstructorID"] = id.Value;
Instructor instructor = viewModel.Instructors.Where(
i => i.ID == id.Value).Single();
viewModel.Courses = instructor.CourseAssignments.Select(s => s.Course);
}

if (courseID != null)
{
ViewData["CourseID"] = courseID.Value;
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;
}

return View(viewModel);
}

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.

Get the code

Download or view the completed application.

Next steps
In this tutorial, you:
Learned how to load related data
Created a Courses page
Created an Instructors page
Learned about explicit loading
Advance to the next tutorial to learn how to update related data.
Update related data
 Tutorial: Update related data - ASP.NET MVC with EF
Core
4/26/2019 • 18 minutes to read • Edit Online

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.
In this tutorial, you:
Customize Courses pages
Add Instructors Edit page
Add courses to Edit page
Update Delete page
Add office location and courses to Create page

Prerequisites
Read related data

Customize Courses pages

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:
public IActionResult Create()
{
PopulateDepartmentsDropDownList();
return View();
}

[HttpPost]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Create([Bind("CourseID,Credits,DepartmentID,Title")] Course course)
{
if (ModelState.IsValid)
{
_context.Add(course);
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}
PopulateDepartmentsDropDownList(course.DepartmentID);
return View(course);
}

public async Task<IActionResult> Edit(int? id)

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

var course = await _context.Courses

.AsNoTracking()
.FirstOrDefaultAsync(m => m.CourseID == id);
if (course == null)
{
return NotFound();
}
PopulateDepartmentsDropDownList(course.DepartmentID);
return View(course);
}
 [HttpPost, ActionName("Edit")]
[ValidateAntiForgeryToken]
public async Task<IActionResult> EditPost(int? id)
{
if (id == null)
{
return NotFound();
}

var courseToUpdate = await _context.Courses

.FirstOrDefaultAsync(c => c.CourseID == id);

if (await TryUpdateModelAsync<Course>(courseToUpdate,
"",
c => c.Credits, c => c.DepartmentID, c => c.Title))
{
try
{
await _context.SaveChangesAsync();
}
catch (DbUpdateException /* ex */)
{
//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.");
}
return RedirectToAction(nameof(Index));
}
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:

public IActionResult Create()

{
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:

public async Task<IActionResult> Edit(int? id)

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

var course = await _context.Courses

.AsNoTracking()
.FirstOrDefaultAsync(m => m.CourseID == id);
if (course == null)
{
return NotFound();
}
PopulateDepartmentsDropDownList(course.DepartmentID);
return View(course);
}

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.

public async Task<IActionResult> Details(int? id)

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

var course = await _context.Courses

.Include(c => c.Department)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.CourseID == id);
if (course == null)
{
return NotFound();
}

return View(course);
}
 public async Task<IActionResult> Delete(int? id)
{
if (id == null)
{
return NotFound();
}

var course = await _context.Courses

.Include(c => c.Department)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.CourseID == id);
if (course == null)
{
return NotFound();
}

return View(course);
}

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.

<div class="form-group">
<label asp-for="Department" class="control-label"></label>
<select asp-for="DepartmentID" class="form-control" asp-items="ViewBag.DepartmentID">
<option value="">-- Select Department --</option>
</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.

<div class="form-group">
<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

@{
ViewData["Title"] = "Delete";
}

<h2>Delete</h2>

<h3>Are you sure you want to delete this?</h3>

<div>
<h4>Course</h4>
<hr />
<dl class="row">
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.CourseID)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.CourseID)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Title)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Title)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Credits)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Credits)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Department)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Department.Name)
</dd>
</dl>

<form asp-action="Delete">
<div class="form-actions no-color">
<input type="submit" value="Delete" class="btn btn-default" /> |
<a asp-action="Index">Back to List</a>
</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 Instructors Edit page

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 :
 public async Task<IActionResult> Edit(int? id)
{
if (id == null)
{
return NotFound();
}

var instructor = await _context.Instructors

.Include(i => i.OfficeAssignment)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.ID == id);
if (instructor == null)
{
return NotFound();
}
return View(instructor);
}

Replace the HttpPost Edit method with the following code to handle office assignment updates:

[HttpPost, ActionName("Edit")]
[ValidateAntiForgeryToken]
public async Task<IActionResult> EditPost(int? id)
{
if (id == null)
{
return NotFound();
}

var instructorToUpdate = await _context.Instructors

.Include(i => i.OfficeAssignment)
.FirstOrDefaultAsync(s => s.ID == id);

if (await TryUpdateModelAsync<Instructor>(
instructorToUpdate,
"",
i => i.FirstMidName, i => i.LastName, i => i.HireDate, i => i.OfficeAssignment))
{
if (String.IsNullOrWhiteSpace(instructorToUpdate.OfficeAssignment?.Location))
{
instructorToUpdate.OfficeAssignment = null;
}
try
{
await _context.SaveChangesAsync();
}
catch (DbUpdateException /* ex */)
{
//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.");
}
return RedirectToAction(nameof(Index));
}
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.

if (await TryUpdateModelAsync<Instructor>(
instructorToUpdate,
"",
i => i.FirstMidName, i => i.LastName, i => i.HireDate, i => i.OfficeAssignment))

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.

if (String.IsNullOrWhiteSpace(instructorToUpdate.OfficeAssignment?.Location))
{
instructorToUpdate.OfficeAssignment = null;
}

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:

<div class="form-group">
<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 courses to 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.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Models.SchoolViewModels
{
public class AssignedCourseData
{
public int CourseID { get; set; }
public string Title { get; set; }
public bool Assigned { get; set; }
}
}

In InstructorsController.cs, replace the HttpGet Edit method with the following code. The changes are highlighted.

public async Task<IActionResult> Edit(int? id)

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

var instructor = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments).ThenInclude(i => i.Course)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.ID == id);
if (instructor == null)
{
return NotFound();
}
PopulateAssignedCourseData(instructor);
return View(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]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Edit(int? id, string[] selectedCourses)
{
if (id == null)
{
return NotFound();
}

var instructorToUpdate = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.FirstOrDefaultAsync(m => m.ID == id);

if (await TryUpdateModelAsync<Instructor>(
instructorToUpdate,
"",
i => i.FirstMidName, i => i.LastName, i => i.HireDate, i => i.OfficeAssignment))
{
if (String.IsNullOrWhiteSpace(instructorToUpdate.OfficeAssignment?.Location))
{
instructorToUpdate.OfficeAssignment = null;
}
UpdateInstructorCourses(selectedCourses, instructorToUpdate);
try
{
await _context.SaveChangesAsync();
}
catch (DbUpdateException /* ex */)
{
//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.");
}
return RedirectToAction(nameof(Index));
}
UpdateInstructorCourses(selectedCourses, instructorToUpdate);
PopulateAssignedCourseData(instructorToUpdate);
return View(instructorToUpdate);
}
 private void UpdateInstructorCourses(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.FirstOrDefault(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:
 private void UpdateInstructorCourses(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.FirstOrDefault(i =>
i.CourseID == course.CourseID);
_context.Remove(courseToRemove);
}
}
}
}

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.
 private void UpdateInstructorCourses(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.FirstOrDefault(i =>
i.CourseID == course.CourseID);
_context.Remove(courseToRemove);
}
}
}
}

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.
 private void UpdateInstructorCourses(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.FirstOrDefault(i =>
i.CourseID == course.CourseID);
_context.Remove(courseToRemove);
}
}
}
}

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 might be changed in a way that breaks the code. If the code looks
different after pasting, 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. This problem is fixed in Visual Studio 2019.
 <div class="form-group">
<div class="col-md-offset-2 col-md-10">
<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>
<input type="checkbox"
name="selectedCourses"
value="@course.CourseID"
@(Html.Raw(course.Assigned ? "checked=\"checked\"" : "")) />
@course.CourseID @: @course.Title
@:</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.

Update Delete page

In InstructorsController.cs, delete the DeleteConfirmed method and insert the following code in its place.
 [HttpPost, ActionName("Delete")]
[ValidateAntiForgeryToken]
public async Task<IActionResult> DeleteConfirmed(int id)
{
Instructor instructor = await _context.Instructors
.Include(i => i.CourseAssignments)
.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);

await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}

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 Create page

In InstructorsController.cs, delete the HttpGet and HttpPost Create methods, and then add the following code in
their place:
 public IActionResult Create()
{
var instructor = new Instructor();
instructor.CourseAssignments = new List<CourseAssignment>();
PopulateAssignedCourseData(instructor);
return View();
}

// POST: Instructors/Create
[HttpPost]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Create([Bind("FirstMidName,HireDate,LastName,OfficeAssignment")] Instructor
instructor, string[] selectedCourses)
{
if (selectedCourses != null)
{
instructor.CourseAssignments = new List<CourseAssignment>();
foreach (var course in selectedCourses)
{
var courseToAdd = new CourseAssignment { InstructorID = instructor.ID, CourseID = int.Parse(course)
};
instructor.CourseAssignments.Add(courseToAdd);
}
}
if (ModelState.IsValid)
{
_context.Add(instructor);
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}
PopulateAssignedCourseData(instructor);
return View(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:

instructor.CourseAssignments = new List<CourseAssignment>();

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.

<div class="form-group">
<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>

<div class="form-group">
<div class="col-md-offset-2 col-md-10">
<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>
<input type="checkbox"
name="selectedCourses"
value="@course.CourseID"
@(Html.Raw(course.Assigned ? "checked=\"checked\"" : "")) />
@course.CourseID @: @course.Title
@:</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.
Get the code
Download or view the completed application.

Next steps
In this tutorial, you:
Customized Courses pages
Added Instructors Edit page
Added courses to Edit page
Updated Delete page
Added office location and courses to Create page
Advance to the next tutorial to learn how to handle concurrency conflicts.
Handle concurrency conflicts
 Tutorial: Handle concurrency - ASP.NET MVC with EF
Core
6/17/2019 • 18 minutes to read • Edit Online

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.
In this tutorial, you:
Learn about concurrency conflicts
Add a tracking property
Create Departments controller and views
Update Index view
Update Edit methods
Update Edit view
Test concurrency conflicts
Update the Delete page
Update Details and Create views

Prerequisites
Update related data

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
In Models/Department.cs, add a tracking property named RowVersion:

using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Department
{
public int DepartmentID { get; set; }

[StringLength(50, MinimumLength = 3)]

public string Name { get; set; }

[DataType(DataType.Currency)]
[Column(TypeName = "money")]
public decimal Budget { get; set; }

[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Start Date")]
public DateTime StartDate { get; set; }

public int? InstructorID { get; set; }

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

public Instructor Administrator { get; set; }

public ICollection<Course> Courses { 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:

modelBuilder.Entity<Department>()
.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

dotnet ef database update

Create 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 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>
<a asp-action="Create">Create New</a>
</p>
<table class="table">
<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>
@foreach (var item in Model)
{
<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>
<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 Edit methods

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
.Include(i => i.Administrator)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.DepartmentID == id);

Replace the existing code for the HttpPost Edit method with the following code:

[HttpPost]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Edit(int? id, byte[] rowVersion)
{
if (id == null)
{
return NotFound();
}

var departmentToUpdate = await _context.Departments.Include(i => i.Administrator).FirstOrDefaultAsync(m =>

m.DepartmentID == id);

if (departmentToUpdate == null)
{
Department deletedDepartment = new Department();
await TryUpdateModelAsync(deletedDepartment);
ModelState.AddModelError(string.Empty,
"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;

if (await TryUpdateModelAsync<Department>(
departmentToUpdate,
"",
s => s.Name, s => s.StartDate, s => s.Budget, s => s.InstructorID))
{
try
{
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}
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 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.FirstOrDefaultAsync(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 "
+ "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. 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 FirstOrDefaultAsync 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.

var exceptionEntry = ex.Entries.Single();

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.

var clientValues = (Department)exceptionEntry.Entity;

var databaseEntry = exceptionEntry.GetDatabaseValues();

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 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

@{
ViewData["Title"] = "Edit";
}

<h2>Edit</h2>

<h4>Department</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form asp-action="Edit">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<input type="hidden" asp-for="DepartmentID" />
<input type="hidden" asp-for="RowVersion" />
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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 class="form-group">
<input type="submit" value="Save" class="btn btn-default" />
</div>
</form>
</div>
</div>

<div>
<a asp-action="Index">Back to List</a>
</div>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

Test concurrency conflicts

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.

Update the Delete page

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();
}

var department = await _context.Departments

.Include(d => d.Administrator)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.DepartmentID == id);
if (department == null)
{
if (concurrencyError.GetValueOrDefault())
{
return RedirectToAction(nameof(Index));
}
return NotFound();
}

if (concurrencyError.GetValueOrDefault())
{
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]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Delete(Department department)
{
try
{
if (await _context.Departments.AnyAsync(m => m.DepartmentID == department.DepartmentID))
{
_context.Departments.Remove(department);
await _context.SaveChangesAsync();
}
return RedirectToAction(nameof(Index));
}
catch (DbUpdateConcurrencyException /* ex */)
{
//Log the error (uncomment ex variable name and write a log.)
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:
 public async Task<IActionResult> DeleteConfirmed(int 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.
 @model ContosoUniversity.Models.Department

@{
ViewData["Title"] = "Delete";
}

<h2>Delete</h2>

<p class="text-danger">@ViewData["ConcurrencyErrorMessage"]</p>

<h3>Are you sure you want to delete this?</h3>

<div>
<h4>Department</h4>
<hr />
<dl class="row">
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Name)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Name)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Budget)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Budget)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.StartDate)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.StartDate)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Administrator)
</dt>
<dd class="col-sm-10">
@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 class="form-actions no-color">
<input type="submit" value="Delete" class="btn btn-default" /> |
<a asp-action="Index">Back to List</a>
</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.
 @model ContosoUniversity.Models.Department

@{
ViewData["Title"] = "Details";
}

<h2>Details</h2>

<div>
<h4>Department</h4>
<hr />
<dl class="row">
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Name)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Name)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Budget)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Budget)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.StartDate)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.StartDate)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Administrator)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Administrator.FullName)
</dd>
</dl>
</div>
<div>
<a asp-action="Edit" asp-route-id="@Model.DepartmentID">Edit</a> |
<a asp-action="Index">Back to List</a>
</div>

Replace the code in Views/Departments/Create.cshtml to add a Select option to the drop-down list.
 @model ContosoUniversity.Models.Department

@{
ViewData["Title"] = "Create";
}

<h2>Create</h2>

<h4>Department</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form asp-action="Create">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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 class="form-group">
<input type="submit" value="Create" class="btn btn-default" />
</div>
</form>
</div>
</div>

<div>
<a asp-action="Index">Back to List</a>
</div>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

Get the code

Download or view the completed application.

Additional resources
For more information about how to handle concurrency in EF Core, see Concurrency conflicts.

Next steps
In this tutorial, you:
Learned about concurrency conflicts
 Added a tracking property
Created Departments controller and views
Updated Index view
Updated Edit methods
Updated Edit view
Tested concurrency conflicts
Updated the Delete page
Updated Details and Create views
Advance to the next tutorial to learn how to implement table-per-hierarchy inheritance for the Instructor and
Student entities.
Next: Implement table-per-hierarchy inheritance
 Tutorial: Implement inheritance - ASP.NET MVC with
EF Core
4/26/2019 • 8 minutes to read • Edit Online

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.
In this tutorial, you:
Map inheritance to database
Create the Person class
Update Instructor and Student
Add Person to the model
Create and update migrations
Test the implementation

Prerequisites
Handle Concurrency

Map inheritance to database

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:

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public abstract class Person
{
public int ID { get; set; }

[Required]
[StringLength(50)]
[Display(Name = "Last Name")]
public string LastName { get; set; }
[Required]
[StringLength(50, ErrorMessage = "First name cannot be longer than 50 characters.")]
[Column("FirstName")]
[Display(Name = "First Name")]
public string FirstMidName { get; set; }

[Display(Name = "Full Name")]

public string FullName
{
get
{
return LastName + ", " + FirstMidName;
}
}
}
}

Update Instructor and Student

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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Instructor : Person
{
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Hire Date")]
public DateTime HireDate { get; set; }

public ICollection<CourseAssignment> CourseAssignments { get; set; }

public OfficeAssignment OfficeAssignment { get; set; }
}
}

Make the same changes in Student.cs.

using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Student : Person
{
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Enrollment Date")]
public DateTime EnrollmentDate { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }

}
}

Add Person to the model

Add the Person entity type to SchoolContext.cs. The new lines are highlighted.
 using ContosoUniversity.Models;
using Microsoft.EntityFrameworkCore;

namespace ContosoUniversity.Data
{
public class SchoolContext : DbContext
{
public SchoolContext(DbContextOptions<SchoolContext> options) : base(options)
{
}

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

public DbSet<Enrollment> Enrollments { get; set; }
public DbSet<Student> Students { 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; }
public DbSet<Person> People { 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<Person>().ToTable("Person");

modelBuilder.Entity<CourseAssignment>()
.HasKey(c => new { c.CourseID, c.InstructorID });
}
}
}

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 update migrations

Save your changes and build the project. Then open the command window in the project folder and enter the
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:
 protected override void Up(MigrationBuilder migrationBuilder)
{
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");

migrationBuilder.DropTable(
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",
principalColumn: "ID",
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:

dotnet ef database update

(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 the implementation

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.
Get the code
Download or view the completed application.

Additional resources
For more information about inheritance in Entity Framework Core, see Inheritance.

Next steps
In this tutorial, you:
Mapped inheritance to database
Created the Person class
Updated Instructor and Student
Added Person to the model
Created and update migrations
Tested the implementation
Advance to the next tutorial to learn how to handle a variety of relatively advanced Entity Framework scenarios.
Next: Advanced topics
 Tutorial: Learn about advanced scenarios - ASP.NET
MVC with EF Core
8/13/2019 • 13 minutes to read • Edit Online

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.
In this tutorial, you:
Perform raw SQL queries
Call a query to return entities
Call a query to return other types
Call an update query
Examine SQL queries
Create an abstraction layer
Learn about Automatic change detection
Learn about EF Core source code and development plans
Learn how to use dynamic LINQ to simplify code

Prerequisites
Implement Inheritance

Perform 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 to return entities

The DbSet<TEntity> class provides a method that you can use to execute a query that returns an entity of type
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:

public async Task<IActionResult> Details(int? id)

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

string query = "SELECT * FROM Department WHERE DepartmentID = {0}";

var department = await _context.Departments
.FromSql(query, id)
.Include(d => d.Administrator)
.AsNoTracking()
.FirstOrDefaultAsync();

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 to return 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 CoursesController.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 Core under Installed in the left pane, click Razor View, 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">
<div class="form-actions no-color">
<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 queries

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.

Create an abstraction layer

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;

EF 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 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.
 public async Task<IActionResult> Index(
string sortOrder,
string currentFilter,
string searchString,
int? pageNumber)
{
ViewData["CurrentSort"] = sortOrder;
ViewData["NameSortParm"] =
String.IsNullOrEmpty(sortOrder) ? "LastName_desc" : "";
ViewData["DateSortParm"] =
sortOrder == "EnrollmentDate" ? "EnrollmentDate_desc" : "EnrollmentDate";

if (searchString != null)
{
pageNumber = 1;
}
else
{
searchString = currentFilter;
}

ViewData["CurrentFilter"] = searchString;

var students = from s in _context.Students

select s;

if (!String.IsNullOrEmpty(searchString))
{
students = students.Where(s => s.LastName.Contains(searchString)
|| s.FirstMidName.Contains(searchString));
}

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(),
pageNumber ?? 1, pageSize));
}

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. John Parente and Paul Goldman worked on updating the tutorial for ASP.NET
Core 2.2.
Troubleshoot 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:

dotnet ef database drop

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.

Get the code

Download or view the completed application.
Additional resources
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 ASP.NET Core.
For information about other topics related to ASP.NET Core MVC, such as authentication and authorization, see
Introduction to ASP.NET Core.

Next steps
In this tutorial, you:
Performed raw SQL queries
Called a query to return entities
Called a query to return other types
Called an update query
Examined SQL queries
Created an abstraction layer
Learned about Automatic change detection
Learned about EF Core source code and development plans
Learned how to use dynamic LINQ to simplify code
This completes this series of tutorials on using the Entity Framework Core in an ASP.NET Core MVC application.
This series worked with a new database; an alternative is to reverse engineer a model from an existing database.
Tutorial: EF Core with MVC, existing database
 ASP.NET Core fundamentals
7/12/2019 • 9 minutes to read • Edit Online

This article is an overview of key topics for understanding how to develop ASP.NET Core apps.

The Startup class

The Startup class is where:
Services required by the app are configured.
The request handling pipeline is defined.
Services are components that are used by the app. For example, a logging component is a service. Code to
configure (or register) services is added to the Startup.ConfigureServices method.
The request handling pipeline is composed as a series of middleware components. For example, a middleware
might handle requests for static files or redirect HTTP requests to HTTPS. Each middleware performs
asynchronous operations on an HttpContext and then either invokes the next middleware in the pipeline or
terminates the request. Code to configure the request handling pipeline is added to the Startup.Configure
method.
Here's a sample Startup class:

public class Startup

{
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

services.AddDbContext<MovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("MovieDb")));
}

public void Configure(IApplicationBuilder app)

{
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseMvc();
}
}

For more information, see App startup in ASP.NET Core.

Dependency injection (services)

ASP.NET Core has a built-in dependency injection (DI) framework that makes configured services available to an
app's classes. One way to get an instance of a service in a class is to create a constructor with a parameter of the
required type. The parameter can be the service type or an interface. The DI system provides the service at
runtime.
Here's a class that uses DI to get an Entity Framework Core context object. The highlighted line is an example of
constructor injection:
 public class IndexModel : PageModel
{
private readonly RazorPagesMovieContext _context;

public IndexModel(RazorPagesMovieContext context)

{
_context = context;
}
// ...
public async Task OnGetAsync()
{
var movies = from m in _context.Movies
select m;
Movies = await movies.ToListAsync();
}
}

While DI is built in, it's designed to let you plug in a third-party Inversion of Control (IoC ) container if you prefer.
For more information, see Dependency injection in ASP.NET Core.

Middleware
The request handling pipeline is composed as a series of middleware components. Each component 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 is added to the pipeline by invoking its Use... extension method in the
Startup.Configure method. For example, to enable rendering of static files, call UseStaticFiles .

The highlighted code in the following example configures the request handling pipeline:

public class Startup

{
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

services.AddDbContext<MovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("MovieDb")));
}

public void Configure(IApplicationBuilder app)

{
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseMvc();
}
}

ASP.NET Core includes a rich set of built-in middleware, and you can write custom middleware.
For more information, see ASP.NET Core Middleware.

Host
An ASP.NET Core app builds a host on startup. The host is an object that encapsulates all of the app's resources,
such as:
An HTTP server implementation
 Middleware components
Logging
DI
Configuration
The main reason for including all of the app's interdependent resources in one object is lifetime management:
control over app startup and graceful shutdown.
Two hosts are available: the Generic Host and the Web Host. The Generic Host is recommended, and the Web
Host is available only for backwards compatibility.
The code to create a host is in Program.Main :

public class Program

{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}

The CreateDefaultBuilder and ConfigureWebHostDefaults methods configure a host with commonly used options,
such as the following:
Use Kestrel as the web server and enable IIS integration.
Load configuration from appsettings.json, appsettings.{Environment Name}.json, environment variables,
command line arguments, and other configuration sources.
Send logging output to the console and debug providers.
For more information, see .NET Generic Host.
Two hosts are available: the Web Host and the Generic Host. In ASP.NET Core 2.x, the Generic Host is only for
non-web scenarios.
The code to create a host is in Program.Main :

public class Program

{
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>();
}

The CreateDefaultBuilder method configures a host with commonly used options, such as the following:
Use Kestrel as the web server and enable IIS integration.
Load configuration from appsettings.json, appsettings.{Environment Name}.json, environment variables,
 command line arguments, and other configuration sources.
Send logging output to the console and debug providers.
For more information, see ASP.NET Core Web Host.
Non-web scenarios
The Generic Host allows other types of apps to use cross-cutting framework extensions, such as logging,
dependency injection (DI), configuration, and app lifetime management. For more information, see .NET Generic
Host and Background tasks with hosted services in ASP.NET Core.

Servers
An ASP.NET Core app uses an HTTP server implementation to listen for HTTP requests. The server surfaces
requests to the app as a set of request features composed into an HttpContext .
Windows
macOS
Linux
ASP.NET Core provides the following server implementations:
Kestrel is a cross-platform web server. Kestrel is often run in a reverse proxy configuration using IIS. In
ASP.NET Core 2.0 or later, Kestrel can be run as a public-facing edge server exposed directly to the Internet.
IIS HTTP Server is a server for windows that uses IIS. With this server, the ASP.NET Core app and IIS run in
the same process.
HTTP.sys is a server for Windows that isn't used with IIS.
Windows
macOS
Linux
ASP.NET Core provides the following server implementations:
Kestrel is a cross-platform web server. Kestrel is often run in a reverse proxy configuration using IIS. In
ASP.NET Core 2.0 or later, Kestrel can be run as a public-facing edge server exposed directly to the Internet.
HTTP.sys is a server for Windows that isn't used with IIS.
For more information, see Web server implementations in ASP.NET Core.

Configuration
ASP.NET Core provides a configuration framework that gets settings as name-value pairs from an ordered set of
configuration providers. There are built-in configuration providers for a variety of sources, such as .json files, .xml
files, environment variables, and command-line arguments. You can also write custom configuration providers.
For example, you could specify that configuration comes from appsettings.json and environment variables. Then
when the value of ConnectionString is requested, the framework looks first in the appsettings.json file. If the value
is found there but also in an environment variable, the value from the environment variable would take
precedence.
For managing confidential configuration data such as passwords, ASP.NET Core provides a Secret Manager tool.
For production secrets, we recommend Azure Key Vault.
For more information, see Configuration in ASP.NET Core.

Options
Where possible, ASP.NET Core follows the options pattern for storing and retrieving configuration values. The
options pattern uses classes to represent groups of related settings.
For example, the following code sets WebSockets options:

var options = new WebSocketOptions

{
KeepAliveInterval = TimeSpan.FromSeconds(120),
ReceiveBufferSize = 4096
};
app.UseWebSockets(options);

For more information, see Options pattern in ASP.NET Core.

Environments
Execution environments, such as Development, Staging, and Production, are a first-class notion in ASP.NET Core.
You can specify the environment an app is running in by setting the ASPNETCORE_ENVIRONMENT environment variable.
ASP.NET Core reads that environment variable at app startup and stores the value in an IHostingEnvironment
implementation. The environment object is available anywhere in the app via DI.
The following sample code from the Startup class configures the app to provide detailed error information only
when it runs in development:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseMvc();
}

For more information, see Use multiple environments in ASP.NET Core.

Logging
ASP.NET Core supports a logging API that works with a variety of built-in and third-party logging providers.
Available providers include the following:
Console
Debug
Event Tracing on Windows
Windows Event Log
TraceSource
Azure App Service
Azure Application Insights
Write logs from anywhere in an app's code by getting an ILogger object from DI and calling log methods.
Here's sample code that uses an ILogger object, with constructor injection and the logging method calls
highlighted.

public class TodoController : ControllerBase

{
private readonly ILogger _logger;

public TodoController(ILogger<TodoController> logger)

{
_logger = logger;
}

[HttpGet("{id}", Name = "GetTodo")]

public ActionResult<TodoItem> GetById(string id)
{
_logger.LogInformation(LoggingEvents.GetItem, "Getting item {ID}", id);
// Item lookup code removed.
if (item == null)
{
_logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({ID}) NOT FOUND", id);
return NotFound();
}
return item;
}
}

The ILogger interface lets you pass any number of fields to the logging provider. The fields are commonly used to
construct a message string, but the provider can also send them as separate fields to a data store. This feature
makes it possible for logging providers to implement semantic logging, also known as structured logging.
For more information, see Logging in .NET Core and ASP.NET Core.

Routing
A route is a URL pattern that is mapped to a handler. The handler is typically a Razor page, an action method in an
MVC controller, or a middleware. ASP.NET Core routing gives you control over the URLs used by your app.
For more information, see Routing in ASP.NET Core.

Error handling
ASP.NET Core has built-in features for handling errors, such as:
A developer exception page
Custom error pages
Static status code pages
Startup exception handling
For more information, see Handle errors in ASP.NET Core.

Make HTTP requests

An implementation of IHttpClientFactory is available for creating HttpClient instances. The factory:
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.
Supports registration and chaining of multiple delegating handlers to build an outgoing request middleware
pipeline. 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.
Integrates with Polly, a popular third-party library for transient fault handling.
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.
For more information, see Make HTTP requests using IHttpClientFactory in ASP.NET Core.

Content root
The content root is the base path to any private content used by the app, such as its Razor files. By default, the
content root is the base path for the executable hosting the app. An alternative location can be specified when
building the host.
For more information, see Content root.
For more information, see Content root.

Web root
The web root (also known as webroot) is the base path to public, static resources, such as CSS, JavaScript, and
image files. The static files middleware will only serve files from the web root directory (and sub-directories) by
default. The web root path defaults to {Content Root}/wwwroot, but a different location can be specified when
building the host.
In Razor (.cshtml) files, the tilde-slash ~/ points to the web root. Paths beginning with ~/ are referred to as
virtual paths.
For more information, see Static files in ASP.NET Core.
 App startup in ASP.NET Core
8/9/2019 • 8 minutes to read • Edit Online

By Rick Anderson, Tom Dykstra, Luke Latham, and Steve Smith

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:
Optionally includes a ConfigureServices method to configure the app's services. A service is a reusable
component that provides app functionality. Services are configured—also described as registered—in
ConfigureServices and consumed across the app via dependency injection ( DI ) or ApplicationServices.
Includes a Configure method to create the app's request processing pipeline.
ConfigureServices and Configure are called by the ASP.NET Core runtime when the app starts:

public class Startup

{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}

public IConfiguration Configuration { get; }

public void ConfigureServices(IServiceCollection services)

{
services.AddRazorPages();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)

{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}

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

app.UseRouting();

app.UseAuthorization();

app.UseEndpoints(endpoints =>
{
endpoints.MapRazorPages();
});
}
}
The preceding sample is for Razor Pages; the MVC version is similar.

public class Startup

{
// Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
...
}

// Use this method to configure the HTTP request pipeline.

public void Configure(IApplicationBuilder app)
{
...
}
}

The class is specified when the app's host is built. The Startup class is typically specified by calling the
Startup
WebHostBuilderExtensions.UseStartup<TStartup> method on the host builder:

public class Program

{
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>();
}

public class Program

{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}

The host provides services that are available to the Startup class constructor. The app adds additional services
via ConfigureServices . Both the host and app services are available in Configure and throughout the app.
Only the following service types can be injected into the Startup constructor when using IHostBuilder:
IWebHostEnvironment
IHostEnvironment
IConfiguration
 public class Startup
{
private readonly IWebHostEnvironment _env;
public IConfiguration Configuration { get; }

public Startup(IWebHostEnvironment env, IConfiguration configuration)

{
Configuration = configuration;
_env = env;
}

public void ConfigureServices(IServiceCollection services)

{
if (_env.IsDevelopment())
{
}
else
{
}
// _config["key"]
}
}

Most services are not available until the Configure method is called.
The host provides 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 .
 public class Startup
{
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;
}

public void ConfigureServices(IServiceCollection services)

{
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 IWebHostEnvironment is to use a conventions-based approach.

An alternative to injecting IHostingEnvironment is to use a conventions-based approach.
When the app defines separate Startup classes for different environments (for example, StartupDevelopment ),
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.
See The host for more information on the host. For information on handling errors during startup, see Startup
exception handling.

The ConfigureServices method

The ConfigureServices method is:
Optional.
Called by the host before the Configure method to configure the app's services.
Where configuration options are set by convention.
The host may configure some services before Startup methods are called. For more information, see The host.
For features that require substantial setup, there are Add{Service} extension methods on IServiceCollection.
For example, AddDbContext, AddDefaultIdentity, AddEntityFrameworkStores, and AddRazorPages:
[!code-csharp[](startup/3.0_samples/StartupFilterSample/StartupIdentity.cs ?name=snippet)]

public void ConfigureServices(IServiceCollection services)

{
services.AddDbContext<ApplicationDbContext>(options =>
options.UseSqlServer(
Configuration.GetConnectionString("DefaultConnection")));
services.AddDefaultIdentity<IdentityUser>()
.AddDefaultUI(UIFramework.Bootstrap4)
.AddEntityFrameworkStores<ApplicationDbContext>();

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

// Add application services.

services.AddTransient<IEmailSender, AuthMessageSender>();
services.AddTransient<ISmsSender, AuthMessageSender>();
}

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 ApplicationServices.
See SetCompatibilityVersion for more information on SetCompatibilityVersion .

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:
Developer Exception Page
Exception handler
HTTP Strict Transport Security (HSTS )
HTTPS redirection
Static files
ASP.NET Core MVC and Razor Pages
General Data Protection Regulation (GDPR )
 public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}

public IConfiguration Configuration { get; }

public void ConfigureServices(IServiceCollection services)

{
services.AddRazorPages();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)

{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}

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

app.UseRouting();

app.UseAuthorization();

app.UseEndpoints(endpoints =>
{
endpoints.MapRazorPages();
});
}
}

The preceding sample is for Razor Pages; the MVC version is similar.

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}

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

app.UseMvc();
}

Each Use extension method adds one or more middleware components to the request pipeline. For instance,
UseStaticFiles configures middleware to serve static files.
Each middleware component in the request pipeline is responsible for invoking the next component in the
pipeline or short-circuiting the chain, if appropriate.
Additional services, such as IWebHostEnvironment , ILoggerFactory , or anything defined in ConfigureServices ,
can be specified in the Configure method signature. These services are injected if they're available.
Additional services, such as IHostingEnvironment and ILoggerFactory , or anything defined in
ConfigureServices , can be specified in the Configure method signature. These services are injected if they're
available.
For more information on how to use IApplicationBuilder and the order of middleware processing, see
ASP.NET Core Middleware.

Configure services without Startup

To configure services and the request processing pipeline without using a Startup class, call ConfigureServices
and Configure convenience methods on the host builder. Multiple calls to ConfigureServices append to one
another. If multiple Configure method calls exist, the last Configure call is used.

public class Program

{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureAppConfiguration((hostingContext, config) =>
{
})
.ConfigureServices(services =>
{
services.AddControllersWithViews();

}).ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.Configure(app =>
{
var loggerFactory = app.ApplicationServices
.GetRequiredService<ILoggerFactory>();
var logger = loggerFactory.CreateLogger<Program>();
var env = app.ApplicationServices.GetRequiredService<IWebHostEnvironment>();
var config = app.ApplicationServices.GetRequiredService<IConfiguration>();

logger.LogInformation("Logged in Configure");

if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Home/Error");
app.UseHsts();
}

var configValue = config["MyConfigKey"];

}
);
});
}
 public class Program
{
public static IHostingEnvironment HostingEnvironment { get; set; }
public static IConfiguration Configuration { get; set; }

public static void Main(string[] args)

{
CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.ConfigureAppConfiguration((hostingContext, config) =>
{
})
.ConfigureServices(services =>
{
...
})
.Configure(app =>
{
var loggerFactory = app.ApplicationServices
.GetRequiredService<ILoggerFactory>();
var logger = loggerFactory.CreateLogger<Program>();
var env = app.ApplicationServices.GetRequiredService<IHostingEnvironment>();
var config = app.ApplicationServices.GetRequiredService<IConfiguration>();

logger.LogInformation("Logged in Configure");

if (env.IsDevelopment())
{
...
}
else
{
...
}

var configValue = config["subsection:suboption1"];

...
});
}

Extend Startup with startup filters

Use IStartupFilter to configure middleware at the beginning or end of an app's Configure middleware pipeline.
IStartupFilter is used to create a pipeline of Configure methods. IStartupFilter.Configure can set a
middleware to run before or after middleware added by libraries.
IStartupFilter implements 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 can add 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 following example demonstrates how to register a middleware with IStartupFilter . The
RequestSetOptionsMiddleware middleware sets an options value from a query string parameter:
 public class RequestSetOptionsMiddleware
{
private readonly RequestDelegate _next;

public RequestSetOptionsMiddleware( RequestDelegate next )

{
_next = next;
}

// Test with https://localhost:5001/Privacy/?option=Hello

public async Task Invoke(HttpContext httpContext)
{
var option = httpContext.Request.Query["option"];

if (!string.IsNullOrWhiteSpace(option))
{
httpContext.Items["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);
};
}
}

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 ConfigureServices.

public class Program

{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureAppConfiguration((hostingContext, config) =>
{
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
})
.ConfigureServices(services =>
{
services.AddTransient<IStartupFilter,
RequestSetOptionsStartupFilter>();
});
}

WebHost.CreateDefaultBuilder(args)
.ConfigureServices(services =>
{
services.AddTransient<IStartupFilter,
RequestSetOptionsStartupFilter>();
})
.UseStartup<Startup>()
.Build();

When a query string parameter for option is provided, the middleware processes the value assignment before
the ASP.NET Core 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 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 Use hosting startup assemblies in
ASP.NET Core.

Additional resources
The host
Use multiple environments in ASP.NET Core
ASP.NET Core Middleware
Logging in .NET Core and ASP.NET Core
Configuration in ASP.NET Core
 Dependency injection in ASP.NET Core
8/6/2019 • 16 minutes to read • Edit Online

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.
View or download sample code (how to download)

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:

public class IndexModel : PageModel

{
MyDependency _dependency = new MyDependency();

public async Task OnGetAsync()

{
await _dependency.WriteMessage(
"IndexModel.OnGetAsync created this message.");
}
}

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 or base class 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);
}

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;
}

public Task WriteMessage(string message)

{
_logger.LogInformation(
"MyDependency.WriteMessage called. Message: {MESSAGE}",
message);

return Task.FromResult(0);
}
}

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.
The container resolves ILogger<TCategoryName> by taking advantage of (generic) open types,
eliminating the need to register every (generic) constructed type:
 services.AddSingleton(typeof(ILogger<T>), typeof(Logger<T>));

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.

public void ConfigureServices(IServiceCollection services)

{
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

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>();
}

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 built in type, such as a string , the type can be injected
by using configuration or the options pattern:

public class MyDependency : IMyDependency

{
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:
 public class IndexModel : PageModel
{
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; }

public async Task OnGetAsync()

{
await _myDependency.WriteMessage(
"IndexModel.OnGetAsync created this message.");
}
}

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
 SERVICE TYPE LIFETIME

Microsoft.Extensions.Logging.ILogger<TCategory Singleton
Name>

Microsoft.Extensions.Logging.ILoggerFactory Singleton

Microsoft.Extensions.ObjectPool.ObjectPoolProvid Singleton
er

Microsoft.Extensions.Options.IConfigureOptions<T Transient
Options>

Microsoft.Extensions.Options.IOptions<TOptions> 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<TContext>, AddIdentityCore, and AddMvc:

public void ConfigureServices(IServiceCollection services)

{
services.AddDbContext<ApplicationDbContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")));

services.AddIdentity<ApplicationUser, IdentityRole>()
.AddEntityFrameworkStores<ApplicationDbContext>()
.AddDefaultTokenProviders();

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 ( AddTransient) are created each time they're requested from the
service container. This lifetime works best for lightweight, stateless services.
Scoped
Scoped lifetime services ( AddScoped) are created once per client request (connection).
 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 ( AddSingleton) are created the first time they're requested (or
when Startup.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.

Service registration methods

Each service registration extension method offers overloads that are useful in specific
scenarios.

AUTOMATIC
OBJECT MULTIPLE
METHOD DISPOSAL IMPLEMENTATIONS PASS ARGS

Add{LIFETIME} Yes Yes No

<{SERVICE},
{IMPLEMENTATION}>
()
Example:
services.AddScoped<IMyDep,
MyDep>();

Add{LIFETIME} Yes Yes Yes

<{SERVICE}>(sp =>
new
{IMPLEMENTATION})
Examples:
services.AddScoped<IMyDep>
(sp => new MyDep());
services.AddScoped<IMyDep>
(sp => new MyDep("A
string!"));

Add{LIFETIME} Yes No No
<{IMPLEMENTATION}>
()
Example:
services.AddScoped<MyDep>
();
 AUTOMATIC
OBJECT MULTIPLE
METHOD DISPOSAL IMPLEMENTATIONS PASS ARGS

Add{LIFETIME} No Yes Yes

<{SERVICE}>(new
{IMPLEMENTATION})
Examples:
services.AddScoped<IMyDep>
(new MyDep());
services.AddScoped<IMyDep>
(new MyDep("A string!"));

Add{LIFETIME}(new No No Yes
{IMPLEMENTATION})
Examples:
services.AddScoped(new
MyDep());
services.AddScoped(new
MyDep("A string!"));

For more information on type disposal, see the Disposal of services section. A common
scenario for multiple implementations is mocking types for testing.
TryAdd{LIFETIME} methods only register the service if there isn't already an implementation
registered.
In the following example, the first line registers MyDependency for IMyDependency . The second
line has no effect because IMyDependency already has a registered implementation:

services.AddSingleton<IMyDependency, MyDependency>();
// The following line has no effect:
services.TryAddSingleton<IMyDependency, DifferentDependency>();

For more information, see:

TryAdd
TryAddTransient
TryAddScoped
TryAddSingleton
TryAddEnumerable(ServiceDescriptor) methods only register the service if there isn't already
an implementation of the same type. Multiple services are resolved via
IEnumerable<{SERVICE}> . When registering services, the developer only wants to add an
instance if one of the same type hasn't already been added. Generally, this method is used by
library authors to avoid registering two copies of an instance in the container.
In the following example, the first line registers MyDep for IMyDep1 . The second line registers
MyDep for IMyDep2 . The third line has no effect because IMyDep1 already has a registered
implementation of MyDep :
 public interface IMyDep1 {}
public interface IMyDep2 {}

public class MyDep : IMyDep1, IMyDep2 {}

services.TryAddEnumerable(ServiceDescriptor.Singleton<IMyDep1, MyDep>());
services.TryAddEnumerable(ServiceDescriptor.Singleton<IMyDep2, MyDep>());
// Two registrations of MyDep for IMyDep1 is avoided by the following line:
services.TryAddEnumerable(ServiceDescriptor.Singleton<IMyDep1, MyDep>());

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 exists. 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 are usually added to the service container using the scoped
lifetime because web app database operations are normally scoped to the client request. The
default lifetime is scoped if a lifetime isn't specified by an AddDbContext<TContext> overload
when registering the database context. Services of a given lifetime shouldn't use a database
context with a shorter lifetime than the service.

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

{
}

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; }

}

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.
When transient services are created when requested from the container, the OperationId
of the IOperationTransient service is different than the OperationId of the
OperationService . OperationService receives a new instance of the IOperationTransient
class. The new instance yields a different OperationId .
When scoped services are created per client request, the OperationId of the
IOperationScoped service is the same as that of OperationService within a client request.
Across client requests, both services share a different OperationId value.
When singleton and singleton-instance services are created once and used across all client
requests and all services, the OperationId is constant across all service requests.
 public class OperationService
{
public OperationService(
IOperationTransient transientOperation,
IOperationScoped scopedOperation,
IOperationSingleton singletonOperation,
IOperationSingletonInstance instanceOperation)
{
TransientOperation = transientOperation;
ScopedOperation = scopedOperation;
SingletonOperation = singletonOperation;
SingletonInstanceOperation = instanceOperation;
}

public IOperationTransient TransientOperation { get; }

public IOperationScoped ScopedOperation { get; }
public IOperationSingleton SingletonOperation { get; }
public IOperationSingletonInstance SingletonInstanceOperation { get; }
}

In Startup.ConfigureServices , each type is added to the container according to its named

lifetime:

public void ConfigureServices(IServiceCollection services)

{
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

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>();
}

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 class IndexModel : PageModel
{
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; }

public async Task OnGetAsync()

{
await _myDependency.WriteMessage(
"IndexModel.OnGetAsync created this message.");
}
}

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
Singleton: 01271bc1-9e31-48e7-8f7c-7261b040ded9
Instance: 00000000-0000-0000-0000-000000000000
Second request:
Controller operations:
Transient: b63bd538-0a37-4ff1-90ba-081c5138dda0
Scoped: 31e820c5-4834-4d22-83fc-a60118acb9f4
Singleton: 01271bc1-9e31-48e7-8f7c-7261b040ded9
Instance: 00000000-0000-0000-0000-000000000000
OperationService operations:
Transient: c4cbacb8-36a2-436d-81c8-8c1b78808aaf
Scoped: 31e820c5-4834-4d22-83fc-a60118acb9f4
Singleton: 01271bc1-9e31-48e7-8f7c-7261b040ded9
Instance: 00000000-0000-0000-0000-000000000000
Observe which of the OperationId values vary within a request and between requests:
Transient objects are always different. The transient OperationId value for both the first
and second client requests are different for both OperationService operations and across
client requests. A new instance is provided to each service request and client request.
Scoped objects are the same within a client request but different across client requests.
Singleton objects are the same for every object and every request regardless of whether an
Operation instance is provided in Startup.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 :

public static void Main(string[] args)

{
var host = CreateWebHostBuilder(args).Build();

using (var serviceScope = host.Services.CreateScope())

{
var services = serviceScope.ServiceProvider;

try
{
var serviceContext = services.GetRequiredService<MyScopedService>();
// Use the context here
}
catch (Exception ex)
{
var logger = services.GetRequiredService<ILogger<Program>>();
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.

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.
Avoid direct instantiation of dependent classes within services. Direct instantiation couples
the code to a particular implementation.
Make app classes 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 class Service2 : IDisposable {}
public class Service3 : IDisposable {}

public interface ISomeService {}

public class SomeServiceImplementation : ISomeService, IDisposable {}

public void ConfigureServices(IServiceCollection services)

{
// 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());
}

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
Create thread-safe singleton services. If a singleton service has a dependency on a transient
service, the transient service may also require thread safety 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
and Task based service resolution is not supported. C# does not support
async/await
asynchronous constructors; therefore, the recommended pattern is to use
asynchronous methods after synchronously resolving the service.
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 DI.
Avoid static access to services (for example, statically-typing
IApplicationBuilder.ApplicationServices for use elsewhere).
Avoid using the service locator pattern. For example, don't invoke GetService to obtain
a service instance when you can use DI instead:
Incorrect:

public class MyClass()

{
public void MyMethod()
{
var optionsMonitor =
_services.GetService<IOptionsMonitor<MyOptions>>();
var option = optionsMonitor.CurrentValue.Option;

...
}
}

Correct:
 public class MyClass
{
private readonly IOptionsMonitor<MyOptions> _optionsMonitor;

public MyClass(IOptionsMonitor<MyOptions> optionsMonitor)

{
_optionsMonitor = optionsMonitor;
}

public void MyMethod()

{
var option = _optionsMonitor.CurrentValue.Option;

...
}
}

Another service locator variation to avoid is injecting a factory that resolves

dependencies at runtime. Both of these practices mix Inversion of Control strategies.
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.
DI is an alternative to static/global object access patterns. You may not be able to realize the
benefits of DI if you mix it with static object access.

Additional resources
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
ASP.NET Core Blazor dependency injection
App startup in ASP.NET Core
Factory-based middleware activation in ASP.NET Core
Writing Clean Code in ASP.NET Core with Dependency Injection (MSDN )
Explicit Dependencies Principle
Inversion of Control Containers and the Dependency Injection Pattern (Martin Fowler)
How to register a service with multiple interfaces in ASP.NET Core DI
 ASP.NET Core Middleware
7/18/2019 • 8 minutes to read • Edit Online

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.
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. When a middleware short-circuits, it's
called a terminal middleware because it prevents further middleware from processing the request.
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 additional 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. Exception-handling delegates
should be 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.
 public class Startup
{
public void Configure(IApplicationBuilder app)
{
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:

public class Startup

{
public void Configure(IApplicationBuilder app)
{
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.
});

app.Run(async context =>

{
await context.Response.WriteAsync("Hello from 2nd delegate.");
});
}
}

When a delegate doesn't pass a request to the next delegate, it's called short-circuiting the request pipeline.
Short-circuiting is often desirable because it avoids unnecessary work. For example, Static File Middleware
can act as a terminal middleware by processing a request for a static file and short-circuiting the rest of the
pipeline. Middleware added to the pipeline before the middleware that terminates further processing still
processes code after their next.Invoke statements. However, see the following warning about attempting to
write to a response that has already been sent.

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
When the app runs in the Development environment:
Developer Exception Page Middleware (UseDeveloperExceptionPage) reports app runtime
errors.
Database Error Page Middleware (UseDatabaseErrorPage) reports database runtime errors.
When the app runs in the Production environment:
Exception Handler Middleware (UseExceptionHandler) catches exceptions thrown in the
following middlewares.
HTTP Strict Transport Security Protocol (HSTS ) Middleware (UseHsts) adds the
Strict-Transport-Security header.
2. HTTPS Redirection Middleware (UseHttpsRedirection) redirects HTTP requests to HTTPS.
3. Static File Middleware (UseStaticFiles) returns static files and short-circuits further request processing.
4. Cookie Policy Middleware (UseCookiePolicy) conforms the app to the EU General Data Protection
Regulation (GDPR ) regulations.
5. Authentication Middleware (UseAuthentication) attempts to authenticate the user before they're allowed
access to secure resources.
6. Session Middleware (UseSession) establishes and maintains session state. If the app uses session state,
call Session Middleware after Cookie Policy Middleware and before MVC Middleware.
7. MVC (UseMvc) to add MVC to the request pipeline.

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseDatabaseErrorPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseCookiePolicy();
app.UseAuthentication();
app.UseSession();
app.UseMvc();
}

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 File Middleware is called early in the pipeline so that it can handle requests and short-circuit without
going through the remaining components. The Static File 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 File 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.
The following example demonstrates a middleware order where requests for static files are handled by Static
File Middleware before Response Compression Middleware. Static files aren't compressed with this
middleware order. The MVC responses from UseMvcWithDefaultRoute can be compressed.

public void Configure(IApplicationBuilder app)

{
// Static files not compressed by Static File Middleware.
app.UseStaticFiles();
app.UseResponseCompression();
app.UseMvcWithDefaultRoute();
}

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.

public class Startup

{
private static void HandleMapTest1(IApplicationBuilder app)
{
app.Run(async context =>
{
await context.Response.WriteAsync("Map Test 1");
});
}

private static void HandleMapTest2(IApplicationBuilder app)

{
app.Run(async context =>
{
await context.Response.WriteAsync("Map Test 2");
});
}

public void Configure(IApplicationBuilder app)

{
app.Map("/map1", HandleMapTest1);

app.Map("/map2", HandleMapTest2);

app.Run(async context =>

{
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/map2 Map Test 2

localhost:1234/map3 Hello from non-Map delegate.

When is used, the matched path segments are removed from

Map 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 :

public class Startup

{
private static void HandleBranch(IApplicationBuilder app)
{
app.Run(async context =>
{
var branchVer = context.Request.Query["branch"];
await context.Response.WriteAsync($"Branch used = {branchVer}");
});
}

public void Configure(IApplicationBuilder app)

{
app.MapWhen(context => context.Request.Query.ContainsKey("branch"),
HandleBranch);

app.Run(async context =>

{
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/?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:

public class Startup

{
private static void HandleMultiSeg(IApplicationBuilder app)
{
app.Run(async context =>
{
await context.Response.WriteAsync("Map multiple segments.");
});
}

public void Configure(IApplicationBuilder app)

{
app.Map("/map1/seg1", HandleMultiSeg);

app.Run(async context =>

{
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
middleware placement in the request processing pipeline and under what conditions the middleware may
terminate request processing. When a middleware short-circuits the request processing pipeline and
prevents further downstream middleware from processing a request, it's called a terminal middleware. For
more information on short-circuiting, see the Create a middleware pipeline with IApplicationBuilder section.

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
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.

Exception Handling Handles exceptions. 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.

Health Check Checks the health of an ASP.NET Terminal if a request matches a health
Core app and its dependencies, such check endpoint.
as checking database availability.

HTTP Method Override Allows an incoming POST request to Before components that consume the
override the method. updated method.
 MIDDLEWARE DESCRIPTION ORDER

HTTPS Redirection Redirect all HTTP requests to HTTPS. Before components that consume 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.
Examples: Forwarded Headers, URL
Rewriting.

MVC Processes requests with MVC/Razor Terminal if a request matches a route.

Pages.

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 the
and redirecting requests. URL.

WebSockets Enables the WebSockets protocol. Before components that are required
to accept WebSocket requests.

Additional resources
Write custom ASP.NET Core middleware
Migrate HTTP handlers and modules to ASP.NET Core middleware
App startup in ASP.NET Core
Request Features in ASP.NET Core
Factory-based middleware activation in ASP.NET Core
Middleware activation with a third-party container in ASP.NET Core
 .NET Generic Host
7/10/2019 • 20 minutes to read • Edit Online

This article introduces the .NET Core Generic Host ( HostBuilder) and provides guidance on how to use it.

What's a host?
A host is an object that encapsulates an app's resources, such as:
Dependency injection (DI)
Logging
Configuration
IHostedService implementations

When a host starts, it calls IHostedService.StartAsync on each implementation of IHostedService that it finds in
the DI container. In a web app, one of the IHostedService implementations is a web service that starts an HTTP
server implementation.
The main reason for including all of the app's interdependent resources in one object is lifetime management:
control over app startup and graceful shutdown.
In versions of ASP.NET Core earlier than 3.0, the Web Host is used for HTTP workloads. The Web Host is no
longer recommended for web apps and remains available only for backward compatibility.

Set up a host
The host is typically configured, built, and run by code in the Program class. The Main method:
Calls a CreateHostBuilder method to create and configure a builder object.
Calls Build and Run methods on the builder object.
Here's Program.cs code for a non-HTTP workload, with a single IHostedService implementation added to the
DI container.

public class Program

{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureServices((hostContext, services) =>
{
services.AddHostedService<Worker>();
});
}

For an HTTP workload, the Main method is the same but CreateHostBuilder calls ConfigureWebHostDefaults :
 public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});

If the app uses Entity Framework Core, don't change the name or signature of the CreateHostBuilder method.
The Entity Framework Core tools expect to find a CreateHostBuilder method that configures the host without
running the app. For more information, see Design-time DbContext Creation.

Default builder settings

The CreateDefaultBuilder method:
Sets the content root to the path returned by GetCurrentDirectory.
Loads host configuration from:
Environment variables prefixed with "DOTNET_".
Command-line arguments.
Loads app configuration from:
appsettings.json.
appsettings.{Environment}.json.
Secret Manager when the app runs in the Development environment.
Environment variables.
Command-line arguments.
Adds the following logging providers:
Console
Debug
EventSource
EventLog (only when running on Windows)
Enables scope validation and dependency validation when the environment is Development.
The ConfigureWebHostDefaults method:
Loads host configuration from environment variables prefixed with "ASPNETCORE_".
Sets Kestrel server as the web server and configures it using the app's hosting configuration providers. For
the Kestrel server's default options, see Kestrel web server implementation in ASP.NET Core.
Adds Host Filtering middleware.
Adds Forwarded Headers middleware if ASPNETCORE_FORWARDEDHEADERS_ENABLED=true.
Enables IIS integration. For the IIS default options, see Host ASP.NET Core on Windows with IIS.
The Settings for all app types and Settings for web apps sections later in this article show how to override
default builder settings.

Framework-provided services
Services that are registered automatically include the following:
IHostApplicationLifetime
IHostLifetime
IHostEnvironment / IWebHostEnvironment
For a list of all framework-provided services, see Dependency injection in ASP.NET Core.

IHostApplicationLifetime
Inject the IHostApplicationLifetime (formerly IApplicationLifetime ) service into any class to handle post-
startup and graceful shutdown tasks. Three properties on the interface are cancellation tokens used to register
app start and app stop event handler methods. The interface also includes a StopApplication method.
The following example is an IHostedService implementation that registers the IApplicationLifetime events:

internal class LifetimeEventsHostedService : IHostedService

{
private readonly ILogger _logger;
private readonly IHostApplicationLifetime _appLifetime;

public LifetimeEventsHostedService(
ILogger<LifetimeEventsHostedService> logger,
IHostApplicationLifetime appLifetime)
{
_logger = logger;
_appLifetime = appLifetime;
}

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)

{
return Task.CompletedTask;
}

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

}
}

IHostLifetime
The IHostLifetime implementation controls when the host starts and when it stops. The last implementation
registered is used.
ConsoleLifetime is the default IHostLifetime implementation. ConsoleLifetime :
listens for Ctrl+C/SIGINT or SIGTERM and calls StopApplication to start the shutdown process.
Unblocks extensions such as RunAsync and WaitForShutdownAsync.

IHostEnvironment
Inject the IHostEnvironment service into a class to get information about the following:
ApplicationName
EnvironmentName
ContentRootPath
Web apps implement the IWebHostEnvironment interface, which inherits IHostEnvironment and adds:
WebRootPath

Host configuration
Host configuration is used for the properties of the IHostEnvironment implementation.
Host configuration is available from HostBuilderContext.Configuration inside ConfigureAppConfiguration.
After ConfigureAppConfiguration , HostBuilderContext.Configuration is replaced with the app config.
To add host configuration, call ConfigureHostConfiguration on IHostBuilder . ConfigureHostConfiguration can
be called multiple times with additive results. The host uses whichever option sets a value last on a given key.
The environment variable provider with prefix DOTNET_ and command line args are included by
CreateDefaultBuilder. For web apps, the environment variable provider with prefix ASPNETCORE_ is added. The
prefix is removed when the environment variables are read. For example, the environment variable value for
ASPNETCORE_ENVIRONMENT becomes the host configuration value for the environment key.

The following example creates host configuration:

Host.CreateDefaultBuilder(args)
.ConfigureHostConfiguration(configHost =>
{
configHost.SetBasePath(Directory.GetCurrentDirectory());
configHost.AddJsonFile("hostsettings.json", optional: true);
configHost.AddEnvironmentVariables(prefix: "PREFIX_");
configHost.AddCommandLine(args);
});

App configuration
App configuration is created by calling ConfigureAppConfiguration on IHostBuilder .
ConfigureAppConfiguration can be called multiple times with additive results. The app uses whichever option
sets a value last on a given key.
The configuration created by ConfigureAppConfiguration is available at HostBuilderContext.Configuration for
subsequent operations and as a service from DI. The host configuration is also added to the app configuration.
For more information, see Configuration in ASP.NET Core.

Settings for all app types

This section lists host settings that apply to both HTTP and non-HTTP workloads. By default, environment
variables used to configure these settings can have a DOTNET_ or ASPNETCORE_ prefix.
ApplicationName
The IHostEnvironment.ApplicationName property is set from host configuration during host construction.
Key: applicationName
Type: string
Default: The name of the assembly that contains the app's entry point. Environment variable:
<PREFIX_>APPLICATIONNAME

To set this value, use the environment variable.

ContentRootPath
The IHostEnvironment.ContentRootPath property determines where the host begins searching for content files.
If the path doesn't exist, the host fails to start.
Key: contentRoot
Type: string
Default: The folder where the app assembly resides.
Environment variable: <PREFIX_>CONTENTROOT
To set this value, use the environment variable or call UseContentRoot on IHostBuilder :

Host.CreateDefaultBuilder(args)
.UseContentRoot("c:\\content-root")
//...

EnvironmentName
The IHostEnvironment.EnvironmentName property can be set to any value. Framework-defined values include
Development , Staging , and Production . Values aren't case sensitive.

Key: environment
Type: string
Default: Production
Environment variable: <PREFIX_>ENVIRONMENT

To set this value, use the environment variable or call UseEnvironment on IHostBuilder :

Host.CreateDefaultBuilder(args)
.UseEnvironment("Development")
//...

ShutdownTimeout
HostOptions.ShutdownTimeout sets the timeout for StopAsync. The default value is five seconds. During the
timeout period, the host:
Triggers IHostApplicationLifetime.ApplicationStopping.
Attempts to stop hosted services, logging 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.
Key: shutdownTimeoutSeconds
Type: int
Default: 5 seconds Environment variable: <PREFIX_>SHUTDOWNTIMEOUTSECONDS

To set this value, use the environment variable or configure HostOptions . The following example sets the
timeout to 20 seconds:

Host.CreateDefaultBuilder(args)
.ConfigureServices((hostContext, services) =>
{
services.Configure<HostOptions>(option =>
{
option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
});
});

Settings for web apps

Some host settings apply only to HTTP workloads. By default, environment variables used to configure these
settings can have a DOTNET_ or ASPNETCORE_ prefix.
Extension methods on IWebHostBuilder are available for these settings. Code samples that show how to call the
extension methods assume webBuilder is an instance of IWebHostBuilder , as in the following example:

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.CaptureStartupErrors(true);
webBuilder.UseStartup<Startup>();
});

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.
Key: captureStartupErrors
Type: bool ( true or 1 )
Default: Defaults to false unless the app runs with Kestrel behind IIS, where the default is true .
Environment variable: <PREFIX_>CAPTURESTARTUPERRORS
To set this value, use configuration or call CaptureStartupErrors :

webBuilder.CaptureStartupErrors(true);

DetailedErrors
When enabled, or when the environment is Development , the app captures detailed errors.
Key: detailedErrors
Type: bool ( true or 1 )
Default: false
Environment variable: <PREFIX_>_DETAILEDERRORS

To set this value, use configuration or call UseSetting :

webBuilder.UseSetting(WebHostDefaults.DetailedErrorsKey, "true");
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.
Key: hostingStartupAssemblies
Type: string
Default: Empty string
Environment variable: <PREFIX_>_HOSTINGSTARTUPASSEMBLIES
To set this value, use configuration or call UseSetting :

webBuilder.UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");

HostingStartupExcludeAssemblies
A semicolon-delimited string of hosting startup assemblies to exclude on startup.
Key: hostingStartupExcludeAssemblies
Type: string
Default: Empty string
Environment variable: <PREFIX_>_HOSTINGSTARTUPEXCLUDEASSEMBLIES
To set this value, use configuration or call UseSetting :

webBuilder.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");

HTTPS_Port
The HTTPS redirect port. Used in enforcing HTTPS.
Key: https_port Type: string Default: A default value isn't set. Environment variable: <PREFIX_>HTTPS_PORT

To set this value, use configuration or call UseSetting :

webBuilder.UseSetting("https_port", "8080");

PreferHostingUrls
Indicates whether the host should listen on the URLs configured with the IWebHostBuilder instead of those
configured with the IServer implementation.
Key: preferHostingUrls
Type: bool ( true or 1 )
Default: true
Environment variable: <PREFIX_>_PREFERHOSTINGURLS

To set this value, use the environment variable or call PreferHostingUrls :

webBuilder.PreferHostingUrls(false);

PreventHostingStartup
Prevents the automatic loading of hosting startup assemblies, including hosting startup assemblies configured
by the app's assembly. For more information, see Use hosting startup assemblies in ASP.NET Core.
Key: preventHostingStartup
Type: bool ( true or 1 )
Default: false
Environment variable: <PREFIX_>_PREVENTHOSTINGSTARTUP
To set this value, use the environment variable or call UseSetting :

webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");

StartupAssembly
The assembly to search for the Startup class.
Key: startupAssembly Type: string
Default: The app's assembly
Environment variable: <PREFIX_>STARTUPASSEMBLY
To set this value, use the environment variable or call UseStartup . UseStartup can take an assembly name (
string ) or a type ( TStartup ). If multiple UseStartup methods are called, the last one takes precedence.

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

URLs
A semicolon-delimited list of IP addresses or host addresses with ports and protocols that the server should
listen on for requests. 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 among servers.
Key: urls
Type: string
Default: http://localhost:5000 and https://localhost:5001 Environment variable: <PREFIX_>URLS

To set this value, use the environment variable or call UseUrls :

webBuilder.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.
WebRoot
The relative path to the app's static assets.
Key: webroot
Type: string
Default: (Content Root)/wwwroot, if the path exists. If the path doesn't exist, a no-op file provider is used.
Environment variable: <PREFIX_>WEBROOT
To set this value, use the environment variable or call UseWebRoot :

webBuilder.UseWebRoot("public");
Manage the host lifetime
Call methods on the built IHost implementation to start and stop the app. These methods affect all
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.
RunAsync
RunAsync runs the app and returns a Task that completes when the cancellation token or shutdown is
triggered.
RunConsoleAsync
RunConsoleAsync enables console support, builds and starts the host, and waits for Ctrl+C/SIGINT or
SIGTERM to shut down.
Start
Start starts the host synchronously.
StartAsync
StartAsync starts the host and returns a Task that completes when the cancellation token or shutdown is
triggered.
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.
StopAsync
StopAsync attempts to stop the host within the provided timeout.
WaitForShutdown
WaitForShutdown blocks the calling thread until shutdown is triggered by the IHostLifetime, such as via
Ctrl+C/SIGINT or SIGTERM.
WaitForShutdownAsync
WaitForShutdownAsync returns a Task that completes when shutdown is triggered via the given token and
calls StopAsync.
External control
Direct control of the host lifetime can be achieved using methods that can be called externally:
 public class Program
{
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));
}
}
}

ASP.NET Core apps configure and launch a host. The host is responsible for app startup and lifetime
management.
This article covers the ASP.NET Core Generic Host ( HostBuilder), which is used for apps that don't process
HTTP requests.
The purpose of 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 Generic Host benefit
from cross-cutting capabilities, such as configuration, dependency injection (DI), and logging.
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. Generic Host will replace Web Host in a future release and act as the primary host
API in both HTTP and non-HTTP scenarios.
View or download sample code (how to download)
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();
}

Options
HostOptions configure options for the IHost.
Shutdown timeout
ShutdownTimeout sets the timeout for StopAsync. The default value is five seconds.
The following option configuration in Program.Main increases the default five second shutdown timeout to 20
seconds:

var host = new HostBuilder()

.ConfigureServices((hostContext, services) =>
{
services.Configure<HostOptions>(option =>
{
option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
});
})
.Build();

Default services
The following services are registered during host initialization:
Environment (IHostingEnvironment)
HostBuilderContext
Configuration (IConfiguration)
IApplicationLifetime (ApplicationLifetime)
IHostLifetime (ConsoleLifetime)
IHost
Options (AddOptions)
Logging (AddLogging)

Host configuration
Host configuration is created by:
Calling extension methods on IHostBuilder to set the content root and environment.
Reading configuration from configuration providers in ConfigureHostConfiguration.
Extension methods
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_>APPLICATIONNAME ( <PREFIX_> is optional and user-defined)
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.

var host = new HostBuilder()

.UseContentRoot("c:\\<content-root>")

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.

var host = new HostBuilder()

.UseEnvironment(EnvironmentName.Development)

ConfigureHostConfiguration
ConfigureHostConfiguration uses an IConfigurationBuilder to create an IConfiguration for the host. The host
configuration is used to initialize the IHostingEnvironment for use in the app's build process.
ConfigureHostConfiguration can be called multiple times with additive results. The host uses whichever option
sets a value last on a given key.
No providers are included by default. You must explicitly specify whatever configuration providers the app
requires in ConfigureHostConfiguration, including:
File configuration (for example, from a hostsettings.json file).
Environment variable configuration.
Command-line argument configuration.
Any other required configuration providers.
File configuration of the host is enabled by specifying the app's base path with SetBasePath followed by a call
to one of the file configuration providers. The sample app uses a JSON file, hostsettings.json, and calls
AddJsonFile to consume the file's host configuration settings.
To add environment variable configuration of the host, call AddEnvironmentVariables on the host builder.
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.
Command-line configuration is added by calling AddCommandLine. Command-line configuration is added last
to permit command-line arguments to override configuration provided by the earlier configuration providers.
hostsettings.json:

{
"environment": "Development"
}

Additional configuration can be provided with the applicationName and contentRoot keys.
Example HostBuilder configuration using ConfigureHostConfiguration:

var host = new HostBuilder()

.ConfigureHostConfiguration(configHost =>
{
configHost.SetBasePath(Directory.GetCurrentDirectory());
configHost.AddJsonFile("hostsettings.json", optional: true);
configHost.AddEnvironmentVariables(prefix: "PREFIX_");
configHost.AddCommandLine(args);
})

ConfigureAppConfiguration
App 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 on a given key. The configuration created by ConfigureAppConfiguration is available at
HostBuilderContext.Configuration for subsequent operations and in Services.
App configuration automatically receives host configuration provided by ConfigureHostConfiguration.
Example app configuration using ConfigureAppConfiguration:
 var host = new HostBuilder()
.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": {
"Default": "Warning"
}
},
"AllowedHosts": "*"
}

appsettings.Development.json:

{
"Logging": {
"LogLevel": {
"Default": "Debug",
"System": "Information",
"Microsoft": "Information"
}
}
}

appsettings.Production.json:

{
"Logging": {
"LogLevel": {
"Default": "Error",
"System": "Information",
"Microsoft": "Information"
}
}
}

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" Exclude="bin\**\*;obj\**\*"
CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>
 NOTE
Configuration extension methods, such as AddJsonFile and AddEnvironmentVariables require additional NuGet packages,
such as Microsoft.Extensions.Configuration.Json and Microsoft.Extensions.Configuration.EnvironmentVariables. Unless the
app uses the Microsoft.AspNetCore.App metapackage, these packages must be added to the project in addition to the
core Microsoft.Extensions.Configuration package. For more information, see Configuration in ASP.NET Core.

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 extension method to add a service for lifetime events,
AddHostedService
LifetimeEventsHostedService , and a timed background task, TimedHostedService , to the app:

var host = new HostBuilder()

.ConfigureServices((hostContext, services) =>
{
if (hostContext.HostingEnvironment.IsDevelopment())
{
// Development service configuration
}
else
{
// Non-development service configuration
}

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.

var host = new HostBuilder()

.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.

var host = new HostBuilder()

.UseConsoleLifetime()
Container configuration
To support plugging in other containers, the host can accept an IServiceProviderFactory<TContainerBuilder>.
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;
using Microsoft.Extensions.DependencyInjection;

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:

var host = new HostBuilder()

.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.
 var host = new HostBuilder()
.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.DependencyInjection;
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 class Program

{
public void Main(string[] args)
{
var host = new HostBuilder()
.Build();

host.Run();
}
}

RunAsync
RunAsync runs the app and returns a Task that completes when the cancellation token or shutdown is
triggered:

public class Program

{
public static async Task Main(string[] args)
{
var host = new HostBuilder()
.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.

public class Program

{
public static async Task Main(string[] args)
{
var hostBuilder = new HostBuilder();

await hostBuilder.RunConsoleAsync();
}
}

Start and StopAsync

Start starts the host synchronously.
StopAsync attempts to stop the host within the provided timeout.

public class Program

{
public static async Task Main(string[] args)
{
var host = new HostBuilder()
.Build();

using (host)
{
host.Start();

await host.StopAsync(TimeSpan.FromSeconds(5));
}
}
}

StartAsync and StopAsync

StartAsync starts the app.
StopAsync stops the app.

public class Program

{
public static async Task Main(string[] args)
{
var host = new HostBuilder()
.Build();

using (host)
{
await host.StartAsync();

await host.StopAsync();
}
}
}

WaitForShutdown
WaitForShutdown is triggered via the IHostLifetime, such as ConsoleLifetime (listens for Ctrl+C/SIGINT or
SIGTERM ). WaitForShutdown calls StopAsync.
 public class Program
{
public void Main(string[] args)
{
var host = new HostBuilder()
.Build();

using (host)
{
host.Start();

host.WaitForShutdown();
}
}
}

WaitForShutdownAsync
WaitForShutdownAsync returns a Task that completes when shutdown is triggered via the given token and
calls StopAsync.

public class Program

{
public static async Task Main(string[] args)
{
var host = new HostBuilder()
.Build();

using (host)
{
await host.StartAsync();

await host.WaitForShutdownAsync();
}

}
}

External control
External control of the host can be achieved using methods that can be called externally:
 public class Program
{
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));
}
}
}

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 class MyClass

{
private readonly IHostingEnvironment _env;

public MyClass(IHostingEnvironment env)

{
_env = env;
}

public void DoSomething()

{
var environmentName = _env.EnvironmentName;
}
}

For more information, see Use multiple environments in ASP.NET Core.

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.

CANCELLATION TOKEN TRIGGERED WHEN…

ApplicationStarted The host has fully started.

 CANCELLATION TOKEN TRIGGERED WHEN…

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

{
private readonly ILogger _logger;
private readonly IApplicationLifetime _appLifetime;

public LifetimeEventsHostedService(
ILogger<LifetimeEventsHostedService> logger,
IApplicationLifetime appLifetime)
{
_logger = logger;
_appLifetime = appLifetime;
}

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)

{
return Task.CompletedTask;
}

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 class MyClass

{
private readonly IApplicationLifetime _appLifetime;

public MyClass(IApplicationLifetime appLifetime)

{
_appLifetime = appLifetime;
}

public void Shutdown()

{
_appLifetime.StopApplication();
}
}

Additional resources
Background tasks with hosted services in ASP.NET Core
 ASP.NET Core Web Host
6/21/2019 • 15 minutes to read • Edit Online

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. The host can also
set up logging, dependency injection, and configuration.
This article covers the Web Host, which remains available only for backward compatibility. The Generic Host is
recommended for all app types.
This article covers the Web Host, which is for hosting web apps. For other kinds of apps, use the 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 app calls CreateDefaultBuilder to start setting
up a host:

public class Program

{
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>();
}

The code that calls CreateDefaultBuilder is in a method named CreateWebHostBuilder , which separates it from
the code in Main that calls Run on the builder object. This separation is required if you use Entity Framework
Core tools. The tools expect to find a CreateWebHostBuilder method that they can call at design time to configure
the host without running the app. An alternative is to implement IDesignTimeDbContextFactory . For more
information, see Design-time DbContext Creation.
CreateDefaultBuilder performs the following tasks:
Configures Kestrel server as the web server using the app's hosting configuration providers. For the Kestrel
server's 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 ).
Command-line arguments.
Loads app configuration in the following order from:
appsettings.json.
appsettings.{Environment}.json.
Secret Manager when the app runs in the Development environment using the entry assembly.
 Environment variables.
Command-line arguments.
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 with the ASP.NET Core Module, CreateDefaultBuilder enables IIS Integration,
which configures the app's base address and port. IIS Integration 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.

WebHost.CreateDefaultBuilder(args)
.ConfigureAppConfiguration((hostingContext, config) =>
{
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.

WebHost.CreateDefaultBuilder(args)
.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 :

WebHost.CreateDefaultBuilder(args)
.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 :
 WebHost.CreateDefaultBuilder(args)
.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.

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 App 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_APPLICATIONNAME

WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.ApplicationKey, "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.

WebHost.CreateDefaultBuilder(args)
.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.

WebHost.CreateDefaultBuilder(args)
.UseContentRoot("c:\\<content-root>")

Detailed Errors
Determines if detailed errors should be captured.
Key: detailedErrors
Type: bool ( true or 1 )
Default: false
Set using: UseSetting
Environment variable: ASPNETCORE_DETAILEDERRORS

When enabled (or when the Environment is set to Development ), the app captures detailed exceptions.

WebHost.CreateDefaultBuilder(args)
.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. For more information, see Use multiple environments in ASP.NET Core.
 WebHost.CreateDefaultBuilder(args)
.UseEnvironment(EnvironmentName.Development)

Hosting Startup Assemblies

Sets the app's hosting startup assemblies.
Key: hostingStartupAssemblies
Type: string
Default: Empty string
Set using: UseSetting
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.

WebHost.CreateDefaultBuilder(args)
.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

WebHost.CreateDefaultBuilder(args)
.UseSetting("https_port", "8080")

Hosting Startup Exclude Assemblies

A semicolon-delimited string of hosting startup assemblies to exclude on startup.
Key: hostingStartupExcludeAssemblies
Type: string
Default: Empty string
Set using: UseSetting
Environment variable: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

WebHost.CreateDefaultBuilder(args)
.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
Type: bool ( true or 1 )
Default: true
Set using: PreferHostingUrls
Environment variable: ASPNETCORE_PREFERHOSTINGURLS
 WebHost.CreateDefaultBuilder(args)
.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 Use hosting startup assemblies in ASP.NET Core.
Key: preventHostingStartup
Type: bool ( true or 1 )
Default: false
Set using: UseSetting
Environment variable: ASPNETCORE_PREVENTHOSTINGSTARTUP

WebHost.CreateDefaultBuilder(args)
.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 among servers.

WebHost.CreateDefaultBuilder(args)
.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.
Shutdown Timeout
Specifies the amount of time to wait for 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 (for example,
UseSetting
.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.

WebHost.CreateDefaultBuilder(args)
.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.

WebHost.CreateDefaultBuilder(args)
.UseStartup("StartupAssemblyName")

WebHost.CreateDefaultBuilder(args)
.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

WebHost.CreateDefaultBuilder(args)
.UseWebRoot("public")

Override configuration
Use Configuration to configure 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:
 public class Program
{
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args)

{
var config = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("hostsettings.json", optional: true)
.AddCommandLine(args)
.Build();

return WebHost.CreateDefaultBuilder(args)
.UseUrls("http://*:5000")
.UseConfiguration(config)
.Configure(app =>
{
app.Run(context =>
context.Response.WriteAsync("Hello, World!"));
});
}
}

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"
};

var host = new WebHostBuilder()

.UseKestrel()
.UseStartup<Startup>()
.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!")))

{
Console.WriteLine("Use Ctrl-C to shutdown the host...");
host.WaitForShutdown();
}
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!"))))
{
Console.WriteLine("Use Ctrl-C to shutdown the host...");
host.WaitForShutdown();
}

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...");
host.WaitForShutdown();
}
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!");
};
})))
{
Console.WriteLine("Use Ctrl-C to shut down 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.
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 =>
{
await context.Response.WriteAsync("Hello World!");
};
})))
{
Console.WriteLine("Use Ctrl-C to shut down the host...");
host.WaitForShutdown();
}

Produces the same result as StartWith(Action<IApplicationBuilder> app), except the app responds on
http://localhost:8080 .

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
{
private readonly IHostingEnvironment _env;

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 :

public class Startup

{
public Startup(IHostingEnvironment env)
{
HostingEnvironment = env;
}

public IHostingEnvironment HostingEnvironment { get; }

public void ConfigureServices(IServiceCollection services)

{
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:
 public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
// In Development, use the Developer Exception Page
app.UseDeveloperExceptionPage();
}
else
{
// In Staging/Production, route exceptions to /error
app.UseExceptionHandler("/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)

{
if (env.IsDevelopment())
{
// 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 class Startup
{
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:

WebHost.CreateDefaultBuilder(args)
.UseDefaultServiceProvider((context, options) => {
options.ValidateScopes = true;
})

Additional resources
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
 Web server implementations in ASP.NET Core
7/12/2019 • 6 minutes to read • Edit Online

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 a set of request features composed into an HttpContext.

Kestrel
Kestrel is the default web server included in ASP.NET Core project templates.
Use Kestrel:
By itself as an edge server processing requests directly from a network, including the Internet.

With a reverse proxy server, such as Internet Information Services (IIS ), Nginx, or Apache. A reverse proxy
server receives HTTP requests from the Internet and forwards them to Kestrel.

Either hosting configuration—with or without a reverse proxy server—is supported for ASP.NET Core 2.1 or later
apps.
For Kestrel configuration guidance and information on when to use Kestrel in a reverse proxy configuration, see
Kestrel web server implementation in ASP.NET Core.
Windows
macOS
Linux
ASP.NET Core ships with the following:
Kestrel server is the default, cross-platform HTTP server implementation.
IIS HTTP Server is an in-process server for IIS.
HTTP.sys server is a Windows-only HTTP server based on the HTTP.sys kernel driver and HTTP Server API.
When using IIS or IIS Express, the app either runs:
In the same process as the IIS worker process (the in-process hosting model) with the IIS HTTP Server. In-
process is the recommended configuration.
In a process separate from the IIS worker process (the out-of-process hosting model) with the Kestrel server.
The ASP.NET Core Module is a native IIS module that handles native IIS requests between IIS and the in-process
IIS HTTP Server or Kestrel. For more information, see ASP.NET Core Module.
Hosting models
Using in-process hosting, an ASP.NET Core app runs in the same process as its IIS worker process. In-process
hosting provides improved performance over out-of-process hosting because requests aren't proxied over the
loopback adapter, a network interface that returns outgoing network traffic back to the same machine. IIS handles
process management with the Windows Process Activation Service (WAS ).
Using out-of-process hosting, ASP.NET Core apps run in a process separate from the IIS worker process, and the
module 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 shuts down or crashes. This is essentially the same behavior as seen with
apps that run in-process that are managed by the Windows Process Activation Service (WAS ).
For more information and configuration guidance, see the following topics:
Host ASP.NET Core on Windows with IIS
ASP.NET Core Module
Windows
macOS
Linux
ASP.NET Core ships with the following:
Kestrel server is the default, cross-platform HTTP server.
HTTP.sys server is a Windows-only HTTP server based on the HTTP.sys kernel driver and HTTP Server API.
When using IIS or IIS Express, the app runs in a process separate from the IIS worker process (out-of-process)
with the Kestrel server.
Because ASP.NET Core apps run in a process separate from the IIS worker process, the module 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 shuts down or crashes. This is essentially the same behavior as seen with apps that run in-process that
are managed by the Windows Process Activation Service (WAS ).
The following diagram illustrates the relationship between IIS, the ASP.NET Core Module, and an app hosted
out-of-process:

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 or 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 the 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. Middleware added by IIS Integration updates the scheme, remote IP, and pathbase to account for
forwarding the request to Kestrel. The app's response is passed back to IIS, which pushes it back out to the HTTP
client that initiated the request.
For IIS and ASP.NET Core Module configuration guidance, see the following topics:
Host ASP.NET Core on Windows with IIS
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 ASP.NET Core 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 ASP.NET Core 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 more information, see HTTP.sys web
server implementation in ASP.NET Core.

HTTP.sys can also be used for apps that are only exposed to an internal network.

For HTTP.sys configuration guidance, see HTTP.sys web server implementation in ASP.NET Core.

ASP.NET Core server infrastructure

The IApplicationBuilder available in the Startup.Configure method exposes the ServerFeatures property of type
IFeatureCollection. Kestrel and HTTP.sys 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
The server is launched when the Integrated Development Environment (IDE ) or editor starts the app:
Visual Studio – Launch profiles can be used to start the app and server with either IIS Express/ASP.NET Core
Module or the console.
Visual Studio Code – The app and server are started by Omnisharp, which activates the CoreCLR debugger.
Visual Studio for Mac – The app and server are started by the Mono Soft-Mode Debugger.
When launching the 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 dotnet run and .NET Core distribution packaging.

HTTP/2 support
HTTP/2 is supported with ASP.NET Core in the following deployment scenarios:
Kestrel
Operating system
Windows Server 2016/Windows 10 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
Target framework: .NET Core 2.2 or later
IIS (out-of-process)
Windows Server 2016/Windows 10 or later; IIS 10 or later
Public-facing edge server 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.
†Kestrel has limited support for HTTP/2 on Windows Server 2012 R2 and Windows 8.1. Support is limited
because the list of supported TLS cipher suites available on these operating systems is limited. A certificate
generated using an Elliptic Curve Digital Signature Algorithm (ECDSA) may be required to secure TLS
connections.
HTTP.sys
Windows Server 2016/Windows 10 or later
Target framework: Not applicable to HTTP.sys deployments.
IIS (out-of-process)
Windows Server 2016/Windows 10 or later; IIS 10 or later
Public-facing edge server 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.

Additional resources
Kestrel web server implementation in ASP.NET Core
ASP.NET Core Module
Host ASP.NET Core on Windows with IIS
Deploy ASP.NET Core apps to Azure App Service
Host ASP.NET Core on Linux with Nginx
Host ASP.NET Core on Linux with Apache
HTTP.sys web server implementation in ASP.NET Core
 Configuration in ASP.NET Core
8/13/2019 • 32 minutes to read • Edit Online

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
Azure App Configuration
Command-line arguments
Custom providers (installed or created)
Directory files
Environment variables
In-memory .NET objects
Settings files
Configuration packages for common configuration provider scenarios
(Microsoft.Extensions.Configuration) are included implicitly by the framework.
Configuration packages for common configuration provider scenarios
(Microsoft.Extensions.Configuration) are included in the Microsoft.AspNetCore.App metapackage.
Code examples that follow and in the sample app use the Microsoft.Extensions.Configuration
namespace:

using Microsoft.Extensions.Configuration;

The options pattern is an extension of the configuration concepts described in this topic. Options use
classes to represent groups of related settings. For more information, see Options pattern in ASP.NET
Core.
View or download sample code (how to download)

Host versus 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 are also included in
the app's configuration. For more information on how the configuration providers are used when the
host is built and how configuration sources affect host configuration, see ASP.NET Core fundamentals.

Default configuration
Web apps based on the ASP.NET Core dotnet new templates call CreateDefaultBuilder when building a
host. CreateDefaultBuilder provides default configuration for the app in the following order:
The following applies to apps using the Generic Host. For details on the default configuration when
using the Web Host, see the ASP.NET Core 2.2 version of this topic.
 Host configuration is provided from:
Environment variables prefixed with DOTNET_ (for example, DOTNET_ENVIRONMENT ) using the
Environment Variables Configuration Provider. The prefix ( DOTNET_ ) is stripped when the
configuration key-value pairs are loaded.
Command-line arguments using the Command-line Configuration Provider.
Web Host default configuration is established ( ConfigureWebHostDefaults ):
Kestrel is used as the web server and configured using the app's configuration providers.
Add Host Filtering Middleware.
Add Forwarded Headers Middleware if the ASPNETCORE_FORWARDEDHEADERS_ENABLED
environment variable is set to true .
Enable IIS integration.
App configuration is provided from:
appsettings.json using the File Configuration Provider.
appsettings.{Environment}.json using the File Configuration Provider.
Secret Manager when the app runs in the Development environment using the entry
assembly.
Environment variables using the Environment Variables Configuration Provider.
Command-line arguments using the Command-line Configuration Provider.
Web apps based on the ASP.NET Core dotnet new templates call CreateDefaultBuilder when building a
host. CreateDefaultBuilder provides default configuration for the app in the following order:
The following applies to apps using the Web Host. For details on the default configuration when using
the Generic Host, see the latest version of this topic.
Host configuration is provided from:
Environment variables prefixed with ASPNETCORE_ (for example, ASPNETCORE_ENVIRONMENT )
using the Environment Variables Configuration Provider. The prefix ( ASPNETCORE_ ) is stripped
when the configuration key-value pairs are loaded.
Command-line arguments using the Command-line Configuration Provider.
App configuration is provided from:
appsettings.json using the File Configuration Provider.
appsettings.{Environment}.json using the File Configuration Provider.
Secret Manager when the app runs in the Development environment using the entry
assembly.
Environment variables using the Environment Variables Configuration Provider.
Command-line arguments using the Command-line Configuration Provider.

Security
Adopt the following practices to secure sensitive configuration data:
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.
For more information, see the following topics:
Use multiple environments in ASP.NET Core
 Safe storage of app secrets in development in ASP.NET Core – 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 safely stores app secrets for ASP.NET Core apps. 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
Sources and providers
At app startup, configuration sources are read in the order that their configuration providers are
specified.
Configuration providers that implement change detection have the ability to reload configuration when
an underlying setting is changed. For example, the File Configuration Provider (described later in this
topic) and the Azure Key Vault Configuration Provider implement change detection.
IConfiguration is available in the app's dependency injection (DI) container. IConfiguration can be
injected into a Razor Pages PageModel to obtain configuration for the class:
 public class IndexModel : PageModel
{
private readonly IConfiguration _config;

public IndexModel(IConfiguration config)

{
_config = config;
}

// The _config local variable is used to obtain configuration

// throughout the class.
}

Configuration providers can't utilize DI, as it's not available when they're set up by the host.
Keys
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 automatically converted into 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.
Values
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

Azure App Configuration Provider (Azure Azure App Configuration

documentation)

Command-line Configuration Provider Command-line parameters

Custom configuration provider Custom source

Environment Variables Configuration Provider Environment variables

 PROVIDER PROVIDES CONFIGURATION FROM…

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. Azure Key Vault
3. User secrets (Secret Manager) (Development environment only)
4. Environment variables
5. Command-line arguments
A common practice is 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.
The preceding sequence of providers is used when you initialize a new host builder with
CreateDefaultBuilder . For more information, see the Default configuration section.

Configure the host builder with ConfigureHostConfiguration

To configure the host builder, call ConfigureHostConfiguration and supply the configuration.
ConfigureHostConfiguration is used to initialize the IHostEnvironment for use later in the build process.
ConfigureHostConfiguration can be called multiple times with additive results.

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureHostConfiguration((hostingContext, config) =>
{
var dict = new Dictionary<string, string>
{
{"MemoryCollectionKey1", "value1"},
{"MemoryCollectionKey2", "value2"}
};

config.AddInMemoryCollection(dict);
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});

Configure the host builder with UseConfiguration

To configure the host builder, call UseConfiguration on the host builder with the configuration.
 public static IWebHostBuilder CreateWebHostBuilder(string[] args)
{
var dict = new Dictionary<string, string>
{
{"MemoryCollectionKey1", "value1"},
{"MemoryCollectionKey2", "value2"}
};

var config = new ConfigurationBuilder()

.AddInMemoryCollection(dict)
.Build();

return WebHost.CreateDefaultBuilder(args)
.UseConfiguration(config)
.UseStartup<Startup>();
}

ConfigureAppConfiguration
Call ConfigureAppConfiguration when building the host to specify the app's configuration providers in
addition to those added automatically by CreateDefaultBuilder :

public class Program

{
public static Dictionary<string, string> arrayDict =
new Dictionary<string, string>
{
{"array:entries:0", "value0"},
{"array:entries:1", "value1"},
{"array:entries:2", "value2"},
{"array:entries:4", "value4"},
{"array:entries:5", "value5"}
};

public static void Main(string[] args)

{
CreateHostBuilder(args).Build().Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureAppConfiguration((hostingContext, config) =>
{
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);
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
 public class Program
{
public static Dictionary<string, string> arrayDict =
new Dictionary<string, string>
{
{"array:entries:0", "value0"},
{"array:entries:1", "value1"},
{"array:entries:2", "value2"},
{"array:entries:4", "value4"},
{"array:entries:5", "value5"}
};

public static void Main(string[] args)

{
CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.ConfigureAppConfiguration((hostingContext, config) =>
{
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);
})
.UseStartup<Startup>();
}

Override previous configuration with command-line arguments

To provide app configuration that can be overridden with command-line arguments, call
AddCommandLine last:

.ConfigureAppConfiguration((hostingContext, config) =>

{
// Call other providers here
config.AddCommandLine(args);
})

Consume configuration during app startup

Configuration supplied to the app in ConfigureAppConfiguration is available during the app's startup,
including Startup.ConfigureServices . For more information, see the Access configuration during
startup section.

Command-line Configuration Provider

The CommandLineConfigurationProvider loads configuration from command-line argument key-value
pairs at runtime.
To activate command-line configuration, the AddCommandLine extension method is called on an
instance of ConfigurationBuilder.
AddCommandLine is automatically called when CreateDefaultBuilder(string []) is called. For more
information, see the Default configuration section.
CreateDefaultBuilder also loads:
Optional configuration from appsettings.json and appsettings.{Environment}.json files.
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.
For apps based on the ASP.NET Core templates, AddCommandLine has already been called by
CreateDefaultBuilder . To add additional configuration providers and maintain the ability to override
configuration from those providers with command-line arguments, call the app's additional providers
in ConfigureAppConfiguration and call AddCommandLine last.

.ConfigureAppConfiguration((hostingContext, config) =>

{
// Call other providers here
config.AddCommandLine(args);
})

Example
The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the
host, which includes a call to AddCommandLine.
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 isn't required 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=value1 --CommandLineKey2=value2 /CommandLineKey3=value3
dotnet run --CommandLineKey1 value1 /CommandLineKey2 value2
dotnet run CommandLineKey1= CommandLineKey2=value2

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.
Create a switch mappings dictionary. In the following example, two switch mappings are created:

public static readonly Dictionary<string, string> _switchMappings =

new Dictionary<string, string>
{
{ "-CLKey1", "CommandLineKey1" },
{ "-CLKey2", "CommandLineKey2" }
};

When the host is built, call AddCommandLine with the switch mappings dictionary:

.ConfigureAppConfiguration((hostingContext, config) =>

{
config.AddCommandLine(args, _switchMappings);
})

For apps that use switch mappings, the call to CreateDefaultBuilder shouldn't pass arguments. The
CreateDefaultBuilder method's AddCommandLine call doesn't include mapped switches, and there's no
way to pass the switch mapping dictionary to CreateDefaultBuilder . The solution isn't 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.

After the switch mappings dictionary is created, it contains the data shown in the following table.

KEY VALUE

-CLKey1 CommandLineKey1

-CLKey2 CommandLineKey2

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

CommandLineKey2 value2

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 (for example, Bash). A double underscore ( __ ) is supported by all platforms and is
automatically 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 used to load environment variables prefixed with DOTNET_ for host
configuration when a new host builder is initialized with the Generic Host and CreateDefaultBuilder is
called. For more information, see the Default configuration section.
AddEnvironmentVariables is used to load environment variables prefixed with ASPNETCORE_ for host
configuration when a new host builder is initialized with the Web Host and CreateDefaultBuilder is
called. For more information, see the Default configuration section.
CreateDefaultBuilder also loads:
App configuration from unprefixed environment variables by calling AddEnvironmentVariables
without a prefix.
Optional configuration from appsettings.json and appsettings.{Environment}.json files.
User secrets (Secret Manager) in the Development environment.
Command-line arguments.
The Environment Variables 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.
If you need to provide app configuration from additional environment variables, call the app's
additional providers in ConfigureAppConfiguration and call AddEnvironmentVariables with the prefix.

.ConfigureAppConfiguration((hostingContext, config) =>

{
// Call additional providers here as needed.
// Call AddEnvironmentVariables last if you need to allow
// environment variables to override values from other
// providers.
config.AddEnvironmentVariables(prefix: "PREFIX_");
})
}
Example
The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the
host, which includes a call to AddEnvironmentVariables .
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. See the sample app's Pages/Index.cshtml.cs file.
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:

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:

var config = new ConfigurationBuilder()

.AddEnvironmentVariables("CUSTOM_")
.Build();

The prefix is stripped off when the configuration key-value pairs are created.
When the host builder is created, host configuration is provided by environment variables. For more
information on the prefix used for these environment variables, see the Default configuration section.
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
:
Value: System.Data.SqlClient

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
INI 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.
Call ConfigureAppConfiguration when building the host to specify the app's configuration:

.ConfigureAppConfiguration((hostingContext, config) =>

{
config.SetBasePath(Directory.GetCurrentDirectory());
config.AddIniFile(
"config.ini", optional: true, reloadOnChange: true);
})
The base path is set with SetBasePath.
A generic example of an INI configuration file:

[section0]
key0=value
key1=value

[section1]
subsection:key=value

[section2:subsection0]
key=value

[section2:subsection1]
key=value

The previous configuration file loads the following keys with value :
section0:key0
section0:key1
section1:subsection:key
section2:subsection0:key
section2:subsection1:key
JSON Configuration Provider
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.
Overloads permit specifying:
Whether the file is optional.
Whether the configuration is reloaded if the file changes.
The IFileProvider used to access the file.
AddJsonFile is automatically called twice when you initialize a new host builder 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.
For more information, see the Default configuration section.
CreateDefaultBuilder also loads:
Environment variables.
User secrets (Secret Manager) in the Development environment.
Command-line arguments.
The JSON Configuration Provider is established first. Therefore, user secrets, environment variables,
and command-line arguments override configuration set by the appsettings files.
Call ConfigureAppConfiguration when building the host to specify the app's configuration for files other
than appsettings.json and appsettings.{Environment}.json:
 .ConfigureAppConfiguration((hostingContext, config) =>
{
config.SetBasePath(Directory.GetCurrentDirectory());
config.AddJsonFile(
"config.json", optional: true, reloadOnChange: true);
})

The base path is set with SetBasePath.

Example
The sample app takes advantage of the static convenience method CreateDefaultBuilder to build the
host, which includes two calls to AddJsonFile . Configuration is loaded from appsettings.json and
appsettings.{Environment}.json.
1. Run the sample app. Open a browser to the app at http://localhost:5000 .
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 * *

XML Configuration Provider

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.
Overloads permit specifying:
Whether the file is optional.
Whether the configuration is reloaded if the file changes.
The IFileProvider used to access the file.
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.
Call ConfigureAppConfiguration when building the host to specify the app's configuration:

.ConfigureAppConfiguration((hostingContext, config) =>

{
config.SetBasePath(Directory.GetCurrentDirectory());
config.AddXmlFile(
"config.xml", optional: true, reloadOnChange: true);
})

The base path is set with SetBasePath.

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>

The previous configuration file loads the following keys with value :
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:

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
<section name="section0">
<key name="key0">value</key>
<key name="key1">value</key>
</section>
<section name="section1">
<key name="key0">value</key>
<key name="key1">value</key>
</section>
</configuration>

The previous configuration file loads the following keys with value :
section:section0:key:key0
section:section0:key:key1
section:section1:key:key0
section:section1:key:key1
Attributes can be used to supply values:

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
<key attribute="value" />
<section>
<key attribute="value" />
</section>
</configuration>

The previous configuration file loads the following keys with value :
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.
Overloads permit specifying:
An Action<KeyPerFileConfigurationSource> delegate that configures the source.
Whether the directory is optional and the path to the directory.
The double-underscore ( __ ) is used as a configuration key delimiter in file names. For example, the file
name Logging__LogLevel__System produces the configuration key Logging:LogLevel:System .
Call ConfigureAppConfiguration when building the host to specify the app's configuration:

.ConfigureAppConfiguration((hostingContext, config) =>

{
config.SetBasePath(Directory.GetCurrentDirectory());
var path = Path.Combine(
Directory.GetCurrentDirectory(), "path/to/files");
config.AddKeyPerFile(directoryPath: path, optional: true);
})

The base path is set with SetBasePath.

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>> .
Call ConfigureAppConfiguration when building the host to specify the app's configuration.
In the following example, a configuration dictionary is created:

public static readonly Dictionary<string, string> _dict =

new Dictionary<string, string>
{
{"MemoryCollectionKey1", "value1"},
{"MemoryCollectionKey2", "value2"}
};

The dictionary is used with a call to AddInMemoryCollection to provide the configuration:

.ConfigureAppConfiguration((hostingContext, config) =>

{
config.AddInMemoryCollection(_dict);
})

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 . If NumberKey isn't found in the
configuration keys, the default value of 99 is used.
Types the value as an int .
Stores the value in the NumberConfig property for use by the page.

public class IndexModel : PageModel

{
public IndexModel(IConfiguration config)
{
_config = config;
}

public int NumberConfig { get; private set; }

public void OnGet()

{
NumberConfig = _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
 section2:subsection0:key1
section2:subsection1:key0
section2:subsection1: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:

var configSection = _config.GetSection("section1");

The configSection doesn't have a value, only a key and a path.

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.
When GetSection returns a matching section, Value isn't populated. A Key and Path are returned when
the section exists.
GetChildren
A call to IConfiguration.GetChildren on section2 obtains an IEnumerable<IConfigurationSection> that
includes:
subsection0
subsection1

var configSection = _config.GetSection("section2");

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 Name { get; set; }
public string Registry { get; set; }
public string Class { get; set; }
public decimal Length { get; set; }
public bool Commissioned { get; set; }
}

public class Starship

{
public string Name { get; set; }
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": {
"name": "USS Enterprise",
"registry": "NCC-1701",
"class": "Constitution",
"length": 304.8,
"commissioned": false
},
"trademark": "Paramount Pictures Corp. http://www.paramount.com"
}

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
 KEY VALUE

trademark Paramount Pictures Corp. https://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;

var starship = new Starship();

_config.GetSection("starship").Bind(starship);
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 string Title { get; set; }
public DateTime AirDate { get; set; }
public int Episodes { get; set; }
}

public class Actors

{
public string Names { get; set; }
}
 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 string Title { get; set; }
public DateTime AirDate { get; set; }
public int Episodes { get; set; }
}

public class Actors

{
public string Names { get; set; }
}

The sample app has a tvshow.xml file containing the configuration data:

<?xml version="1.0" encoding="UTF-8"?>

<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>

<?xml version="1.0" encoding="UTF-8"?>

<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 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;
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>();

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:entries:0 value0

array:entries:1 value1

array:entries:2 value2

array:entries:4 value4

array:entries:5 value5

These keys and values are loaded in the sample app using the Memory Configuration Provider:
public class Program
{
public static Dictionary<string, string> arrayDict =
new Dictionary<string, string>
{
{"array:entries:0", "value0"},
{"array:entries:1", "value1"},
{"array:entries:2", "value2"},
{"array:entries:4", "value4"},
{"array:entries:5", "value5"}
};

public static void Main(string[] args)

{
CreateHostBuilder(args).Build().Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureAppConfiguration((hostingContext, config) =>
{
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);
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
 public class Program
{
public static Dictionary<string, string> arrayDict =
new Dictionary<string, string>
{
{"array:entries:0", "value0"},
{"array:entries:1", "value1"},
{"array:entries:2", "value2"},
{"array:entries:4", "value4"},
{"array:entries:5", "value5"}
};

public static void Main(string[] args)

{
CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.ConfigureAppConfiguration((hostingContext, config) =>
{
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);
})
.UseStartup<Startup>();
}

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; }
}

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>();

ArrayExample = _config.GetSection("array").Get<ArrayExample>();

The bound object, an instance of ArrayExample , receives the array data from configuration.

ARRAYEXAMPLE.ENTRIES INDEX ARRAYEXAMPLE.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 ArrayExample
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
ArrayExample.Entries matches the complete configuration array:

missing_value.json:

{
"array:entries:3": "value3"
}

In ConfigureAppConfiguration :

config.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 ArrayExample class instance is bound after the JSON Configuration Provider includes the entry
for index #3, the ArrayExample.Entries array includes the value.
 ARRAYEXAMPLE.ENTRIES INDEX ARRAYEXAMPLE.ENTRIES 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; }
}

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;
}
}

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:

public class Program

{
public static Dictionary<string, string> arrayDict =
new Dictionary<string, string>
{
{"array:entries:0", "value0"},
{"array:entries:1", "value1"},
{"array:entries:2", "value2"},
{"array:entries:4", "value4"},
{"array:entries:5", "value5"}
};

public static void Main(string[] args)

{
CreateHostBuilder(args).Build().Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureAppConfiguration((hostingContext, config) =>
{
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);
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}

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;
}
}

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:

public class Program

{
public static Dictionary<string, string> arrayDict =
new Dictionary<string, string>
{
{"array:entries:0", "value0"},
{"array:entries:1", "value1"},
{"array:entries:2", "value2"},
{"array:entries:4", "value4"},
{"array:entries:5", "value5"}
};

public static void Main(string[] args)

{
CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.ConfigureAppConfiguration((hostingContext, config) =>
{
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);
})
.UseStartup<Startup>();
}

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 class Startup
{
private readonly IConfiguration _config;

public Startup(IConfiguration config)

{
_config = config;
}

public void ConfigureServices(IServiceCollection services)

{
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:
 @using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<!DOCTYPE html>
<html lang="en">
<head>
<title>Index View</title>
</head>
<body>
<h1>Access configuration in an MVC view</h1>
<p>Configuration value for 'key': @Configuration["key"]</p>
</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 Use hosting startup assemblies
in ASP.NET Core.

Additional resources
Options pattern in ASP.NET Core
 Options pattern in ASP.NET Core
4/26/2019 • 12 minutes to read • Edit Online

By Luke Latham
For the 1.1 version of this topic, download Options pattern in ASP.NET Core (version 1.1, PDF ).
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 ) or Encapsulation – 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.
Options also provide a mechanism to validate configuration data. For more information, see the Options
validation section.
View or download sample code (how to download)

Prerequisites
Reference the Microsoft.AspNetCore.App metapackage or add a package reference to the
Microsoft.Extensions.Options.ConfigurationExtensions package.

Options interfaces
IOptionsMonitor<TOptions> is used to retrieve options and manage options notifications for TOptions
instances. IOptionsMonitor<TOptions> supports the following scenarios:
Change notifications
Named options
Reloadable configuration
Selective options invalidation (IOptionsMonitorCache<TOptions>)
Post-configuration scenarios allow you to set or change options after all IConfigureOptions<TOptions>
configuration occurs.
IOptionsFactory<TOptions> is responsible for creating new options instances. It has a single Create method.
The default implementation takes all registered IConfigureOptions<TOptions> and
IPostConfigureOptions<TOptions> and runs all the configurations first, followed by the post-configuration. It
distinguishes between IConfigureNamedOptions<TOptions> and IConfigureOptions<TOptions> and only calls
the appropriate interface.
IOptionsMonitorCache<TOptions> is used by IOptionsMonitor<TOptions> to cache TOptions instances. The
IOptionsMonitorCache<TOptions> invalidates options instances in the monitor so that the value is recomputed
(TryRemove). Values can be manually introduced with TryAdd. The Clear method is used when all named
instances should be recreated on demand.
IOptionsSnapshot<TOptions> is useful in scenarios where options should be recomputed on every request. For
more information, see the Reload configuration data with IOptionsSnapshot section.
IOptions<TOptions> can be used to support options. However, IOptions<TOptions> doesn't support the
preceding scenarios of IOptionsMonitor<TOptions>. You may continue to use IOptions<TOptions> in existing
frameworks and libraries that already use the IOptions<TOptions> interface and don't require the scenarios
provided by IOptionsMonitor<TOptions>.

General options configuration

General 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 and bound to configuration:

// Example #1: General configuration

// Register the Configuration instance which MyOptions binds against.
services.Configure<MyOptions>(Configuration);

The following page model uses constructor dependency injection with IOptionsMonitor<TOptions> to access
the settings (Pages/Index.cshtml.cs):

private readonly MyOptions _options;

public IndexModel(
IOptionsMonitor<MyOptions> optionsAccessor,
IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig,
IOptionsMonitor<MySubOptions> subOptionsAccessor,
IOptionsSnapshot<MyOptions> snapshotOptionsAccessor,
IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
_options = optionsAccessor.CurrentValue;
_optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
_subOptions = subOptionsAccessor.CurrentValue;
_snapshotOptions = snapshotOptionsAccessor.Value;
_named_options_1 = namedOptionsAccessor.Get("named_options_1");
_named_options_2 = namedOptionsAccessor.Get("named_options_2");
}

// 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": {
"Default": "Warning"
}
},
"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()

.SetBasePath(Directory.GetCurrentDirectory())
.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(
IOptionsMonitor<MyOptions> optionsAccessor,
IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig,
IOptionsMonitor<MySubOptions> subOptionsAccessor,
IOptionsSnapshot<MyOptions> snapshotOptionsAccessor,
IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
_options = optionsAccessor.CurrentValue;
_optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
_subOptions = subOptionsAccessor.CurrentValue;
_snapshotOptions = snapshotOptionsAccessor.Value;
_named_options_1 = namedOptionsAccessor.Get("named_options_1");
_named_options_2 = namedOptionsAccessor.Get("named_options_2");
}

// 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 from NuGet packages and
are applied in the order that they're registered. For more information, see Configuration in ASP.NET Core.
Each call to Configure 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_delegate, 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: Suboptions

// 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": {
"Default": "Warning"
}
},
"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(
IOptionsMonitor<MyOptions> optionsAccessor,
IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig,
IOptionsMonitor<MySubOptions> subOptionsAccessor,
IOptionsSnapshot<MyOptions> snapshotOptionsAccessor,
IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
_options = optionsAccessor.CurrentValue;
_optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
_subOptions = subOptionsAccessor.CurrentValue;
_snapshotOptions = snapshotOptionsAccessor.Value;
_named_options_1 = namedOptionsAccessor.Get("named_options_1");
_named_options_2 = namedOptionsAccessor.Get("named_options_2");
}

// Example #3: Suboptions

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 suboption 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 IOptionsMonitor<TOptions> directly into a view
(Pages/Index.cshtml.cs):

private readonly MyOptions _options;

public IndexModel(
IOptionsMonitor<MyOptions> optionsAccessor,
IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig,
IOptionsMonitor<MySubOptions> subOptionsAccessor,
IOptionsSnapshot<MyOptions> snapshotOptionsAccessor,
IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
_options = optionsAccessor.CurrentValue;
_optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
_subOptions = subOptionsAccessor.CurrentValue;
_snapshotOptions = snapshotOptionsAccessor.Value;
_named_options_1 = namedOptionsAccessor.Get("named_options_1");
_named_options_2 = namedOptionsAccessor.Get("named_options_2");
}

// Example #4: Bind options directly to the page

MyOptions = _options;

The sample app shows how to inject IOptionsMonitor<MyOptions> with an @inject directive:
 @page
@model IndexModel
@using Microsoft.Extensions.Options
@inject IOptionsMonitor<MyOptions> OptionsAccessor
@{
ViewData["Title"] = "Options Sample";
}

<h1>@ViewData["Title"]</h1>

When the app is run, the options values are shown in the rendered page:

Reload configuration data with IOptionsSnapshot

Reloading configuration data with IOptionsSnapshot<TOptions> is demonstrated in Example #5 in the sample
app.
IOptionsSnapshot<TOptions> supports reloading options with minimal processing overhead.
Options are computed once per request when accessed and cached for the lifetime of the request.
The following example demonstrates how a new IOptionsSnapshot<TOptions> 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(
IOptionsMonitor<MyOptions> optionsAccessor,
IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig,
IOptionsMonitor<MySubOptions> subOptionsAccessor,
IOptionsSnapshot<MyOptions> snapshotOptionsAccessor,
IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
_options = optionsAccessor.CurrentValue;
_optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
_subOptions = subOptionsAccessor.CurrentValue;
_snapshotOptions = snapshotOptionsAccessor.Value;
_named_options_1 = namedOptionsAccessor.Get("named_options_1");
_named_options_2 = namedOptionsAccessor.Get("named_options_2");
}
 // 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<TOptions> 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 OptionsServiceCollectionExtensions.Configure, which calls the
ConfigureNamedOptions<TOptions>.Configure extension 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 Get (Pages/Index.cshtml.cs):

private readonly MyOptions _named_options_1;

private readonly MyOptions _named_options_2;
 public IndexModel(
IOptionsMonitor<MyOptions> optionsAccessor,
IOptionsMonitor<MyOptionsWithDelegateConfig> optionsAccessorWithDelegateConfig,
IOptionsMonitor<MySubOptions> subOptionsAccessor,
IOptionsSnapshot<MyOptions> snapshotOptionsAccessor,
IOptionsSnapshot<MyOptions> namedOptionsAccessor)
{
_options = optionsAccessor.CurrentValue;
_optionsWithDelegateConfig = optionsAccessorWithDelegateConfig.CurrentValue;
_subOptions = subOptionsAccessor.CurrentValue;
_snapshotOptions = snapshotOptionsAccessor.Value;
_named_options_1 = namedOptionsAccessor.Get("named_options_1");
_named_options_2 = namedOptionsAccessor.Get("named_options_2");
}

// 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 options with the ConfigureAll method

Configure all options instances with the ConfigureAll method. The following code configures Option1 for all
configuration instances with a common value. Add the following code manually to the
Startup.ConfigureServices 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 IConfigureOptions<TOptions> instances are treated as targeting the
Options.DefaultName instance, which is string.Empty . IConfigureNamedOptions<TOptions> also implements
IConfigureOptions<TOptions>. The default implementation of the IOptionsFactory<TOptions> 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).

OptionsBuilder API
OptionsBuilder<TOptions> is used to configure TOptions instances. OptionsBuilder streamlines creating
named options as it's only a single parameter to the initial AddOptions<TOptions>(string optionsName) call instead
of appearing in all of the subsequent calls. Options validation and the ConfigureOptions overloads that accept
service dependencies are only available via OptionsBuilder .

// Options.DefaultName = "" is used.

services.AddOptions<MyOptions>().Configure(o => o.Property = "default");

services.AddOptions<MyOptions>("optionalName")
.Configure(o => o.Property = "named");

Use DI services to configure options

You can access other services from dependency injection while configuring options in two ways:
Pass a configuration delegate to Configure on OptionsBuilder<TOptions>. OptionsBuilder<TOptions>
provides overloads of Configure that allow you to use up to five services to configure options:

services.AddOptions<MyOptions>("optionalName")
.Configure<Service1, Service2, Service3, Service4, Service5>(
(o, s, s2, s3, s4, s5) =>
o.Property = DoSomethingWith(s, s2, s3, s4, s5));

Create your own type that implements IConfigureOptions<TOptions> or

IConfigureNamedOptions<TOptions> and register the type as a service.
We recommend passing a configuration delegate to Configure, since creating a service is more complex.
Creating your own type is equivalent to what the framework does for you when you use Configure. Calling
Configure registers a transient generic IConfigureNamedOptions<TOptions>, which has a constructor that
accepts the generic service types specified.

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(IOptionsMonitor<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);
}

Data Annotation-based validation is available from the Microsoft.Extensions.Options.DataAnnotations package

by calling the ValidateDataAnnotations method on OptionsBuilder<TOptions> .
Microsoft.Extensions.Options.DataAnnotations is included in the Microsoft.AspNetCore.App metapackage
(ASP.NET Core 2.2 or later).
 private class AnnotatedOptions
{
[Required]
public string Required { get; set; }

[StringLength(5, ErrorMessage = "Too long.")]

public string StringLength { get; set; }

[Range(-5, 5, ErrorMessage = "Out of range.")]

public int IntRange { get; set; }
}

[Fact]
public void CanValidateDataAnnotations()
{
var services = new ServiceCollection();
services.AddOptions<AnnotatedOptions>()
.Configure(o =>
{
o.StringLength = "111111";
o.IntRange = 10;
o.Custom = "nowhere";
})
.ValidateDataAnnotations();

var sp = services.BuildServiceProvider();

var error = Assert.Throws<OptionsValidationException>(() =>

sp.GetRequiredService<IOptionsMonitor<AnnotatedOptions>>().Value);
ValidateFailure<AnnotatedOptions>(error, Options.DefaultName, 1,
"DataAnnotation validation failed for members Required " +
"with the error 'The Required field is required.'.",
"DataAnnotation validation failed for members StringLength " +
"with the error 'Too long.'.",
"DataAnnotation validation failed for members IntRange " +
"with the error 'Out of range.'.");
}

Eager validation (fail fast at startup) is under consideration for a future release.

Options post-configuration
Set post-configuration with IPostConfigureOptions<TOptions>. Post-configuration runs after all
IConfigureOptions<TOptions> configuration occurs:

services.PostConfigure<MyOptions>(myOptions =>
{
myOptions.Option1 = "post_configured_option1_value";
});

PostConfigure is available to post-configure named options:

services.PostConfigure<MyOptions>("named_options_1", myOptions =>

{
myOptions.Option1 = "post_configured_option1_value";
});

Use PostConfigureAll to post-configure all configuration instances:

 services.PostConfigureAll<MyOptions>(myOptions =>
{
myOptions.Option1 = "post_configured_option1_value";
});

Accessing options during startup

IOptions<TOptions> and IOptionsMonitor<TOptions> can be used in Startup.Configure , since services are
built before the Configure method executes.

public void Configure(IApplicationBuilder app, IOptionsMonitor<MyOptions> optionsAccessor)

{
var option1 = optionsAccessor.CurrentValue.Option1;
}

Don't use IOptions<TOptions> or IOptionsMonitor<TOptions> in Startup.ConfigureServices . An inconsistent

options state may exist due to the ordering of service registrations.

Additional resources
Configuration in ASP.NET Core
 Use multiple environments in ASP.NET Core
4/26/2019 • 8 minutes to read • Edit Online

By Rick Anderson
ASP.NET Core configures app behavior based on the runtime environment using an environment variable.
View or download sample code (how to download)

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 .

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}

if (env.IsProduction() || env.IsStaging() || env.IsEnvironment("Staging_2"))

{
app.UseExceptionHandler("/Error");
}

app.UseStaticFiles();
app.UseMvc();
}

The preceding code:

Calls UseDeveloperExceptionPage 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:
 <environment include="Development">
<div>&lt;environment include="Development"&gt;</div>
</environment>
<environment exclude="Development">
<div>&lt;environment exclude="Development"&gt;</div>
</environment>
<environment include="Staging,Development,Staging_2">
<div>
&lt;environment include="Staging,Development,Staging_2"&gt;
</div>
</environment>

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",
"launchBrowser": true,
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Staging"
},
"applicationUrl": "http://localhost:54340/"
},
"Kestrel Staging": {
"commandName": "Project",
"launchBrowser": true,
"environmentVariables": {
"ASPNETCORE_My_Environment": "1",
"ASPNETCORE_DETAILEDERRORS": "1",
"ASPNETCORE_ENVIRONMENT": "Staging"
},
"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": {
"commandName": "Project",
"launchBrowser": true,
"applicationUrl": "https://localhost:5001;http://localhost:5000",
"environmentVariables": {
"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:

IISExpress
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": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
]
}

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.
Project file or publish profile
For Windows IIS deployments: Include the <EnvironmentName> property in the publish profile ( .pubxml) or
project file. This approach sets the environment in web.config when the project is published:
 <PropertyGroup>
<EnvironmentName>Development</EnvironmentName>
</PropertyGroup>

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:
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.<Environment>.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
{
public void ConfigureServices(IServiceCollection services)
{
...
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
...
}
}

// Startup class to use in the Production environment

public class StartupProduction
{
public void ConfigureServices(IServiceCollection services)
{
...
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
...
}
}

// Fallback Startup class

// Selected if the environment doesn't match a Startup{EnvironmentName} class
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
...
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
...
}
}

Use the UseStartup(IWebHostBuilder, String) overload that accepts an assembly name:

public static void Main(string[] args)

{
CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args)

{
var assemblyName = typeof(Startup).GetTypeInfo().Assembly.FullName;

return WebHost.CreateDefaultBuilder(args)
.UseStartup(assemblyName);
}
Startup method conventions
Configure and ConfigureServices support environment-specific versions of the form
Configure<EnvironmentName> and Configure<EnvironmentName>Services :

public class Startup

{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}

public IConfiguration Configuration { get; }

public void ConfigureServices(IServiceCollection services)

{
StartupConfigureServices(services);
}

public void ConfigureStagingServices(IServiceCollection services)

{
StartupConfigureServices(services);
}

private void StartupConfigureServices(IServiceCollection services)

{
services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}

if (env.IsProduction() || env.IsStaging() || env.IsEnvironment("Staging_2"))

{
app.UseExceptionHandler("/Error");
}

app.UseStaticFiles();
app.UseMvc();
}

public void ConfigureStaging(IApplicationBuilder app, IHostingEnvironment env)

{
if (!env.IsStaging())
{
throw new Exception("Not staging.");
}

app.UseExceptionHandler("/Error");
app.UseStaticFiles();
app.UseMvc();
}
}

Additional resources
App startup in ASP.NET Core
Configuration in ASP.NET Core
IHostingEnvironment.EnvironmentName
 Logging in .NET Core and ASP.NET Core
8/13/2019 • 29 minutes to read • Edit Online

By Tom Dykstra and Steve Smith

.NET Core supports a logging API that works with a variety of built-in and third-party logging providers. This
article shows how to use the logging API with built-in providers.
Most of the code examples shown in this article are from ASP.NET Core apps. The logging-specific parts of these
code snippets apply to any .NET Core app that uses the Generic host. For information about how to use the Generic
Host in non-web console apps, see Hosted services.
Logging code for apps without Generic Host differs in the way providers are added and loggers are created. Non-
host code examples are shown in those sections of the article.
View or download sample code (how to download)

Add providers
A logging provider displays or stores logs. For example, the Console provider displays logs on the console, and the
Azure Application Insights provider stores them in Azure Application Insights. Logs can be sent to multiple
destinations by adding multiple providers.
To add a provider in an app that uses Generic Host, call the provider's Add{provider name} extension method in
Program.cs:

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureLogging(logging =>
{
logging.ClearProviders();
logging.AddConsole();
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});

In a non-host console app, call the provider's Add{provider name} extension method while creating a LoggerFactory
:

var loggerFactory = LoggerFactory.Create(builder =>

{
builder
.AddFilter("Microsoft", LogLevel.Warning)
.AddFilter("System", LogLevel.Warning)
.AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
.AddConsole()
.AddEventLog();
});
ILogger logger = loggerFactory.CreateLogger<Program>();
logger.LogInformation("Example log message");

LoggerFactory and AddConsole require a using statement for Microsoft.Extensions.Logging .

The default ASP.NET Core project templates call CreateDefaultBuilder, which adds the following logging providers:
Console
Debug
EventSource
EventLog (only when running on Windows)
You can replace the default providers with your own choices. Call ClearProviders, and add the providers you want.

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureLogging(logging =>
{
logging.ClearProviders();
logging.AddConsole();
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});

To add a provider, call the provider's Add{provider name} extension method in Program.cs:

public static void Main(string[] args)

{
var webHost = new WebHostBuilder()
.UseKestrel()
.UseContentRoot(Directory.GetCurrentDirectory())
.ConfigureAppConfiguration((hostingContext, config) =>
{
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) =>
{
// Requires `using Microsoft.Extensions.Logging;`
logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
logging.AddConsole();
logging.AddDebug();
logging.AddEventSourceLogger();
})
.UseStartup<Startup>()
.Build();

webHost.Run();
}

The preceding code requires references to Microsoft.Extensions.Logging and Microsoft.Extensions.Configuration .

The default project template calls CreateDefaultBuilder, which adds the following logging providers:
Console
Debug
EventSource (starting in ASP.NET Core 2.2)
 public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>();

If you use CreateDefaultBuilder , you can replace the default providers with your own choices. Call ClearProviders,
and add the providers you want.

public static void Main(string[] args)

{
var host = CreateWebHostBuilder(args).Build();

var todoRepository = host.Services.GetRequiredService<ITodoRepository>();

todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

var logger = host.Services.GetRequiredService<ILogger<Program>>();

logger.LogInformation("Seeded the database.");

host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureLogging(logging =>
{
logging.ClearProviders();
logging.AddConsole();
});

Learn more about built-in logging providers and third-party logging providers later in the article.

Create logs
To create logs, use an ILogger<TCategoryName> object. In a web app or hosted service, get an ILogger from
dependency injection (DI). In non-host console apps, use the LoggerFactory to create an ILogger .
The following ASP.NET Core example creates a logger with TodoApiSample.Pages.AboutModel as the category. The
log category is a string that is associated with each log. The ILogger<T> instance provided by DI creates logs that
have the fully qualified name of type T as the category.

public class AboutModel : PageModel

{
private readonly ILogger _logger;

public AboutModel(ILogger<AboutModel> logger)

{
_logger = logger;
}

The following non-host console app example creates a logger with LoggingConsoleApp.Program as the category.
 var loggerFactory = LoggerFactory.Create(builder =>
{
builder
.AddFilter("Microsoft", LogLevel.Warning)
.AddFilter("System", LogLevel.Warning)
.AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
.AddConsole()
.AddEventLog();
});
ILogger logger = loggerFactory.CreateLogger<Program>();
logger.LogInformation("Example log message");

public class AboutModel : PageModel

{
private readonly ILogger _logger;

public AboutModel(ILogger<AboutModel> logger)

{
_logger = logger;
}

In the following ASP.NET Core and console app examples, the logger is used to create logs with Information as
the level. The Log level indicates the severity of the logged event.

public void OnGet()

{
Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
_logger.LogInformation("Message displayed: {Message}", Message);
}

var loggerFactory = LoggerFactory.Create(builder =>

{
builder
.AddFilter("Microsoft", LogLevel.Warning)
.AddFilter("System", LogLevel.Warning)
.AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
.AddConsole()
.AddEventLog();
});
ILogger logger = loggerFactory.CreateLogger<Program>();
logger.LogInformation("Example log message");

public void OnGet()

{
Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
_logger.LogInformation("Message displayed: {Message}", Message);
}

Levels and categories are explained in more detail later in this article.
Create logs in the Program class
To write logs in the Program class of an ASP.NET Core app, get an ILogger instance from DI after building the
host:
 public static void Main(string[] args)
{
var host = CreateHostBuilder(args).Build();

var todoRepository = host.Services.GetRequiredService<ITodoRepository>();

todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

var logger = host.Services.GetRequiredService<ILogger<Program>>();

logger.LogInformation("Seeded the database.");

IMyService myService = host.Services.GetRequiredService<IMyService>();

myService.WriteLog("Logged from MyService.");

host.Run();
}

Create logs in the Startup class

To write logs in the Startup.Configure method of an ASP.NET Core app, include an ILogger parameter in the
method signature:

public void Configure(IApplicationBuilder app, IHostEnvironment env, ILogger<Startup> logger)

{
if (env.IsDevelopment())
{
logger.LogInformation("In Development environment");
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}

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

app.UseRouting();

app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
endpoints.MapRazorPages();
});
}

Writing logs before completion of the DI container setup in the Startup.ConfigureServices method is not
supported:
Logger injection into the Startup constructor is not supported.
Logger injection into the Startup.ConfigureServices method signature is not supported

The reason for this restriction is that logging depends on DI and on configuration, which in turns depends on DI.
The DI container isn't set up until ConfigureServices finishes.
Constructor injection of a logger into Startup works in earlier versions of ASP.NET Core because a separate DI
container is created for the Web Host. For information about why only one container is created for the Generic
Host, see the breaking change announcement.
If you need to configure a service that depends on ILogger<T> , you can still do that by using constructor injection
or by providing a factory method. The factory method approach is recommended only if there is no other option.
For example, suppose you need to fill a property with a service from DI:

public void ConfigureServices(IServiceCollection services)

{
services.AddControllers();
services.AddRazorPages();

services.AddSingleton<IMyService>((container) =>
{
var logger = container.GetRequiredService<ILogger<MyService>>();
return new MyService() { Logger = logger };
});

services.AddSingleton<ITodoRepository, TodoRepository>();
}

The preceding highlighted code is a Func that runs the first time the DI container needs to construct an instance of
MyService . You can access any of the registered services in this way.

Create logs in Startup

To write logs in the Startup class, include an ILogger parameter in the constructor signature:
 public class Startup
{
private readonly ILogger _logger;

public Startup(IConfiguration configuration, ILogger<Startup> logger)

{
Configuration = configuration;
_logger = logger;
}

public IConfiguration Configuration { get; }

public void ConfigureServices(IServiceCollection services)

{
services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

// Add our repository type

services.AddSingleton<ITodoRepository, TodoRepository>();
_logger.LogInformation("Added TodoRepository to services");
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
if (env.IsDevelopment())
{
_logger.LogInformation("In Development environment");
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}

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

app.UseMvc();
}
}

Create logs in the Program class

To write logs in the Program class, get an ILogger instance from DI:
 public static void Main(string[] args)
{
var host = CreateWebHostBuilder(args).Build();

var todoRepository = host.Services.GetRequiredService<ITodoRepository>();

todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

var logger = host.Services.GetRequiredService<ILogger<Program>>();

logger.LogInformation("Seeded the database.");

host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureLogging(logging =>
{
logging.ClearProviders();
logging.AddConsole();
});

No asynchronous logger methods

Logging should be so fast that it isn't worth the performance cost of asynchronous code. If your logging data store
is slow, don't write to it directly. Consider writing the log messages to a fast store initially, then move them to the
slow store later. For example, if you're logging to SQL Server, you don't want to do that directly in a Log method,
since the Log methods are synchronous. Instead, synchronously add log messages to an in-memory queue and
have a background worker pull the messages out of the queue to do the asynchronous work of pushing data to
SQL Server.

Configuration
Logging provider configuration is provided by one or more configuration providers:
File formats (INI, JSON, and XML ).
Command-line arguments.
Environment variables.
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
}
}
}

The Logging property can have LogLevel and log provider properties (Console is shown).
The LogLevelproperty under Logging specifies the minimum level to log for selected categories. In the example,
System and Microsoft categories log at Information level, and all others log at Debug level.
Other properties under Logging specify logging providers. The example is for the Console provider. If a provider
supports log scopes, IncludeScopes indicates whether they're enabled. A provider property (such as Console in the
example) may also specify a LogLevel property. LogLevel under a provider specifies levels to log for that provider.
If levels are specified in Logging.{providername}.LogLevel , they override anything set in Logging.LogLevel .
For information on implementing configuration providers, see Configuration in ASP.NET Core.

Sample logging output

With the sample code shown in the preceding section, logs appear in the console when the app is run from the
command line. Here's an example of console output:

info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
Request starting HTTP/1.1 GET http://localhost:5000/api/todo/0
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
Request finished in 84.26180000000001ms 307
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
Request starting HTTP/2 GET https://localhost:5001/api/todo/0
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
Executing endpoint 'TodoApiSample.Controllers.TodoController.GetById (TodoApiSample)'
info: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[3]
Route matched with {action = "GetById", controller = "Todo", page = ""}. Executing controller action with
signature Microsoft.AspNetCore.Mvc.IActionResult GetById(System.String) on controller
TodoApiSample.Controllers.TodoController (TodoApiSample).
info: TodoApiSample.Controllers.TodoController[1002]
Getting item 0
warn: TodoApiSample.Controllers.TodoController[4000]
GetById(0) NOT FOUND
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
Executing HttpStatusCodeResult, setting HTTP status code 404
 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
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 42.9286ms
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]
Request finished in 148.889ms 404

The preceding logs were generated by making an HTTP Get request to the sample app at
http://localhost:5000/api/todo/0 .

Here's an example of the same logs as they appear in the Debug window when you run the sample app in Visual
Studio:

Microsoft.AspNetCore.Hosting.Diagnostics: Information: Request starting HTTP/2.0 GET

https://localhost:44328/api/todo/0
Microsoft.AspNetCore.Routing.EndpointMiddleware: Information: Executing endpoint
'TodoApiSample.Controllers.TodoController.GetById (TodoApiSample)'
Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker: Information: Route matched with {action =
"GetById", controller = "Todo", page = ""}. Executing controller action with signature
Microsoft.AspNetCore.Mvc.IActionResult GetById(System.String) on controller
TodoApiSample.Controllers.TodoController (TodoApiSample).
TodoApiSample.Controllers.TodoController: Information: Getting item 0
TodoApiSample.Controllers.TodoController: Warning: GetById(0) NOT FOUND
Microsoft.AspNetCore.Mvc.StatusCodeResult: Information: Executing HttpStatusCodeResult, setting HTTP status
code 404
Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker: Information: Executed action
TodoApiSample.Controllers.TodoController.GetById (TodoApiSample) in 34.167ms
Microsoft.AspNetCore.Routing.EndpointMiddleware: Information: Executed endpoint
'TodoApiSample.Controllers.TodoController.GetById (TodoApiSample)'
Microsoft.AspNetCore.Hosting.Diagnostics: Information: Request finished in 98.41300000000001ms 404

The logs that are created by the ILogger calls shown in the preceding section begin with "TodoApiSample". The
logs that begin with "Microsoft" categories are from ASP.NET Core framework code. ASP.NET Core and
application code are using the same logging API and providers.

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 are created by the ILogger calls shown in the preceding section begin with "TodoApi". The logs that
begin with "Microsoft" categories are from ASP.NET Core framework code. ASP.NET Core and application code
are using the same logging API and 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
When an ILogger object is created, a category is specified for it. That category is included with each log message
created by that instance of ILogger . The category may be any string, but the convention is to use the class name,
such as "TodoApi.Controllers.TodoController".
Use ILogger<T> to get an ILogger instance that uses the fully qualified type name of T as the category:

public class TodoController : Controller

{
private readonly ITodoRepository _todoRepository;
private readonly ILogger _logger;

public TodoController(ITodoRepository todoRepository,

ILogger<TodoController> logger)
{
_todoRepository = todoRepository;
_logger = logger;
}

public class TodoController : Controller

{
private readonly ITodoRepository _todoRepository;
private readonly ILogger _logger;

public TodoController(ITodoRepository todoRepository,

ILogger<TodoController> logger)
{
_todoRepository = todoRepository;
_logger = logger;
}

To explicitly specify the category, call ILoggerFactory.CreateLogger :

public class TodoController : Controller

{
private readonly ITodoRepository _todoRepository;
private readonly ILogger _logger;

public TodoController(ITodoRepository todoRepository,

ILoggerFactory logger)
{
_todoRepository = todoRepository;
_logger = logger.CreateLogger("TodoApiSample.Controllers.TodoController");
}
 public class TodoController : Controller
{
private readonly ITodoRepository _todoRepository;
private readonly ILogger _logger;

public TodoController(ITodoRepository todoRepository,

ILoggerFactory logger)
{
_todoRepository = todoRepository;
_logger = logger.CreateLogger("TodoApiSample.Controllers.TodoController");
}

ILogger<T> is equivalent to calling CreateLogger with the fully qualified type name of T .

Log level
Every log specifies a LogLevel value. The log level indicates the severity or importance. For example, you might
write an Information log when a method ends normally and a Warning log when a method returns a 404 Not
Found status code.
The following code creates Information and Warning logs:

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);
}

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);
}

In the preceding code, 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 the message template section later in this article.
Log methods that include the level in the method name (for example, LogInformation and LogWarning ) are
extension methods for ILogger. 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 ILogger and the logger extensions source code.
ASP.NET Core defines the following log levels, ordered here from lowest to highest severity.
Trace = 0
 For information that's typically valuable only for debugging. These messages may contain sensitive
application data and so shouldn't be enabled in a production environment. Disabled by default.
Debug = 1
For information that may be useful in development and debugging. Example:
Entering method Configure with flag set to true. Enable Debug level logs in production only when
troubleshooting, due to the high volume of logs.
Information = 2
For tracking the general flow of the app. These logs typically have some long-term value. Example:
Request received for path /api/todo

Warning = 3
For abnormal or unexpected events in the app flow. These may include errors or other conditions that don't
cause the app to stop but might 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 app-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.
Use the log level to control how much log output is written to a particular storage medium or display window. For
example:
In production, send Trace through Information level to a volume data store. Send Warning through Critical
to a value data store.
During development, send Warning through Critical to the console, and add Trace through Information
when troubleshooting.
The Log filtering section later in this article explains how to control which log levels a provider handles.
ASP.NET Core writes logs for framework events. The log examples earlier in this article excluded logs below
Information level, so no Debug or Trace level logs were created. Here's an example of console logs produced by
running the sample app configured to show Debug logs:
info: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[3]
Route matched with {action = "GetById", controller = "Todo", page = ""}. Executing controller action with
signature Microsoft.AspNetCore.Mvc.IActionResult GetById(System.String) on controller
TodoApiSample.Controllers.TodoController (TodoApiSample).
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
Execution plan of authorization filters (in the following order): None
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
Execution plan of resource filters (in the following order):
Microsoft.AspNetCore.Mvc.ViewFeatures.Filters.SaveTempDataFilter
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
Execution plan of action filters (in the following order):
Microsoft.AspNetCore.Mvc.Filters.ControllerActionFilter (Order: -2147483648),
Microsoft.AspNetCore.Mvc.ModelBinding.UnsupportedContentTypeFilter (Order: -3000)
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
Execution plan of exception filters (in the following order): None
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
Execution plan of result filters (in the following order):
Microsoft.AspNetCore.Mvc.ViewFeatures.Filters.SaveTempDataFilter
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder[22]
Attempting to bind parameter 'id' of type 'System.String' ...
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.Binders.SimpleTypeModelBinder[44]
Attempting to bind parameter 'id' of type 'System.String' using the name 'id' in request data ...
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.Binders.SimpleTypeModelBinder[45]
Done attempting to bind parameter 'id' of type 'System.String'.
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder[23]
Done attempting to bind parameter 'id' of type 'System.String'.
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder[26]
Attempting to validate the bound parameter 'id' of type 'System.String' ...
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder[27]
Done attempting to validate the bound parameter 'id' of type 'System.String'.
info: TodoApiSample.Controllers.TodoController[1002]
Getting item 0
warn: TodoApiSample.Controllers.TodoController[4000]
GetById(0) NOT FOUND
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[2]
Executed action TodoApiSample.Controllers.TodoController.GetById (TodoApiSample) in 32.690400000000004ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
Executed endpoint 'TodoApiSample.Controllers.TodoController.GetById (TodoApiSample)'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
Request finished in 176.9103ms 404
 info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
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)
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
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
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 0.8788ms
dbug: Microsoft.AspNetCore.Server.Kestrel[9]
Connection id "0HL6L7NEFF2QD" completed keep alive response.
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]
Request finished in 2.7286ms 404

Log event ID
Each log can specify an event ID. The sample app does this by using a locally defined LoggingEvents class:

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);
}

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;
}
 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);
}

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 associates a set of events. For example, all logs related to displaying a list of items on a page might be
1001.
The logging provider may store the event ID in an ID field, in the logging message, or not at all. The Debug
provider doesn't show event IDs. The console provider shows event IDs in brackets after the category:

info: TodoApi.Controllers.TodoController[1002]
Getting item invalidid
warn: TodoApi.Controllers.TodoController[4000]
GetById(invalidid) NOT FOUND

Log message template

Each log specifies a message template. The message template can contain placeholders for which arguments are
provided. Use names for the placeholders, not numbers.

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);
}
 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);
}

The order of placeholders, not their names, determines which parameters are used to provide their values. In the
following code, notice that the parameter names are out of sequence in the message template:

string p1 = "parm1";
string p2 = "parm2";
_logger.LogInformation("Parameter values: {p2}, {p1}", p1, p2);

This code creates a log message with the parameter values in sequence:

Parameter values: parm1, parm2

The logging framework works this way so that logging providers can implement semantic logging, also known as
structured logging. The arguments themselves are passed to the logging system, not just the formatted message
template. This information enables logging providers to store the parameter values as fields. For example, suppose
logger method calls look like this:

_logger.LogInformation("Getting item {ID} at {RequestTime}", id, DateTime.Now);

If you're sending the logs to Azure Table Storage, each Azure Table entity can have ID and RequestTime properties,
which simplifies queries on log data. A query can find all logs within a particular RequestTime range without
parsing 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:

catch (Exception ex)

{
_logger.LogWarning(LoggingEvents.GetItemNotFound, ex, "GetById({ID}) NOT FOUND", id);
return NotFound();
}
return new ObjectResult(item);

catch (Exception ex)

{
_logger.LogWarning(LoggingEvents.GetItemNotFound, ex, "GetById({ID}) NOT FOUND", id);
return NotFound();
}
return new ObjectResult(item);

Different providers handle the exception information in different ways. Here's an example of Debug provider
output from the code shown above.
 TodoApiSample.Controllers.TodoController: Warning: GetById(55) NOT FOUND

System.Exception: Item not found exception.

at TodoApiSample.Controllers.TodoController.GetById(String id) in
C:\TodoApiSample\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.
To suppress all logs, 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 template code calls CreateDefaultBuilder to set up logging for the Console and Debug providers. The
CreateDefaultBuilder method sets up logging to look for configuration in a Logging section, as explained earlier in
this article.
The configuration data specifies minimum log levels by provider and category, as in the following example:

{
"Logging": {
"Debug": {
"LogLevel": {
"Default": "Information"
}
},
"Console": {
"IncludeScopes": false,
"LogLevel": {
"Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
"Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
"Microsoft.AspNetCore.Mvc.Razor": "Error",
"Default": "Information"
}
},
"LogLevel": {
"Default": "Debug"
}
}
}
 {
"Logging": {
"Debug": {
"LogLevel": {
"Default": "Information"
}
},
"Console": {
"IncludeScopes": false,
"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 for all
providers. A single rule is chosen for each provider when an ILogger object is created.
Filter rules in code
The following example shows how to register filter rules in code:

.ConfigureLogging(logging =>
logging.AddFilter("System", LogLevel.Debug)
.AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Trace))

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureLogging(logging =>
logging.AddFilter("System", LogLevel.Debug)
.AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Trace));

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.R Warning

azor.Internal

3 Console Microsoft.AspNetCore.Mvc.R Debug

azor.Razor
 CATEGORIES THAT BEGIN
NUMBER PROVIDER WITH ... MINIMUM LOG LEVEL

4 Console Microsoft.AspNetCore.Mvc.R Error

azor

5 Console All categories Information

6 All providers All categories Debug

7 All providers System Debug

8 Debug Microsoft Trace

When an ILogger object is created, the ILoggerFactory object selects a single rule per provider to apply to that
logger. All messages written by an ILogger instance 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 no match is found, select all rules with an empty provider.
From the result of the preceding step, select rules with longest matching category prefix. If no match is 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 .
With the preceding list of rules, suppose 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.
The resulting ILogger instance sends logs of Trace level and above to the Debug provider. Logs of Debug level
and above are sent to the Console provider.
Provider aliases
Each provider defines an alias that can be used in configuration in place of the fully qualified type name. For the
built-in providers, use the following aliases:
Console
Debug
EventSource
EventLog
TraceSource
AzureAppServicesFile
AzureAppServicesBlob
ApplicationInsights
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:
 public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning));

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
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. For example:

.ConfigureLogging(logBuilder =>
{
logBuilder.AddFilter((provider, category, logLevel) =>
{
if (provider == "Microsoft.Extensions.Logging.Console.ConsoleLoggerProvider" &&
category == "TodoApiSample.Controllers.TodoController")
{
return false;
}
return true;
});
})

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureLogging(logBuilder =>
{
logBuilder.AddFilter((provider, category, logLevel) =>
{
if (provider == "Microsoft.Extensions.Logging.Console.ConsoleLoggerProvider" &&
category == "TodoApiSample.Controllers.TodoController")
{
return false;
}
return true;
});
});

System categories and levels

Here are some categories used by ASP.NET Core and Entity Framework Core, with notes about what logs to expect
from them:

CATEGORY NOTES

Microsoft.AspNetCore General ASP.NET Core diagnostics.

Microsoft.AspNetCore.DataProtection Which keys were considered, found, and used.

Microsoft.AspNetCore.HostFiltering Hosts allowed.

 CATEGORY NOTES

Microsoft.AspNetCore.Hosting How long HTTP requests took to complete and what time they
started. Which hosting startup assemblies were loaded.

Microsoft.AspNetCore.Mvc MVC and Razor diagnostics. Model binding, filter execution,

view compilation, action selection.

Microsoft.AspNetCore.Routing Route matching information.

Microsoft.AspNetCore.Server Connection start, stop, and keep alive responses. HTTPS

certificate information.

Microsoft.AspNetCore.StaticFiles Files served.

Microsoft.EntityFrameworkCore General Entity Framework Core diagnostics. Database activity

and configuration, change detection, migrations.

Log scopes
A scope can group a set of logical operations. This grouping can be used to attach the same data to each log that's
created as part of a set. For example, every log created as part of processing a transaction can include the
transaction ID.
A scope is an IDisposable type that's returned by the BeginScope method and lasts until it's disposed. Use a scope
by wrapping logger calls in a using block:

public IActionResult GetById(string id)

{
TodoItem item;
using (_logger.BeginScope("Message attached to logs created in the using block"))
{
_logger.LogInformation(LoggingEvents.GetItem, "Getting item {ID}", id);
item = _todoRepository.Find(id);
if (item == null)
{
_logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({ID}) NOT FOUND", id);
return NotFound();
}
}
return new ObjectResult(item);
}

public IActionResult GetById(string id)

{
TodoItem item;
using (_logger.BeginScope("Message attached to logs created in the using block"))
{
_logger.LogInformation(LoggingEvents.GetItem, "Getting item {ID}", id);
item = _todoRepository.Find(id);
if (item == null)
{
_logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({ID}) NOT FOUND", id);
return NotFound();
}
}
return new ObjectResult(item);
}
The following code enables scopes for the console provider:
Program.cs:

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureLogging((hostingContext, logging) =>
{
logging.ClearProviders();
logging.AddConsole(options => options.IncludeScopes = true);
logging.AddDebug();
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});

.ConfigureLogging((hostingContext, logging) =>

{
logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
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.

Each log message includes the scoped information:

info: TodoApiSample.Controllers.TodoController[1002]
=> RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApiSample.Controllers.TodoController.GetById
(TodoApi) => Message attached to logs created in the using block
Getting item 0
warn: TodoApiSample.Controllers.TodoController[4000]
=> RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApiSample.Controllers.TodoController.GetById
(TodoApi) => Message attached to logs created in the using block
GetById(0) NOT FOUND

Built-in logging providers

ASP.NET Core ships the following providers:
Console
Debug
EventSource
EventLog
TraceSource
AzureAppServicesFile
AzureAppServicesBlob
ApplicationInsights
For information on stdout and debug logging with the ASP.NET Core Module, see Troubleshoot ASP.NET Core on
Azure App Service and IIS and ASP.NET Core Module.
Console provider
The Microsoft.Extensions.Logging.Console provider package sends log output to the console.

logging.AddConsole();

To see console logging output, open a command prompt in the project folder and run the following command:

dotnet run

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();

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();

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 Core.
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();

AddEventLog overloads let you pass in EventLogSettings.

TraceSource provider
The Microsoft.Extensions.Logging.TraceSource provider package uses the TraceSource libraries and providers.

logging.AddTraceSource(sourceSwitchName);

AddTraceSource overloads let you pass in a source switch and a trace listener.
To use this provider, an app has to run on the .NET Framework (rather than .NET Core). The provider can route
messages to a variety of listeners, such as the TextWriterTraceListener used in the sample app.
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.

logging.AddAzureWebAppDiagnostics();

The provider package isn't included in the shared framework. To use the provider, add the provider package to the
project.
The provider package isn't included in the Microsoft.AspNetCore.App metapackage. When targeting .NET
Framework or referencing the Microsoft.AspNetCore.App metapackage, add the provider package to the project.
To configure provider settings, use AzureFileLoggerOptions and AzureBlobLoggerOptions, as shown in the
following example:
 public static void Main(string[] args)
{
var host = CreateHostBuilder(args).Build();

var todoRepository = host.Services.GetRequiredService<ITodoRepository>();

todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

var logger = host.Services.GetRequiredService<ILogger<Program>>();

logger.LogInformation("Seeded the database.");

host.Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureLogging(logging => logging.AddAzureWebAppDiagnostics())
.ConfigureServices(serviceCollection => serviceCollection
.Configure<AzureFileLoggerOptions>(options =>
{
options.FileName = "azure-diagnostics-";
options.FileSizeLimit = 50 * 1024;
options.RetainedFileCountLimit = 5;
}).Configure<AzureBlobLoggerOptions>(options =>
{
options.BlobName = "log.txt";
})
)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});

To configure provider settings, use AzureFileLoggerOptions and AzureBlobLoggerOptions, as shown in the

following example:

public static void Main(string[] args)

{
var host = CreateWebHostBuilder(args).Build();

var todoRepository = host.Services.GetRequiredService<ITodoRepository>();

todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

var logger = host.Services.GetRequiredService<ILogger<Program>>();

logger.LogInformation("Seeded the database.");

host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.ConfigureLogging(logging => logging.AddAzureWebAppDiagnostics())
.ConfigureServices(serviceCollection => serviceCollection
.Configure<AzureFileLoggerOptions>(options =>
{
options.FileName = "azure-diagnostics-";
options.FileSizeLimit = 50 * 1024;
options.RetainedFileCountLimit = 5;
}).Configure<AzureBlobLoggerOptions>(options =>
{
options.BlobName = "log.txt";
}))
.UseStartup<Startup>();
An AddAzureWebAppDiagnostics overload lets you pass in AzureAppServicesDiagnosticsSettings. The settings
object 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 in addition to what's provided with an ILogger method
call.)
When you deploy to an App Service app, the application honors the settings in the App Service logs section of the
App Service page of the Azure portal. When the following settings are updated, the changes take effect
immediately without requiring a restart or redeployment of the app.
Application Logging (Filesystem )
Application Logging (Blob)
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.
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.
Azure log streaming
Azure log streaming lets you view log activity in real time from:
The app server
The web server
Failed request tracing
To configure Azure log streaming:
Navigate to the App Service logs page from your app's portal page.
Set Application Logging (Filesystem ) to On.
Choose the log Level.
Navigate to the Log Stream page to view app messages. They're logged by the app through the ILogger interface.
Azure Application Insights trace logging
The Microsoft.Extensions.Logging.ApplicationInsights provider package writes logs to Azure Application Insights.
Application Insights is a service that monitors a web app and provides tools for querying and analyzing the
telemetry data. If you use this provider, you can query and analyze your logs by using the Application Insights tools.
The logging provider is included as a dependency of Microsoft.ApplicationInsights.AspNetCore, which is the
package that provides all available telemetry for ASP.NET Core. If you use this package, you don't have to install
the provider package.
Don't use the Microsoft.ApplicationInsights.Web package—that's for ASP.NET 4.x.
For more information, see the following resources:
Application Insights overview
Application Insights for ASP.NET Core applications - Start here if you want to implement the full range of
Application Insights telemetry along with logging.
ApplicationInsightsLoggerProvider for .NET Core ILogger logs - Start here if you want to implement the
logging provider without the rest of Application Insights telemetry.
Application Insights logging adapters.
Install, configure, and initialize the Application Insights SDK - Interactive tutorial on the Microsoft Learn site.

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)
Sentry (GitHub repo)
Serilog (GitHub repo)
Stackdriver (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 ILoggerFactory .
For more information, see each provider's documentation. Third-party logging providers aren't supported by
Microsoft.

Additional resources
High-performance logging with LoggerMessage in ASP.NET Core
 Routing in ASP.NET Core
6/17/2019 • 34 minutes to read • Edit Online

By Ryan Nowak, Steve Smith, and Rick Anderson

For the 1.1 version of this topic, download Routing in ASP.NET Core (version 1.1, PDF ).
Routing is responsible for mapping request URIs to endpoint selectors and dispatching incoming requests to
endpoints. 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, routing is also able to generate URLs that map to endpoint selectors.
To use the latest routing scenarios in ASP.NET Core 2.2, specify the compatibility version to the MVC services
registration in Startup.ConfigureServices :

services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

The EnableEndpointRouting option determines if routing should internally use endpoint-based logic or the
IRouter-based logic of ASP.NET Core 2.1 or earlier. When the compatibility version is set to 2.2 or later, the
default value is true . Set the value to false to use the prior routing logic:

// Use the routing logic of ASP.NET Core 2.1 or earlier:

services.AddMvc(options => options.EnableEndpointRouting = false)
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

For more information on IRouter-based routing, see the ASP.NET Core 2.1 version of this topic.
Routing is responsible for mapping request URIs to route handlers and dispatching an incoming requests.
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 configured
routes from the app, routing is able to generate URLs that map to route handlers.
To use the latest routing scenarios in ASP.NET Core 2.1, specify the compatibility version to the MVC services
registration in Startup.ConfigureServices :

services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

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. For information on routing conventions in Razor Pages, see Razor Pages route and
app conventions in ASP.NET Core.

View or download sample code (how to download)

Routing basics
Most apps should choose a basic and descriptive routing scheme so that URLs are readable and meaningful.
The default conventional route {controller=Home}/{action=Index}/{id?} :
Supports a basic and descriptive routing scheme.
Is a useful starting point for UI-based apps.
Developers commonly add additional terse routes to high-traffic areas of an app in specialized situations (for
example, blog and ecommerce endpoints) using attribute routing or dedicated conventional routes.
Web APIs should use attribute routing to model the app's functionality as a set of resources where operations
are represented by HTTP verbs. This means that many operations (for example, GET, POST) on the same
logical resource will use the same URL. Attribute routing provides a level of control that's needed to carefully
design an API's public endpoint layout.
Razor Pages apps use default conventional routing to serve named resources in the Pages folder of an app.
Additional conventions are available that allow you to customize Razor Pages routing behavior. For more
information, see Introduction to Razor Pages in ASP.NET Core and Razor Pages route and app conventions in
ASP.NET Core.
URL generation support allows the app to be developed without hard-coding URLs to link the app together.
This support allows for starting with a basic routing configuration and modifying the routes after the app's
resource layout is determined.
Routing uses endpoints ( Endpoint ) to represent logical endpoints in an app.
An endpoint defines a delegate to process requests and a collection of arbitrary metadata. The metadata is used
implement cross-cutting concerns based on policies and configuration attached to each endpoint.
The routing system has the following characteristics:
Route template syntax is used to define routes with tokenized route parameters.
Conventional-style and attribute-style endpoint configuration is permitted.
IRouteConstraint is used to determine whether a URL parameter contains a valid value for a given
endpoint constraint.
App models, such as MVC/Razor Pages, register all of their endpoints, which have a predictable
implementation of routing scenarios.
The routing implementation makes routing decisions wherever desired in the middleware pipeline.
Middleware that appears after a Routing Middleware can inspect the result of the Routing Middleware's
endpoint decision for a given request URI.
It's possible to enumerate all of the endpoints in the app anywhere in the middleware pipeline.
An app can use routing to generate URLs (for example, for redirection or links) based on endpoint
information and thus avoid hard-coded URLs, which helps maintainability.
URL generation is based on addresses, which support arbitrary extensibility:
The Link Generator API (LinkGenerator) can be resolved anywhere using dependency injection (DI)
to generate URLs.
Where the Link Generator API isn't available via DI, IUrlHelper offers methods to build URLs.

NOTE
With the release of endpoint routing in ASP.NET Core 2.2, endpoint linking is limited to MVC/Razor Pages actions and
pages. The expansions of endpoint-linking capabilities is planned for future releases.
Routing uses routes (implementations of IRouter) to:
Map incoming requests to route handlers.
Generate the URLs used in responses.
By default, an app has a single collection of routes. When a request arrives, the routes in the collection are
processed in the order that they exist in the collection. The framework attempts to match an incoming request
URL to a route in the collection by calling the RouteAsync method on each route in the collection. A response
can use routing to generate URLs (for example, for redirection or links) based on route information and thus
avoid hard-coded URLs, which helps maintainability.
The routing system has the following characteristics:
Route template syntax is used to define routes with tokenized route parameters.
Conventional-style and attribute-style endpoint configuration is permitted.
IRouteConstraint is used to determine whether a URL parameter contains a valid value for a given endpoint
constraint.
App models, such as MVC/Razor Pages, register all of their routes, which have a predictable implementation
of routing scenarios.
A response can use routing to generate URLs (for example, for redirection or links) based on route
information and thus avoid hard-coded URLs, which helps maintainability.
URL generation is based on routes, which support arbitrary extensibility. IUrlHelper offers methods to build
URLs.
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 and handles routing in MVC and Razor Pages
apps. To learn how to use routing as a standalone component, see the Use Routing Middleware section.
URL matching
URL matching is the process by which routing dispatches an incoming request to an endpoint. This process is
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.
When a Routing Middleware executes, it sets an endpoint ( Endpoint ) and route values to a feature on the
HttpContext. For the current request:
Calling HttpContext.GetEndpoint gets the endpoint.
HttpRequest.RouteValues gets the collection of route values.

Middleware running after the Routing Middleware can see the endpoint and take action. For example, an
Authorization Middleware can interrogate the endpoint's metadata collection for an authorization policy. After
all of the middleware in the request processing pipeline is executed, the selected endpoint's delegate is invoked.
The routing system in endpoint routing is responsible for all dispatching decisions. Since the middleware
applies policies based on the selected endpoint, it's important that any decision that can affect dispatching or
the application of security policies is made inside the routing system.
When the endpoint delegate is executed, the properties of RouteContext.RouteData are set to appropriate
values based on the request processing performed thus far.
URL matching is the process by which routing dispatches an incoming request to a handler. This process is
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 no route handler is found to process the request, the middleware hands the request off to
the next middleware in the request pipeline.
The primary input to RouteAsync is the RouteContext.HttpContext associated with the current request. The
RouteContext.Handler and RouteContext.RouteData are outputs set after a route is matched.
A match that calls RouteAsync also sets the properties of the RouteContext.RouteData to appropriate values
based on the request processing performed thus far.
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 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 RouteData.DataTokens can be of any type, in contrast to RouteData.Values, which
must be 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 with LinkGenerator
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 endpoints and the URLs that access them.
Endpoint routing includes the Link Generator API (LinkGenerator). LinkGenerator is a singleton service that
can be retrieved from DI. The API can be used outside of the context of an executing request. MVC's IUrlHelper
and scenarios that rely on IUrlHelper, such as Tag Helpers, HTML Helpers, and Action Results, use the link
generator to provide link generating capabilities.
The link generator is backed by the concept of an address and address schemes. An address scheme is a way of
determining the endpoints that should be considered for link generation. For example, the route name and
route values scenarios many users are familiar with from MVC/Razor Pages are implemented as an address
scheme.
The link generator can link to MVC/Razor Pages actions and pages via the following extension methods:
GetPathByAction
GetUriByAction
GetPathByPage
GetUriByPage
An overload of these methods accepts arguments that include the HttpContext . These methods are functionally
equivalent to Url.Action and Url.Page but offer additional flexibility and options.
The GetPath* methods are most similar to Url.Action and Url.Page in that they generate a URI containing
an absolute path. The GetUri* methods always generate an absolute URI containing a scheme and host. The
methods that accept an HttpContext generate a URI in the context of the executing request. The ambient route
values, URL base path, scheme, and host from the executing request are used unless overridden.
LinkGenerator is called with an address. Generating a URI occurs in two steps:
1. An address is bound to a list of endpoints that match the address.
2. Each endpoint's RoutePattern is evaluated until a route pattern that matches the supplied values is found.
The resulting output is combined with the other URI parts supplied to the link generator and returned.
The methods provided by LinkGenerator support standard link generation capabilities for any type of address.
The most convenient way to use the link generator is through extension methods that perform operations for a
specific address type.

EX TENSION METHOD DESCRIPTION

GetPathByAddress Generates a URI with an absolute path based on the

provided values.

GetUriByAddress Generates an absolute URI based on the provided values.

WARNING
Pay attention to the following implications of calling LinkGenerator methods:
Use GetUri* extension methods with caution in an app configuration that doesn't validate the Host header of
incoming requests. If the Host header of incoming requests isn't validated, untrusted request input can be sent
back to the client in URIs in a view/page. We recommend that all production apps configure their server to
validate the Host header against known valid values.
Use LinkGenerator with caution in middleware in combination with Map or MapWhen . Map* changes the base
path of the executing request, which affects the output of link generation. All of the LinkGenerator APIs allow
specifying a base path. Always specify an empty base path to undo Map* 's affect on link generation.

Differences from earlier versions of routing

A few differences exist between endpoint routing in ASP.NET Core 2.2 or later and earlier versions of routing in
ASP.NET Core:
The endpoint routing system doesn't support IRouter-based extensibility, including inheriting from
Route.
Endpoint routing doesn't support WebApiCompatShim. Use the 2.1 compatibility version (
.SetCompatibilityVersion(CompatibilityVersion.Version_2_1) ) to continue using the compatibility shim.

Endpoint Routing has different behavior for the casing of generated URIs when using conventional
routes.
Consider the following default route template:

app.UseMvc(routes =>
{
routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");
});

Suppose you generate a link to an action using the following route:

var link = Url.Action("ReadPost", "blog", new { id = 17, });

With IRouter-based routing, this code generates a URI of /blog/ReadPost/17 , which respects the casing
of the provided route value. Endpoint routing in ASP.NET Core 2.2 or later produces /Blog/ReadPost/17
("Blog" is capitalized). Endpoint routing provides the IOutboundParameterTransformer interface that can be
used to customize this behavior globally or to apply different conventions for mapping URLs.
For more information, see the Parameter transformer reference section.
Link Generation used by MVC/Razor Pages with conventional routes behaves differently when
attempting to link to an controller/action or page that doesn't exist.
Consider the following default route template:

app.UseMvc(routes =>
{
routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");
});

Suppose you generate a link to an action using the default template with the following:

var link = Url.Action("ReadPost", "Blog", new { id = 17, });

With IRouter -based routing, the result is always /Blog/ReadPost/17 , even if the BlogController doesn't
exist or doesn't have a ReadPost action method. As expected, endpoint routing in ASP.NET Core 2.2 or
later produces /Blog/ReadPost/17 if the action method exists. However, endpoint routing produces an
empty string if the action doesn't exist. Conceptually, endpoint routing doesn't assume that the endpoint
exists if the action doesn't exist.
The link generation ambient value invalidation algorithm behaves differently when used with endpoint
routing.
Ambient value invalidation is the algorithm that decides which route values from the currently executing
request (the ambient values) can be used in link generation operations. Conventional routing always
invalidated extra route values when linking to a different action. Attribute routing didn't have this
behavior prior to the release of ASP.NET Core 2.2. In earlier versions of ASP.NET Core, links to another
action that use the same route parameter names resulted in link generation errors. In ASP.NET Core 2.2
or later, both forms of routing invalidate values when linking to another action.
Consider the following example in ASP.NET Core 2.1 or earlier. When linking to another action (or
another page), route values can be reused in undesirable ways.
In /Pages/Store/Product.cshtml:

@page "{id}"
@Url.Page("/Login")

In /Pages/Login.cshtml:

@page "{id?}"

If the URI is /Store/Product/18 in ASP.NET Core 2.1 or earlier, the link generated on the Store/Info page
by @Url.Page("/Login") is /Login/18 . The id value of 18 is reused, even though the link destination is
different part of the app entirely. The id route value in the context of the /Login page is probably a
user ID value, not a store product ID value.
In endpoint routing with ASP.NET Core 2.2 or later, the result is /Login . Ambient values aren't reused
when the linked destination is a different action or page.
Round-tripping route parameter syntax: Forward slashes aren't encoded when using a double-asterisk (
 ** ) catch-all parameter syntax.
During link generation, the routing system encodes the value captured in a double-asterisk ( ** ) catch-
all parameter (for example, {**myparametername} ) except the forward slashes. The double-asterisk catch-
all is supported with IRouter -based routing in ASP.NET Core 2.2 or later.
The single asterisk catch-all parameter syntax in prior versions of ASP.NET Core ( {*myparametername} )
remains supported, and forward slashes are encoded.

LINK GENERATED WITH

ROUTE URL.ACTION(NEW { CATEGORY = "ADMIN/PRODUCTS" }) …

/search/{*page} /search/admin%2Fproducts (the forward slash is

encoded)

/search/{**page} /search/admin/products

Middleware example
In the following example, a middleware uses the LinkGenerator API to create link to an action method that lists
store products. Using the link generator by injecting it into a class and calling GenerateLink is available to any
class in an app.

using Microsoft.AspNetCore.Routing;

public class ProductsLinkMiddleware

{
private readonly LinkGenerator _linkGenerator;

public ProductsLinkMiddleware(RequestDelegate next, LinkGenerator linkGenerator)

{
_linkGenerator = linkGenerator;
}

public async Task InvokeAsync(HttpContext httpContext)

{
var url = _linkGenerator.GetPathByAction("ListProducts", "Store");

httpContext.Response.ContentType = "text/plain";

await httpContext.Response.WriteAsync($"Go to {url} to see our products.");

}
}

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 route 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 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 Values and AmbientValues to decide whether 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. 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 should obtain services or
additional data associated with the current context.

TIP
Think of VirtualPathContext.Values as a set of overrides for the VirtualPathContext.AmbientValues. URL generation
attempts to reuse route values from the current request 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.
Create routes
Routing provides the Route class as the standard implementation of IRouter. Route uses the route template
syntax to define patterns to 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. Any of the IRouteBuilder extension methods create an instance of Route and add it to the route
collection.
MapRoute doesn't accept a route handler parameter. MapRoute only adds routes that are handled by the
DefaultHandler. To learn more about routing in MVC, see Routing to controller actions in ASP.NET Core.
MapRoute doesn't accept a route handler parameter. MapRoute only adds routes that are handled by the
DefaultHandler. The default handler is an IRouter , and the handler might not 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 in 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",
template: "{controller=Home}/{action=Index}/{id?}");

This template matches a URL path and extracts the route values. For example, the path /Products/Details/17
generates the following route values: { controller = Products, action = Details, id = 17 } .
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. The parameters defined by
enclosing the parameter name in braces { ... } .
The preceding template could also match the URL path / and 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 an optional parameter.
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 the Route
template reference section for a thorough description of route template scenarios and syntax.
In the following example, the route parameter definition {id:int} defines a route constraint for the id route
parameter:

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 . 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 an explanation of route
constraints provided by the framework.
Additional overloads of MapRoute accept values for constraints , dataTokens , and defaults . 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 MapRoute examples create equivalent routes:

routes.MapRoute(
name: "default_route",
template: "{controller}/{action}/{id?}",
defaults: new { controller = "Home", action = "Index" });

routes.MapRoute(
name: "default_route",
template: "{controller=Home}/{action=Index}/{id?}");

TIP
The inline syntax for defining constraints and defaults can be convenient for simple routes. However, there are scenarios,
such as data tokens, that aren't supported by inline syntax.

The following example demonstrates a few additional scenarios:

routes.MapRoute(
name: "blog",
template: "Blog/{**article}",
defaults: new { controller = "Blog", action = "ReadArticle" });

The preceding 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 double asterisk ( ** ) before the route parameter name. Catch-
all route parameters capture the remainder of the URL path and can also match the empty string.
 routes.MapRoute(
name: "blog",
template: "Blog/{*article}",
defaults: new { controller = "Blog", action = "ReadArticle" });

The preceding template matches a URL path like /Blog/All-About-Routing/Introduction and extracts the values
{ 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.
The following 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" });

The preceding 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 } .

Route class 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.

The following example uses a general ASP.NET Core MVC default route:
 routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");

With the route values { controller = Products, action = List } , the URL /Products/List is generated. The
route values are substituted for the corresponding route parameters to form the URL path. Since id is an
optional route parameter, the URL is successfully generated without a value for id .
With the route values { controller = Home, action = Index } , the URL / is generated. The provided route
values match the default values, and the segments corresponding to the default values are safely omitted.
Both URLs generated round-trip with the following route definition ( /Home/Index and / ) produce the same
route values that were used to generate the URL.

NOTE
An app using ASP.NET Core MVC should use UrlHelper to generate URLs instead of calling into routing directly.

For more information on URL generation, see the Url generation reference section.

Use Routing Middleware

Reference the Microsoft.AspNetCore.App metapackage in the app's project file.
Add routing to the service container in Startup.ConfigureServices :

public void ConfigureServices(IServiceCollection services)

{
services.AddRouting();
}

Routes must be configured in the Startup.Configure method. The sample app uses the following APIs:
RouteBuilder
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$)}/{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]

/package/track/-3/ Hello! Route values: [operation, track], [id, -3]

/package/track/ The request falls through, no match.

GET /hello/Joe Hi, Joe!

POST /hello/Joe The request falls through, matches HTTP GET only.

GET /hello/Joe/Smith The request falls 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
(RequestDelegateRouteBuilderExtensions):
MapDelete
MapGet
MapMiddlewareDelete
MapMiddlewareGet
MapMiddlewarePost
MapMiddlewarePut
MapMiddlewareRoute
 MapMiddlewareVerb
MapPost
MapPut
MapRoute
MapVerb
Some of listed methods, such as MapGet, require a RequestDelegate. 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, 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
a literal route parameter delimiter ( { or } ), escape the delimiter by repeating the character ( {{ or }} ).
URL patterns that attempt to capture a file name with an optional file extension have additional considerations.
For example, consider the template files/{filename}.{ext?} . When values for both filename and ext exist,
both values are populated. If only a value for 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 an asterisk ( * ) or double asterisk ( ** ) as a prefix to a route parameter to bind to the rest of the
URI. These are called a catch-all parameters. For example, blog/{**slug} matches any URI that starts with
/blog and has any value following it, which is assigned to the slug route value. Catch-all parameters can also
match the empty string.
The catch-all parameter escapes the appropriate characters when the route is used to generate a URL, including
path separator ( / ) characters. For example, the route foo/{*path} with route values { path = "my/path" }
generates foo/my%2Fpath . Note the escaped forward slash. To round-trip path separator characters, use the **
route parameter prefix. The route foo/{**path} with { path = "my/path" } generates foo/my/path .
You can use the asterisk ( * ) 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 has any value
following it, which is assigned to the slug route value. Catch-all parameters can also match the empty string.
The catch-all parameter escapes the appropriate characters when the route is used to generate a URL, including
path separator ( / ) characters. For example, the route foo/{*path} with route values { path = "my/path" }
generates foo/my%2Fpath . Note the escaped forward slash.
Route parameters may have default values designated by specifying the default value 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. Route parameters are
made optional 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 have constraints that 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 enclosed in parentheses ( (...) ) after the constraint name. Multiple
inline constraints can be specified by appending another colon ( : ) and constraint name.
The constraint name and arguments are 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 list of
the constraints provided by the framework, see the Route constraint reference section.
Route parameters may also have parameter transformers, which transform a parameter's value when
generating links and matching actions and pages to URLs. Like constraints, parameter transformers can be
added inline to a route parameter by adding a colon ( : ) and transformer name after the route parameter
name. For example, the route template blog/{article:slugify} specifies a slugify transformer. For more
information on parameter transformers, see the Parameter transformer reference section.
The following table demonstrates example route templates and their behavior.

ROUTE TEMPLATE EXAMPLE MATCHING URI THE REQUEST URI…

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 the Products controller and

List action.

{controller}/{action}/{id?} /Products/Details/123 Maps to the Products controller and

Details action ( id set to 123).

{controller=Home}/{action=Index}/{id?}/ Maps to the 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 match has occurred to the incoming URL and the URL path is tokenized into
route values. Route constraints generally inspect the route value associated via the route template and make a
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. Constraints are used in routing requests and link generation.

WARNING
Don't use constraints for input validation. If constraints are used for input validation, 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 similar routes, not to validate the inputs for a particular route.

The following table demonstrates example 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
culture - see warning)

double {weight:double} 1.234 , -1,001.01e8 Matches a valid double

value (in the invariant
culture - see warning)

float {weight:float} 1.234 , -1,001.01e8 Matches a valid float

value (in the invariant
culture - see warning)

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
 CONSTRAINT EXAMPLE EXAMPLE MATCHES NOTES

maxlength(value) {filename:maxlength(8)} Richard String must be no more

than 8 characters

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 \ (single backslash) characters provided in the string as \\ (double backslash)
characters in the C# source file in order to escape the \ string escape character (unless using verbatim string
literals). To escape routing parameter delimiter characters ( { , } , [ , ] ), double the characters in the
expression ( {{ , } , [[ , ]] ). The following table shows a regular expression and the escaped version.

REGULAR EXPRESSION ESCAPED REGULAR EXPRESSION

^\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 caret ( ^ ) character and match starting position of the
string. The expressions often end with the dollar sign ( $ ) character and match end 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
following table provides 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

For more information on regular expression syntax, see .NET Framework Regular Expressions.
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.

Custom Route Constraints

In addition to the built-in route constraints, custom route constraints can be created by implementing the
IRouteConstraint interface. The IRouteConstraint interface contains a single method, Match , which returns
true if the constraint is satisfied and false otherwise.

To use a custom IRouteConstraint, the route constraint type must be registered with the app's ConstraintMap in
the app's service container. A ConstraintMap is a dictionary that maps route constraint keys to IRouteConstraint
implementations that validate those constraints. An app's ConstraintMap can be updated in
Startup.ConfigureServices either as part of a services.AddRouting call or by configuring RouteOptions directly
with services.Configure<RouteOptions> . For example:

services.AddRouting(options =>
{
options.ConstraintMap.Add("customName", typeof(MyCustomConstraint));
});

The constraint can then be applied to routes in the usual manner, using the name specified when registering the
constraint type. For example:

[HttpGet("{id:customName}")]
public ActionResult<string> Get(string id)

Parameter transformer reference

Parameter transformers:
Execute when generating a link for a Route.
Implement Microsoft.AspNetCore.Routing.IOutboundParameterTransformer .
Are configured using ConstraintMap.
Take the parameter's route value and transform it to a new string value.
Result in using the transformed value in the generated link.
For example, a custom slugify parameter transformer in route pattern blog\{article:slugify} with
Url.Action(new { article = "MyTestArticle" }) generates blog\my-test-article .

To use a parameter transformer in a route pattern, configure it first using ConstraintMap in

Startup.ConfigureServices :

services.AddRouting(options =>
{
// Replace the type and the name used to refer to it with your own
// IOutboundParameterTransformer implementation
options.ConstraintMap["slugify"] = typeof(SlugifyParameterTransformer);
});

Parameter transformers are used by the framework to transform the URI where an endpoint resolves. For
example, ASP.NET Core MVC uses parameter transformers to transform the route value used to match an
area , controller , action , and page .

routes.MapRoute(
name: "default",
template: "{controller:slugify=Home}/{action:slugify=Index}/{id?}");

With the preceding route, the action SubscriptionManagementController.GetAll() is matched with the URI
/subscription-management/get-all . A parameter transformer doesn't change the route values used to generate a
link. For example, Url.Action("GetAll", "SubscriptionManagement") outputs /subscription-management/get-all .
ASP.NET Core provides API conventions for using a parameter transformers with generated routes:
ASP.NET Core MVC has the Microsoft.AspNetCore.Mvc.ApplicationModels.RouteTokenTransformerConvention
API convention. This convention applies a specified parameter transformer to all attribute routes in the app.
The parameter transformer transforms attribute route tokens as they are replaced. For more information,
see Use a parameter transformer to customize token replacement.
 Razor Pages has the Microsoft.AspNetCore.Mvc.ApplicationModels.PageRouteTransformerConvention API
convention. This convention applies a specified parameter transformer to all automatically discovered Razor
Pages. The parameter transformer transforms the folder and file name segments of Razor Pages routes. For
more information, see Use a parameter transformer to customize page routes.

URL generation reference

The following example shows how to generate a link to a route given a dictionary of route values and a
RouteCollection.

app.Run(async (context) =>

{
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/>");
await context.Response.WriteAsync(
$"<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
are convenient to use because they limit the number of values a developer must specify within a request
context. The current route values of the current request are considered ambient values for link generation. In an
ASP.NET Core MVC app's 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. Ambient values are also ignored when an explicitly
provided value overrides the ambient value. Matching occurs from left to right in the URL.
Values explicitly provided but that don't match a segment of the route 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

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.

Complex segments
Complex segments (for example [Route("/x{token}y")] ) are processed by matching up literals from right to left
in a non-greedy way. See this code for a detailed explanation of how complex segments are matched. The code
sample is not used by ASP.NET Core, but it provides a good explanation of complex segments.
 Handle errors in ASP.NET Core
7/18/2019 • 8 minutes to read • Edit Online

By Tom Dykstra, Luke Latham, and Steve Smith

This article covers common approaches to handling errors in ASP.NET Core apps.
View or download sample code. (How to download.) The article includes instructions about how to set
preprocessor directives ( #if , #endif , #define ) in the sample app to enable different scenarios.

Developer Exception Page

The Developer Exception Page displays detailed information about request exceptions. The page is made
available by the Microsoft.AspNetCore.Diagnostics package, which is in the Microsoft.AspNetCore.App
metapackage. Add code to the Startup.Configure method to enable the page when the app is running in the
Development environment:

if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}

Place the call to UseDeveloperExceptionPage before any middleware that you want to catch exceptions.

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. For more information on configuring
environments, see Use multiple environments in ASP.NET Core.

The page includes the following information about the exception and the request:
Stack trace
Query string parameters (if any)
Cookies (if any)
Headers
To see the Developer Exception Page in the sample app, use the DevEnvironment preprocessor directive and
select Trigger an exception on the home page.

Exception handler page

To configure a custom error handling page for the Production environment, use the Exception Handling
Middleware. The middleware:
Catches and logs exceptions.
Re-executes the request in an alternate pipeline for the page or controller indicated. The request isn't re-
 executed if the response has started.
In the following example, UseExceptionHandler adds the Exception Handling Middleware in non-Development
environments:

if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}

The Razor Pages app template provides an Error page (.cshtml) and PageModel class ( ErrorModel ) in the Pages
folder. For an MVC app, the project template includes an Error action method and an Error view. Here's the
action method:

[AllowAnonymous]
public IActionResult Error()
{
return View(new ErrorViewModel
{ RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier });
}

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.
Access the exception
Use IExceptionHandlerPathFeature to access the exception and the original request path in an error handler
controller or page:

var exceptionHandlerPathFeature =
HttpContext.Features.Get<IExceptionHandlerPathFeature>();
if (exceptionHandlerPathFeature?.Error is FileNotFoundException)
{
ExceptionMessage = "File error thrown";
}
if (exceptionHandlerPathFeature?.Path == "/index")
{
ExceptionMessage += " from home page";
}

WARNING
Do not serve sensitive error information to clients. Serving errors is a security risk.

To see the exception handling page in the sample app, use the ProdEnvironment and ErrorHandlerPage
preprocessor directives, and select Trigger an exception on the home page.

Exception handler lambda

An alternative to a custom exception handler page is to provide a lambda to UseExceptionHandler. Using a
lambda allows access to the error before returning the response.
Here's an example of using a lambda for exception handling:

if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler(errorApp =>
{
errorApp.Run(async context =>
{
context.Response.StatusCode = 500;
context.Response.ContentType = "text/html";

await context.Response.WriteAsync("<html lang=\"en\"><body>\r\n");

await context.Response.WriteAsync("ERROR!<br><br>\r\n");

var exceptionHandlerPathFeature =
context.Features.Get<IExceptionHandlerPathFeature>();

// Use exceptionHandlerPathFeature to process the exception (for example,

// logging), but do NOT expose sensitive error information directly to
// the client.

if (exceptionHandlerPathFeature?.Error is FileNotFoundException)
{
await context.Response.WriteAsync("File error thrown!<br><br>\r\n");
}

await context.Response.WriteAsync("<a href=\"/\">Home</a><br>\r\n");

await context.Response.WriteAsync("</body></html>\r\n");
await context.Response.WriteAsync(new string(' ', 512)); // IE padding
});
});
app.UseHsts();
}

WARNING
Do not serve sensitive error information from IExceptionHandlerFeature or IExceptionHandlerPathFeature to clients.
Serving errors is a security risk.

To see the result of the exception handling lambda in the sample app, use the ProdEnvironment and
ErrorHandlerLambda preprocessor directives, and select Trigger an exception on the home page.

UseStatusCodePages
By default, an ASP.NET Core app doesn't provide a status code page for HTTP status codes, such as 404 - Not
Found. The app returns a status code and an empty response body. To provide status code pages, use Status
Code Pages middleware.
The middleware is made available by the Microsoft.AspNetCore.Diagnostics package, which is in the
Microsoft.AspNetCore.App metapackage.
To enable default text-only handlers for common error status codes, call UseStatusCodePages in the
Startup.Configure method:

app.UseStatusCodePages();
Call UseStatusCodePages before request handling middleware (for example, Static File Middleware and MVC
Middleware).
Here's an example of text displayed by the default handlers:

Status Code: 404; Not Found

To see one of the various status code page formats in the sample app, use one of the preprocessor directives that
begin with StatusCodePages , and select Trigger a 404 on the home page.

UseStatusCodePages with format string

To customize the response content type and text, use the overload of UseStatusCodePages that takes a content
type and format string:

app.UseStatusCodePages(
"text/plain", "Status code page, status code: {0}");

UseStatusCodePages with lambda

To specify custom error-handling and response-writing code, use the overload of UseStatusCodePages that takes
a lambda expression:

app.UseStatusCodePages(async context =>

{
context.HttpContext.Response.ContentType = "text/plain";

await context.HttpContext.Response.WriteAsync(
"Status code page, status code: " +
context.HttpContext.Response.StatusCode);
});

UseStatusCodePagesWithRedirect
The UseStatusCodePagesWithRedirects extension method:
Sends a 302 - Found status code to the client.
Redirects the client to the location provided in the URL template.

app.UseStatusCodePagesWithRedirects("/StatusCode?code={0}");

The URL template can include a {0} placeholder for the status code, as shown in the example. If the URL
template starts with a tilde (~), the tilde is replaced by the app's PathBase . If you point to an endpoint within the
app, create an MVC view or Razor page for the endpoint. For a Razor Pages example, see
Pages/StatusCode.cshtml in the sample app.
This method is commonly used when the app:
Should redirect the client to a different endpoint, usually in cases where a different app processes the error.
For web apps, the client's browser address bar reflects the redirected endpoint.
Shouldn't preserve and return the original status code with the initial redirect response.
UseStatusCodePagesWithReExecute
The UseStatusCodePagesWithReExecute extension method:
Returns the original status code to the client.
Generates the response body by re-executing the request pipeline using an alternate path.

app.UseStatusCodePagesWithReExecute("/StatusCode","?code={0}");

If you point to an endpoint within the app, create an MVC view or Razor page for the endpoint. For a Razor
Pages example, see Pages/StatusCode.cshtml in the sample app.
This method is commonly used when the app should:
Process the request without redirecting to a different endpoint. For web apps, the client's browser address bar
reflects the originally requested endpoint.
Preserve and return the original status code with the response.
The URL and query string templates may include a placeholder ( {0} ) for the status code. The URL template
must start with a slash ( / ). When using a placeholder in the path, confirm that the endpoint (page or controller)
can process the path segment. For example, a Razor Page for errors should accept the optional path segment
value with the @page directive:

@page "{code?}"

The endpoint that processes the error can get the original URL that generated the error, as shown in the
following example:

var statusCodeReExecuteFeature = HttpContext.Features.Get<IStatusCodeReExecuteFeature>();

if (statusCodeReExecuteFeature != null)
{
OriginalURL =
statusCodeReExecuteFeature.OriginalPathBase
+ statusCodeReExecuteFeature.OriginalPath
+ statusCodeReExecuteFeature.OriginalQueryString;
}

Disable status code pages

To disable status code pages for an MVC controller or action method, use the [SkipStatusCodePages] attribute.
To disable status code pages for specific requests in a Razor Pages handler method or in an MVC controller, use
IStatusCodePagesFeature:

var statusCodePagesFeature = HttpContext.Features.Get<IStatusCodePagesFeature>();

if (statusCodePagesFeature != null)
{
statusCodePagesFeature.Enabled = false;
}

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.
Response headers
Once the headers for a response are sent:
The app can't change the response's status code.
Any exception pages or handlers can't run. The response must be completed or the connection aborted.

Server exception handling

In addition to the exception handling logic in your app, the HTTP server implementation can handle some
exceptions. If the server catches an exception before response headers are sent, the server sends a 500 - Internal
Server Error response without a response body. If the server catches an exception after response headers are
sent, the server closes the connection. Requests that aren't handled by your app are handled by the server. Any
exception that occurs when the server is handling the request is handled by the server's exception handling. The
app's custom error pages, exception handling middleware, and filters don't affect this behavior.

Startup exception handling

Only the hosting layer can handle exceptions that take place during app startup. The host can be configured to
capture startup errors and capture detailed errors.
The hosting layer can show an error page for a captured startup error only if the error occurs after host
address/port binding. If binding fails:
The hosting layer logs a critical exception.
The dotnet process crashes.
No error page is displayed when the HTTP server is Kestrel.
When running on IIS (or Azure App Service) or IIS Express, a 502.5 - Process Failure is returned by the ASP.NET
Core Module if the process can't start. For more information, see Troubleshoot ASP.NET Core on Azure App
Service and IIS.

Database error page

The Database Error Page middleware captures database-related exceptions that can be resolved by using Entity
Framework migrations. When these exceptions occur, an HTML response with details of possible actions to
resolve the issue is generated. This page should be enabled only in the Development environment. Enable the
page by adding code to Startup.Configure :

if (env.IsDevelopment())
{
app.UseDatabaseErrorPage();
}

Exception filters
In MVC apps, exception filters can be configured globally or on a per-controller or per-action basis. In Razor
Pages apps, they can be configured globally or per page model. These filters handle any unhandled exception
that occurs during the execution of a controller action or another filter. For more information, see Filters in
ASP.NET Core.
 TIP
Exception filters are useful for trapping exceptions that occur within MVC actions, but they're not as flexible as the
Exception Handling Middleware. We recommend using the middleware. Use filters only where you need to perform error
handling differently based on which MVC action is chosen.

Model state errors

For information about how to handle model state errors, see Model binding and Model validation.

Additional resources
Troubleshoot ASP.NET Core on Azure App Service and IIS
Common errors reference for Azure App Service and IIS with ASP.NET Core
 Make HTTP requests using IHttpClientFactory in
ASP.NET Core
8/2/2019 • 15 minutes to read • Edit Online

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.
View or download sample code (how to download)

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/AspNetCore.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 good 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;
}

public async Task OnGet()

{
var request = new HttpRequestMessage(HttpMethod.Get,
"repos/aspnet/AspNetCore.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.
Provides IntelliSense and compiler help when consuming clients.
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.
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/AspNetCore.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;
}

public async Task OnGet()

{
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

{
public string Message { get; set; }
}

A typed client can be added, using Refit to generate the implementation:

public void ConfigureServices(IServiceCollection services)

{
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,
CancellationToken cancellationToken)
{
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 IHttpClientFactory creates a separate
DI scope for each handler. Handlers are free to depend upon services of any scope. Services that handlers depend
upon are disposed when the handler is disposed.
Once registered, AddHttpMessageHandler can be called, passing in the type for the handler.
In the preceding code, the ValidateHeaderHandler is registered with DI. The handler must be registered in DI as a
transient service, never scoped. If the handler is registered as a scoped service and any services that the handler
depends upon are disposable:
The handler's services could be disposed before the handler goes out of scope.
The disposed handler services causes the handler to fail.
Once registered, AddHttpMessageHandler can be called, passing in the handler type.
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 one of the following approaches to share per-request state with message handlers:
Pass data into the handler using HttpRequestMessage.Properties .
Use IHttpContextAccessor to access the current request.
Create a custom AsyncLocal storage object to pass the data.

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:
Support adding Polly-based handlers to clients.
Can be used after installing the Microsoft.Extensions.Http.Polly NuGet package. The package isn't included in
the ASP.NET Core shared framework.
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>(

TimeSpan.FromSeconds(10));
var longTimeout = Policy.TimeoutAsync<HttpResponseMessage>(
TimeSpan.FromSeconds(30));

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 an HTTP GET, a 10-second timeout is applied. For any other
HTTP method, a 30-second timeout is used.
Add multiple Polly handlers
It's 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. The factory manages the lifetimes of the HttpMessageHandler instances.
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
};
});

Use IHttpClientFactory in a console app

In a console app, add the following package references to the project:
Microsoft.Extensions.Hosting
Microsoft.Extensions.Http
In the following example:
IHttpClientFactory is registered in the Generic Host's service container.
MyService creates a client factory instance from the service, which is used to create an HttpClient .
HttpClient is used to retrieve a webpage.
Main creates a scope to execute the service's GetPage method and write the first 500 characters of the
webpage content to the console.

using System;
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
class Program
{
static async Task<int> Main(string[] args)
{
var builder = new HostBuilder()
.ConfigureServices((hostContext, services) =>
{
services.AddHttpClient();
services.AddTransient<IMyService, MyService>();
}).UseConsoleLifetime();

var host = builder.Build();

 using (var serviceScope = host.Services.CreateScope())
{
var services = serviceScope.ServiceProvider;

try
{
var myService = services.GetRequiredService<IMyService>();
var pageContent = await myService.GetPage();

Console.WriteLine(pageContent.Substring(0, 500));
}
catch (Exception ex)
{
var logger = services.GetRequiredService<ILogger<Program>>();

logger.LogError(ex, "An error occurred.");

}
}

return 0;
}

public interface IMyService

{
Task<string> GetPage();
}

public class MyService : IMyService

{
private readonly IHttpClientFactory _clientFactory;

public MyService(IHttpClientFactory clientFactory)

{
_clientFactory = clientFactory;
}

public async Task<string> GetPage()

{
// Content from BBC One: Dr. Who website (©BBC)
var request = new HttpRequestMessage(HttpMethod.Get,
"https://www.bbc.co.uk/programmes/b006q2x0");
var client = _clientFactory.CreateClient();
var response = await client.SendAsync(request);

if (response.IsSuccessStatusCode)
{
return await response.Content.ReadAsStringAsync();
}
else
{
return $"StatusCode: {response.StatusCode}";
}
}
}
}

using System;
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
class Program
{
static async Task<int> Main(string[] args)
{
var builder = new HostBuilder()
 .ConfigureServices((hostContext, services) =>
{
services.AddHttpClient();
services.AddTransient<IMyService, MyService>();
}).UseConsoleLifetime();

var host = builder.Build();

using (var serviceScope = host.Services.CreateScope())

{
var services = serviceScope.ServiceProvider;

try
{
var myService = services.GetRequiredService<IMyService>();
var pageContent = await myService.GetPage();

Console.WriteLine(pageContent.Substring(0, 500));
}
catch (Exception ex)
{
var logger = services.GetRequiredService<ILogger<Program>>();

logger.LogError(ex, "An error occurred.");

}
}

return 0;
}

public interface IMyService

{
Task<string> GetPage();
}

public class MyService : IMyService

{
private readonly IHttpClientFactory _clientFactory;

public MyService(IHttpClientFactory clientFactory)

{
_clientFactory = clientFactory;
}

public async Task<string> GetPage()

{
// Content from BBC One: Dr. Who website (©BBC)
var request = new HttpRequestMessage(HttpMethod.Get,
"https://www.bbc.co.uk/programmes/b006q2x0");
var client = _clientFactory.CreateClient();
var response = await client.SendAsync(request);

if (response.IsSuccessStatusCode)
{
return await response.Content.ReadAsStringAsync();
}
else
{
return $"StatusCode: {response.StatusCode}";
}
}
}
}

Additional resources
Use HttpClientFactory to implement resilient HTTP requests
Implement HTTP call retries with exponential backoff with HttpClientFactory and Polly policies
Implement the Circuit Breaker pattern
 Static files in ASP.NET Core
7/18/2019 • 8 minutes to read • Edit Online

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 serving of these files.
View or download sample code (how to download)

Serve static files

Static files are stored within the 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.
The WebHost.CreateDefaultBuilder method sets the content root to the current directory:

public class Program

{
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>();
}

Set the content root to the current directory by invoking UseContentRoot inside of Program.Main :

public class Program

{
public static void Main(string[] args)
{
var host = new WebHostBuilder()
.UseKestrel()
.UseContentRoot(Directory.GetCurrentDirectory())
.UseIISIntegration()
.UseStartup<Startup>()
.UseApplicationInsights()
.Build();

host.Run();
}
}

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.
If targeting .NET Framework, add the Microsoft.AspNetCore.StaticFiles package to the project. If targeting .NET
Core, the Microsoft.AspNetCore.App metapackage includes this package.
If targeting .NET Framework, add the Microsoft.AspNetCore.StaticFiles package to the project. If targeting .NET
Core, the Microsoft.AspNetCore.All metapackage includes this package.
Add the Microsoft.AspNetCore.StaticFiles package to the project.
Configure the middleware which enables the serving of static files.
Serve files inside of web root
Invoke the UseStaticFiles method within Startup.Configure :

public void Configure(IApplicationBuilder app)

{
app.UseStaticFiles();
}

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" />

In the preceding code, the tilde character ~/ points to webroot. For more information, see Web root.
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:

public void Configure(IApplicationBuilder app)

{
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:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
var cachePeriod = env.IsDevelopment() ? "600" : "604800";
app.UseStaticFiles(new StaticFileOptions
{
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.
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 :

public void Configure(IApplicationBuilder app)

{
app.UseStaticFiles(); // For the wwwroot folder

app.UseStaticFiles(new StaticFileOptions
{
FileProvider = new PhysicalFileProvider(
Path.Combine(Directory.GetCurrentDirectory(), "wwwroot", "images")),
RequestPath = "/MyImages"
});

app.UseDirectoryBrowser(new DirectoryBrowserOptions
{
FileProvider = new PhysicalFileProvider(
Path.Combine(Directory.GetCurrentDirectory(), "wwwroot", "images")),
RequestPath = "/MyImages"
});
}

Add required services by invoking the AddDirectoryBrowser method from Startup.ConfigureServices :

public void ConfigureServices(IServiceCollection services)

{
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:
 public void Configure(IApplicationBuilder app)
{
app.UseStaticFiles(); // For the wwwroot folder

app.UseStaticFiles(new StaticFileOptions
{
FileProvider = new PhysicalFileProvider(
Path.Combine(Directory.GetCurrentDirectory(), "wwwroot", "images")),
RequestPath = "/MyImages"
});

app.UseDirectoryBrowser(new DirectoryBrowserOptions
{
FileProvider = new PhysicalFileProvider(
Path.Combine(Directory.GetCurrentDirectory(), "wwwroot", "images")),
RequestPath = "/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 :

public void Configure(IApplicationBuilder app)

{
app.UseDefaultFiles();
app.UseStaticFiles();
}

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 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:

public void Configure(IApplicationBuilder app)

{
// Serve my app-specific default file, if present.
DefaultFilesOptions options = new DefaultFilesOptions();
options.DefaultFileNames.Clear();
options.DefaultFileNames.Add("mydefault.html");
app.UseDefaultFiles(options);
app.UseStaticFiles();
}
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 :

public void Configure(IApplicationBuilder app)

{
app.UseStaticFiles(); // For the wwwroot folder

app.UseFileServer(new FileServerOptions
{
FileProvider = new PhysicalFileProvider(
Path.Combine(Directory.GetCurrentDirectory(), "MyStaticFiles")),
RequestPath = "/StaticFiles",
EnableDirectoryBrowsing = true
});
}

AddDirectoryBrowser must be called when the EnableDirectoryBrowsing property value is true :

public void ConfigureServices(IServiceCollection services)

{
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 perform a client-side redirect from http://{SERVER ADDRESS}/StaticFiles
(without a trailing slash) to http://{SERVER ADDRESS}/StaticFiles/ (with a trailing slash). Relative URLs within the
StaticFiles directory are 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.

public void Configure(IApplicationBuilder app)

{
// 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");

app.UseStaticFiles(new StaticFileOptions
{
FileProvider = new PhysicalFileProvider(
Path.Combine(Directory.GetCurrentDirectory(), "wwwroot", "images")),
RequestPath = "/MyImages",
ContentTypeProvider = provider
});

app.UseDirectoryBrowser(new DirectoryBrowserOptions
{
FileProvider = new PhysicalFileProvider(
Path.Combine(Directory.GetCurrentDirectory(), "wwwroot", "images")),
RequestPath = "/MyImages"
});
}

See MIME content types.

Non-standard content types
Static File Middleware understands almost 400 known file content types. If the user requests a file with an
unknown file type, Static File Middleware passes the request to the next middleware in the pipeline. If no
middleware handles the request, a 404 Not Found response is returned. If directory browsing is enabled, a link
to the file is displayed in a directory listing.
The following code enables serving unknown types and renders the unknown file as an image:

public void Configure(IApplicationBuilder app)

{
app.UseStaticFiles(new StaticFileOptions
{
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.

Additional resources
Middleware
Introduction to ASP.NET Core
 Introduction to Razor Pages in ASP.NET Core
7/18/2019 • 20 minutes to read • Edit Online

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
Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 2.2 or later

WARNING
If you use Visual Studio 2017, see dotnet/sdk issue #3124 for information about .NET Core SDK versions that don't
work with Visual Studio.

Create a Razor Pages project

Visual Studio
Visual Studio for Mac
Visual Studio Code
See Get started with Razor Pages for detailed instructions on how to create a Razor Pages project.

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 used in an ASP.NET Core app with controllers and views.
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.

Write 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 class Startup
{
public IHostingEnvironment HostingEnvironment { get; }

public void ConfigureServices(IServiceCollection services)

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

public void Configure(IApplicationBuilder app)

{
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:

using Microsoft.EntityFrameworkCore;

namespace RazorPagesContacts.Data
{
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;
using Microsoft.AspNetCore.Mvc.RazorPages;
using RazorPagesContacts.Data;

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 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:
 public async Task<IActionResult> OnPostAsync()
{
if (!ModelState.IsValid)
{
return Page();
}

_db.Customers.Add(Customer);
await _db.SaveChangesAsync();
return RedirectToPage("/Index");
}

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.

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");
}
}

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.

WARNING
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 GET binding 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
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

<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.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using RazorPagesContacts.Data;
using System.Collections.Generic;
using Microsoft.EntityFrameworkCore;

namespace RazorPagesContacts.Pages
{
public class IndexModel : PageModel
{
private readonly AppDbContext _db;

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);
await _db.SaveChangesAsync();
}

return RedirectToPage();
}
}
}

The Index.cshtml file contains the following markup to create an edit link for each contact:

<a asp-page="./Edit" asp-route-id="@contact.Id">edit</a>

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 . Use the asp-area
attribute to specify an area. For more information, see Areas in ASP.NET Core.
The Pages/Edit.cshtml file:
 @page "{id:int}"
@model RazorPagesContacts.Pages.EditModel
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

@{
ViewData["Title"] = "Edit Customer";
}

<h1>Edit Customer - @Model.Customer.Id</h1>

<form method="post">
<div asp-validation-summary="All"></div>
<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;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using RazorPagesContacts.Data;

namespace RazorPagesContacts.Pages
{
public class EditModel : PageModel
{
private readonly AppDbContext _db;

public EditModel(AppDbContext db)

{
_db = db;
}

[BindProperty]
public Customer Customer { get; set; }

public async Task<IActionResult> OnGetAsync(int id)

{
Customer = await _db.Customers.FindAsync(id);

if (Customer == null)
{
return RedirectToPage("/Index");
}

return Page();
}

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

_db.Attach(Customer).State = EntityState.Modified;

try
{
await _db.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
throw new Exception($"Customer {Customer.Id} not found!");
}

return RedirectToPage("/Index");
}
}
}

The Index.cshtml file also contains markup to create a delete button for each customer contact:

<button type="submit" asp-page-handler="delete"

asp-route-id="@contact.Id">delete</button>

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&amp;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 on 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 handler method with
the name OnPostRemoveAsync is selected.

public async Task<IActionResult> OnPostDeleteAsync(int id)

{
var contact = await _db.Customers.FindAsync(id);

if (contact != null)
{
_db.Customers.Remove(contact);
await _db.SaveChangesAsync();
}

return RedirectToPage();
}

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 as required

Properties on a PageModel can be decorated with the Required attribute:
 using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using System.ComponentModel.DataAnnotations;

namespace RazorPagesMovie.Pages.Movies
{
public class CreateModel : PageModel
{
public IActionResult OnGet()
{
return Page();
}

[BindProperty]
[Required(ErrorMessage = "Color is required")]
public string Color { get; set; }

public IActionResult OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

// Process color.

return RedirectToPage("./Index");
}
}
}

For more information, see Model validation.

Handle HEAD requests with an OnGet handler fallback

HEAD requests allow you to retrieve the headers for a specific resource. Unlike GET requests, HEAD requests
don't return a response body.
Ordinarily, an OnHead handler is created and called for HEAD requests:

public void OnHead()

{
HttpContext.Response.Headers.Add("HandledBy", "Handled by OnHead!");
}

In ASP.NET Core 2.1 or later, Razor Pages falls back to calling the OnGet handler if no OnHead handler is
defined. This behavior is enabled by the call to SetCompatibilityVersion in Startup.ConfigureServices :

services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

The default templates generate the SetCompatibilityVersion call in ASP.NET Core 2.1 and 2.2.
SetCompatibilityVersion effectively sets the Razor Pages option AllowMappingHeadRequestsToGetHandler to
true .

Rather than opting in to all behaviors with SetCompatibilityVersion , you can explicitly opt in to specific
behaviors. The following code opts in to allowing HEAD requests to be mapped to the OnGet 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
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

@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:

namespace RazorPagesContacts.Pages
{
public class EditModel : PageModel
{
private readonly AppDbContext _db;

public EditModel(AppDbContext db)

{
_db = db;
}

// Code removed for brevity.

The Pages/_ViewImports.cshtml file sets the following namespace:

@namespace RazorPagesContacts.Pages
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

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
@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 updated Pages/Create.cshtml view file:

@page
@model CreateModel

<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 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 :

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

_db.Customers.Add(Customer);
await _db.SaveChangesAsync();
return RedirectToPage("/Index");
}

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).
To redirect to a page in a different Area, specify the area:

RedirectToPage("/Index", new { area = "Services" });

For more information, see Areas in ASP.NET Core.

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
{
private readonly AppDbContext _db;

public CreateDotModel(AppDbContext db)

{
_db = db;
}

[TempData]
public string Message { get; set; }

[BindProperty]
public Customer Customer { get; set; }

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

_db.Customers.Add(Customer);
await _db.SaveChangesAsync();
Message = $"Customer {Customer.Name} added";
return RedirectToPage("./Index");
}
}

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]
public string Message { get; set; }

For more information, see TempData .

Multiple handlers per page

The following page generates markup for two handlers using the asp-page-handler Tag Helper:
 @page
@model CreateFATHModel

<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" 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:
 using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using RazorPagesContacts.Data;

namespace RazorPagesContacts.Pages.Customers
{
public class CreateFATHModel : PageModel
{
private readonly AppDbContext _db;

public CreateFATHModel(AppDbContext db)

{
_db = db;
}

[BindProperty]
public Customer Customer { get; set; }

public async Task<IActionResult> OnPostJoinListAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

_db.Customers.Add(Customer);
await _db.SaveChangesAsync();
return RedirectToPage("/Index");
}

public async Task<IActionResult> OnPostJoinListUCAsync()

{
if (!ModelState.IsValid)
{
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 .

<input type="submit" asp-page-handler="JoinList" value="Join" />

<input type="submit" asp-page-handler="JoinListUC" value="JOIN UC" />

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>
<div asp-validation-summary="All"></div>
<form method="POST">
<div>Name: <input asp-for="Customer.Name" /></div>
<input type="submit" asp-page-handler="JoinList" value="Join" />
<input type="submit" asp-page-handler="JoinListUC" value="JOIN UC" />
</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:

public void ConfigureServices(IServiceCollection services)

{
services.AddMvc()
.AddRazorPagesOptions(options =>
{
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()
.AddRazorPagesOptions(options =>
{
...
})
.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()
.AddRazorPagesOptions(options =>
{
...
})
.WithRazorPagesRoot("/path/to/razor/pages");

Additional resources
Introduction to ASP.NET Core
Razor syntax reference for ASP.NET Core
Areas in ASP.NET Core
Tutorial: 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
 Tutorial: Create a Razor Pages web app with ASP.NET
Core
8/13/2019 • 2 minutes to read • Edit Online

This series of tutorials explains the basics of building a Razor Pages web app.
For a more advanced introduction aimed at experienced developers, see Introduction to Razor Pages.
This series includes the following tutorials:
1. Create a Razor Pages web app
2. Add a model to a Razor Pages app
3. Scaffold (generate) Razor pages
4. Work with a database
5. Update Razor pages
6. Add search
7. Add a new field
8. Add validation
At the end, you'll have an app that can display and manage a database of movies.

Additional resources
Youtube version of this tutorial
 Tutorial: Get started with Razor Pages in ASP.NET
Core
7/31/2019 • 10 minutes to read • Edit Online

By Rick Anderson
This is the first tutorial of a series that teaches the basics of building an ASP.NET Core Razor Pages web app.
For a more advanced introduction aimed at experienced developers, see Introduction to Razor Pages.
At the end of the series, you'll have an app that manages a database of movies.
View or download sample code (how to download).
View or download sample code (how to download).
In this tutorial, you:
Create a Razor Pages web app.
Run the app.
Examine the project files.
At the end of this tutorial, you'll have a working Razor Pages web app that you'll build on in later tutorials.

Prerequisites
Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 3.0 Preview

Create a Razor Pages web app

Visual Studio
Visual Studio Code
Visual Studio for Mac
From the Visual Studio File menu, select New > Project.
Create a new ASP.NET Core Web Application and select Next.

Name the project RazorPagesMovie. It's important to name the project RazorPagesMovie so the
namespaces will match when you copy and paste code.

Select ASP.NET Core 3.0 in the dropdown, Web Application, and then select Create.
The following starter project is created:

Run the app

Visual Studio
Visual Studio Code
Visual Studio for Mac
Press Ctrl+F5 to run without the debugger.
Visual Studio displays the following dialog:
 Select Yes if you trust the IIS Express SSL certificate.
The following dialog is displayed:

Select Yes if you agree to trust the development certificate.

See Trust the ASP.NET Core HTTPS development certificate for more information.
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 the 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.

Examine the project files

Here's an overview of the main project folders and files that you'll work with in later tutorials.
Pages folder
Contains Razor pages and supporting files. Each Razor page is a pair of files:
A .cshtml file that contains HTML markup with C# code using Razor syntax.
A .cshtml.cs file that contains C# code that handles page events.
Supporting files have names that begin with an underscore. For example, the _Layout.cshtml file configures
UI elements common to all pages. This file sets up the navigation menu at the top of the page and the
copyright notice at the bottom of the page. For more information, see Layout in ASP.NET Core.
wwwroot folder
Contains static files, such as HTML files, JavaScript files, and CSS files. For more information, see Static files
in ASP.NET Core.
appSettings.json
Contains configuration data, such as connection strings. For more information, see Configuration in ASP.NET
Core.
Program.cs
Contains the entry point for the program. For more information, see .NET Generic Host.
Startup.cs
Contains code that configures app behavior. For more information, see App startup in ASP.NET Core.

Next steps
Advance to the next tutorial in the series:

ADD A
M ODEL

This is the first tutorial of a series. The series teaches the basics of building an ASP.NET Core Razor Pages
web app.
For a more advanced introduction aimed at experienced developers, see Introduction to Razor Pages.
At the end of the series, you'll have an app that manages a database of movies.
View or download sample code (how to download).
View or download sample code (how to download).
In this tutorial, you:
Create a Razor Pages web app.
Run the app.
Examine the project files.
At the end of this tutorial, you'll have a working Razor Pages web app that you'll build on in later tutorials.
Prerequisites
Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 2.2 or later

WARNING
If you use Visual Studio 2017, see dotnet/sdk issue #3124 for information about .NET Core SDK versions that don't
work with Visual Studio.

Create a Razor Pages web app

Visual Studio
Visual Studio Code
Visual Studio for Mac
From the Visual Studio File menu, select New > Project.
Create a new ASP.NET Core Web Application and select Next.

Name the project RazorPagesMovie. It's important to name the project RazorPagesMovie so the
namespaces will match when you copy and paste code.
 Select ASP.NET Core 2.2 in the dropdown, Web Application, and then select Create.

The following starter project is created:

Run the app
Visual Studio
Visual Studio Code
Visual Studio for Mac
Press Ctrl+F5 to run without the debugger.
Visual Studio displays the following dialog:

Select Yes if you trust the IIS Express SSL certificate.

The following dialog is displayed:
Select Yes if you agree to trust the development certificate.
See Trust the ASP.NET Core HTTPS development certificate for more information.
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 the 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.
On the app's home page, select Accept to consent to tracking.
This app doesn't track personal information, but the project template includes the consent feature in
case you need it to comply with the European Union's General Data Protection Regulation (GDPR ).

The following image shows the app after you give consent to tracking:
Examine the project files
Here's an overview of the main project folders and files that you'll work with in later tutorials.
Pages folder
Contains Razor pages and supporting files. Each Razor page is a pair of files:
A .cshtml file that contains HTML markup with C# code using Razor syntax.
A .cshtml.cs file that contains C# code that handles page events.
Supporting files have names that begin with an underscore. For example, the _Layout.cshtml file configures
UI elements common to all pages. This file sets up the navigation menu at the top of the page and the
copyright notice at the bottom of the page. For more information, see Layout in ASP.NET Core.
wwwroot folder
Contains static files, such as HTML files, JavaScript files, and CSS files. For more information, see Static files
in ASP.NET Core.
appSettings.json
Contains configuration data, such as connection strings. For more information, see Configuration in ASP.NET
Core.
Program.cs
Contains the entry point for the program. For more information, see .NET Generic Host.
Startup.cs
Contains code that configures app behavior, such as whether it requires consent for cookies. For more
information, see App startup in ASP.NET Core.

Additional resources
Youtube version of this tutorial

Next steps
Advance to the next tutorial in the series:
ADD A
M ODEL
 Add a model to a Razor Pages app in ASP.NET
Core
8/7/2019 • 25 minutes to read • Edit Online

By Rick Anderson
In this section, classes are added for managing movies in a database. These classes are used with Entity
Framework Core (EF Core) to work with a database. EF Core is an object-relational mapping (ORM ) framework
that simplifies data access.
The model classes 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.
View or download sample code (how to download).
View or download sample code (how to download).

Add a data model

Visual Studio
Visual Studio Code
Visual Studio for Mac
Right-click the RazorPagesMovie project > Add > New Folder. Name the folder Models.
Right click the Models folder. Select Add > Class. Name the class Movie.
Add the following properties to the Movie class:

using System;
using System.ComponentModel.DataAnnotations;

namespace RazorPagesMovie.Models
{
public class Movie
{
public int ID { get; set; }
public string Title { get; set; }

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }
public string Genre { get; set; }
public decimal Price { get; set; }
}
}

The Movie class contains:

The ID field is required by the database for the primary key.
[DataType(DataType.Date)] : The DataType attribute specifies the type of the data (Date). With this
attribute:
The user is not required to enter time information in the date field.
Only the date is displayed, not time information.
DataAnnotations are covered in a later tutorial.
Build the project to verify there are no compilation errors.

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.
Visual Studio
Visual Studio Code
Visual Studio for Mac
Create a Pages/Movies folder:
Right click on the Pages folder > Add > New Folder.
Name the folder Movies
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 change the generated name from
RazorPagesMovie.Models.RazorPagesMovieContext to RazorPagesMovie.Data.RazorPagesMovieContext.
This change is not required. It creates the database context class with the correct namespace.
Select Add.

The appsettings.json file is updated with the connection string used to connect to a local database.
Files created
Visual Studio
Visual Studio Code / Visual Studio for Mac
The scaffold process creates and updates the following files:
Pages/Movies: Create, Delete, Details, Edit, and Index.
 Data/RazorPagesMovieContext.cs
Updated
Startup.cs
The created and updated files are explained in the next section.

Initial migration
Visual Studio
Visual Studio Code
Visual Studio for Mac
In this section, the Package Manager Console (PMC ) is used 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 InitialCreate
Update-Database

The preceding commands generate the following warning: "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
'HasColumnType()'."
You can ignore that warning, it will be fixed in a later tutorial.
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 RazorPagesMovieContext.cs file). The
InitialCreate argument is used to name the migrations. Any name can be used, but by convention a name is
selected that describes the migration.
The ef database update command runs the Up method in the Migrations/<time-stamp>_InitialCreate.cs file.
The Up method creates the database.
Visual Studio
Visual Studio Code
Visual Studio for Mac
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:

public void ConfigureServices(IServiceCollection services)

{
services.AddRazorPages();

services.AddDbContext<RazorPagesMovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("RazorPagesMovieContext")));
}

The coordinates EF Core functionality (Create, Read, Update, Delete, etc.) for the
RazorPagesMovieContext
Movie model. The data context ( RazorPagesMovieContext ) is derived from
Microsoft.EntityFrameworkCore.DbContext. The data context specifies which entities are included in the data
model.

using Microsoft.EntityFrameworkCore;

namespace RazorPagesMovie.Models
{
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.
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. Any name can be used, but by convention a name that describes the
migration is used. For more information, see Tutorial: Using the migrations feature - ASP.NET MVC with EF
Core.
The Update-Database command runs the Up method in the Migrations/{time-stamp }_InitialCreate.cs file, which
creates the database.
Test the app
Run the app and append /Movies to the URL in the browser ( http://localhost:port/movies ).

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.

Test the Create link.

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 for non US-English date formats, the app must be
globalized. For globalization instructions, see this GitHub issue.

Test the Edit, Details, and Delete links.

The next tutorial explains the files created by scaffolding.

Additional resources
 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

In this section, classes are added for managing movies in a database. These classes are used with Entity
Framework Core (EF Core) to work with a database. EF Core is an object-relational mapping (ORM ) framework
that simplifies data access code.
The model classes 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.
View or download sample code (how to download).
View or download sample code (how to download).

Add a data model

Visual Studio
Visual Studio Code
Visual Studio for Mac
Right-click the RazorPagesMovie project > Add > New Folder. Name the folder Models.
Right click the Models folder. Select Add > Class. Name the class Movie.
Add the following properties to the Movie class:

using System;
using System.ComponentModel.DataAnnotations;

namespace RazorPagesMovie.Models
{
public class Movie
{
public int ID { get; set; }
public string Title { get; set; }

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }
public string Genre { get; set; }
public decimal Price { get; set; }
}
}

The Movie class contains:

The ID field is required by the database for the primary key.
[DataType(DataType.Date)] : The DataType attribute specifies the type of the data (Date). With this
attribute:
The user is not required to enter time information in the date field.
Only the date is displayed, not time information.
DataAnnotations are covered in a later tutorial.
Build the project to verify there are no compilation errors.

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.
Visual Studio
Visual Studio Code
Visual Studio for Mac
Create a Pages/Movies folder:
Right click on the Pages folder > Add > New Folder.
Name the folder Movies
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.
Select Add.

The appsettings.json file is updated with the connection string used to connect to a local database.
The scaffold process creates and updates the following files:
Files created
Pages/Movies: Create, Delete, Details, Edit, and Index.
Data/RazorPagesMovieContext.cs
File updated
Startup.cs
The created and updated files are explained in the next section.
Initial migration
Visual Studio
Visual Studio Code
Visual Studio for Mac
In this section, the Package Manager Console (PMC ) is used 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

The preceding commands generate the following warning: "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
'HasColumnType()'."
You can ignore that warning, it will be fixed in a later tutorial.
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 RazorPagesMovieContext.cs file). The
InitialCreate argument is used to name the migrations. Any name can be used, but by convention a name is
selected that describes the migration.
The ef database update command runs the Up method in the Migrations/<time-stamp>_InitialCreate.cs file.
The Up method creates the database.
Visual Studio
Visual Studio Code
Visual Studio for Mac
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:

// This method gets called by the runtime.

// Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
services.Configure<CookiePolicyOptions>(options =>
{
// This lambda determines whether user consent for non-essential cookies is
// needed for a given request.
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

services.AddDbContext<RazorPagesMovieContext>(options =>
options.UseSqlServer(
Configuration.GetConnectionString("RazorPagesMovieContext")));
}

The coordinates EF Core functionality (Create, Read, Update, Delete, etc.) for the
RazorPagesMovieContext
Movie model. The data context ( RazorPagesMovieContext ) is derived from
Microsoft.EntityFrameworkCore.DbContext. The data context specifies which entities are included in the data
model.

using Microsoft.EntityFrameworkCore;

namespace RazorPagesMovie.Models
{
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.
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. Any name can be used, but by convention a name that describes the
migration is used. For more information, see Tutorial: Using the migrations feature - ASP.NET MVC with EF
Core.
The Update-Database command runs the Up method in the Migrations/{time-stamp }_InitialCreate.cs file, which
creates the database.
Test the app
Run the app and append /Movies to the URL in the browser ( http://localhost:port/movies ).

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.

Test the Create link.

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 for non US-English date formats, the app must be
globalized. For globalization instructions, see this GitHub issue.

Test the Edit, Details, and Delete links.

The next tutorial explains the files created by scaffolding.
Additional resources

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
7/22/2019 • 16 minutes to read • Edit Online

By Rick Anderson
This tutorial examines the Razor Pages created by scaffolding in the previous tutorial.
View or download sample code (how to download).
View or download sample code (how to download).

The Create, Delete, Details, and Edit pages

Examine the Pages/Movies/Index.cshtml.cs Page Model:

// Unused usings removed.

using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using RazorPagesMovie.Models;
using System.Collections.Generic;
using System.Threading.Tasks;

namespace RazorPagesMovie.Pages.Movies
{
public class IndexModel : PageModel
{
private readonly RazorPagesMovie.Data.RazorPagesMovieContext _context;

public IndexModel(RazorPagesMovie.Data.RazorPagesMovieContext context)

{
_context = context;
}

public IList<Movie> Movie { get;set; }

public async Task OnGetAsync()

{
Movie = await _context.Movie.ToListAsync();
}
}
}

Razor Pages are derived from PageModel . By convention, the PageModel -derived class is called <PageName>Model .
The constructor uses dependency injection to add the RazorPagesMovieContext 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 OnGetreturns 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:
 public async Task<IActionResult> OnPostAsync()
{
if (!ModelState.IsValid)
{
return Page();
}

_context.Movie.Add(Movie);
await _context.SaveChangesAsync();

return RedirectToPage("./Index");
}
}

Examine the Pages/Movies/Index.cshtml Razor Page:

 @page
@model RazorPagesMovie.Pages.Movies.IndexModel

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-page="Create">Create New</a>
</p>
<table class="table">
<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
@model RazorPagesMovie.Pages.Movies.IndexModel

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.DisplayFor HTML Helpers on the page.

The layout page

Select the menu links (RazorPagesMovie, Home, and Privacy). Each page shows the same menu layout. The
menu layout is implemented in the Pages/Shared/_Layout.cshtml file. Open the Pages/Shared/_Layout.cshtml
file.
Layout templates allow the HTML container layout to be:
Specified in one place.
Applied in multiple pages in the site.
Find the @RenderBody() line. RenderBody is a placeholder where all the page-specific views show up, wrapped in
the layout page. For example, select the Privacy link and the Pages/Privacy.cshtml view is rendered inside the
RenderBody method.

ViewData and layout

Consider the following markup from the Pages/Movies/Index.cshtml file:

@page
@model RazorPagesMovie.Pages.Movies.IndexModel

@{
ViewData["Title"] = "Index";
}

The preceding highlighted markup is an example of Razor transitioning into C#. The { and } characters
enclose a block of C# code.
The PageModel base class contains a ViewData dictionary property that can be used to add data that and pass it
to a View. Objects are added to 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 _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.
Update the layout
Change the <title> element in the Pages/Shared/_Layout.cshtml file to display Movie rather than
RazorPagesMovie.

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@ViewData["Title"] - Movie</title>

Find the following anchor element in the Pages/Shared/_Layout.cshtml file.

<a class="navbar-brand" asp-area="" asp-page="/Index">RazorPagesMovie</a>

Replace the preceding element with the following markup:

<a class="navbar-brand" asp-page="/Movies/Index">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. The
asp-area attribute value is empty, so the area isn't used in the link. See Areas for more information.

Save your changes, and test the app by clicking on the RpMovie link. See the _Layout.cshtml file in GitHub if
you have any problems.
Test the other links (Home, RpMovie, 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.

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.
See 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.
The Create page model
Examine the Pages/Movies/Create.cshtml.cs page model:

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using RazorPagesMovie.Models;
using System;
using System.Threading.Tasks;

namespace RazorPagesMovie.Pages.Movies
{
public class CreateModel : PageModel
{
private readonly RazorPagesMovie.Data.RazorPagesMovieContext _context;

public CreateModel(RazorPagesMovie.Data.RazorPagesMovieContext context)

{
_context = context;
}

public IActionResult OnGet()

{
return Page();
}

[BindProperty]
public Movie Movie { get; set; }

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

_context.Movie.Add(Movie);
await _context.SaveChangesAsync();

return RedirectToPage("./Index");
}
}
}

The OnGet method initializes any state needed for the page. The Create page doesn't have any state to initialize,
so Page is returned. Later in the tutorial, an example of OnGet initializing state is shown. 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:
 public async Task<IActionResult> OnPostAsync()
{
if (!ModelState.IsValid)
{
return Page();
}

_context.Movie.Add(Movie);
await _context.SaveChangesAsync();

return RedirectToPage("./Index");
}

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. Client-side validation and model validation are discussed 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";
}

<h1>Create</h1>

<h4>Movie</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<input type="submit" value="Create" class="btn btn-primary" />
</div>
</form>
</div>
</div>

<div>
<a asp-page="Index">Back to List</a>
</div>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio displays the following tags in a distinctive bold font used for Tag Helpers:
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<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>
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 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>

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.
For more information on Tag Helpers such as <form method="post"> , see Tag Helpers in ASP.NET Core.

Additional resources

P R E V IO U S : A D D IN G A N E X T:
M ODEL D A TA B A SE
By Rick Anderson
This tutorial examines the Razor Pages created by scaffolding in the previous tutorial.
View or download sample.

The Create, Delete, Details, and Edit pages

Examine the Pages/Movies/Index.cshtml.cs Page Model:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using RazorPagesMovie.Models;

namespace RazorPagesMovie.Pages.Movies
{
public class IndexModel : PageModel
{
private readonly RazorPagesMovie.Models.RazorPagesMovieContext _context;

public IndexModel(RazorPagesMovie.Models.RazorPagesMovieContext context)

{
_context = context;
}

public IList<Movie> Movie { get;set; }

public async Task OnGetAsync()

{
Movie = await _context.Movie.ToListAsync();
}
}
}

Razor Pages are derived from PageModel . By convention, the PageModel -derived class is called <PageName>Model .
The constructor uses dependency injection to add the RazorPagesMovieContext 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:
 public async Task<IActionResult> OnPostAsync()
{
if (!ModelState.IsValid)
{
return Page();
}

_context.Movie.Add(Movie);
await _context.SaveChangesAsync();

return RedirectToPage("./Index");
}

Examine the Pages/Movies/Index.cshtml Razor Page:

 @page
@model RazorPagesMovie.Pages.Movies.IndexModel

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-page="Create">Create New</a>
</p>
<table class="table">
<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
@model RazorPagesMovie.Pages.Movies.IndexModel

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.DisplayFor HTML Helpers on the page.

The layout page

Select the menu links (RazorPagesMovie, Home, and Privacy). Each page shows the same menu layout. The
menu layout is implemented in the Pages/Shared/_Layout.cshtml file. Open the Pages/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 page-
specific views you create show up, wrapped in the layout page. For example, if you select the Privacy link, the
Pages/Privacy.cshtml view is rendered inside the RenderBody method.
ViewData and layout
Consider the following code from the Pages/Movies/Index.cshtml file:

@page
@model RazorPagesMovie.Pages.Movies.IndexModel

@{
ViewData["Title"] = "Index";
}

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 _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 which doesn't appear in your layout file. Unlike
HTML comments ( <!-- --> ), Razor comments are not sent to the client.
Update the layout
Change the <title> element in the Pages/Shared/_Layout.cshtml file to display Movie rather than
RazorPagesMovie.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@ViewData["Title"] - Movie</title>

Find the following anchor element in the Pages/Shared/_Layout.cshtml file.

<a class="navbar-brand" asp-area="" asp-page="/Index">RazorPagesMovie</a>

Replace the preceding element with the following markup.

<a class="navbar-brand" asp-page="/Movies/Index">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. The
asp-area attribute value is empty, so the area isn't used in the link. See Areas for more information.

Save your changes, and test the app by clicking on the RpMovie link. See the _Layout.cshtml file in GitHub if
you have any problems.
Test the other links (Home, RpMovie, 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.

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.
The Create page model
Examine the Pages/Movies/Create.cshtml.cs page model:

// Unused usings removed.

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using RazorPagesMovie.Models;
using System;
using System.Threading.Tasks;

namespace RazorPagesMovie.Pages.Movies
{
public class CreateModel : PageModel
{
private readonly RazorPagesMovie.Models.RazorPagesMovieContext _context;

public CreateModel(RazorPagesMovie.Models.RazorPagesMovieContext context)

{
_context = context;
}

public IActionResult OnGet()

{
return Page();
}

[BindProperty]
public Movie Movie { get; set; }

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

_context.Movie.Add(Movie);
await _context.SaveChangesAsync();

return RedirectToPage("./Index");
}
}
}

The OnGet method initializes any state needed for the page. The Create page doesn't have any state to initialize,
so 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:
 public async Task<IActionResult> OnPostAsync()
{
if (!ModelState.IsValid)
{
return Page();
}

_context.Movie.Add(Movie);
await _context.SaveChangesAsync();

return RedirectToPage("./Index");
}

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. Client-side validation and model validation are discussed 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";
}

<h1>Create</h1>

<h4>Movie</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<input type="submit" value="Create" class="btn btn-primary" />
</div>
</form>
</div>
</div>

<div>
<a asp-page="Index">Back to List</a>
</div>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio displays the <form method="post"> tag in a distinctive bold 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 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>

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.

Additional resources
YouTube version of this tutorial
P R E V IO U S : A D D IN G A N E X T:
M ODEL D A TA B A SE
 Work with a database and ASP.NET Core
7/24/2019 • 12 minutes to read • Edit Online

By Rick Anderson and Joe Audette

View or download sample code (how to download).
View or download sample code (how to download).
The RazorPagesMovieContext 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 Startup.cs:

Visual Studio
Visual Studio Code / Visual Studio for Mac

public void ConfigureServices(IServiceCollection services)

{
services.AddRazorPages();

services.AddDbContext<RazorPagesMovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("RazorPagesMovieContext")));
}

The ASP.NET Core Configuration system reads the ConnectionString . For local development, it gets the
connection string from the appsettings.json file.
Visual Studio
Visual Studio Code / Visual Studio for Mac
The name value for the database ( Database={Database name} ) will be different for your generated code. The name
value is arbitrary.

{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*",
"ConnectionStrings": {
"RazorPagesMovieContext": "Server=(localdb)\\mssqllocaldb;Database=RazorPagesMovieContext-
bc;Trusted_Connection=True;MultipleActiveResultSets=true"
}
}

When the app is deployed to a test or production server, an environment variable can be used to set the
connection string to a real database server. See Configuration for more information.
Visual Studio
Visual Studio Code / Visual Studio for Mac
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 with the following code:
 using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using RazorPagesMovie.Data;
using System;
using System.Linq;

namespace RazorPagesMovie.Models
{
public static class SeedData
{
public static void Initialize(IServiceProvider serviceProvider)
{
using (var context = new RazorPagesMovieContext(
serviceProvider.GetRequiredService<
DbContextOptions<RazorPagesMovieContext>>()))
{
// 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 ",
ReleaseDate = DateTime.Parse("1984-3-13"),
Genre = "Comedy",
Price = 8.99M
},

new Movie
{
Title = "Ghostbusters 2",
ReleaseDate = DateTime.Parse("1986-2-23"),
Genre = "Comedy",
Price = 9.99M
},

new Movie
{
Title = "Rio Bravo",
ReleaseDate = DateTime.Parse("1959-4-15"),
Genre = "Western",
Price = 3.99M
}
);
context.SaveChanges();
}
}
}
}

If there are any movies in the DB, the seed initializer returns and no movies are added.
 if (context.Movie.Any())
{
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.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using RazorPagesMovie.Data;
using RazorPagesMovie.Models;
using System;

namespace RazorPagesMovie
{
public class Program
{
public static void Main(string[] args)
{
var host = CreateHostBuilder(args).Build();

using (var scope = host.Services.CreateScope())

{
var services = scope.ServiceProvider;

try
{
var context = services.
GetRequiredService<RazorPagesMovieContext>();
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 IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
// webBuilder.UseStartup<Startup>();
webBuilder.UseStartup<StartupVal>();

});
}
}

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
Visual Studio
Visual Studio Code / Visual Studio for Mac
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 next tutorial will improve the presentation of the data.

Additional resources

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

View or download sample code (how to download).

View or download sample code (how to download).
The RazorPagesMovieContext 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 Startup.cs:

Visual Studio
Visual Studio Code / Visual Studio for Mac
 // This method gets called by the runtime.
// Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
services.Configure<CookiePolicyOptions>(options =>
{
// This lambda determines whether user consent for non-essential cookies is
// needed for a given request.
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

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.
Visual Studio
Visual Studio Code
Visual Studio for Mac
The name value for the database ( Database={Database name} ) will be different for your generated code. The name
value is arbitrary.

{
"Logging": {
"LogLevel": {
"Default": "Warning"
}
},
"AllowedHosts": "*",
"ConnectionStrings": {
"RazorPagesMovieContext": "Server=(localdb)\\mssqllocaldb;Database=RazorPagesMovieContext-
1234;Trusted_Connection=True;MultipleActiveResultSets=true"
}
}

When the app is deployed to a test or production server, an environment variable can be used to set the
connection string to a real database server. See Configuration for more information.
Visual Studio
Visual Studio Code
Visual Studio for Mac

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 with the following code:
 using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using System;
using System.Linq;

namespace RazorPagesMovie.Models
{
public static class SeedData
{
public static void Initialize(IServiceProvider serviceProvider)
{
using (var context = new RazorPagesMovieContext(
serviceProvider.GetRequiredService<
DbContextOptions<RazorPagesMovieContext>>()))
{
// 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 ",
ReleaseDate = DateTime.Parse("1984-3-13"),
Genre = "Comedy",
Price = 8.99M
},

new Movie
{
Title = "Ghostbusters 2",
ReleaseDate = DateTime.Parse("1986-2-23"),
Genre = "Comedy",
Price = 9.99M
},

new Movie
{
Title = "Rio Bravo",
ReleaseDate = DateTime.Parse("1959-4-15"),
Genre = "Western",
Price = 3.99M
}
);
context.SaveChanges();
}
}
}
}

If there are any movies in the DB, the seed initializer returns and no movies are added.
 if (context.Movie.Any())
{
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.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using RazorPagesMovie.Models;
using System;
using Microsoft.EntityFrameworkCore;

namespace RazorPagesMovie
{
public class Program
{
public static void Main(string[] args)
{
var host = CreateWebHostBuilder(args).Build();

using (var scope = host.Services.CreateScope())

{
var services = scope.ServiceProvider;

try
{
var context=services.
GetRequiredService<RazorPagesMovieContext>();
context.Database.Migrate();
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 IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(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
Visual Studio
Visual Studio Code
Visual Studio for Mac
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.

Additional resources
YouTube version of this tutorial

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
7/24/2019 • 9 minutes to read • Edit Online

By Rick Anderson
The scaffolded movie app has a good start, but the presentation isn't ideal. 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;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace RazorPagesMovie.Models
{
public class Movie
{
public int ID { get; set; }
public string Title { get; set; }

[Display(Name = "Release Date")]

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }
public string Genre { get; set; }

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

public decimal Price { get; set; }
}
}

The [Column(TypeName = "decimal(18, 2)")] data annotation enables Entity Framework Core to correctly map
Price to currency in the database. For more information, see Data Types.
DataAnnotations is covered 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.
 @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>

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, the ?id=1 in
https://localhost:5001/Movies/Details?id=1 ).

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?}"

To test the behavior of @page "{id:int?}" :

 Set the page directive in Pages/Movies/Details.cshtml to @page "{id:int?}" .
Set a break point in public async Task<IActionResult> OnGetAsync(int? id) (in
Pages/Movies/Details.cshtml.cs).
Navigate to https://localhost:5001/Movies/Details/ .

With the @page "{id:int}" directive, the break point is never hit. The routing engine returns HTTP 404. Using
@page "{id:int?}" , the OnGetAsync method returns NotFound ( HTTP 404 ).

Review concurrency exception handling

Review the OnPostAsync method in the Pages/Movies/Edit.cshtml.cs file:

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

_context.Attach(Movie).State = EntityState.Modified;

try
{
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!MovieExists(Movie.ID))
{
return NotFound();
}
else
{
throw;
}
}

return RedirectToPage("./Index");
}

private bool MovieExists(int id)

{
return _context.Movie.Any(e => e.ID == id);
}

The previous code detects concurrency exceptions when the one client deletes the movie and the other client
posts changes to the movie.
To test the catch block:
Set a breakpoint on catch (DbUpdateConcurrencyException)
Select Edit for a movie, make changes, but don't enter Save.
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 may want to detect concurrency conflicts. See Handle concurrency conflicts for more
information.
Posting and binding review
Examine the Pages/Movies/Edit.cshtml.cs file:
 public class EditModel : PageModel
{
private readonly RazorPagesMovie.Data.RazorPagesMovieContext _context;

public EditModel(RazorPagesMovie.Data.RazorPagesMovieContext context)

{
_context = context;
}

[BindProperty]
public Movie Movie { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Movie = await _context.Movie.FirstOrDefaultAsync(m => m.ID == id);

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

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

_context.Attach(Movie).State = EntityState.Modified;

try
{
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!MovieExists(Movie.ID))
{
return NotFound();
}
else
{
throw;
}
}

return RedirectToPage("./Index");
}

private bool MovieExists(int id)

{
return _context.Movie.Any(e => e.ID == id);
}

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]
public Movie Movie { get; set; }

If there are errors in the model state (for example, ReleaseDate cannot be converted to a date), the form
is redisplayed 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.

Additional resources

P R E V IO U S : W O R K IN G W IT H A N E X T: A D D
D A TA B A SE SE A RCH

The scaffolded movie app has a good start, but the presentation isn't ideal. 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;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace RazorPagesMovie.Models
{
public class Movie
{
public int ID { get; set; }
public string Title { get; set; }

[Display(Name = "Release Date")]

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }
public string Genre { get; set; }

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

public decimal Price { get; set; }
}
}

The [Column(TypeName = "decimal(18, 2)")] data annotation enables Entity Framework Core to correctly map
Price to currency in the database. For more information, see Data Types.
DataAnnotations is covered 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.

@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>

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, the ?id=1 in
https://localhost:5001/Movies/Details?id=1 ).

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?}"
To test the behavior of @page "{id:int?}" :
Set the page directive in Pages/Movies/Details.cshtml to @page "{id:int?}" .
Set a break point in public async Task<IActionResult> OnGetAsync(int? id) (in
Pages/Movies/Details.cshtml.cs).
Navigate to https://localhost:5001/Movies/Details/ .

With the @page "{id:int}" directive, the break point is never hit. The routing engine returns HTTP 404. Using
@page "{id:int?}" , the OnGetAsync method returns NotFound ( HTTP 404 ).

Review concurrency exception handling

Review the OnPostAsync method in the Pages/Movies/Edit.cshtml.cs file:

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

_context.Attach(Movie).State = EntityState.Modified;

try
{
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!MovieExists(Movie.ID))
{
return NotFound();
}
else
{
throw;
}
}

return RedirectToPage("./Index");
}

private bool MovieExists(int id)

{
return _context.Movie.Any(e => e.ID == id);
}

The previous code detects concurrency exceptions when the one client deletes the movie and the other client
posts changes to the movie.
To test the catch block:
Set a breakpoint on catch (DbUpdateConcurrencyException)
Select Edit for a movie, make changes, but don't enter Save.
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 may want to detect concurrency conflicts. See Handle concurrency conflicts for more
information.
Posting and binding review
Examine the Pages/Movies/Edit.cshtml.cs file:

public class EditModel : PageModel

{
private readonly RazorPagesMovieContext _context;

public EditModel(RazorPagesMovieContext context)

{
_context = context;
}

[BindProperty]
public Movie Movie { get; set; }

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();
}

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

_context.Attach(Movie).State = EntityState.Modified;

try
{
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!_context.Movie.Any(e => e.ID == Movie.ID))
{
return NotFound();
}
else
{
throw;
}
}

return RedirectToPage("./Index");
}
}

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]
public Movie Movie { get; set; }

If there are errors in the model state (for example, ReleaseDate cannot be converted to a date), the form
is displayed 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.

Additional resources
YouTube version of this tutorial

P R E V IO U S : W O R K IN G W IT H A N E X T: A D D
D A TA B A SE SE A RCH
 Add search to ASP.NET Core Razor Pages
7/24/2019 • 9 minutes to read • Edit Online

By Rick Anderson
View or download sample code (how to download).
View or download sample code (how to download).
In the following sections, searching movies by genre or name is added.
Add the following highlighted properties to Pages/Movies/Index.cshtml.cs:

public class IndexModel : PageModel

{
private readonly RazorPagesMovie.Data.RazorPagesMovieContext _context;

public IndexModel(RazorPagesMovie.Data.RazorPagesMovieContext context)

{
_context = context;
}

public IList<Movie> Movie { get; set; }

[BindProperty(SupportsGet = true)]
public string SearchString { get; set; }
// Requires using Microsoft.AspNetCore.Mvc.Rendering;
public SelectList Genres { get; set; }
[BindProperty(SupportsGet = true)]
public string MovieGenre { get; set; }

SearchString : contains the text users enter in the search text box. SearchString is decorated with the
[BindProperty] attribute. [BindProperty] binds form values and query strings with the same name as the
property. (SupportsGet = true) is required for binding on GET requests.
Genres : contains the list of genres. Genres allows the user to select a genre from the list. SelectList
requires using Microsoft.AspNetCore.Mvc.Rendering;
MovieGenre : contains the specific genre the user selects (for example, "Western").
Genres and MovieGenre are used later in this tutorial.

WARNING
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 GET binding 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)]

Update the Index page's OnGetAsync method with the following code:
 public async Task OnGetAsync()
{
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:

// using System.Linq;
var movies = from m in _context.Movie
select m;

The query is only defined at this point, it has not been run against the database.
If the SearchString property is not null or empty, the movies query is modified to filter on the search string:

if (!string.IsNullOrEmpty(SearchString))
{
movies = movies.Where(s => s.Title.Contains(SearchString));
}

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,
https://localhost:5001/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, https://localhost:5001/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.

The ASP.NET Core runtime uses model binding to set the value of the SearchString property from the query
string ( ?searchString=Ghost ) or route data ( https://localhost:5001/Movies/Ghost ). Model binding is not case
sensitive.
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
@model RazorPagesMovie.Pages.Movies.IndexModel

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-page="Create">Create New</a>
</p>

<form>
<p>
Title: <input type="text" asp-for="SearchString" />
<input type="submit" value="Filter" />
</p>
</form>

<table class="table">
@*Markup removed for brevity.*@

The HTML <form> tag uses the following Tag Helpers:

Form Tag Helper. When the form is submitted, the filter string is sent to the Pages/Movies/Index page via
query string.
Input Tag Helper
Save the changes and test the filter.
Search by genre
Update the OnGetAsync method with the following code:

public async Task OnGetAsync()

{
// Use LINQ to get list of genres.
IQueryable<string> genreQuery = from m in _context.Movie
orderby m.Genre
select m.Genre;

var movies = from m in _context.Movie

select m;

if (!string.IsNullOrEmpty(SearchString))
{
movies = movies.Where(s => s.Title.Contains(SearchString));
}

if (!string.IsNullOrEmpty(MovieGenre))
{
movies = movies.Where(x => x.Genre == MovieGenre);
}
Genres = new SelectList(await genreQuery.Distinct().ToListAsync());
Movie = await movies.ToListAsync();
}

The following code is a LINQ query that retrieves all the genres from the database.

// Use LINQ to get list of genres.

IQueryable<string> genreQuery = from m in _context.Movie
orderby m.Genre
select m.Genre;

The SelectList of genres is created by projecting the distinct genres.

 Genres = new SelectList(await genreQuery.Distinct().ToListAsync());

Add search by genre to the Razor Page

Update Index.cshtml as follows:

@page
@model RazorPagesMovie.Pages.Movies.IndexModel

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-page="Create">Create New</a>
</p>

<form>
<p>
<select asp-for="MovieGenre" asp-items="Model.Genres">
<option value="">All</option>
</select>
Title: <input type="text" asp-for="SearchString" />
<input type="submit" value="Filter" />
</p>
</form>

<table class="table">
@*Markup removed for brevity.*@

Test the app by searching by genre, by movie title, and by both.

Additional resources
YouTube version of this tutorial

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

View or download sample code (how to download).

View or download sample code (how to download).
In the following sections, searching movies by genre or name is added.
Add the following highlighted properties to Pages/Movies/Index.cshtml.cs:
 public class IndexModel : PageModel
{
private readonly RazorPagesMovie.Models.RazorPagesMovieContext _context;

public IndexModel(RazorPagesMovie.Models.RazorPagesMovieContext context)

{
_context = context;
}

public IList<Movie> Movie { get; set; }

[BindProperty(SupportsGet = true)]
public string SearchString { get; set; }
// Requires using Microsoft.AspNetCore.Mvc.Rendering;
public SelectList Genres { get; set; }
[BindProperty(SupportsGet = true)]
public string MovieGenre { get; set; }

SearchString : contains the text users enter in the search text box. SearchString is decorated with the
[BindProperty] attribute. [BindProperty] binds form values and query strings with the same name as the
property. (SupportsGet = true) is required for binding on GET requests.
Genres : contains the list of genres. Genres allows the user to select a genre from the list. SelectList
requires using Microsoft.AspNetCore.Mvc.Rendering;
MovieGenre : contains the specific genre the user selects (for example, "Western").
Genres and MovieGenre are used later in this tutorial.

WARNING
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 GET binding 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)]

Update the Index page's OnGetAsync method with the following code:

public async Task OnGetAsync()

{
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:

// using System.Linq;
var movies = from m in _context.Movie
select m;

The query is only defined at this point, it has not been run against the database.
If the SearchString property is not null or empty, the movies query is modified to filter on the search string:
 if (!string.IsNullOrEmpty(SearchString))
{
movies = movies.Where(s => s.Title.Contains(SearchString));
}

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,
https://localhost:5001/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, https://localhost:5001/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.
The ASP.NET Core runtime uses model binding to set the value of the SearchString property from the query
string ( ?searchString=Ghost ) or route data ( https://localhost:5001/Movies/Ghost ). Model binding is not case
sensitive.
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
@model RazorPagesMovie.Pages.Movies.IndexModel

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-page="Create">Create New</a>
</p>

<form>
<p>
Title: <input type="text" asp-for="SearchString" />
<input type="submit" value="Filter" />
</p>
</form>

<table class="table">
@*Markup removed for brevity.*@

The HTML <form> tag uses the following Tag Helpers:

Form Tag Helper. When the form is submitted, the filter string is sent to the Pages/Movies/Index page via
query string.
Input Tag Helper
Save the changes and test the filter.

Search by genre
Update the OnGetAsync method with the following code:

public async Task OnGetAsync()

{
// Use LINQ to get list of genres.
IQueryable<string> genreQuery = from m in _context.Movie
orderby m.Genre
select m.Genre;

var movies = from m in _context.Movie

select m;

if (!string.IsNullOrEmpty(SearchString))
{
movies = movies.Where(s => s.Title.Contains(SearchString));
}

if (!string.IsNullOrEmpty(MovieGenre))
{
movies = movies.Where(x => x.Genre == MovieGenre);
}
Genres = new SelectList(await genreQuery.Distinct().ToListAsync());
Movie = await movies.ToListAsync();
}

The following code is a LINQ query that retrieves all the genres from the database.

// Use LINQ to get list of genres.

IQueryable<string> genreQuery = from m in _context.Movie
orderby m.Genre
select m.Genre;
The SelectList of genres is created by projecting the distinct genres.

Genres = new SelectList(await genreQuery.Distinct().ToListAsync());

Add search by genre to the Razor Page

Update Index.cshtml as follows:

@page
@model RazorPagesMovie.Pages.Movies.IndexModel

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-page="Create">Create New</a>
</p>

<form>
<p>
<select asp-for="MovieGenre" asp-items="Model.Genres">
<option value="">All</option>
</select>
Title: <input type="text" asp-for="SearchString" />
<input type="submit" value="Filter" />
</p>
</form>

<table class="table">
@*Markup removed for brevity.*@

Test the app by searching by genre, by movie title, and by both.

Additional resources
YouTube version of this tutorial

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
7/31/2019 • 10 minutes to read • Edit Online

By Rick Anderson
View or download sample code (how to download).
View or download sample code (how to download).
In this section Entity Framework Code First Migrations is used to:
Add a new field to the model.
Migrate the new field schema 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 int ID { get; set; }
public string Title { get; set; }

[Display(Name = "Release Date")]

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }
public string Genre { get; set; }

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

public decimal Price { get; set; }
public string Rating { get; set; }
}

Build the app.

Edit Pages/Movies/Index.cshtml, and add a Rating field:

@page
@model RazorPagesMovie.Pages.Movies.IndexModel

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-page="Create">Create New</a>
</p>
 <form>
<p>
<select asp-for="MovieGenre" asp-items="Model.Genres">
<option value="">All</option>
</select>
Title: <input type="text" asp-for="SearchString" />
<input type="submit" value="Filter" />
</p>
</form>

<table class="table">

<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>
@Html.DisplayNameFor(model => model.Movie[0].Rating)
</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>
@Html.DisplayFor(modelItem => item.Rating)
</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>

Update the following pages:

Add the Rating field to the Delete and Details pages.
Update Create.cshtml with a Rating field.
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. Don't
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.

context.Movie.AddRange(
new Movie
{
Title = "When Harry Met Sally",
ReleaseDate = DateTime.Parse("1989-2-12"),
Genre = "Romantic Comedy",
Price = 7.99M,
Rating = "R"
},

See the completed SeedData.cs file.

Build the solution.
Visual Studio
Visual Studio Code / Visual Studio for Mac
Add a migration for the rating field
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.
The Update-Database command tells the framework to apply the schema changes to the database.
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).
Another option is to delete the database and use migrations to re-create the database. To delete the database in
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, set a
break point in the SeedData.Initialize method.

Additional resources
YouTube version of this tutorial

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

View or download sample code (how to download).

View or download sample code (how to download).
In this section Entity Framework Code First Migrations is used to:
Add a new field to the model.
Migrate the new field schema 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 int ID { get; set; }
public string Title { get; set; }

[Display(Name = "Release Date")]

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }
public string Genre { get; set; }

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

public decimal Price { get; set; }
public string Rating { get; set; }
}

Build the app.

Edit Pages/Movies/Index.cshtml, and add a Rating field:

@page
@model RazorPagesMovie.Pages.Movies.IndexModel

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-page="Create">Create New</a>
</p>

<form>
<p>
<select asp-for="MovieGenre" asp-items="Model.Genres">
<option value="">All</option>
</select>
Title: <input type="text" asp-for="SearchString" />
<input type="submit" value="Filter" />
</p>
</form>

<table class="table">

<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>
@Html.DisplayNameFor(model => model.Movie[0].Rating)
</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>
@Html.DisplayFor(modelItem => item.Rating)
</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>

Update the following pages:

Add the Rating field to the Delete and Details pages.
Update Create.cshtml with a Rating field.
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. Don't
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.
 context.Movie.AddRange(
new Movie
{
Title = "When Harry Met Sally",
ReleaseDate = DateTime.Parse("1989-2-12"),
Genre = "Romantic Comedy",
Price = 7.99M,
Rating = "R"
},

See the completed SeedData.cs file.

Build the solution.
Visual Studio
Visual Studio Code / Visual Studio for Mac
Add a migration for the rating field
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.
The Update-Database command tells the framework to apply the schema changes to the database.
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).
Another option is to delete the database and use migrations to re-create the database. To delete the database in
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, set a
break point in the SeedData.Initialize method.

Additional resources
YouTube version of this tutorial

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
7/24/2019 • 9 minutes to read • Edit Online

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.
Make 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.

Add validation rules to the movie model

The DataAnnotations namespace provides a set of built-in 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 any validation.
Update the Movie class to take advantage of the built-in Required , StringLength , RegularExpression , and
Range validation attributes.
 public class Movie
{
public int Id { get; set; }

[StringLength(60, MinimumLength = 3)]

[Required]
public string Title { get; set; }

[Display(Name = "Release Date")]

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }

[Range(1, 100)]
[DataType(DataType.Currency)]
[Column(TypeName = "decimal(18, 2)")]
public decimal Price { get; set; }

[RegularExpression(@"^[A-Z]+[a-zA-Z""'\s-]*$")]
[Required]
[StringLength(30)]
public string Genre { get; set; }

[RegularExpression(@"^[A-Z]+[a-zA-Z0-9""'\s-]*$")]
[StringLength(5)]
[Required]
public string Rating { get; set; }
}

The validation attributes specify behavior that you want to enforce on the model properties they're applied to:
The Required and MinimumLength attributes indicate 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 preceding code,
"Genre":
Must only use letters.
The first letter is required to be uppercase. White space, numbers, and special characters are not
allowed.
The RegularExpression "Rating":
Requires that the first character be an uppercase letter.
Allows special characters and numbers in subsequent spaces. "PG -13" is valid for a rating, but fails for
a "Genre".
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 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 commas in decimal fields. 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.

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. You can disable JavaScript using browser's developer tools. 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 invalid data.
Verify the model state is invalid:

if (!ModelState.IsValid)
{
return Page();
}

The following code shows a portion of the Create.cshtml page 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.

<form method="post">
<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>

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.

[Display(Name = "Release Date")]

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }

[Range(1, 100)]
[DataType(DataType.Currency)]
public decimal Price { get; set; }
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 [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 DisplayFormat attribute is used to explicitly specify the date format:

[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]

public DateTime ReleaseDate { get; set; }

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
{
public int ID { get; set; }

[StringLength(60, MinimumLength = 3)]

public string Title { get; set; }

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

public DateTime ReleaseDate { get; set; }

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

public string Genre { get; set; }

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

[Column(TypeName = "decimal(18, 2)")]
public decimal Price { get; set; }

[RegularExpression(@"^[A-Z]+[a-zA-Z0-9""'\s-]*$"), StringLength(5)]
public string Rating { get; set; }
}

Get started with Razor Pages and EF Core shows advanced EF Core operations with Razor Pages.
Apply migrations
The DataAnnotations applied to the class change the schema. For example, the DataAnnotations applied to the
Title field:

[StringLength(60, MinimumLength = 3)]

[Required]
public string Title { get; set; }

Limits the characters to 60.

Doesn't allow a null value.

Visual Studio
Visual Studio Code / Visual Studio for Mac
The Movie table currently has the following schema:

CREATE TABLE [dbo].[Movie] (

[ID] INT IDENTITY (1, 1) NOT NULL,
[Title] NVARCHAR (MAX) NULL,
[ReleaseDate] DATETIME2 (7) NOT NULL,
[Genre] NVARCHAR (MAX) NULL,
[Price] DECIMAL (18, 2) NOT NULL,
[Rating] NVARCHAR (MAX) NULL,
CONSTRAINT [PK_Movie] PRIMARY KEY CLUSTERED ([ID] ASC)
);

The preceding schema changes don't cause EF to throw an exception. However, create a migration so the schema
is consistent with the model.
From the Tools menu, select NuGet Package Manager > Package Manager Console. In the PMC, enter the
following commands:

Add-Migration New_DataAnnotations
Update-Database
Update-Database runs the Up methods of the New_DataAnnotations class. Examine the Up method:

public partial class New_DataAnnotations : Migration

{
protected override void Up(MigrationBuilder migrationBuilder)
{
migrationBuilder.AlterColumn<string>(
name: "Title",
table: "Movie",
maxLength: 60,
nullable: false,
oldClrType: typeof(string),
oldNullable: true);

migrationBuilder.AlterColumn<string>(
name: "Rating",
table: "Movie",
maxLength: 5,
nullable: false,
oldClrType: typeof(string),
oldNullable: true);

migrationBuilder.AlterColumn<string>(
name: "Genre",
table: "Movie",
maxLength: 30,
nullable: false,
oldClrType: typeof(string),
oldNullable: true);
}

The updated Movie table has the following schema:

CREATE TABLE [dbo].[Movie] (

[ID] INT IDENTITY (1, 1) NOT NULL,
[Title] NVARCHAR (60) NOT NULL,
[ReleaseDate] DATETIME2 (7) NOT NULL,
[Genre] NVARCHAR (30) NOT NULL,
[Price] DECIMAL (18, 2) NOT NULL,
[Rating] NVARCHAR (5) NOT NULL,
CONSTRAINT [PK_Movie] PRIMARY KEY CLUSTERED ([ID] ASC)
);

Publish to Azure
For information on deploying to Azure, see Tutorial: Build an ASP.NET Core app in Azure with SQL Database.
Thanks for completing this introduction to Razor Pages. Get started with Razor Pages and EF Core is an excellent
follow up to this tutorial.

Additional resources
Tag Helpers in forms in ASP.NET Core
Globalization and localization in ASP.NET Core
Tag Helpers in ASP.NET Core
Author Tag Helpers in ASP.NET Core
YouTube version of this tutorial
P R E V IO U S : A D D IN G A N E W
F IE L D
 Filter methods for Razor Pages in ASP.NET Core
4/26/2019 • 4 minutes to read • Edit Online

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.
View or download sample code (how to download)
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;
using Microsoft.Extensions.Logging;
using System.Threading.Tasks;

namespace PageFilter.Filters
{
public class SampleAsyncPageFilter : IAsyncPageFilter
{
private readonly ILogger _logger;

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.");
await next.Invoke();
}
}
}

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:

public void ConfigureServices(IServiceCollection services)

{
services.AddMvc(options =>
{
options.Filters.Add(new SampleAsyncPageFilter(_logger));
});
}

The following code shows the complete Startup class:

 using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using PageFilter.Filters;

namespace PageFilter
{
public class Startup
{
ILogger _logger;
public Startup(ILoggerFactory loggerFactory, IConfiguration configuration)
{
_logger = loggerFactory.CreateLogger<GlobalFiltersLogger>();
Configuration = configuration;
}

public IConfiguration Configuration { get; }

public void ConfigureServices(IServiceCollection services)

{
services.AddMvc(options =>
{
options.Filters.Add(new SampleAsyncPageFilter(_logger));
});
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}

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

app.UseMvc();
}
}
}

The following code calls AddFolderApplicationModelConvention to apply the SampleAsyncPageFilter to only pages in
/subFolder:

public void ConfigureServices(IServiceCollection services)

{
services.AddMvc()
.AddRazorPagesOptions(options =>
{
options.Conventions.AddFolderApplicationModelConvention(
"/subFolder",
model => model.Filters.Add(new SampleAsyncPageFilter(_logger)));
});
}

The following code implements the synchronous IPageFilter :

 using Microsoft.AspNetCore.Mvc.Filters;
using Microsoft.Extensions.Logging;

namespace PageFilter.Filters
{
public class SamplePageFilter : IPageFilter
{
private readonly ILogger _logger;

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 :

public void ConfigureServices(IServiceCollection services)

{
services.AddMvc(options =>
{
options.Filters.Add(new SamplePageFilter(_logger));
});
}

Implement Razor Page filters by overriding filter methods

The following code overrides the synchronous Razor Page filters:
 using Microsoft.AspNetCore.Mvc.Filters;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.Extensions.Logging;

namespace PageFilter.Pages
{
public class IndexModel : PageModel
{
private readonly ILogger _logger;

public IndexModel(ILogger<IndexModel> logger)

{
_logger = logger;
}
public string Message { get; set; }

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:
 using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc.Filters;

namespace PageFilter.Filters
{
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
{
private readonly ILogger _logger;

public ContactModel(ILogger<ContactModel> logger)

{
_logger = logger;
}
public string Message { get; set; }

public async Task OnGetAsync()

{
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;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;

namespace PageFilter.Pages
{
[Authorize]
public class ModelWithAuthFilterModel : PageModel
{
public IActionResult OnGet() => Page();
}
}
 Razor Pages route and app conventions in ASP.NET
Core
8/9/2019 • 13 minutes to read • Edit Online

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.
View or download sample code (how to download)

SCENARIO THE SAMPLE DEMONSTRATES ...

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)

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:
 public void ConfigureServices(IServiceCollection services)
{
services.AddMvc()
.AddRazorPagesOptions(options =>
{
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?}"),
}
});
}
}
}

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());

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" }));
}
}
 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());

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)
{
// Access the PageHandlerModel
}
}

public class GlobalPageHandlerModelConvention

: IPageHandlerModelConvention
{
public void Apply(PageHandlerModel model)
{
// Access the PageHandlerModel
}
}

Startup.cs:

options.Conventions.Add(new GlobalPageHandlerModelConvention());
 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 =>

{
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 = 2,
Template = AttributeRouteModel.CombineTemplates(
selector.AttributeRouteModel.Template,
"{otherPagesTemplate?}"),
}
});
}
});

options.Conventions.AddFolderRouteModelConvention("/OtherPages", 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 = 2,
Template = AttributeRouteModel.CombineTemplates(
selector.AttributeRouteModel.Template,
"{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.
Wherever possible, don't set the Order , which results in Order = 0 . Rely on routing to select the correct route.
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 =>

{
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 = 2,
Template = AttributeRouteModel.CombineTemplates(
selector.AttributeRouteModel.Template,
"{aboutTemplate?}"),
}
});
}
});
 options.Conventions.AddPageRouteModelConvention("/About", 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 = 2,
Template = AttributeRouteModel.CombineTemplates(
selector.AttributeRouteModel.Template,
"{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.

Wherever possible, don't set the Order , which results in Order = 0 . Rely on routing to select the correct route.
Request the sample's About page at localhost:5000/About/GlobalRouteValue/AboutRouteValue and inspect the result:

Use a parameter transformer to customize page routes

Page routes generated by ASP.NET Core can be customized using a parameter transformer. A parameter
transformer implements IOutboundParameterTransformer and transforms the value of parameters. For example, a
custom SlugifyParameterTransformer parameter transformer changes the SubscriptionManagement route value to
subscription-management .

The PageRouteTransformerConvention page route model convention applies a parameter transformer to the folder
and file name segments of automatically generated page routes in an app. For example, the Razor Pages file at
/Pages/SubscriptionManagement/ViewAll.cshtml would have its route rewritten from
/SubscriptionManagement/ViewAll to /subscription-management/view-all .
PageRouteTransformerConvention only transforms the automatically generated segments of a page route that come
from the Razor Pages folder and file name. It doesn't transform route segments added with the @page directive.
The convention also doesn't transform routes added by AddPageRoute.
The PageRouteTransformerConvention is registered as an option in Startup.ConfigureServices :

public void ConfigureServices(IServiceCollection services)

{
services.AddMvc()
.AddRazorPagesOptions(options =>
{
options.Conventions.Add(
new PageRouteTransformerConvention(
new SlugifyParameterTransformer()));
});
}

public class SlugifyParameterTransformer : IOutboundParameterTransformer

{
public string TransformOutbound(object value)
{
if (value == null) { return null; }

// Slugify value
return Regex.Replace(value.ToString(), "([a-z])([A-Z])", "$1-$2").ToLower();
}
}

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?}");

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";
}

<h1>@ViewData["Title"]</h1>
<h2>@Model.Message</h2>

<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>

@page "{text?}"
@model ContactModel
@{
ViewData["Title"] = "Contact";
}

<h1>@ViewData["Title"]</h1>
<h2>@Model.Message</h2>

<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:

public class AddHeaderAttribute : ResultFilterAttribute

{
private readonly string _name;
private readonly string[] _values;

public AddHeaderAttribute(string name, string[] values)

{
_name = name;
_values = values;
}

public override void OnResultExecuting(ResultExecutingContext context)

{
context.HttpContext.Response.Headers.Add(_name, _values);
base.OnResultExecuting(context);
}
}
 public class AddHeaderAttribute : ResultFilterAttribute
{
private readonly string _name;
private readonly string[] _values;

public AddHeaderAttribute(string name, string[] values)

{
_name = name;
_values = values;
}

public override void OnResultExecuting(ResultExecutingContext context)

{
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 =>

{
model.Filters.Add(new AddHeaderAttribute(
"OtherPagesHeader", new string[] { "OtherPages Header Value" }));
});

options.Conventions.AddFolderApplicationModelConvention("/OtherPages", model =>

{
model.Filters.Add(new AddHeaderAttribute(
"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 =>

{
model.Filters.Add(new AddHeaderAttribute(
"AboutHeader", new string[] { "About Header Value" }));
});

options.Conventions.AddPageApplicationModelConvention("/About", model =>

{
model.Filters.Add(new AddHeaderAttribute(
"AboutHeader", new string[] { "About Header Value" }));
});

Request the sample's About page at localhost:5000/About and inspect the headers to view the result:

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();
});

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 has no effect 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());

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;
}
}
}
 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;
}
}
}

Request the sample's About page at localhost:5000/About and inspect the headers to view the result:

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.

Additional resources
Razor Pages authorization conventions in ASP.NET Core
Areas in ASP.NET Core
 Upload files to a Razor Page in ASP.NET Core
7/11/2019 • 19 minutes to read • Edit Online

By Luke Latham
This topic builds upon the sample app in Tutorial: 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.
View or download sample code (how to download)

Security considerations
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:
 using Microsoft.AspNetCore.Http;
using System.ComponentModel.DataAnnotations;

namespace RazorPagesMovie.Models
{
public class FileUpload
{
[Required]
[Display(Name="Title")]
[StringLength(60, MinimumLength = 3)]
public string Title { get; set; }

[Required]
[Display(Name="Public Schedule")]
public IFormFile UploadPublicSchedule { get; set; }

[Required]
[Display(Name="Private Schedule")]
public IFormFile UploadPrivateSchedule { get; set; }
}
}

using Microsoft.AspNetCore.Http;
using System.ComponentModel.DataAnnotations;

namespace RazorPagesMovie.Models
{
public class FileUpload
{
[Required]
[Display(Name="Title")]
[StringLength(60, MinimumLength = 3)]
public string Title { get; set; }

[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.ComponentModel.DataAnnotations;
using System.IO;
using System.Net;
using System.Reflection;
using System.Text;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc.ModelBinding;
using RazorPagesMovie.Models;

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)
{
modelState.AddModelError(formFile.Name,
$"The {fieldDisplayName}file ({fileName}) is empty.");
}
else if (formFile.Length > 1048576)
{
modelState.AddModelError(formFile.Name,
$"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
 // 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
{
modelState.AddModelError(formFile.Name,
$"The {fieldDisplayName}file ({fileName}) is empty.");
}
}
}
catch (Exception ex)
{
modelState.AddModelError(formFile.Name,
$"The {fieldDisplayName}file ({fileName}) upload failed. " +
$"Please contact the Help Desk for support. Error: {ex.Message}");
// Log the exception
}
}

return string.Empty;
}
}
}

using System;
using System.ComponentModel.DataAnnotations;
using System.IO;
using System.Net;
using System.Reflection;
using System.Text;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc.ModelBinding;
using RazorPagesMovie.Models;

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")
{
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)
{
modelState.AddModelError(formFile.Name,
$"The {fieldDisplayName}file ({fileName}) is empty.");
}
else if (formFile.Length > 1048576)
{
modelState.AddModelError(formFile.Name,
$"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
{
modelState.AddModelError(formFile.Name,
$"The {fieldDisplayName}file ({fileName}) is empty.");
}
}
}
catch (Exception ex)
{
modelState.AddModelError(formFile.Name,
$"The {fieldDisplayName}file ({fileName}) upload failed. " +
$"Please contact the Help Desk for support. Error: {ex.Message}");
// Log the exception
}
}

return string.Empty;
}
}
}

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:

public async Task<IActionResult> OnPostAsync()

{
// Perform an initial check to catch FileUpload class attribute violations.
if (!ModelState.IsValid)
{
return Page();
}

var filePath = "<PATH-AND-FILE-NAME>";

using (var fileStream = new FileStream(filePath, FileMode.Create))

{
await FileUpload.UploadPublicSchedule.CopyToAsync(fileStream);
}

return RedirectToPage("./Index");
}

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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace RazorPagesMovie.Models
{
public class Schedule
{
public int ID { get; set; }
public string Title { get; set; }

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)")]

[DisplayFormat(DataFormatString = "{0:N1}")]
public long PrivateScheduleSize { get; set; }

[Display(Name = "Uploaded (UTC)")]

[DisplayFormat(DataFormatString = "{0:F}")]
public DateTime UploadDT { get; set; }
}
}
 using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace RazorPagesMovie.Models
{
public class Schedule
{
public int ID { get; set; }
public string Title { get; set; }

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)")]

[DisplayFormat(DataFormatString = "{0:N1}")]
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.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.EntityFrameworkCore;

namespace RazorPagesMovie.Models
{
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:
 using Microsoft.EntityFrameworkCore;

namespace RazorPagesMovie.Models
{
public class MovieContext : DbContext
{
public MovieContext(DbContextOptions<MovieContext> options)
: base(options)
{
}

public DbSet<Movie> Movie { get; set; }

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">
<div class="col-md-4">
<form method="post" enctype="multipart/form-data">
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<label asp-for="FileUpload.UploadPrivateSchedule" class="control-label"></label>
<input asp-for="FileUpload.UploadPrivateSchedule" type="file" class="form-control"
style="height:auto" />
<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>
<table class="table">
<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>
<th class="text-center">
@Html.DisplayNameFor(model => model.Schedule[0].PrivateScheduleSize)
</th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Schedule) {
<tr>
<td>
<a asp-page="./Delete" asp-route-id="@item.ID">Delete</a>
</td>
<td>
@Html.DisplayFor(modelItem => item.Title)
</td>
<td>
@Html.DisplayFor(modelItem => item.UploadDT)
</td>
<td class="text-center">
@Html.DisplayFor(modelItem => item.PublicScheduleSize)
</td>
<td class="text-center">
@Html.DisplayFor(modelItem => item.PrivateScheduleSize)
</td>
</tr>
}
</tbody>
</table>

@section Scripts {
@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

@page
@model RazorPagesMovie.Pages.Schedules.IndexModel

@{
ViewData["Title"] = "Schedules";
}

<h2>Schedules</h2>
<hr />

<h3>Upload Schedules</h3>
<div class="row">
<div class="col-md-4">
<form method="post" enctype="multipart/form-data">
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<label asp-for="FileUpload.UploadPrivateSchedule" class="control-label"></label>
<input asp-for="FileUpload.UploadPrivateSchedule" type="file" class="form-control"
style="height:auto" />
<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>
<table class="table">
<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>
<th class="text-center">
@Html.DisplayNameFor(model => model.Schedule[0].PrivateScheduleSize)
</th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Schedule) {
<tr>
<td>
<a asp-page="./Delete" asp-route-id="@item.ID">Delete</a>
</td>
<td>
@Html.DisplayFor(modelItem => item.Title)
</td>
 <td>
@Html.DisplayFor(modelItem => item.UploadDT)
</td>
<td class="text-center">
@Html.DisplayFor(modelItem => item.PublicScheduleSize)
</td>
<td class="text-center">
@Html.DisplayFor(modelItem => item.PrivateScheduleSize)
</td>
</tr>
}
</tbody>
</table>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

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 System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using RazorPagesMovie.Models;
using RazorPagesMovie.Utilities;

namespace RazorPagesMovie.Pages.Schedules
{
public class IndexModel : PageModel
{
private readonly RazorPagesMovie.Models.RazorPagesMovieContext _context;

public IndexModel(RazorPagesMovie.Models.RazorPagesMovieContext context)

{
_context = context;
}

[BindProperty]
public FileUpload FileUpload { get; set; }

public IList<Schedule> Schedule { get; private set; }

public async Task OnGetAsync()

{
Schedule = await _context.Schedule.AsNoTracking().ToListAsync();
 Schedule = await _context.Schedule.AsNoTracking().ToListAsync();
}

public async Task<IActionResult> OnPostAsync()

{
// Perform an initial check to catch FileUpload class
// attribute violations.
if (!ModelState.IsValid)
{
Schedule = await _context.Schedule.AsNoTracking().ToListAsync();
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.
if (!ModelState.IsValid)
{
Schedule = await _context.Schedule.AsNoTracking().ToListAsync();
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);
await _context.SaveChangesAsync();

return RedirectToPage("./Index");
}
}
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using RazorPagesMovie.Models;
using RazorPagesMovie.Utilities;

namespace RazorPagesMovie.Pages.Schedules
{
public class IndexModel : PageModel
{
private readonly RazorPagesMovie.Models.MovieContext _context;

public IndexModel(RazorPagesMovie.Models.MovieContext context)

{
_context = context;
}

[BindProperty]
public FileUpload FileUpload { get; set; }
 public IList<Schedule> Schedule { get; private set; }

public async Task OnGetAsync()

{
Schedule = await _context.Schedule.AsNoTracking().ToListAsync();
}

public async Task<IActionResult> OnPostAsync()

{
// Perform an initial check to catch FileUpload class
// attribute violations.
if (!ModelState.IsValid)
{
Schedule = await _context.Schedule.AsNoTracking().ToListAsync();
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.
if (!ModelState.IsValid)
{
Schedule = await _context.Schedule.AsNoTracking().ToListAsync();
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);
await _context.SaveChangesAsync();

return RedirectToPage("./Index");
}
}
}

The page model ( IndexModel in Index.cshtml.cs) binds the FileUpload class:

[BindProperty]
public FileUpload FileUpload { get; set; }

[BindProperty]
public FileUpload FileUpload { get; set; }

The model also uses a list of the schedules ( IList<Schedule> ) to display the schedules stored in the database on
the page:

public IList<Schedule> Schedule { get; private set; }

 public IList<Schedule> Schedule { get; private set; }

When the page loads with OnGetAsync , Schedules is populated from the database and used to generate an HTML
table of loaded schedules:

public async Task OnGetAsync()

{
Schedule = await _context.Schedule.AsNoTracking().ToListAsync();
}

public async Task OnGetAsync()

{
Schedule = await _context.Schedule.AsNoTracking().ToListAsync();
}

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:

public async Task<IActionResult> OnPostAsync()

{
// Perform an initial check to catch FileUpload class
// attribute violations.
if (!ModelState.IsValid)
{
Schedule = await _context.Schedule.AsNoTracking().ToListAsync();
return Page();
}

var publicScheduleData =
await FileHelpers.ProcessSchedule(FileUpload.UploadPublicSchedule, ModelState);

var privateScheduleData =
await FileHelpers.ProcessSchedule(FileUpload.UploadPrivateSchedule, ModelState);

// Perform a second check to catch ProcessSchedule method

// violations.
if (!ModelState.IsValid)
{
Schedule = await _context.Schedule.AsNoTracking().ToListAsync();
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);
await _context.SaveChangesAsync();

return RedirectToPage("./Index");
}
 public async Task<IActionResult> OnPostAsync()
{
// Perform an initial check to catch FileUpload class
// attribute violations.
if (!ModelState.IsValid)
{
Schedule = await _context.Schedule.AsNoTracking().ToListAsync();
return Page();
}

var publicScheduleData =
await FileHelpers.ProcessSchedule(FileUpload.UploadPublicSchedule, ModelState);

var privateScheduleData =
await FileHelpers.ProcessSchedule(FileUpload.UploadPrivateSchedule, ModelState);

// Perform a second check to catch ProcessSchedule method

// violations.
if (!ModelState.IsValid)
{
Schedule = await _context.Schedule.AsNoTracking().ToListAsync();
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);
await _context.SaveChangesAsync();

return RedirectToPage("./Index");
}

Link the file upload Razor Page

Open Pages/Shared/_Layout.cshtml and add a link to the navigation bar to reach the Schedules page:

<div class="navbar-collapse collapse">

<ul class="nav navbar-nav">
<li><a asp-page="/Index">Home</a></li>
<li><a asp-page="/Schedules/Index">Schedules</a></li>
<li><a asp-page="/About">About</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>

<h3>Are you sure you want to delete this?</h3>

<div>
<h4>Schedule</h4>
<hr />
<dl class="dl-horizontal">
<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>

<form method="post">
<input type="hidden" asp-for="Schedule.ID" />
<input type="submit" value="Delete" class="btn btn-default" /> |
<a asp-page="./Index">Back to List</a>
</form>
</div>
 @page "{id:int}"
@model RazorPagesMovie.Pages.Schedules.DeleteModel

@{
ViewData["Title"] = "Delete Schedule";
}

<h2>Delete Schedule</h2>

<h3>Are you sure you want to delete this?</h3>

<div>
<h4>Schedule</h4>
<hr />
<dl class="dl-horizontal">
<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>

<form method="post">
<input type="hidden" asp-for="Schedule.ID" />
<input type="submit" value="Delete" class="btn btn-default" /> |
<a asp-page="./Index">Back to List</a>
</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:
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using RazorPagesMovie.Models;

namespace RazorPagesMovie.Pages.Schedules
{
public class DeleteModel : PageModel
{
private readonly RazorPagesMovie.Models.RazorPagesMovieContext _context;

public DeleteModel(RazorPagesMovie.Models.RazorPagesMovieContext context)

{
_context = context;
}

[BindProperty]
public Schedule Schedule { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Schedule = await _context.Schedule.SingleOrDefaultAsync(m => m.ID == id);

if (Schedule == null)
{
return NotFound();
}
return Page();
}

public async Task<IActionResult> OnPostAsync(int? id)

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

Schedule = await _context.Schedule.FindAsync(id);

if (Schedule != null)
{
_context.Schedule.Remove(Schedule);
await _context.SaveChangesAsync();
}

return RedirectToPage("./Index");
}
}
}
 using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using RazorPagesMovie.Models;

namespace RazorPagesMovie.Pages.Schedules
{
public class DeleteModel : PageModel
{
private readonly RazorPagesMovie.Models.MovieContext _context;

public DeleteModel(RazorPagesMovie.Models.MovieContext context)

{
_context = context;
}

[BindProperty]
public Schedule Schedule { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Schedule = await _context.Schedule.SingleOrDefaultAsync(m => m.ID == id);

if (Schedule == null)
{
return NotFound();
}
return Page();
}

public async Task<IActionResult> OnPostAsync(int? id)

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

Schedule = await _context.Schedule.FindAsync(id);

if (Schedule != null)
{
_context.Schedule.Remove(Schedule);
await _context.SaveChangesAsync();
}

return RedirectToPage("./Index");
}
}
}

The OnPostAsync method handles deleting the schedule by its id :

 public async Task<IActionResult> OnPostAsync(int? id)
{
if (id == null)
{
return NotFound();
}

Schedule = await _context.Schedule.FindAsync(id);

if (Schedule != null)
{
_context.Schedule.Remove(Schedule);
await _context.SaveChangesAsync();
}

return RedirectToPage("./Index");
}

public async Task<IActionResult> OnPostAsync(int? id)

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

Schedule = await _context.Schedule.FindAsync(id);

if (Schedule != null)
{
_context.Schedule.Remove(Schedule);
await _context.SaveChangesAsync();
}

return RedirectToPage("./Index");
}

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 File uploads in ASP.NET Core: Troubleshooting.
 ASP.NET Core Razor SDK
6/18/2019 • 4 minutes to read • Edit Online

By Rick Anderson

Overview
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.
The Razor SDK includes a <Content> element with an Include attribute set to the **\*.cshtml globbing pattern.
Matching files are published.
The Razor SDK includes <Content> elements with Include attributes set to the **\*.cshtml and **\*.razor
globbing patterns. Matching files are published.

Prerequisites
.NET Core 2.1 SDK or later

Use the Razor SDK

Most web apps aren't required to explicitly 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">
<!-- omitted for brevity -->
</Project>

Typically, a package reference to Microsoft.AspNetCore.Mvc is required to receive additional dependencies

that are required to build and compile Razor Pages and Razor views. At a minimum, your project should
add package references to:
Microsoft.AspNetCore.Razor.Design
Microsoft.AspNetCore.Mvc.Razor.Extensions
Microsoft.AspNetCore.Mvc.Razor
The Microsoft.AspNetCore.Razor.Design package provides the Razor compilation tasks and targets for the
project.
The preceding packages are included in Microsoft.AspNetCore.Mvc . The following markup shows a project
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>
<TargetFramework>netcoreapp2.1</TargetFramework>
</PropertyGroup>

<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.1.3" />
</ItemGroup>

</Project>

WARNING
The Microsoft.AspNetCore.Razor.Design and Microsoft.AspNetCore.Mvc.Razor.Extensions packages are included in
the Microsoft.AspNetCore.App metapackage. However, the version-less Microsoft.AspNetCore.App package reference
provides a metapackage to the app that doesn't include the latest version of Microsoft.AspNetCore.Razor.Design .
Projects must reference a consistent version of Microsoft.AspNetCore.Razor.Design (or Microsoft.AspNetCore.Mvc ) so
that the latest build-time fixes for Razor are included. For more information, see this GitHub issue.

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 properties and items in the following table 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.microsoft.com/">

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.

 PROPERTY DESCRIPTION

RazorCompileToolset Used to determine the toolset used to build the Razor

assembly. Valid values are Implicit , RazorSDK , and
PrecompilationTool .

EnableDefaultContentItems Default is true . When true , includes web.config, .json, and

.cshtml files as content in the project. When referenced via
Microsoft.NET.Sdk.Web , files under wwwroot and config
files are also included.

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 the file
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 aren't required for a
published app 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 aren't required for a
published app if Razor compilation occurs at build-time or
publish-time. Set to true if your published app requires
runtime compilation. For example, set the value to true if
the app modifies .cshtml files at runtime or uses embedded
views. Defaults to false .

IncludeRazorContentInPack When true , all Razor content items (.cshtml files) are
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 .

For more information on properties, see MSBuild properties.

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 a web app, ensure your app is targeting the Microsoft.NET.Sdk.Web SDK.

Razor language version

When targeting the Microsoft.NET.Sdk.Web SDK, the Razor language version is inferred from the the app's target
framework version. For projects targeting the Microsoft.NET.Sdk.Razor SDK or in the rare case that the app
requires a different Razor language version than the inferred value, a version can be configured by setting the
<RazorLangVersion> property in the app's project file:

<PropertyGroup>
<RazorLangVersion>{VERSION}</RazorLangVersion>
</PropertyGroup>

Additional resources
Additions to the csproj format for .NET Core
Common MSBuild project items
 Overview of ASP.NET Core MVC
8/1/2019 • 9 minutes to read • Edit Online

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. 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.
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, 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, move 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
Dependency injection
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.

[Route("api/[controller]")]
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.
 using System.ComponentModel.DataAnnotations;
public class LoginViewModel
{
[Required]
[EmailAddress]
public string Email { get; set; }

[Required]
[DataType(DataType.Password)]
public string Password { get; set; }

[Display(Name = "Remember me?")]

public bool RememberMe { get; set; }
}

A controller action:

public async Task<IActionResult> Login(LoginViewModel model, string returnUrl = null)

{
if (ModelState.IsValid)
{
// 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.
Dependency injection
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 names="Development">
<script src="~/lib/jquery/dist/jquery.js"></script>
</environment>
<environment names="Staging,Production">
<script src="https://ajax.aspnetcdn.com/ajax/jquery/jquery-2.1.4.min.js"
asp-fallback-src="~/lib/jquery/dist/jquery.min.js"
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
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.
 Create a web app with ASP.NET Core MVC
4/26/2019 • 2 minutes to read • Edit Online

This tutorial teaches ASP.NET Core MVC web development with controllers and views. If you're new to ASP.NET
Core web development, consider the Razor Pages version of this tutorial, which provides an easier starting point.
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
8/6/2019 • 11 minutes to read • Edit Online

By Rick Anderson
This tutorial teaches ASP.NET Core MVC web development with controllers and views. If you're new to
ASP.NET Core web development, consider the Razor Pages version of this tutorial, which provides an easier
starting point.
This tutorial teaches the basics of building an ASP.NET Core MVC web app.
The app manages a database of movie titles. You learn how to:
Create a web app.
Add and scaffold a model.
Work with a database.
Add search and validation.
At the end, you have an app that can manage and display movie data.
View or download sample code (how to download).

Prerequisites
Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 3.0 Preview

Create a web app

Visual Studio
Visual Studio Code
Visual Studio for Mac
From the Visual Studio select Create a new project.
Select ASP.NET Core Web Application and then select Next.
Name the project MvcMovie and select Create. It's important to name the project MvcMovie so when
you copy code, the namespace will match.

Select Web Application(Model-View-Controller), and then select Create.

Visual Studio used the 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.
Run the app
Visual Studio
Visual Studio Code
Visual Studio for Mac
Select Ctrl-F5 to run the app in non-debug mode.
Visual Studio displays the following dialog:

Select Yes if you trust the IIS Express SSL certificate.

The following dialog is displayed:
Select Yes if you agree to trust the development certificate.
See Trust the ASP.NET Core HTTPS development certificate for more information.
Visual Studio starts IIS Express and runs the 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.
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.
You can launch the app in debug or non-debug mode from the Debug menu item:

You can debug the app by selecting the IIS Express button
 The following image shows the app:

Visual Studio
Visual Studio Code
Visual Studio for Mac

Visual Studio help

Learn to debug C# code using Visual Studio
Introduction to the Visual Studio IDE
In the next part of this tutorial, you learn about MVC and start writing some code.

NEXT

This tutorial teaches ASP.NET Core MVC web development with controllers and views. If you're new to
ASP.NET Core web development, consider the Razor Pages version of this tutorial, which provides an easier
starting point.
This tutorial teaches the basics of building an ASP.NET Core MVC web app.
The app manages a database of movie titles. You learn how to:
Create a web app.
Add and scaffold a model.
Work with a database.
Add search and validation.
At the end, you have an app that can manage and display movie data.
View or download sample code (how to download).

Prerequisites
Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 2.2 or later

WARNING
If you use Visual Studio 2017, see dotnet/sdk issue #3124 for information about .NET Core SDK versions that don't work
with Visual Studio.

Create a web app

Visual Studio
Visual Studio Code
Visual Studio for Mac
From the Visual Studio select Create a new project.
Selecct ASP.NET Core Web Application and then select Next.

Name the project MvcMovie and select Create. It's important to name the project MvcMovie so when
you copy code, the namespace will match.
 Select Web Application(Model-View-Controller), and then select Create.

Visual Studio used the 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.
Run the app
Visual Studio
Visual Studio Code
Visual Studio for Mac
Select Ctrl-F5 to run the app in non-debug mode.
Visual Studio displays the following dialog:

Select Yes if you trust the IIS Express SSL certificate.

The following dialog is displayed:

Select Yes if you agree to trust the development certificate.

See Trust the ASP.NET Core HTTPS development certificate for more information.
Visual Studio starts IIS Express and runs the 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.
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.
You can launch the app in debug or non-debug mode from the Debug menu item:
You can debug the app by selecting the IIS Express button

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
Visual Studio Code
Visual Studio for Mac

Visual Studio help

Learn to debug C# code using Visual Studio
Introduction to the Visual Studio IDE
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
8/6/2019 • 12 minutes to read • Edit Online

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, https://localhost:5001/Home/Privacy has route data of Home (the controller) and Privacy
(the action method to call on the home controller). https://localhost:5001/Movies/Edit/5 is a request to
edit the movie with ID=5 using the movie controller. Route data is explained 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.

Add a controller
Visual Studio
Visual Studio Code
Visual Studio for Mac
In Solution Explorer, right-click Controllers > Add > Controller
 In the Add Scaffold dialog box, select MVC Controller - Empty

In the Add Empty MVC Controller dialog, enter HelloWorldController and select ADD.
Replace the contents of Controllers/HelloWorldController.cs with the following:
 using Microsoft.AspNetCore.Mvc;
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 https://localhost:5001/HelloWorld , and
combines the protocol used: HTTPS , the network location of the web server (including the TCP port):
localhost:5001 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 the scaffolding engine is used to generate HTTP POST methods which update
data.
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]

The routing format is set in the Configure method in Startup.cs file.

app.UseEndpoints(endpoints =>
{
endpoints.MapControllerRoute(
name: "default",
pattern: "{controller=Home}/{action=Index}/{id?}");
endpoints.MapRazorPages();
});

When you browse to 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:{PORT}/HelloWorld maps to the
HelloWorldController class. The second part of the URL segment determines the action method on the class.
So localhost:{PORT}/HelloWorld/Index would cause the Index method of the HelloWorldController class to run.
Notice that you only had to browse to localhost:{PORT}/HelloWorld and the Index method was called by
default. That's 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. Route data is explained later in the
tutorial.
Browse to https://localhost:{PORT}/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.

// GET: /HelloWorld/Welcome/
// 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 in $"Hello {name}, NumTimes is: {numTimes}" .
Run the app and browse to:
https://localhost:{PORT}/HelloWorld/Welcome?name=Rick&numtimes=4

(Replace {PORT} 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: https://localhost:{PORT}/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 MapControllerRoute method. The trailing ? (in id? ) indicates the
id parameter is optional.

app.UseEndpoints(endpoints =>
{
endpoints.MapControllerRoute(
name: "default",
pattern: "{controller=Home}/{action=Index}/{id?}");
endpoints.MapRazorPages();
});

In these examples the controller has been doing the "VC" portion of MVC - that is, the View and the 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 generate the HTML response. You do that in the next tutorial.

P R E V IO U S NEXT

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, https://localhost:5001/Home/About has route data of Home (the controller) and About (the
action method to call on the home controller). https://localhost:5001/Movies/Edit/5 is a request to edit
the movie with ID=5 using the movie controller. Route data is explained 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.

Add a controller
Visual Studio
Visual Studio Code
Visual Studio for Mac
In Solution Explorer, right-click Controllers > Add > Controller
 In the Add Scaffold dialog box, select MVC Controller - Empty

In the Add Empty MVC Controller dialog, enter HelloWorldController and select ADD.
Replace the contents of Controllers/HelloWorldController.cs with the following:
 using Microsoft.AspNetCore.Mvc;
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 https://localhost:5001/HelloWorld , and
combines the protocol used: HTTPS , the network location of the web server (including the TCP port):
localhost:5001 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 the scaffolding engine is used to generate HTTP POST methods which update
data.
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]

The routing format is set in the Configure method in Startup.cs file.

app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});

When you browse to 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:{PORT}/HelloWorld maps to the
HelloWorldController class. The second part of the URL segment determines the action method on the class. So
localhost:{PORT}/HelloWorld/Index would cause the Index method of the HelloWorldController class to run.
Notice that you only had to browse to localhost:{PORT}/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. Route data is explained later in the
tutorial.
Browse to https://localhost:{PORT}/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.

// GET: /HelloWorld/Welcome/
// 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 in $"Hello {name}, NumTimes is: {numTimes}" .
Run the app and browse to:
https://localhost:{PORT}/HelloWorld/Welcome?name=Rick&numtimes=4

(Replace {PORT} 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: https://localhost:{PORT}/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.

app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});

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.

P R E V IO U S NEXT
 Add a view to an ASP.NET Core MVC app
8/6/2019 • 16 minutes to read • Edit Online

By Rick Anderson
In this section you modify the HelloWorldController class to use Razor view 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 with 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 calls the controller's View method. It uses a view template to generate an HTML response.
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 .

Add a view
Visual Studio
Visual Studio Code
Visual Studio for Mac
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
Select Razor View
Keep the Name box value, Index.cshtml.
Select Add
Replace the contents of the Views/HelloWorld/Index.cshtml Razor view file with the following:

@{
ViewData["Title"] = "Index";
}

<h2>Index</h2>

<p>Hello from our View Template!</p>

Navigate to https://localhost:{PORT}/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 a view template file name wasn't specified, MVC defaulted to using
the default view file. The default view file has the same name as the method ( Index ), so in the
/Views/HelloWorld/Index.cshtml is used. The image below shows the string "Hello from our View Template!"
hard-coded in the view.
Change views and layout pages
Select the menu links (MvcMovie, Home, and Privacy). 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 Privacy link, the
Views/Home/Privacy.cshtml view is rendered inside the RenderBody method.

Change the title, footer, and menu link in the layout file
Replace the content of the Views\Shared_Layout.cshtml file with the following markup. The changes are
highlighted:
 <!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@ViewData["Title"] - Movie App</title>
<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
<link rel="stylesheet" href="~/css/site.css" />
</head>
<body>
<header>
<nav class="navbar navbar-expand-sm navbar-toggleable-sm navbar-light bg-white border-bottom box-
shadow mb-3">
<div class="container">
<a class="navbar-brand" asp-controller="Movies" asp-action="Index">Movie App</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target=".navbar-
collapse" aria-controls="navbarSupportedContent"
aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="navbar-collapse collapse d-sm-inline-flex flex-sm-row-reverse">
<ul class="navbar-nav flex-grow-1">
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-
action="Index">Home</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-
action="Privacy">Privacy</a>
</li>
</ul>
</div>
</div>
</nav>
</header>
<div class="container">
<main role="main" class="pb-3">
@RenderBody()
</main>
</div>

<footer class="border-top footer text-muted">

<div class="container">
&copy; 2019 - Movie App - <a asp-area="" asp-controller="Home" asp-action="Privacy">Privacy</a>
</div>
</footer>
<script src="~/lib/jquery/dist/jquery.js"></script>
<script src="~/lib/bootstrap/dist/js/bootstrap.bundle.js"></script>
<script src="~/js/site.js" asp-append-version="true"></script>
@RenderSection("Scripts", required: false)
</body>
</html>

The preceding markup made the following changes:

3 occurrences of MvcMovie to Movie App .
The anchor element
<a class="navbar-brand" asp-area="" asp-controller="Home" asp-action="Index">MvcMovie</a> to
<a class="navbar-brand" asp-controller="Movies" asp-action="Index">Movie App</a> .

In the preceding markup, the asp-area="" anchor Tag Helper attribute and attribute value was omitted because
this app is not using Areas.
Note: The Movies controller has not been implemented. At this point, the Movie App link is not functional.
Save your changes and select the Privacy link. Notice how the title on the browser tab displays Privacy Policy
- Movie App instead of Privacy Policy - Mvc Movie:

Select the Home 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. The Layout
property can be used to set a different layout view, or set it to null so no layout file will be used.
Change the title and <h2> element of the Views/HelloWorld/Index.cshtml view file:

@{
ViewData["Title"] = "Movie List";
}

<h2>My Movie List</h2>

<p>Hello from our View Template!</p>

The title and <h2> element are slightly different so you can see which bit of code changes the display.
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:

<title>@ViewData["Title"] - Movie App</title>

Save the change and navigate to https://localhost:{PORT}/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.
The content in the Index.cshtml view template is merged with the Views/Shared/_Layout.cshtml view template. A
single HTML response is sent to the browser. Layout templates make it easy to make changes that apply across
all of the pages in an app. 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 the code is
written 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 the 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.

In HelloWorldController.cs, change the Welcome method to add a Message and NumTimes value to the ViewData
dictionary. The ViewData dictionary is a dynamic object, which means any type can be used; 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:
 using Microsoft.AspNetCore.Mvc;
using System.Text.Encodings.Web;

namespace MvcMovie.Controllers
{
public class HelloWorldController : Controller
{
public IActionResult Index()
{
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:

https://localhost:{PORT}/HelloWorld/Welcome?name=Rick&numtimes=4

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, the ViewData dictionary was used to pass data from the controller to a view. Later in the
tutorial, a view model is used 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 When to use ViewBag, ViewData, or
TempData for more information.
In the next tutorial, a database of movies is created.

P R E V IO U S NEXT

In this section you modify the HelloWorldController class to use Razor view 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 with 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 calls the controller's View method. It uses a view template to generate an HTML response.
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 .

Add a view
Visual Studio
Visual Studio Code
Visual Studio for Mac
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
Select Razor View
Keep the Name box value, Index.cshtml.
Select Add

Replace the contents of the Views/HelloWorld/Index.cshtml Razor view file with the following:

@{
ViewData["Title"] = "Index";
}

<h2>Index</h2>

<p>Hello from our View Template!</p>

Navigate to https://localhost:{PORT}/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 a view template file name wasn't specified, MVC defaulted to using
the default view file. The default view file has the same name as the method ( Index ), so in the
/Views/HelloWorld/Index.cshtml is used. The image below shows the string "Hello from our View Template!"
hard-coded in the view.
Change views and layout pages
Select the menu links (MvcMovie, Home, and Privacy). 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 Privacy link, the
Views/Home/Privacy.cshtml view is rendered inside the RenderBody method.

Change the title, footer, and menu link in the layout file
In the title and footer elements, change MvcMovie to Movie App .
Change the anchor element
<a class="navbar-brand" asp-area="" asp-controller="Home" asp-action="Index">MvcMovie</a> to
<a class="navbar-brand" asp-controller="Movies" asp-action="Index">Movie App</a> .

The following markup shows the highlighted changes:

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@ViewData["Title"] - Movie App</title>

<environment include="Development">
<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
</environment>
<environment exclude="Development">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-
bootstrap/4.1.3/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"
crossorigin="anonymous"
integrity="sha256-eSi1q2PG6J7g7ib17yAaWMcrr5GrtohYChqibrV7PBE="/>
</environment>
<link rel="stylesheet" href="~/css/site.css" />
</head>
<body>
 <body>
<header>
<nav class="navbar navbar-expand-sm navbar-toggleable-sm navbar-light bg-white border-bottom box-
shadow mb-3">
<div class="container">
<a class="navbar-brand" asp-controller="Movies" asp-action="Index">Movie App</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target=".navbar-
collapse" aria-controls="navbarSupportedContent"
aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="navbar-collapse collapse d-sm-inline-flex flex-sm-row-reverse">
<ul class="navbar-nav flex-grow-1">
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-
action="Index">Home</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-
action="Privacy">Privacy</a>
</li>
</ul>
</div>
</div>
</nav>
</header>
<div class="container">
<partial name="_CookieConsentPartial" />
<main role="main" class="pb-3">
@RenderBody()
</main>
</div>

<footer class="border-top footer text-muted">

<div class="container">
&copy; 2019 - Movie App - <a asp-area="" asp-controller="Home" asp-action="Privacy">Privacy</a>
</div>
</footer>

<environment include="Development">
<script src="~/lib/jquery/dist/jquery.js"></script>
<script src="~/lib/bootstrap/dist/js/bootstrap.bundle.js"></script>
</environment>
<environment exclude="Development">
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js"
asp-fallback-src="~/lib/jquery/dist/jquery.min.js"
asp-fallback-test="window.jQuery"
crossorigin="anonymous"
integrity="sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8=">
</script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-
bootstrap/4.1.3/js/bootstrap.bundle.min.js"
asp-fallback-src="~/lib/bootstrap/dist/js/bootstrap.bundle.min.js"
asp-fallback-test="window.jQuery && window.jQuery.fn && window.jQuery.fn.modal"
crossorigin="anonymous"
integrity="sha256-E/V4cWE4qvAeO5MOhjtGtqDzPndRO1LBk8lJ/PR7CA4=">
</script>
</environment>
<script src="~/js/site.js" asp-append-version="true"></script>

@RenderSection("Scripts", required: false)

</body>
</html>

In the preceding markup, the asp-area anchor Tag Helper attribute was omitted because this app is not using
Areas.
Note: The Movies controller has not been implemented. At this point, the Movie App link is not functional.
Save your changes and select the Privacy link. Notice how the title on the browser tab displays Privacy Policy
- Movie App instead of Privacy Policy - Mvc Movie:

Select the Home 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. The Layout
property can be used to set a different layout view, or set it to null so no layout file will be used.
Change the title and <h2> element of the Views/HelloWorld/Index.cshtml view file:

@{
ViewData["Title"] = "Movie List";
}

<h2>My Movie List</h2>

<p>Hello from our View Template!</p>

The title and <h2> element are slightly different so you can see which bit of code changes the display.
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:

<title>@ViewData["Title"] - Movie App</title>

Save the change and navigate to https://localhost:{PORT}/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 the code is
written 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 the 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.

In HelloWorldController.cs, change the Welcome method to add a Message and NumTimes value to the ViewData
dictionary. The ViewData dictionary is a dynamic object, which means any type can be used; 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:

using Microsoft.AspNetCore.Mvc;
using System.Text.Encodings.Web;

namespace MvcMovie.Controllers
{
public class HelloWorldController : Controller
{
public IActionResult Index()
{
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:

https://localhost:{PORT}/HelloWorld/Welcome?name=Rick&numtimes=4

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, the ViewData dictionary was used to pass data from the controller to a view. Later in the
tutorial, a view model is used 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 When to use ViewBag, ViewData, or
TempData for more information.
In the next tutorial, a database of movies is created.

P R E V IO U S NEXT
 Add a model to an ASP.NET Core MVC app
6/11/2019 • 12 minutes to read • Edit Online

By Rick Anderson and Tom Dykstra

In this section, you add 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.
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 just define the properties of the data that will be 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. For information about that approach, see
ASP.NET Core - Existing Database.

Add a data model class

Visual Studio
Visual Studio Code / Visual Studio for Mac
Right-click the Models folder > Add > Class. Name the class Movie.
Add the following properties to the Movie class:

using System;
using System.ComponentModel.DataAnnotations;

namespace MvcMovie.Models
{
public class Movie
{
public int Id { get; set; }
public string Title { get; set; }

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }
public string Genre { get; set; }
public decimal Price { get; set; }
}
}

The Movie class contains:

The Id field which is required by the database for the primary key.
[DataType(DataType.Date)] : The DataType attribute specifies the type of the data ( Date ). With this
attribute:
The user is not required to enter time information in the date field.
Only the date is displayed, not time information.
DataAnnotations are covered in a later tutorial.
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.
Visual Studio
Visual Studio Code
Visual Studio for Mac
In Solution Explorer, right-click the Controllers folder > Add > New Scaffolded Item.

In the Add Scaffold dialog, select 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
Select 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.
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 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.

Initial migration
In this section, the following tasks are completed:
Add an initial migration.
Update the database with the initial migration.
Visual Studio
Visual Studio Code / Visual Studio for Mac
1. From the Tools menu, select NuGet Package Manager > Package Manager Console (PMC ).

2. In the PMC, enter the following commands:

Add-Migration Initial
Update-Database

The Add-Migration command generates code to create the initial database schema.
The database schema is based on the model specified in the MvcMovieContext class. The Initial
argument is the migration name. Any name can be used, but by convention, a name that describes the
migration is used. For more information, see Tutorial: Using the migrations feature - ASP.NET MVC with
EF Core.
The Update-Database command runs the Up method in the Migrations/{time-stamp }_InitialCreate.cs file,
which creates the database.
Examine the context registered with dependency injection
ASP.NET Core is built with dependency injection (DI). Services (such as the EF Core DB context) are registered
with DI 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.
Visual Studio
Visual Studio Code / Visual Studio for Mac
The scaffolding tool automatically created a DB context and registered it with the DI container.
Examine the following Startup.ConfigureServices method. The highlighted line was added by the scaffolder:

public void ConfigureServices(IServiceCollection services)

{
services.Configure<CookiePolicyOptions>(options =>
{
// This lambda determines whether user consent for non-essential cookies
// is needed for a given request.
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

services.AddDbContext<MvcMovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("MvcMovieContext")));
}

The MvcMovieContext coordinates EF Core functionality (Create, Read, Update, Delete, etc.) for the Movie model.
The data context ( MvcMovieContext ) is derived from Microsoft.EntityFrameworkCore.DbContext. The data context
specifies which entities are included in the data model:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.EntityFrameworkCore;

namespace MvcMovie.Models
{
public class MvcMovieContext : DbContext
{
public MvcMovieContext (DbContextOptions<MvcMovieContext> options)
: base(options)
{
}

public DbSet<MvcMovie.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.
Test the app
Run the app and append /Movies to the URL in the browser ( http://localhost:port/movies ).

If you get a database exception similar to the following:

SqlException: Cannot open database "MvcMovieContext-GUID" requested by the login. The login failed.
Login failed for user 'User-name'.

You missed the migrations step.

Test the Create link. Enter and submit data.

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 for non US-English date formats, the app must be globalized.
For globalization instructions, see this GitHub issue.

Test the Edit, Details, and Delete links.

Examine the Startup class:

public void ConfigureServices(IServiceCollection services)

{
services.Configure<CookiePolicyOptions>(options =>
{
// This lambda determines whether user consent for non-essential cookies
// is needed for a given request.
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

services.AddDbContext<MvcMovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("MvcMovieContext")));
}

The preceding highlighted code shows the movie database context being added to the Dependency Injection
container:
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);
}

The id parameter is generally passed as route data. For example https://localhost:5001/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:
https://localhost:5001/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.

var movie = await _context.Movie

.FirstOrDefaultAsync(m => m.Id == id);

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";
}

<h1>Details</h1>

<div>
<h4>Movie</h4>
<hr />
<dl class="row">
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Title)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Title)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.ReleaseDate)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.ReleaseDate)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Genre)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Genre)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Price)
</dt>
<dd class="col-sm-10">
@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, the following @model statement was automatically included at
the top of the Details.cshtml file:

@model MvcMovie.Models.Movie

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>

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-action="Create">Create New</a>
</p>
<table class="table">
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.Title)
</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>
@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-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:

Additional resources
Tag Helpers
Globalization and localization
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 in ASP.NET Core
4/26/2019 • 4 minutes to read • Edit Online

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:

Visual Studio
Visual Studio Code / Visual Studio for Mac

public void ConfigureServices(IServiceCollection services)

{
services.Configure<CookiePolicyOptions>(options =>
{
// This lambda determines whether user consent for non-essential cookies
// is needed for a given request.
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

services.AddDbContext<MvcMovieContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("MvcMovieContext")));
}

The ASP.NET Core Configuration system reads the ConnectionString . For local development, it gets the
connection string from the appsettings.json file:

"ConnectionStrings": {
"MvcMovieContext": "Server=(localdb)\\mssqllocaldb;Database=MvcMovieContext-
2;Trusted_Connection=True;MultipleActiveResultSets=true"
}

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.
Visual Studio
Visual Studio Code / Visual Studio for Mac

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 > 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
Create a new class named SeedData in the Models folder. Replace the generated code with the following:
 using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using System;
using System.Linq;

namespace MvcMovie.Models
{
public static class SeedData
{
public static void Initialize(IServiceProvider serviceProvider)
{
using (var context = new MvcMovieContext(
serviceProvider.GetRequiredService<
DbContextOptions<MvcMovieContext>>()))
{
// 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 ",
ReleaseDate = DateTime.Parse("1984-3-13"),
Genre = "Comedy",
Price = 8.99M
},

new Movie
{
Title = "Ghostbusters 2",
ReleaseDate = DateTime.Parse("1986-2-23"),
Genre = "Comedy",
Price = 9.99M
},

new Movie
{
Title = "Rio Bravo",
ReleaseDate = DateTime.Parse("1959-4-15"),
Genre = "Western",
Price = 3.99M
}
);
context.SaveChanges();
}
}
}
}

If there are any movies in the DB, the seed initializer returns and no movies are added.
 if (context.Movie.Any())
{
return; // DB has been seeded.
}

Add the seed initializer

Replace the contents of Program.cs with the following code:

using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using System;
using Microsoft.EntityFrameworkCore;
using MvcMovie.Models;
using MvcMovie;

namespace MvcMovie
{
public class Program
{
public static void Main(string[] args)
{
var host = CreateWebHostBuilder(args).Build();

using (var scope = host.Services.CreateScope())

{
var services = scope.ServiceProvider;

try
{
var context = services.GetRequiredService<MvcMovieContext>();
context.Database.Migrate();
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 IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>();
}
}

Test the app

Visual Studio
Visual Studio Code / Visual Studio for Mac
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
7/11/2019 • 9 minutes to read • Edit Online

By Rick Anderson
We have a good start to the movie app, but the presentation isn't ideal, for example, ReleaseDate should be two
words.

Open the Models/Movie.cs file and add the highlighted lines shown below:
 using System;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace MvcMovie.Models
{
public class Movie
{
public int Id { get; set; }
public string Title { get; set; }

[Display(Name = "Release Date")]

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }
public string Genre { get; set; }

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

public decimal Price { get; set; }
}
}

We 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.
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.
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.
 <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>

Tag Helpers enable server-side code to participate in creating and rendering HTML elements in Razor files. In the
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:

app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});

ASP.NET Core translates https://localhost:5001/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. For more information, see Additional
resources.
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);
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!MovieExists(movie.ID))
{
return NotFound();
}
else
{
throw;
}
}
return RedirectToAction("Index");
}
return View(movie);
}

// GET: Movies/Edit/5
public async Task<IActionResult> Edit(int? id)
{
if (id == null)
{
return NotFound();
}

var movie = await _context.Movie.SingleOrDefaultAsync(m => m.ID == 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);
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!MovieExists(movie.ID))
{
return NotFound();
}
else
{
throw;
}
}
return RedirectToAction("Index");
}
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. For more information, see Protect your controller from over -posting.
ViewModels provide an alternative approach to prevent over-posting.
Notice the second Edit action method is preceded by the [HttpPost] attribute.
[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);
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!MovieExists(movie.ID))
{
return NotFound();
}
else
{
throw;
}
}
return RedirectToAction(nameof(Index));
}
return View(movie);
}
 // 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);
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!MovieExists(movie.ID))
{
return NotFound();
}
else
{
throw;
}
}
return RedirectToAction("Index");
}
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
FindAsync method, and returns the selected movie to the Edit view. If a movie cannot be found, NotFound ( HTTP
404) is returned.
 // 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);
}

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:
 @model MvcMovie.Models.Movie

@{
ViewData["Title"] = "Edit";
}

<h1>Edit</h1>

<h4>Movie</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form asp-action="Edit">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<input type="hidden" asp-for="Id" />
<div class="form-group">
<label asp-for="Title" class="control-label"></label>
<input asp-for="Title" class="form-control" />
<span asp-validation-for="Title" class="text-danger"></span>
</div>
<div class="form-group">
<label asp-for="ReleaseDate" class="control-label"></label>
<input asp-for="ReleaseDate" class="form-control" />
<span asp-validation-for="ReleaseDate" class="text-danger"></span>
</div>
<div class="form-group">
<label asp-for="Genre" class="control-label"></label>
<input asp-for="Genre" class="form-control" />
<span asp-validation-for="Genre" class="text-danger"></span>
</div>
<div class="form-group">
<label asp-for="Price" class="control-label"></label>
<input asp-for="Price" class="form-control" />
<span asp-validation-for="Price" class="text-danger"></span>
</div>
<div class="form-group">
<input type="submit" value="Save" class="btn btn-primary" />
</div>
</form>
</div>
</div>

<div>
<a asp-action="Index">Back to List</a>
</div>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

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">
<div class="form-horizontal">
<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" />
<div class="form-group">
<label class="control-label col-md-2" for="Genre" />
<div class="col-md-10">
<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>
<div class="form-group">
<label class="control-label col-md-2" for="Price" />
<div class="col-md-10">
<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-
replace="true"></span>
</div>
</div>
<!-- Markup removed for brevity -->
<div class="form-group">
<div class="col-md-offset-2 col-md-10">
<input type="submit" value="Save" class="btn btn-default" />
</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]
[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);
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!MovieExists(movie.ID))
{
return NotFound();
}
else
{
throw;
}
}
return RedirectToAction(nameof(Index));
}
return View(movie);
}
 // 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);
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!MovieExists(movie.ID))
{
return NotFound();
}
else
{
throw;
}
}
return RedirectToAction("Index");
}
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.

Additional resources
Globalization and localization
Introduction to Tag Helpers
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
8/7/2019 • 7 minutes to read • Edit Online

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 found inside Controllers/MoviesController.cs with the following code:

public async Task<IActionResult> Index(string searchString)

{
var movies = from m in _context.Movie
select m;

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

return View(await movies.ToListAsync());

}

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

var movies = from m in _context.Movie

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 value of the search
string:

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

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 SQLite, 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.

app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});

Change the parameter to id and all occurrences of searchString change to id .

The previous Index method:

public async Task<IActionResult> Index(string searchString)

{
var movies = from m in _context.Movie
select m;

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

return View(await movies.ToListAsync());

}

The updated Index method with id parameter:

 public async Task<IActionResult> Index(string id)
{
var movies = from m in _context.Movie
select m;

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

return View(await movies.ToListAsync());

}

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 :

public async Task<IActionResult> Index(string searchString)

{
var movies = from m in _context.Movie
select m;

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

return View(await movies.ToListAsync());

}

Open the Views/Movies/Index.cshtml file, and add the <form> markup highlighted below:
 ViewData["Title"] = "Index";
}

<h2>Index</h2>

<p>
<a asp-action="Create">Create New</a>
</p>

<form asp-controller="Movies" asp-action="Index">

<p>
Title: <input type="text" name="SearchString">
<input type="submit" value="Filter" />
</p>
</form>

<table class="table">
<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:{PORT}/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. Fix this by specifying the request should be HTTP GET found in the
Views/Movies/Index.cshtml file.
 @model IEnumerable<MvcMovie.Models.Movie>

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-action="Create">Create New</a>
</p>
<form asp-controller="Movies" asp-action="Index" method="get">
<p>
Title: <input type="text" name="SearchString">
<input type="submit" value="Filter" />
</p>
</form>

<table class="table">
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.Title)

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">

Add Search by genre

Add the following MovieGenreViewModel class to the Models folder:

using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

namespace MvcMovie.Models
{
public class MovieGenreViewModel
{
public List<Movie> Movies { get; set; }
public SelectList Genres { get; set; }
public string MovieGenre { get; set; }
public string SearchString { get; set; }
}
}

The movie-genre view model will contain:

A list of movies.
A SelectList containing the list of genres. This allows the user to select a genre from the list.
MovieGenre , which contains the selected genre.
SearchString , which contains the text users enter in the search text box.

Replace the Index method in MoviesController.cs with the following code:

// GET: Movies
public async Task<IActionResult> Index(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;

var movies = from m in _context.Movie

select m;

if (!string.IsNullOrEmpty(searchString))
{
movies = movies.Where(s => s.Title.Contains(searchString));
}

if (!string.IsNullOrEmpty(movieGenre))
{
movies = movies.Where(x => x.Genre == movieGenre);
}

var movieGenreVM = new MovieGenreViewModel

{
Genres = new SelectList(await genreQuery.Distinct().ToListAsync()),
Movies = await movies.ToListAsync()
};

return View(movieGenreVM);
}

The following code is a LINQ query that retrieves all the genres from the database.

// Use LINQ to get list of genres.

IQueryable<string> genreQuery = from m in _context.Movie
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).
When the user searches for the item, the search value is retained in the search box.

Add search by genre to the Index view

Update Index.cshtml found in Views/Movies/ as follows:
@model MvcMovie.Models.MovieGenreViewModel

@{
ViewData["Title"] = "Index";
}

<h1>Index</h1>

<p>
<a asp-action="Create">Create New</a>
</p>
<form asp-controller="Movies" asp-action="Index" method="get">
<p>

<select asp-for="MovieGenre" asp-items="Model.Genres">

<option value="">All</option>
</select>

Title: <input type="text" asp-for="SearchString" />

<input type="submit" value="Filter" />
</p>
</form>

<table class="table">
<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>
@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-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>
Examine the lambda expression used in the following HTML Helper:
@Html.DisplayNameFor(model => model.Movies[0].Title)

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.
Test the app by searching by genre, by movie title, and by both:

P R E V IO U S NEXT
 Add a new field to an ASP.NET Core MVC app
8/2/2019 • 5 minutes to read • Edit Online

By Rick Anderson
In this section Entity Framework Code First Migrations is used to:
Add a new field to the model.
Migrate the new field to the database.
When EF Code First is used to automatically create a database, Code First:
Adds a table to the database to track the schema of the database.
Verifies 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.

Add a Rating Property to the Movie Model

Add a Rating property to Models/Movie.cs:

public class Movie

{
public int Id { get; set; }
public string Title { get; set; }

[Display(Name = "Release Date")]

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }
public string Genre { get; set; }

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

public decimal Price { get; set; }
public string Rating { get; set; }
}

Build the app

Visual Studio
Visual Studio Code
Visual Studio for Mac
Ctrl+Shift+B
Because you've added a new field to the Movie class, you 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")]

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>
@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>
@Html.DisplayNameFor(model => model.Movies[0].Rating)
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Movies)
{
<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>
@Html.DisplayFor(modelItem => item.Rating)
</td>
<td>
<a asp-action="Edit" asp-route-id="@item.Id">Edit</a> |

Update the /Views/Movies/Create.cshtml with a Rating field.

Visual Studio / Visual Studio for Mac
Visual Studio Code
You can copy/paste the previous "form group" and let intelliSense help you update the fields. IntelliSense works
with Tag Helpers.
Update the the remaining templates.
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 .

new Movie
{
Title = "When Harry Met Sally",
ReleaseDate = DateTime.Parse("1989-1-11"),
Genre = "Romantic Comedy",
Rating = "R",
Price = 7.99M
},

The app won't work until the DB is updated to include the new field. If it's run now, the following SqlException is
thrown:
SqlException: Invalid column name 'Rating'.

This error occurs 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.)
There are a few approaches to resolving the error:
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're 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. This is a good approach for early development and when
using SQLite.
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, Code First Migrations is used.
Visual Studio
Visual Studio Code / Visual Studio for Mac
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 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 all the records in the DB are deleted, the initialize method will seed the DB and include the Rating field.
Run the app and verify you can create/edit/display movies with a Rating field. You should 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
7/11/2019 • 9 minutes to read • Edit Online

By Rick Anderson
In this section:
Validation logic is added to the Movie model.
You 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.

Add validation rules to the movie model

The DataAnnotations namespace provides a set of built-in 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 any validation.
Update the Movie class to take advantage of the built-in Required , StringLength , RegularExpression , and
Range validation attributes.
 public class Movie
{
public int Id { get; set; }

[StringLength(60, MinimumLength = 3)]

[Required]
public string Title { get; set; }

[Display(Name = "Release Date")]

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }

[Range(1, 100)]
[DataType(DataType.Currency)]
[Column(TypeName = "decimal(18, 2)")]
public decimal Price { get; set; }

[RegularExpression(@"^[A-Z]+[a-zA-Z""'\s-]*$")]
[Required]
[StringLength(30)]
public string Genre { get; set; }

[RegularExpression(@"^[A-Z]+[a-zA-Z0-9""'\s-]*$")]
[StringLength(5)]
[Required]
public string Rating { get; set; }
}

The validation attributes specify behavior that you want to enforce on the model properties they're applied to:
The Required and MinimumLength attributes indicate 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 preceding code,
"Genre":
Must only use letters.
The first letter is required to be uppercase. White space, numbers, and special characters are not
allowed.
The RegularExpression "Rating":
Requires that the first character be an uppercase letter.
Allows special characters and numbers in subsequent spaces. "PG -13" is valid for a rating, but fails for a
"Genre".
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
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
You may not be able to enter decimal commas in decimal fields. 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.
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]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Create(
[Bind("ID,Title,ReleaseDate,Genre,Price, Rating")] Movie movie)
{
if (ModelState.IsValid)
{
_context.Add(movie);
await _context.SaveChangesAsync();
return RedirectToAction("Index");
}
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.
The portion of the Create.cshtml view template is shown in the following markup:

<h4>Movie</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form asp-action="Create">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<div class="form-group">
<label asp-for="Title" class="control-label"></label>
<input asp-for="Title" class="form-control" />
<span asp-validation-for="Title" class="text-danger"></span>
</div>

@*Markup removed for brevity.*@

The preceding markup is used by the action methods to display the initial form and to redisplay it in the event of
an error.
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.
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.

Using DataType Attributes

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.
 [Display(Name = "Release Date")]
[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }

[Range(1, 100)]
[DataType(DataType.Currency)]
public decimal Price { get; set; }

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.
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)]

public DateTime ReleaseDate { get; set; }

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
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 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:
[Range(typeof(DateTime), "1/1/1966", "1/1/2020")]

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.
The following code shows combining attributes on one line:
 public class Movie
{
public int Id { get; set; }

[StringLength(60, MinimumLength = 3)]

public string Title { get; set; }

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

public DateTime ReleaseDate { get; set; }

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

public string Genre { get; set; }

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

[Column(TypeName = "decimal(18, 2)")]
public decimal Price { get; set; }

[RegularExpression(@"^[A-Z]+[a-zA-Z0-9""'\s-]*$"), StringLength(5)]
public string Rating { get; set; }
}

In the next part of the series, we review the app and make some improvements to the automatically generated
Details and Delete methods.

Additional resources
Working with Forms
Globalization and localization
Introduction to Tag Helpers
Author Tag Helpers

P R E V IO U S NEXT
 Examine the Details and Delete methods of an
ASP.NET Core app
8/7/2019 • 3 minutes to read • Edit Online

By Rick Anderson
Open the Movie controller and examine the Details method:

// 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);
}

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.

app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});

EF makes it easy to search for data using the FirstOrDefaultAsync 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:{PORT}/Movies/Details/1 to something like http://localhost:{PORT}/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();
}

var movie = await _context.Movie

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

return View(movie);
}

// POST: Movies/Delete/5
[HttpPost, ActionName("Delete")]
[ValidateAntiForgeryToken]
public async Task<IActionResult> DeleteConfirmed(int id)
{
var movie = await _context.Movie.FindAsync(id);
_context.Movie.Remove(movie);
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}

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:

// GET: Movies/Delete/5
public async Task<IActionResult> Delete(int? id)
{

// POST: Movies/Delete/5
[HttpPost, ActionName("Delete")]
[ValidateAntiForgeryToken]
public async Task<IActionResult> DeleteConfirmed(int id)
{

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:

// POST: Movies/Delete/6
[HttpPost]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Delete(int id, bool notUsed)

Publish to Azure
For information on deploying to Azure, see Tutorial: Build a .NET Core and SQL Database web app in Azure App
Service.

P R E V IO U S
 Views in ASP.NET Core MVC
4/26/2019 • 13 minutes to read • Edit Online

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 separation of concerns 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:

@{
ViewData["Title"] = "About";
}
<h2>@ViewData["Title"].</h2>
<h3>@ViewData["Message"]</h3>

<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

public IActionResult About()

{
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"
};

return View(viewModel);
}

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 Name { get; set; }
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. Note: Key lookups are case-
insensitive for both ViewData and ViewBag .
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:
 public class HomeController : Controller
{
[ViewData]
public string Title { get; set; }

public IActionResult About()

{
Title = "About Us";
ViewData["Message"] = "Your application description page.";

return View();
}
}

In the About view, 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>
...

ViewBag
ViewBag isn't available in Razor Pages.
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

ViewBag isn't available in Razor Pages.
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.
 Partial views in ASP.NET Core
6/12/2019 • 8 minutes to read • Edit Online

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.
View or download sample code (how to download)

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. In Razor
Pages, a PageModel can return a partial view represented as a PartialViewResult object. 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.
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. Referencing and rendering
partial views is described in the Reference a partial view section.
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

Use a partial view in a Razor Pages PageModel
In ASP.NET Core 2.0 or 2.1, the following handler method renders the _AuthorPartialRP.cshtml partial view to
the response:

public IActionResult OnGetPartial() =>

new PartialViewResult
{
ViewName = "_AuthorPartialRP",
ViewData = ViewData,
};

In ASP.NET Core 2.2 or later, a handler method can alternatively call the Partial method to produce a
PartialViewResult object:

public IActionResult OnGetPartial() =>

Partial("_AuthorPartialRP");

Use a partial view in a markup file

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:
Asynchronous HTML Helper
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.

Asynchronous HTML Helper
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

<h2>@Model.Title</h2>
@* 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 ...

Additional resources
Razor syntax reference for ASP.NET Core
Tag Helpers in ASP.NET Core
Partial Tag Helper in ASP.NET Core
View components in ASP.NET Core
Areas in ASP.NET Core
Razor syntax reference for ASP.NET Core
View components in ASP.NET Core
Areas in ASP.NET Core
 Handle requests with controllers in ASP.NET Core
MVC
4/26/2019 • 4 minutes to read • Edit Online

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 and PhysicalFile . For example,
return PhysicalFile(customerFilePath, "text/xml"); returns PhysicalFileResult.

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.
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.
 Routing to controller actions in ASP.NET Core
4/26/2019 • 31 minutes to read • Edit Online

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:

app.UseMvc(routes =>
{
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 class ProductsController : Controller

{
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:

routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");

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 class HomeController : Controller

{
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 :

app.UseMvcWithDefaultRoute();

Can be used to replace:

app.UseMvc(routes =>
{
routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");
});

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:

routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");

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 defaultroute, the URL path /Products/List maps to the ProductsController.List action, and
/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:

app.UseMvc(routes =>
{
routes.MapRoute("blog", "blog/{*article}",
defaults: new { controller = "Blog", action = "Article" });
routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");
});

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 class ProductsController : Controller

{
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:

app.UseMvc(routes =>
{
routes.MapRoute("blog", "blog/{*article}",
defaults: new { controller = "Blog", action = "Article" });
routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");
});

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:

public class HomeController : Controller

{
[Route("")]
[Route("Home")]
[Route("Home/Index")]
public IActionResult Index()
{
return View();
}
[Route("Home/About")]
public IActionResult About()
{
return View();
}
[Route("Home/Contact")]
public IActionResult 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 :

public class ProductsApiController : Controller

{
[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")]
public class ProductsApiController : Controller
{
[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 / or ~/ 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")]
public class HomeController : Controller
{
[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 ""
public IActionResult Index()
{
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"

public IActionResult 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] are replaced with the values of the action name, area name,
and controller name from the action where the route is defined. In the following example, the actions match
URL paths as described in the comments:
 [Route("[controller]/[action]")]
public class ProductsController : Controller
{
[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:

public class ProductsController : Controller

{
[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.

[Route("api/[controller]")]
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]")] generates a unique route name for each
action.
To match the literal token replacement delimiter [ or ] , escape it by repeating the character ( [[ or ]] ).
Use a parameter transformer to customize token replacement
Token replacement can be customized using a parameter transformer. A parameter transformer implements
IOutboundParameterTransformer and transforms the value of parameters. For example, a custom
SlugifyParameterTransformer parameter transformer changes the SubscriptionManagement route value to
subscription-management .

The RouteTokenTransformerConvention is an application model convention that:

 Applies a parameter transformer to all attribute routes in an application.
Customizes the attribute route token values as they are replaced.

public class SubscriptionManagementController : Controller

{
[HttpGet("[controller]/[action]")] // Matches '/subscription-management/list-all'
public IActionResult ListAll() { ... }
}

The RouteTokenTransformerConvention is registered as an option in ConfigureServices .

public void ConfigureServices(IServiceCollection services)

{
services.AddMvc(options =>
{
options.Conventions.Add(new RouteTokenTransformerConvention(
new SlugifyParameterTransformer()));
});
}

public class SlugifyParameterTransformer : IOutboundParameterTransformer

{
public string TransformOutbound(object value)
{
if (value == null) { return null; }

// Slugify value
return Regex.Replace(value.ToString(), "([a-z])([A-Z])", "$1-$2").ToLower();
}
}

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]")]
public class ProductsController : Controller
{
[Route("")] // Matches 'Products'
[Route("Index")] // Matches 'Products/Index'
public IActionResult 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]")]
public class ProductsController : 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.
 [Route("api/[controller]")]
public class ProductsController : Controller
{
[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; }

public string Name { 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.

Complex segments
Complex segments (for example, [Route("/dog{token}cat")] ), are processed by matching up literals from right
to left in a non-greedy way. See the source code for a description. For more information, see this issue.

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.

using Microsoft.AspNetCore.Mvc;

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
public void Configure(IApplicationBuilder app)
{
app.UseMvc();
}

using Microsoft.AspNetCore.Mvc;

public class UrlGenerationController : Controller

{
[HttpGet("")]
public IActionResult Source()
{
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.

using Microsoft.AspNetCore.Mvc;

public class TestController : Controller

{
public IActionResult Index()
{
// 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.

using Microsoft.AspNetCore.Mvc;

public class UrlGenerationController : Controller

{
[HttpGet("")]
public IActionResult Source()
{
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)

{
if (ModelState.IsValid)
{
// Update DB with new details.
return RedirectToAction("Index");
}
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.

app.UseMvc(routes =>
{
routes.MapRoute("blog", "blog/{*article}",
defaults: new { controller = "Blog", action = "Article" });
routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");
});

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 :

app.UseMvc(routes =>
{
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:

app.UseMvc(routes =>
{
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:

using Microsoft.AspNetCore.Mvc;

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 } .
 using Microsoft.AspNetCore.Mvc;

namespace MyApp.Namespace1
{
[Area("Blog")]
public class UsersController : Controller
{
public IActionResult AddUser()
{
return View();
}
}
}

using Microsoft.AspNetCore.Mvc;

namespace MyApp.Namespace2
{
// Matches { area = Zebra, controller = Users, action = AddUser }
[Area("Zebra")]
public class UsersController : Controller
{
public IActionResult AddUser()
{
return View();
}
}
}

using Microsoft.AspNetCore.Mvc;

namespace MyApp.Namespace3
{
// Matches { area = string.Empty, controller = Users, action = AddUser }
// Matches { area = null, controller = Users, action = AddUser }
// Matches { controller = Users, action = AddUser }
public class UsersController : Controller
{
public IActionResult 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.

app.UseMvc(routes =>
{
routes.MapAreaRoute("duck_route", "Duck",
"Manage/{controller}/{action}/{id?}");
routes.MapRoute("default", "Manage/{controller=Home}/{action=Index}/{id?}");
});

using Microsoft.AspNetCore.Mvc;

namespace MyApp.Namespace4
{
[Area("Duck")]
public class UsersController : Controller
{
public IActionResult GenerateURLInArea()
{
// Uses the 'ambient' value of area
var url = Url.Action("Index", "Home");
// returns /Manage
return Content(url);
}

public IActionResult GenerateURLOutsideOfArea()

{
// Uses the empty value for area
var url = Url.Action("Index", "Home", new { area = "" });
// returns /Manage/Home/Index
return Content(url);
}
}
}

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.
 public class ProductsController : Controller
{
[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
4/26/2019 • 8 minutes to read • Edit Online

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">

<div class="form-group">
<div class="col-md-10">
<p>Upload one or more files using this form:</p>
<input type="file" name="files" multiple>
</div>
</div>
<div class="form-group">
<div class="col-md-10">
<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 :

public class RegisterViewModel

{
// 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]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Register(RegisterViewModel model)
{
ViewData["ReturnUrl"] = returnUrl;
if (ModelState.IsValid)
{
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]
public IActionResult Index()
{
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:

public void ConfigureServices(IServiceCollection services)

{
// 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]
[ValidateAntiForgeryToken]
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)
{
if (!ModelState.IsValid)
{
return BadRequest(ModelState);
}
}

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>
<!-- This will handle requests up to 50MB -->
<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
4/26/2019 • 2 minutes to read • Edit Online

By Shadi Namrouti, Rick Anderson, and Steve Smith

ASP.NET Core MVC controllers request dependencies explicitly via constructors. ASP.NET Core has built-in
support for dependency injection (DI). DI makes apps easier to test and maintain.
View or download sample code (how to download)

Constructor Injection
Services are added as a constructor parameter, and the runtime resolves the service from the service container.
Services are typically defined using interfaces. For example, consider an app that requires the current time. The
following interface exposes the IDateTime service:

public interface IDateTime

{
DateTime Now { get; }
}

The following code implements the IDateTime interface:

public class SystemDateTime : IDateTime

{
public DateTime Now
{
get { return DateTime.Now; }
}
}

Add the service to the service container:

public void ConfigureServices(IServiceCollection services)

{
services.AddSingleton<IDateTime, SystemDateTime>();

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}

For more information on AddSingleton, see DI service lifetimes.

The following code displays a greeting to the user based on the time of day:
 public class HomeController : Controller
{
private readonly IDateTime _dateTime;

public HomeController(IDateTime dateTime)

{
_dateTime = dateTime;
}

public IActionResult Index()

{
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();
}

Run the app and a message is displayed based on the time.

Action injection with FromServices

The FromServicesAttribute enables injecting a service directly into an action method without using constructor
injection:

public IActionResult About([FromServices] IDateTime dateTime)

{
ViewData["Message"] = $"Current server time: {dateTime.Now}";

return View();
}

Access settings from a controller

Accessing app or configuration settings from within a controller is a common pattern. The options pattern
described in Options pattern in ASP.NET Core is the preferred approach to manage settings. Generally, don't
directly inject IConfiguration into a controller.
Create a class that represents the options. For example:

public class SampleWebSettings

{
public string Title { get; set; }
public int Updates { get; set; }
}

Add the configuration class to the services collection:

 public void ConfigureServices(IServiceCollection services)
{
services.AddSingleton<IDateTime, SystemDateTime>();
services.Configure<SampleWebSettings>(Configuration);

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}

Configure the app to read the settings from a JSON -formatted file:

public class Program

{
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.ConfigureAppConfiguration((hostingContext, config) =>
{
config.AddJsonFile("samplewebsettings.json",
optional: false, // File is not optional.
reloadOnChange: false);
})
.UseStartup<Startup>();
}

The following code requests the IOptions<SampleWebSettings> settings from the service container and uses them
in the Index method:

public class SettingsController : Controller

{
private readonly SampleWebSettings _settings;

public SettingsController(IOptions<SampleWebSettings> settingsOptions)

{
_settings = settingsOptions.Value;
}

public IActionResult Index()

{
ViewData["Title"] = _settings.Title;
ViewData["Updates"] = _settings.Updates;
return View();
}
}

Additional resources
See Test controller logic in ASP.NET Core to learn how to make code easier to test by explicitly requesting
dependencies in controllers.
Replace the default dependency injection container with a third party implementation.
 Dependency injection into views in ASP.NET Core
7/11/2019 • 4 minutes to read • Edit Online

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.
View or download sample code (how to download)

Configuration injection
appsettings.json values can be injected directly into a view.
Example of an appsettings.json file:

{
"root": {
"parent": {
"child": "myvalue"
}
}
}

The syntax for @inject : @inject <type> <name>

An example using @inject :

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration
@{
string myValue = Configuration["root:parent:child"];
...
}

Service injection
A service can be injected into a view using the @inject directive. You can think of @inject as adding a property
to the view, and populating the property using DI.
 @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>
@foreach (var item in Model)
{
<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
public void ConfigureServices(IServiceCollection services)
{
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 Microsoft.AspNetCore.Mvc;
using ViewInjectSample.Model;

namespace ViewInjectSample.Controllers
{
public class ProfileController : Controller
{
[Route("Profile")]
public IActionResult Index()
{
// 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 System.Threading.Tasks
@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:

using System.Collections.Generic;

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 System.Threading.Tasks
@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
 Test controller logic in ASP.NET Core
8/4/2019 • 12 minutes to read • Edit Online

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.
View or download sample code (how to download)

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 class HomeController : Controller
{
private readonly IBrainstormSessionRepository _sessionRepository;

public HomeController(IBrainstormSessionRepository sessionRepository)

{
_sessionRepository = sessionRepository;
}

public async Task<IActionResult> Index()

{
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)
{
if (!ModelState.IsValid)
{
return BadRequest(ModelState);
}
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"
});
sessions.Add(new BrainstormSession()
{
DateCreated = new DateTime(2016, 7, 1),
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
var mockRepo = new Mock<IBrainstormSessionRepository>();
mockRepo.Setup(repo => repo.ListAsync())
.ReturnsAsync(GetTestSessions());
var controller = new HomeController(mockRepo.Object);
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
var mockRepo = new Mock<IBrainstormSessionRepository>();
mockRepo.Setup(repo => repo.AddAsync(It.IsAny<BrainstormSession>()))
.Returns(Task.CompletedTask)
.Verifiable();
var controller = new HomeController(mockRepo.Object);
var newSession = new HomeController.NewSessionModel()
{
SessionName = "Test Name"
};

// Act
var result = await controller.Index(newSession);

// 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.
SessionController 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
(Controllers/SessionController.cs):

public class SessionController : Controller

{
private readonly IBrainstormSessionRepository _sessionRepository;

public SessionController(IBrainstormSessionRepository sessionRepository)

{
_sessionRepository = 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()

{
DateCreated = session.DateCreated,
Name = session.Name,
Id = session.Id
};

return View(viewModel);
}
}

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);
Assert.Equal("Index", redirectToActionResult.ActionName);
}

[Fact]
public async Task IndexReturnsContentWithSessionNotFoundWhenSessionNotFound()
{
// Arrange
int testSessionId = 1;
var mockRepo = new Mock<IBrainstormSessionRepository>();
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
int testSessionId = 1;
var mockRepo = new Mock<IBrainstormSessionRepository>();
mockRepo.Setup(repo => repo.GetByIdAsync(testSessionId))
.ReturnsAsync(GetTestSessions().FirstOrDefault(
s => s.Id == testSessionId));
var controller = new SessionController(mockRepo.Object);

// Act
var result = await controller.Index(testSessionId);

// Assert
var viewResult = Assert.IsType<ViewResult>(result);
var model = Assert.IsType<StormSessionViewModel>(
viewResult.ViewData.Model);
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);
if (session == null)
{
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)
{
if (!ModelState.IsValid)
{
return BadRequest(ModelState);
}

var session = await _sessionRepository.GetByIdAsync(model.SessionId);

if (session == null)
{
return NotFound(model.SessionId);
}

var idea = new Idea()

{
DateCreated = DateTimeOffset.Now,
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
int testSessionId = 123;
var mockRepo = new Mock<IBrainstormSessionRepository>();
mockRepo.Setup(repo => repo.GetByIdAsync(testSessionId))
.ReturnsAsync((BrainstormSession)null);
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
int testSessionId = 123;
var mockRepo = new Mock<IBrainstormSessionRepository>();
mockRepo.Setup(repo => repo.GetByIdAsync(testSessionId))
.ReturnsAsync(GetTestSession());
var controller = new IdeasController(mockRepo.Object);

// Act
var result = await controller.ForSession(testSessionId);

// 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
var mockRepo = new Mock<IBrainstormSessionRepository>();
var controller = new IdeasController(mockRepo.Object);
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
int testSessionId = 123;
var mockRepo = new Mock<IBrainstormSessionRepository>();
mockRepo.Setup(repo => repo.GetByIdAsync(testSessionId))
.ReturnsAsync((BrainstormSession)null);
var controller = new IdeasController(mockRepo.Object);

// 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
int testSessionId = 123;
string testName = "test name";
string testDescription = "test description";
var testSession = GetTestSession();
var mockRepo = new Mock<IBrainstormSessionRepository>();
mockRepo.Setup(repo => repo.GetByIdAsync(testSessionId))
.ReturnsAsync(testSession);
var controller = new IdeasController(mockRepo.Object);

var newIdea = new NewIdeaModel()

{
Description = testDescription,
Name = testName,
SessionId = testSessionId
};
mockRepo.Setup(repo => repo.UpdateAsync(testSession))
.Returns(Task.CompletedTask)
.Verifiable();

// Act
var result = await controller.Create(newIdea);

// Assert
var okResult = Assert.IsType<OkObjectResult>(result);
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}")]
[ProducesResponseType(200)]
[ProducesResponseType(404)]
public async Task<ActionResult<List<IdeaDTO>>> ForSessionActionResult(int sessionId)
{
var session = await _sessionRepository.GetByIdAsync(sessionId);

if (session == null)
{
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 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 mockRepo = new Mock<IBrainstormSessionRepository>();
var controller = new IdeasController(mockRepo.Object);
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 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
int testSessionId = 123;
var mockRepo = new Mock<IBrainstormSessionRepository>();
mockRepo.Setup(repo => repo.GetByIdAsync(testSessionId))
.ReturnsAsync(GetTestSession());
var controller = new IdeasController(mockRepo.Object);

// Act
var result = await controller.ForSessionActionResult(testSessionId);

// Assert
var actionResult = Assert.IsType<ActionResult<List<IdeaDTO>>>(result);
var returnValue = Assert.IsType<List<IdeaDTO>>(actionResult.Value);
var idea = returnValue.FirstOrDefault();
Assert.Equal("One", idea.Name);
}

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")]
[ProducesResponseType(201)]
[ProducesResponseType(400)]
[ProducesResponseType(404)]
public async Task<ActionResult<BrainstormSession>> CreateActionResult([FromBody]NewIdeaModel model)
{
if (!ModelState.IsValid)
{
return BadRequest(ModelState);
}

var session = await _sessionRepository.GetByIdAsync(model.SessionId);

if (session == null)
{
return NotFound(model.SessionId);
}

var idea = new Idea()

{
DateCreated = DateTimeOffset.Now,
Description = model.Description,
Name = model.Name
};
session.AddIdea(idea);

await _sessionRepository.UpdateAsync(session);

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
var mockRepo = new Mock<IBrainstormSessionRepository>();
var controller = new IdeasController(mockRepo.Object);
controller.ModelState.AddModelError("error", "some error");

// 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
var nonExistentSessionId = 999;
string testName = "test name";
string testDescription = "test description";
var mockRepo = new Mock<IBrainstormSessionRepository>();
var controller = new IdeasController(mockRepo.Object);

var newIdea = new NewIdeaModel()

{
Description = testDescription,
Name = testName,
SessionId = nonExistentSessionId
};

// Act
var result = await controller.CreateActionResult(newIdea);

// Assert
var actionResult = Assert.IsType<ActionResult<BrainstormSession>>(result);
Assert.IsType<NotFoundObjectResult>(actionResult.Result);
}

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
int testSessionId = 123;
string testName = "test name";
string testDescription = "test description";
var testSession = GetTestSession();
var mockRepo = new Mock<IBrainstormSessionRepository>();
mockRepo.Setup(repo => repo.GetByIdAsync(testSessionId))
.ReturnsAsync(testSession);
var controller = new IdeasController(mockRepo.Object);

var newIdea = new NewIdeaModel()

{
Description = testDescription,
Name = testName,
SessionId = testSessionId
};
mockRepo.Setup(repo => repo.UpdateAsync(testSession))
.Returns(Task.CompletedTask)
.Verifiable();

// Act
var result = await controller.CreateActionResult(newIdea);

// Assert
var actionResult = Assert.IsType<ActionResult<BrainstormSession>>(result);
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);
}

Additional resources
Integration tests in ASP.NET Core
Create and run unit tests with Visual Studio.
 Introduction to Blazor
8/13/2019 • 4 minutes to read • Edit Online

By Daniel Roth and Luke Latham

Welcome to Blazor!
Blazor is a framework for building interactive client-side web UI with .NET:
Create rich interactive UIs using C# instead of JavaScript.
Share server-side and client-side app logic written in .NET.
Render the UI as HTML and CSS for wide browser support, including mobile browsers.
Using .NET for client-side web development offers the following advantages:
Write code in C# instead of JavaScript.
Leverage the existing .NET ecosystem of .NET libraries.
Share app logic across server and client.
Benefit from .NET's performance, reliability, and security.
Stay productive with Visual Studio on Windows, Linux, and macOS.
Build on a common set of languages, frameworks, and tools that are stable, feature-rich, and easy to use.

Components
Blazor apps are based on components. A component in Blazor is an element of UI, such as a page, dialog, or data
entry form.
Components are .NET classes built into .NET assemblies that:
Define flexible UI rendering logic.
Handle user events.
Can be nested and reused.
Can be shared and distributed as Razor class libraries or NuGet packages.
The component class is usually written in the form of a Razor markup page with a .razor file extension.
Components in Blazor are formally referred to as Razor components. Razor is a syntax for combining HTML
markup with C# code designed for developer productivity. Razor allows you to switch between HTML markup
and C# in the same file with IntelliSense support. Razor Pages and MVC also use Razor. Unlike Razor Pages and
MVC, which are built around a request/response model, components are used specifically for client-side UI logic
and composition.
The following Razor markup demonstrates a component (Dialog.razor), which can be nested within another
component:
 <div>
<h1>@Title</h1>

@ChildContent

<button @onclick="OnYes">Yes!</button>
</div>

@code {
[Parameter]
public string Title { get; set; }

[Parameter]
public RenderFragment ChildContent { get; set; }

private void OnYes()

{
Console.WriteLine("Write to the console in C#! 'Yes' button was selected.");
}
}

The dialog's body content ( ChildContent ) and title ( Title ) are provided by the component that uses this
component in its UI. OnYes is a C# method triggered by the button's onclick event.
Blazor uses natural HTML tags for UI composition. HTML elements specify components, and a tag's attributes
pass values to a component's properties.
In the following example, the Index component uses the Dialog component. ChildContent and Title are set
by the attributes and content of the <Dialog> element.
Index.razor:

@page "/"

<h1>Hello, world!</h1>

Welcome to your new app.

<Dialog Title="Blazor">
Do you want to <i>learn more</i> about Blazor?
</Dialog>

The dialog is rendered when the parent (Index.razor) is accessed in a browser:

When this component is used in the app, IntelliSense in Visual Studio and Visual Studio Code speeds
development with syntax and parameter completion.
Components render into an in-memory representation of the browser's Document Object Model (DOM ) called a
render tree, which is used to update the UI in a flexible and efficient way.

Blazor client-side
Blazor client-side is a single-page app framework for building interactive client-side web apps with .NET. Blazor
client-side uses open web standards without plugins or code transpilation and works in all modern web browsers,
including mobile browsers.
Running .NET code inside web browsers is made possible by WebAssembly (abbreviated wasm). WebAssembly
is a compact bytecode format optimized for fast download and maximum execution speed. WebAssembly is an
open web standard and supported in web browsers without plugins.
WebAssembly code can access the full functionality of the browser via JavaScript, called JavaScript
interoperability (or JavaScript interop). .NET code executed via WebAssembly in the browser runs in the
browser's JavaScript sandbox with the protections that the sandbox provides against malicious actions on the
client machine.

When a Blazor client-side app is built and run in a browser:

C# code files and Razor files are compiled into .NET assemblies.
The assemblies and the .NET runtime are downloaded to the browser.
Blazor client-side bootstraps the .NET runtime and configures the runtime to load the assemblies for the app.
The Blazor client-side runtime uses JavaScript interop to handle DOM manipulation and browser API calls.
The size of the published app, its payload size, is a critical performance factor for an app's useability. A large app
takes a relatively long time to download to a browser, which diminishes the user experience. Blazor client-side
optimizes payload size to reduce download times:
Unused code is stripped out of the app when it's published by the Intermediate Language (IL ) Linker.
HTTP responses are compressed.
The .NET runtime and assemblies are cached in the browser.

Blazor server-side
Blazor decouples component rendering logic from how UI updates are applied. Blazor server-side provides
support for hosting Razor components on the server in an ASP.NET Core app. UI updates are handled over a
SignalR connection.
The runtime handles sending UI events from the browser to the server and applies UI updates sent by the server
back to the browser after running the components.
The connection used by Blazor server-side to communicate with the browser is also used to handle JavaScript
interop calls.

JavaScript interop
For apps that require third-party JavaScript libraries and access to browser APIs, components interoperate with
JavaScript. Components are capable of using any library or API that JavaScript is able to use. C# code can call
into JavaScript code, and JavaScript code can call into C# code. For more information, see ASP.NET Core Blazor
JavaScript interop.

Code sharing and .NET Standard

Blazor implements .NET Standard 2.0. .NET Standard is a formal specification of .NET APIs that are common
across .NET implementations. .NET Standard class libraries can be shared across different .NET platforms, such
as Blazor, .NET Framework, .NET Core, Xamarin, Mono, and Unity.
APIs that aren't applicable inside of a web browser (for example, accessing the file system, opening a socket, and
threading) throw a PlatformNotSupportedException.

Additional resources
WebAssembly
ASP.NET Core Blazor hosting models
C# Guide
Razor syntax reference for ASP.NET Core
HTML
 ASP.NET Core Blazor supported platforms
7/12/2019 • 2 minutes to read • Edit Online

By Luke Latham

Browser requirements
Blazor client-side
BROWSER VERSION

Microsoft Edge Current

Mozilla Firefox Current

Google Chrome, including Android Current

Safari, including iOS Current

Microsoft Internet Explorer Not Supported†

†Microsoft Internet Explorer doesn't support WebAssembly.

Blazor server-side
BROWSER VERSION

Microsoft Edge Current

Mozilla Firefox Current

Google Chrome, including Android Current

Safari, including iOS Current

Microsoft Internet Explorer 11†

†Additional polyfills are required (for example, promises can be added via a Polyfill.io bundle).

Additional resources
ASP.NET Core Blazor hosting models
 Get started with ASP.NET Core Blazor
8/13/2019 • 4 minutes to read • Edit Online

By Daniel Roth and Luke Latham

Get started with Blazor:
1. Install the latest .NET Core 3.0 Preview SDK release.
2. Install the Blazor templates by running the following command in a command shell:

dotnet new -i Microsoft.AspNetCore.Blazor.Templates::3.0.0-preview8.19405.7

3. Follow the guidance for your choice of tooling:

Visual Studio
Visual Studio Code
.NET Core CLI
1. Install the latest Visual Studio preview with the ASP.NET and web development workload.
2. Create a new project.
3. Select Blazor App. Select Next.
4. Provide a project name in the Project name field or accept the default project name. Confirm the
Location entry is correct or provide a location for the project. Select Create.
5. For a Blazor client-side experience, choose the Blazor WebAssembly App template. For a Blazor
server-side experience, choose the Blazor Server App template. Select Create. For information on the
two Blazor hosting models, server-side and client-side, see ASP.NET Core Blazor hosting models.
6. Press F5 to run the app.

NOTE
If you installed the Blazor Visual Studio extension for a prior preview release of ASP.NET Core Blazor (Preview 6 or
earlier), you can uninstall the extension. Installing the Blazor templates in a command shell is now sufficient to
surface the templates in Visual Studio.

Multiple pages are available from tabs in the sidebar:

Home
Counter
Fetch data
On the Counter page, select the Click me button to increment the counter without a page refresh. Incrementing a
counter in a webpage normally requires writing JavaScript, but Razor components provide a better approach
using C#.
Pages/Counter.razor:
 @page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
private int currentCount = 0;

private void IncrementCount()

{
currentCount++;
}
}

A request for /counter in the browser, as specified by the @page directive at the top, causes the Counter
component to render its content. Components render into an in-memory representation of the render tree that
can then be used to update the UI in a flexible and efficient way.
Each time the Click me button is selected:
The onclick event is fired.
The IncrementCount method is called.
The currentCount is incremented.
The component is rendered again.
The runtime compares the new content to the previous content and only applies the changed content to the
Document Object Model (DOM ).
Add a component to another component using HTML syntax. For example, add the Counter component to the
app's homepage by adding a <Counter /> element to the Index component.
Pages/Index.razor:

@page "/"

<h1>Hello, world!</h1>

Welcome to your new app.

<Counter />

Run the app. The homepage has its own counter provided by the Counter component.
Component parameters are specified using attributes or child content, which allow you to set properties on the
child component. To add a parameter to the Counter component, update the component's @code block:
Add a public property for IncrementAmount with a [Parameter] attribute.
Change the IncrementCount method to use the IncrementAmount when increasing the value of currentCount .
Pages/Counter.razor:
 @page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
private int currentCount = 0;

[Parameter]
public int IncrementAmount { get; set; } = 1;

private void IncrementCount()

{
currentCount += IncrementAmount;
}
}

Specify the IncrementAmount in the Index component's <Counter> element using an attribute.
Pages/Index.razor:

@page "/"

<h1>Hello, world!</h1>

Welcome to your new app.

<Counter IncrementAmount="10" />

Run the app. The Index component has its own counter that increments by ten each time the Click me button is
selected. The Counter component (Counter.razor) at /counter continues to increment by one.

Next steps
Build your first Blazor app

Additional resources
Introduction to ASP.NET Core SignalR
 ASP.NET Core Blazor hosting models
8/13/2019 • 7 minutes to read • Edit Online

By Daniel Roth
Blazor is a web framework designed to run client-side in the browser on a WebAssembly-based .NET runtime
(Blazor client-side) or server-side in ASP.NET Core (Blazor server-side). Regardless of the hosting model, the app
and component models are the same.
To create a project for the hosting models described in this article, see Get started with ASP.NET Core Blazor.

Client-side
The principal hosting model for Blazor is running client-side in the browser on WebAssembly. The Blazor app, its
dependencies, and the .NET runtime are downloaded to the browser. The app is executed directly on the browser
UI thread. UI updates and event handling occur within the same process. The app's assets are deployed as static
files to a web server or service capable of serving static content to clients.

To create a Blazor app using the client-side hosting model, use the Blazor WebAssembly App template (dotnet
new blazorwasm).
After selecting the Blazor WebAssembly App template, you have the option of configuring the app to use an
ASP.NET Core backend by selecting the ASP.NET Core hosted check box (dotnet new blazorwasm --hosted ).
The ASP.NET Core app serves the Blazor app to clients. The Blazor client-side app can interact with the server
over the network using web API calls or SignalR.
The templates include the blazor.webassembly.js script that handles:
Downloading the .NET runtime, the app, and the app's dependencies.
Initialization of the runtime to run the app.
The client-side hosting model offers several benefits:
There's no .NET server-side dependency. The app is fully functioning after downloaded to the client.
Client resources and capabilities are fully leveraged.
Work is offloaded from the server to the client.
An ASP.NET Core web server isn't required to host the app. Serverless deployment scenarios are possible (for
 example, serving the app from a CDN ).
There are downsides to client-side hosting:
The app is restricted to the capabilities of the browser.
Capable client hardware and software (for example, WebAssembly support) is required.
Download size is larger, and apps take longer to load.
.NET runtime and tooling support is less mature. For example, limitations exist in .NET Standard support and
debugging.

Server-side
With the server-side hosting model, the app is executed on the server from within an ASP.NET Core app. UI
updates, event handling, and JavaScript calls are handled over a SignalR connection.

To create a Blazor app using the server-side hosting model, use the ASP.NET Core Blazor Server App template
(dotnet new blazorserver). The ASP.NET Core app hosts the server-side app and creates the SignalR endpoint
where clients connect.
The ASP.NET Core app references the app's Startup class to add:
Server-side services.
The app to the request handling pipeline.
The blazor.server.js script† establishes the client connection. It's the app's responsibility to persist and restore app
state as required (for example, in the event of a lost network connection).
The server-side hosting model offers several benefits:
Download size is significantly smaller than a client-side app, and the app loads much faster.
The app takes full advantage of server capabilities, including use of any .NET Core compatible APIs.
.NET Core on the server is used to run the app, so existing .NET tooling, such as debugging, works as
expected.
Thin clients are supported. For example, server-side apps work with browsers that don't support
WebAssembly and on resource-constrained devices.
The app's .NET/C# code base, including the app's component code, isn't served to clients.
There are downsides to server-side hosting:
Higher latency usually exists. Every user interaction involves a network hop.
There's no offline support. If the client connection fails, the app stops working.
 Scalability is challenging for apps with many users. The server must manage multiple client connections and
handle client state.
An ASP.NET Core server is required to serve the app. Serverless deployment scenarios aren't possible (for
example, serving the app from a CDN ).
†The blazor.server.js script is served from an embedded resource in the ASP.NET Core shared framework.
Reconnection to the same server
Blazor server-side apps require an active SignalR connection to the server. If the connection is lost, the app
attempts to reconnect to the server. As long as the client's state is still in memory, the client session resumes
without losing state.
When the client detects that the connection has been lost, a default UI is displayed to the user while the client
attempts to reconnect. If reconnection fails, the user is provided the option to retry. To customize the UI, define an
element with components-reconnect-modal as its id in the _Host.cshtml Razor page. The client updates this
element with one of the following CSS classes based on the state of the connection:
components-reconnect-show – Show the UI to indicate the connection was lost and the client is attempting to
reconnect.
components-reconnect-hide – The client has an active connection, hide the UI.
components-reconnect-failed – Reconnection failed. To attempt reconnection again, call
window.Blazor.reconnect() .

Stateful reconnection after prerendering

Blazor server-side apps are set up by default to prerender the UI on the server before the client connection to the
server is established. This is set up in the _Host.cshtml Razor page:

<body>
<app>@(await Html.RenderComponentAsync<App>())</app>

<script src="_framework/blazor.server.js"></script>
</body>

The client reconnects to the server with the same state that was used to prerender the app. If the app's state is still
in memory, the component state isn't rerendered after the SignalR connection is established.
Render stateful interactive components from Razor pages and views
Stateful interactive components can be added to a Razor page or view. When the page or view renders, the
component is prerendered with it. The app then reconnects to the component state once the client connection is
established as long as the state is still in memory.
For example, the following Razor page renders a Counter component with an initial count that's specified using a
form:
 <h1>My Razor Page</h1>

<form>
<input type="number" asp-for="InitialCount" />
<button type="submit">Set initial count</button>
</form>

@(await Html.RenderComponentAsync<Counter>(new { InitialCount = InitialCount }))

@code {
[BindProperty(SupportsGet=true)]
public int InitialCount { get; set; }
}

Detect when the app is prerendering

While a Blazor server-side app is prerendering, certain actions, such as calling into JavaScript, aren't possible
because a connection with the browser hasn't been established. Components may need to render differently
when prerendered.
To delay JavaScript interop calls until after the connection with the browser is established, you can use the
OnAfterRenderAsync component lifecycle event. This event is only called after the app is fully rendered and the
client connection is established.

@using Microsoft.JSInterop
@inject IJSRuntime JSRuntime

<input @ref="myInput" value="Value set during render" />

@code {
private ElementRef myInput;

protected override void OnAfterRender()

{
JSRuntime.InvokeAsync<object>(
"setElementValue", myInput, "Value set after render");
}
}

The following component demonstrates how to use JavaScript interop as part of a component's initialization logic
in a way that's compatible with prerendering. The component shows that it's possible to trigger a rendering
update from inside OnAfterRenderAsync . The developer must avoid creating an infinite loop in this scenario.
Where JSRuntime.InvokeAsync is called, ElementRef is only used in OnAfterRenderAsync and not in any earlier
lifecycle method because there's no JavaScript element until after the component is rendered.
StateHasChanged is called to rerender the component with the new state obtained from the JavaScript interop call.
The code doesn't create an infinite loop because StateHasChanged is only called when infoFromJs is null .
 @page "/prerendered-interop"
@using Microsoft.AspNetCore.Components
@using Microsoft.JSInterop
@inject IComponentContext ComponentContext
@inject IJSRuntime JSRuntime

<p>
Get value via JS interop call:
<strong id="val-get-by-interop">@(infoFromJs ?? "No value yet")</strong>
</p>

<p>
Set value via JS interop call:
<input id="val-set-by-interop" @ref="myElem" />
</p>

@code {
private string infoFromJs;
private ElementRef myElem;

protected override async Task OnAfterRenderAsync()

{
// TEMPORARY: Currently we need this guard to avoid making the interop
// call during prerendering. Soon this will be unnecessary because we
// will change OnAfterRenderAsync so that it won't run during the
// prerendering phase.
if (!ComponentContext.IsConnected)
{
return;
}

if (infoFromJs == null)
{
infoFromJs = await JSRuntime.InvokeAsync<string>(
"setElementValue", myElem, "Hello from interop call");

StateHasChanged();
}
}
}

To conditionally render different content based on whether the app is currently prerendering content, use the
IsConnected property on the IComponentContext service. When running server -side, IsConnected only returns
true if there's an active connection to the client. It always returns true when running client-side.
 @page "/isconnected-example"
@using Microsoft.AspNetCore.Components.Services
@inject IComponentContext ComponentContext

<h1>IsConnected Example</h1>

<p>
Current state:
<strong id="connected-state">
@(ComponentContext.IsConnected ? "connected" : "not connected")
</strong>
</p>

<p>
Clicks:
<strong id="count">@count</strong>
<button id="increment-count" @onclick="@(() => count++)">Click me</button>
</p>

@code {
private int count;
}

Configure the SignalR client for Blazor server-side apps

Sometimes, you need to configure the SignalR client used by Blazor server-side apps. For example, you might
want to configure logging on the SignalR client to diagnose a connection issue.
To configure the SignalR client in the Pages/_Host.cshtml file:
Add an autostart="false" attribute to the <script> tag for the blazor.server.js script.
Call Blazor.start and pass in a configuration object that specifies the SignalR builder.

<script src="_framework/blazor.server.js" autostart="false"></script>

<script>
Blazor.start({
configureSignalR: function (builder) {
builder.configureLogging(2); // LogLevel.Information
}
});
</script>

Additional resources
Get started with ASP.NET Core Blazor
Introduction to ASP.NET Core SignalR
 Build your first Blazor app
8/13/2019 • 8 minutes to read • Edit Online

By Daniel Roth and Luke Latham

This tutorial shows you how to build and modify a Blazor app.
Follow the guidance in the Get started with ASP.NET Core Blazor article to create a Blazor project for this tutorial.
Name the project ToDoList.

Build components
1. Browse to each of the app's three pages in the Pages folder: Home, Counter, and Fetch data. These pages
are implemented by the Razor component files Index.razor, Counter.razor, and FetchData.razor.
2. On the Counter page, select the Click me button to increment the counter without a page refresh.
Incrementing a counter in a webpage normally requires writing JavaScript, but Blazor provides a better
approach using C#.
3. Examine the implementation of the Counter component in the Counter.razor file.
Pages/Counter.razor:

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
private int currentCount = 0;

private void IncrementCount()

{
currentCount++;
}
}

The UI of the Counter component is defined using HTML. Dynamic rendering logic (for example, loops,
conditionals, expressions) is added using an embedded C# syntax called Razor. The HTML markup and C#
rendering logic are converted into a component class at build time. The name of the generated .NET class
matches the file name.
Members of the component class are defined in an @code block. In the @code block, component state
(properties, fields) and methods are specified for event handling or for defining other component logic.
These members are then used as part of the component's rendering logic and for handling events.
When the Click me button is selected:
The Counter component's registered onclick handler is called (the IncrementCount method).
The Counter component regenerates its render tree.
The new render tree is compared to the previous one.
Only modifications to the Document Object Model (DOM ) are applied. The displayed count is updated.
4. Modify the C# logic of the Counter component to make the count increment by two instead of one.

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
private int currentCount = 0;

private void IncrementCount()

{
currentCount += 2;
}
}

5. Rebuild and run the app to see the changes. Select the Click me button. The counter increments by two.

Use components
Include a component in another component using an HTML syntax.
1. Add the Counter component to the app's Index component by adding a <Counter /> element to the
Index component ( Index.razor).

If you're using Blazor client-side for this experience, a SurveyPrompt component is used by the Index
component. Replace the <SurveyPrompt> element with a <Counter /> element. If you're using a Blazor
server-side app for this experience, add the <Counter /> element to the Index component:
Pages/Index.razor:

@page "/"

<h1>Hello, world!</h1>

Welcome to your new app.

<Counter />

2. Rebuild and run the app. The Index component has its own counter.

Component parameters
Components can also have parameters. Component parameters are defined using public properties on the
component class decorated with [Parameter] . Use attributes to specify arguments for a component in markup.
1. Update the component's @code C# code:
Add a IncrementAmount property decorated with the [Parameter] attribute.
Change the IncrementCount method to use the IncrementAmount when increasing the value of
currentCount .
Pages/Counter.razor:
 @page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
private int currentCount = 0;

[Parameter]
public int IncrementAmount { get; set; } = 1;

private void IncrementCount()

{
currentCount += IncrementAmount;
}
}

1. Specify an IncrementAmount parameter in the Index component's <Counter> element using an attribute.
Set the value to increment the counter by ten.
Pages/Index.razor:

@page "/"

<h1>Hello, world!</h1>

Welcome to your new app.

<Counter IncrementAmount="10" />

2. Reload the Index component. The counter increments by ten each time the Click me button is selected.
The counter in the Counter component continues to increment by one.

Route to components
The @page directive at the top of the Counter.razor file specifies that the Counter component is a routing
endpoint. The Counter component handles requests sent to /counter . Without the @page directive, a component
doesn't handle routed requests, but the component can still be used by other components.

Dependency injection
Services registered in the app's service container are available to components via dependency injection (DI). Inject
services into a component using the @inject directive.
Examine the directives of the FetchData component.
If working with a Blazor server-side app, the WeatherForecastService service is registered as a singleton, so one
instance of the service is available throughout the app. The @inject directive is used to inject the instance of the
WeatherForecastService service into the component.

Pages/FetchData.razor:

@page "/fetchdata"
@using ToDoList.App.Services
@inject WeatherForecastService ForecastService
The FetchData component uses the injected service, as ForecastService , to retrieve an array of WeatherForecast
objects:

@code {
private WeatherForecast[] forecasts;

protected override async Task OnInitAsync()

{
forecasts = await ForecastService.GetForecastAsync(DateTime.Now);
}
}

If working with a Blazor client-side app, HttpClient is injected to obtain weather forecast data from the
weather.json file in the wwwroot/sample-data folder:
Pages/FetchData.razor:

@inject HttpClient Http

...

protected override async Task OnInitAsync()

{
forecasts =
await Http.GetJsonAsync<WeatherForecast[]>("sample-data/weather.json");
}

A @foreach loop is used to render each forecast instance as a row in the table of weather data:

<table class="table">
<thead>
<tr>
<th>Date</th>
<th>Temp. (C)</th>
<th>Temp. (F)</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
@foreach (var forecast in forecasts)
{
<tr>
<td>@forecast.Date.ToShortDateString()</td>
<td>@forecast.TemperatureC</td>
<td>@forecast.TemperatureF</td>
<td>@forecast.Summary</td>
</tr>
}
</tbody>
</table>

Build a todo list

Add a new component to the app that implements a simple todo list.
1. Add an empty file named Todo.razor to the app in the Pages folder:
2. Provide the initial markup for the component:
 @page "/todo"

<h1>Todo</h1>

3. Add the Todo component to the navigation bar.

The NavMenu component (Shared/NavMenu.razor) is used in the app's layout. Layouts are components that
allow you to avoid duplication of content in the app.
Add a <NavLink> element for the Todo component by adding the following list item markup below the
existing list items in the Shared/NavMenu.razor file:

<li class="nav-item px-3">

<NavLink class="nav-link" href="todo">
<span class="oi oi-list-rich" aria-hidden="true"></span> Todo
</NavLink>
</li>

4. Rebuild and run the app. Visit the new Todo page to confirm that the link to the Todo component works.
5. Add a TodoItem.cs file to the root of the project to hold a class that represents a todo item. Use the
following C# code for the TodoItem class:

public class TodoItem

{
public string Title { get; set; }
public bool IsDone { get; set; }
}

6. Return to the Todo component (Pages/Todo.razor):

Add a field for the todo items in an @code block. The Todo component uses this field to maintain the
state of the todo list.
Add unordered list markup and a foreach loop to render each todo item as a list item ( <li> ).

@page "/todo"

<h1>Todo</h1>

<ul>
@foreach (var todo in todos)
{
<li>@todo.Title</li>
}
</ul>

@code {
private IList<TodoItem> todos = new List<TodoItem>();
}

7. The app requires UI elements for adding todo items to the list. Add a text input ( <input> ) and a button (
<button> ) below the unordered list ( <ul>...</ul> ):
 @page "/todo"

<h1>Todo</h1>

<ul>
@foreach (var todo in todos)
{
<li>@todo.Title</li>
}
</ul>

<input placeholder="Something todo" />

<button>Add todo</button>

@code {
private IList<TodoItem> todos = new List<TodoItem>();
}

8. Rebuild and run the app. When the Add todo button is selected, nothing happens because an event
handler isn't wired up to the button.
9. Add an AddTodo method to the Todo component and register it for button selections using the @onclick
attribute. The AddTodo C# method is called when the button is selected:

<input placeholder="Something todo" />

<button @onclick="AddTodo">Add todo</button>

@code {
private IList<TodoItem> todos = new List<TodoItem>();

private void AddTodo()

{
// Todo: Add the todo
}
}

10. To get the title of the new todo item, add a newTodo string field at the top of the @code block and bind it to
the value of the text input using the bind attribute in the <input> element:

private IList<TodoItem> todos = new List<TodoItem>();

private string newTodo;

<input placeholder="Something todo" @bind="@newTodo" />

11. Update the AddTodo method to add the TodoItem with the specified title to the list. Clear the value of the
text input by setting newTodo to an empty string:
 @page "/todo"

<h1>Todo</h1>

<ul>
@foreach (var todo in todos)
{
<li>@todo.Title</li>
}
</ul>

<input placeholder="Something todo" @bind="@newTodo" />

<button @onclick="AddTodo">Add todo</button>

@code {
private IList<TodoItem> todos = new List<TodoItem>();
private string newTodo;

private void AddTodo()

{
if (!string.IsNullOrWhiteSpace(newTodo))
{
todos.Add(new TodoItem { Title = newTodo });
newTodo = string.Empty;
}
}
}

12. Rebuild and run the app. Add some todo items to the todo list to test the new code.
13. The title text for each todo item can be made editable, and a check box can help the user keep track of
completed items. Add a check box input for each todo item and bind its value to the IsDone property.
Change @todo.Title to an <input> element bound to @todo.Title :

<ul>
@foreach (var todo in todos)
{
<li>
<input type="checkbox" @bind="@todo.IsDone" />
<input @bind="@todo.Title" />
</li>
}
</ul>

14. To verify that these values are bound, update the <h1> header to show a count of the number of todo items
that aren't complete ( IsDone is false ).

<h1>Todo (@todos.Count(todo => !todo.IsDone))</h1>

15. The completed Todo component (Pages/Todo.razor):

 @page "/todo"

<h1>Todo (@todos.Count(todo => !todo.IsDone))</h1>

<ul>
@foreach (var todo in todos)
{
<li>
<input type="checkbox" @bind="@todo.IsDone" />
<input @bind="@todo.Title" />
</li>
}
</ul>

<input placeholder="Something todo" @bind="@newTodo" />

<button @onclick="AddTodo">Add todo</button>

@code {
private IList<TodoItem> todos = new List<TodoItem>();
private string newTodo;

private void AddTodo()

{
if (!string.IsNullOrWhiteSpace(newTodo))
{
todos.Add(new TodoItem { Title = newTodo });
newTodo = string.Empty;
}
}
}

16. Rebuild and run the app. Add todo items to test the new code.
Create and use ASP.NET Core Razor components
 Create and use ASP.NET Core Razor components
8/13/2019 • 39 minutes to read • Edit Online

By Luke Latham and Daniel Roth

View or download sample code (how to download)
Blazor apps are built using components. A component is a self-contained chunk of user interface (UI), such as a
page, dialog, or form. A component includes HTML markup and the processing logic required to inject data or
respond to UI events. Components are flexible and lightweight. They can be nested, reused, and shared among
projects.

Component classes
Components are implemented in Razor component files (.razor) using a combination of C# and HTML markup. A
component in Blazor is formally referred to as a Razor component.
A component's name must start with an uppercase character. For example, MyCoolComponent.razor is valid, and
myCoolComponent.razor is invalid.
Components can be authored using the .cshtml file extension as long as the files are identified as Razor
component files using the _RazorComponentInclude MSBuild property. For example, an app that specifies that all
.cshtml files under the Pages folder should be treated as Razor components files:

<PropertyGroup>
<_RazorComponentInclude>Pages\**\*.cshtml</_RazorComponentInclude>
</PropertyGroup>

The UI for a component is defined using HTML. Dynamic rendering logic (for example, loops, conditionals,
expressions) is added using an embedded C# syntax called Razor. When an app is compiled, the HTML markup
and C# rendering logic are converted into a component class. The name of the generated class matches the name
of the file.
Members of the component class are defined in an @code block. In the @code block, component state
(properties, fields) is specified with methods for event handling or for defining other component logic. More than
one @code block is permissible.

NOTE
In prior previews of ASP.NET Core 3.0, @functions blocks were used for the same purpose as @code blocks in Razor
components. @functions blocks continue to function in Razor components, but we recommend using the @code block in
ASP.NET Core 3.0 Preview 6 or later.

Component members can be used as part of the component's rendering logic using C# expressions that start with
@ . For example, a C# field is rendered by prefixing @ to the field name. The following example evaluates and
renders:
_headingFontStyle to the CSS property value for font-style .
_headingText to the content of the <h1> element.
 <h1 style="font-style:@_headingFontStyle">@_headingText</h1>

@code {
private string _headingFontStyle = "italic";
private string _headingText = "Put on your new Blazor!";
}

After the component is initially rendered, the component regenerates its render tree in response to events. Blazor
then compares the new render tree against the previous one and applies any modifications to the browser's
Document Object Model (DOM ).
Components are ordinary C# classes and can be placed anywhere within a project. Components that produce
webpages usually reside in the Pages folder. Non-page components are frequently placed in the Shared folder or
a custom folder added to the project. To use a custom folder, add the custom folder's namespace to either the
parent component or to the app's _Imports.razor file. For example, the following namespace makes components
in a Components folder available when the app's root namespace is WebApplication :

@using WebApplication.Components

Integrate components into Razor Pages and MVC apps

Use components with existing Razor Pages and MVC apps. There's no need to rewrite existing pages or views to
use Razor components. When the page or view is rendered, components are prerendered at the same time.
To render a component from a page or view, use the RenderComponentAsync<TComponent> HTML helper method:

<div id="Counter">
@(await Html.RenderComponentAsync<Counter>(new { IncrementAmount = 10 }))
</div>

While pages and views can use components, the converse isn't true. Components can't use view - and page-
specific scenarios, such as partial views and sections. To use logic from partial view in a component, factor out the
partial view logic into a component.
For more information on how components are rendered and component state is managed in Blazor server-side
apps, see the ASP.NET Core Blazor hosting models article.

Use components
Components can include other components by declaring them using HTML element syntax. The markup for using
a component looks like an HTML tag where the name of the tag is the component type.
Attribute binding is case sensitive. For example, @bind is valid, and @Bind is invalid.
The following markup in Index.razor renders a HeadingComponent instance:

<HeadingComponent />

Components/HeadingComponent.razor:
 @using System.Globalization
@*
The 'using' directive makes System.Globalization available to
the component. System.Globalization provides a method for
converting a string into title case (capitalizes the first
letter of every word in a string), which is used to convert a
a string into title case for a heading.
*@

@*
Heading text is rendered by evaluating the _headingText field.
The font-style of the heading is rendered by evaluating the
_headingFontStyle field.
*@
<h1 style="font-style:@_headingFontStyle">@_headingText</h1>

<form>
<div>
@*
A check box sets the font style and is bound to the
_italicsCheck field.
*@
<input type="checkbox" id="italicsCheck"
@bind="_italicsCheck" />
<label class="form-check-label"
for="italicsCheck">Use italics</label>
</div>

@*
When the form is submitted, the onclick event executes
the UpdateHeading method.
*@
<button type="button" class="btn btn-primary" @onclick="UpdateHeading">
Update heading
</button>
</form>

@code {
private static TextInfo _tinfo = CultureInfo.CurrentCulture.TextInfo;
private string _headingText =
_tinfo.ToTitleCase("welcome to blazor!");
private string _headingFontStyle = "normal";
private bool _italicsCheck = false;

// When UpdateHeading is executed, _italicsCheck determines

// the value of _headingFontStyle to set the font style of the
// heading.
public void UpdateHeading()
{
_headingFontStyle = _italicsCheck ? "italic" : "normal";
}
}

If a component contains an HTML element with an uppercase first letter that doesn't match a component name, a
warning is emitted indicating that the element has an unexpected name. Adding an @using statement for the
component's namespace makes the component available, which removes the warning.

Component parameters
Components can have component parameters, which are defined using public properties on the component class
with the [Parameter] attribute. Use attributes to specify arguments for a component in markup.
Components/ChildComponent.razor:
 <div class="panel panel-default">
<div class="panel-heading">@Title</div>
<div class="panel-body">@ChildContent</div>

<button class="btn btn-primary" @onclick="OnClick">

Trigger a Parent component method
</button>
</div>

@code {
[Parameter]
public string Title { get; set; }

[Parameter]
public RenderFragment ChildContent { get; set; }

[Parameter]
public EventCallback<UIMouseEventArgs> OnClick { get; set; }
}

In the following example, the ParentComponent sets the value of the Title property of the ChildComponent .
Pages/ParentComponent.razor:

@page "/ParentComponent"

<h1>Parent-child example</h1>

<ChildComponent Title="Panel Title from Parent"

OnClick="@ShowMessage">
Content of the child component is supplied
by the parent component.
</ChildComponent>

<p><b>@messageText</b></p>

@code {
private string messageText;

private void ShowMessage(UIMouseEventArgs e)

{
messageText = "Blaze a new trail with Blazor!";
}
}

Child content
Components can set the content of another component. The assigning component provides the content between
the tags that specify the receiving component.
In the following example, the ChildComponent has a ChildContent property that represents a RenderFragment ,
which represents a segment of UI to render. The value of ChildContent is positioned in the component's markup
where the content should be rendered. The value of ChildContent is received from the parent component and
rendered inside the Bootstrap panel's panel-body .
Components/ChildComponent.razor:
 <div class="panel panel-default">
<div class="panel-heading">@Title</div>
<div class="panel-body">@ChildContent</div>

<button class="btn btn-primary" @onclick="OnClick">

Trigger a Parent component method
</button>
</div>

@code {
[Parameter]
public string Title { get; set; }

[Parameter]
public RenderFragment ChildContent { get; set; }

[Parameter]
public EventCallback<UIMouseEventArgs> OnClick { get; set; }
}

NOTE
The property receiving the RenderFragment content must be named ChildContent by convention.

The following ParentComponent can provide content for rendering the ChildComponent by placing the content
inside the <ChildComponent> tags.
Pages/ParentComponent.razor:

@page "/ParentComponent"

<h1>Parent-child example</h1>

<ChildComponent Title="Panel Title from Parent"

OnClick="@ShowMessage">
Content of the child component is supplied
by the parent component.
</ChildComponent>

<p><b>@messageText</b></p>

@code {
private string messageText;

private void ShowMessage(UIMouseEventArgs e)

{
messageText = "Blaze a new trail with Blazor!";
}
}

Attribute splatting and arbitrary parameters

Components can capture and render additional attributes in addition to the component's declared parameters.
Additional attributes can be captured in a dictionary and then splatted onto an element when the component is
rendered using the @attributes Razor directive. This scenario is useful when defining a component that produces
a markup element that supports a variety of customizations. For example, it can be tedious to define attributes
separately for an <input> that supports many parameters.
In the following example, the first <input> element ( id="useIndividualParams" ) uses individual component
parameters, while the second <input> element ( id="useAttributesDict" ) uses attribute splatting:

<input id="useIndividualParams"
maxlength="@Maxlength"
placeholder="@Placeholder"
required="@Required"
size="@Size" />

<input id="useAttributesDict"
@attributes="InputAttributes" />

@code {
[Parameter]
public string Maxlength { get; set; } = "10";

[Parameter]
public string Placeholder { get; set; } = "Input placeholder text";

[Parameter]
public string Required { get; set; } = "required";

[Parameter]
public string Size { get; set; } = "50";

[Parameter]
public Dictionary<string, object> InputAttributes { get; set; } =
new Dictionary<string, object>()
{
{ "maxlength", "10" },
{ "placeholder", "Input placeholder text" },
{ "required", "true" },
{ "size", "50" }
};
}

The type of the parameter must implement IEnumerable<KeyValuePair<string, object>> with string keys. Using
IReadOnlyDictionary<string, object> is also an option in this scenario.

The rendered <input> elements using both approaches is identical:

<input id="useIndividualParams"
maxlength="10"
placeholder="Input placeholder text"
required="required"
size="50">

<input id="useAttributesDict"
maxlength="10"
placeholder="Input placeholder text"
required="true"
size="50">

To accept arbitrary attributes, define a component parameter using the [Parameter] attribute with the
CaptureUnmatchedValues property set to true :

@code {
[Parameter(CaptureUnmatchedAttributes = true)]
public Dictionary<string, object> InputAttributes { get; set; }
}
The CaptureUnmatchedValues property on [Parameter] allows the parameter to match all attributes that don't
match any other parameter. A component can only define a single parameter with CaptureUnmatchedValues . The
property type used with CaptureUnmatchedValues must be assignable from Dictionary<string, object> with string
keys. IEnumerable<KeyValuePair<string, object>> or IReadOnlyDictionary<string, object> are also options in this
scenario.

Data binding
Data binding to both components and DOM elements is accomplished with the @bind attribute. The following
example binds the _italicsCheck field to the check box's checked state:

<input type="checkbox" class="form-check-input" id="italicsCheck"

@bind="_italicsCheck" />

When the check box is selected and cleared, the property's value is updated to true and false , respectively.
The check box is updated in the UI only when the component is rendered, not in response to changing the
property's value. Since components render themselves after event handler code executes, property updates are
usually reflected in the UI immediately.
Using @bind with a CurrentValue property ( <input @bind="CurrentValue" /> ) is essentially equivalent to the
following:

<input value="@CurrentValue"
@onchange="@((UIChangeEventArgs __e) => CurrentValue = __e.Value)" />

When the component is rendered, the value of the input element comes from the CurrentValue property. When
the user types in the text box, the onchange event is fired and the CurrentValue property is set to the changed
value. In reality, the code generation is a little more complex because @bind handles a few cases where type
conversions are performed. In principle, @bind associates the current value of an expression with a value
attribute and handles changes using the registered handler.
In addition to handling onchange events with @bind syntax, a property or field can be bound using other events
by specifying an @bind-value attribute with an event parameter (@bind-value:event). The following example
binds the CurrentValue property for the oninput event:

<input @bind-value="CurrentValue" @bind-value:event="oninput" />

Unlike onchange , which fires when the element loses focus, oninput fires when the value of the text box changes.
Globalization
@bind values are formatted for display and parsed using the current culture's rules.
The current culture can be accessed from the System.Globalization.CultureInfo.CurrentCulture property.
CultureInfo.InvariantCulture is used for the following field types ( <input type="{TYPE}" /> ):
date
number

The preceding field types:

Are displayed using their appropriate browser-based formatting rules.
Can't contain free-form text.
 Provide user interaction characteristics based on the browser's implementation.
The following field types have specific formatting requirements and aren't currently supported by Blazor because
they aren't supported by all major browsers:
datetime-local
month
week

@bind supports the @bind:culture parameter to provide a System.Globalization.CultureInfo for parsing and
formatting a value. Specifying a culture isn't recommended when using the date and number field types. date
and number have built-in Blazor support that provides the required culture.
For information on how to set the user's culture, see the Localization section.
Format strings
Data binding works with DateTime format strings using @bind:format. Other format expressions, such as
currency or number formats, aren't available at this time.

<input @bind="StartDate" @bind:format="yyyy-MM-dd" />

@code {
[Parameter]
public DateTime StartDate { get; set; } = new DateTime(2020, 1, 1);
}

In the preceding code, the <input> element's field type ( type ) defaults to text . @bind:format is supported for
binding the following .NET types:
System.DateTime
System.DateTime?
System.DateTimeOffset
System.DateTimeOffset?
The @bind:format attribute specifies the date format to apply to the value of the <input> element. The format is
also used to parse the value when an onchange event occurs.
Specifying a format for the date field type isn't recommended because Blazor has built-in support to format
dates.
Component parameters
Binding recognizes component parameters, where @bind-{property} can bind a property value across
components.
The following child component ( ChildComponent ) has a Year component parameter and YearChanged callback:
 <h2>Child Component</h2>

<p>Year: @Year</p>

@code {
[Parameter]
public int Year { get; set; }

[Parameter]
public EventCallback<int> YearChanged { get; set; }
}

EventCallback<T> is explained in the EventCallback section.

The following parent component uses ChildComponent and binds the ParentYear parameter from the parent to
the Year parameter on the child component:

@page "/ParentComponent"

<h1>Parent Component</h1>

<p>ParentYear: @ParentYear</p>

<ChildComponent @bind-Year="ParentYear" />

<button class="btn btn-primary" @onclick="ChangeTheYear">

Change Year to 1986
</button>

@code {
[Parameter]
public int ParentYear { get; set; } = 1978;

private void ChangeTheYear()

{
ParentYear = 1986;
}
}

Loading the ParentComponent produces the following markup:

<h1>Parent Component</h1>

<p>ParentYear: 1978</p>

<h2>Child Component</h2>

<p>Year: 1978</p>

If the value of the ParentYear property is changed by selecting the button in the ParentComponent , the Year
property of the ChildComponent is updated. The new value of Year is rendered in the UI when the
ParentComponent is rerendered:

<h1>Parent Component</h1>

<p>ParentYear: 1986</p>

<h2>Child Component</h2>

<p>Year: 1986</p>
The Year parameter is bindable because it has a companion YearChanged event that matches the type of the
Year parameter.
By convention, <ChildComponent @bind-Year="ParentYear" /> is essentially equivalent to writing:

<ChildComponent @bind-Year="ParentYear" @bind-Year:event="YearChanged" />

In general, a property can be bound to a corresponding event handler using @bind-property:event attribute. For
example, the property MyProp can be bound to MyEventHandler using the following two attributes:

<MyComponent @bind-MyProp="MyValue" @bind-MyProp:event="MyEventHandler" />

Event handling
Razor components provide event handling features. For an HTML element attribute named on{event} (for
example, onclick and onsubmit ) with a delegate-typed value, Razor components treats the attribute's value as an
event handler. The attribute's name is always formatted @on{event}.
The following code calls the UpdateHeading method when the button is selected in the UI:

<button class="btn btn-primary" @onclick="UpdateHeading">

Update heading
</button>

@code {
private void UpdateHeading(UIMouseEventArgs e)
{
...
}
}

The following code calls the CheckChanged method when the check box is changed in the UI:

<input type="checkbox" class="form-check-input" @onchange="CheckChanged" />

@code {
private void CheckChanged()
{
...
}
}

Event handlers can also be asynchronous and return a Task. There's no need to manually call StateHasChanged() .
Exceptions are logged when they occur.
In the following example, UpdateHeading is called asynchronously when the button is selected:
 <button class="btn btn-primary" @onclick="UpdateHeading">
Update heading
</button>

@code {
private async Task UpdateHeading(UIMouseEventArgs e)
{
...
}
}

Event argument types

For some events, event argument types are permitted. If access to one of these event types isn't necessary, it isn't
required in the method call.
Supported UIEventArgs are shown in the following table.

EVENT CLASS

Clipboard UIClipboardEventArgs

Drag UIDragEventArgs – DataTransfer is used to hold the

dragged data during a drag and drop operation and may
hold one or more UIDataTransferItem .
UIDataTransferItem represents one drag data item.

Error UIErrorEventArgs

Focus UIFocusEventArgs – Doesn't include support for

relatedTarget .

<input> change UIChangeEventArgs

Keyboard UIKeyboardEventArgs

Mouse UIMouseEventArgs

Mouse pointer UIPointerEventArgs

Mouse wheel UIWheelEventArgs

Progress UIProgressEventArgs

Touch UITouchEventArgs – UITouchPoint represents a single

contact point on a touch-sensitive device.

For information on the properties and event handling behavior of the events in the preceding table, see EventArgs
classes in the reference source.
Lambda expressions
Lambda expressions can also be used:

<button @onclick="@(e => Console.WriteLine("Hello, world!"))">Say hello</button>

It's often convenient to close over additional values, such as when iterating over a set of elements. The following
example creates three buttons, each of which calls UpdateHeading passing an event argument ( UIMouseEventArgs )
and its button number ( buttonNumber ) when selected in the UI:

<h2>@message</h2>

@for (var i = 1; i < 4; i++)

{
var buttonNumber = i;

<button class="btn btn-primary"

@onclick="@(e => UpdateHeading(e, buttonNumber))">
Button #@i
</button>
}

@code {
private string message = "Select a button to learn its position.";

private void UpdateHeading(UIMouseEventArgs e, int buttonNumber)

{
message = $"You selected Button #{buttonNumber} at " +
$"mouse position: {e.ClientX} X {e.ClientY}.";
}
}

NOTE
Do not use the loop variable ( i ) in a for loop directly in a lambda expression. Otherwise the same variable is used by all
lambda expressions causing i 's value to be the same in all lambdas. Always capture its value in a local variable (
buttonNumber in the preceding example) and then use it.

EventCallback
A common scenario with nested components is the desire to run a parent component's method when a child
component event occurs—for example, when an onclick event occurs in the child. To expose events across
components, use an EventCallback . A parent component can assign a callback method to a child component's
EventCallback .

The ChildComponentin the sample app demonstrates how a button's onclick handler is set up to receive an
EventCallback delegate from the sample's ParentComponent . The EventCallback is typed with UIMouseEventArgs ,
which is appropriate for an onclick event from a peripheral device:
 <div class="panel panel-default">
<div class="panel-heading">@Title</div>
<div class="panel-body">@ChildContent</div>

<button class="btn btn-primary" @onclick="OnClick">

Trigger a Parent component method
</button>
</div>

@code {
[Parameter]
public string Title { get; set; }

[Parameter]
public RenderFragment ChildContent { get; set; }

[Parameter]
public EventCallback<UIMouseEventArgs> OnClick { get; set; }
}

The ParentComponent sets the child's EventCallback<T> to its ShowMessage method:

@page "/ParentComponent"

<h1>Parent-child example</h1>

<ChildComponent Title="Panel Title from Parent"

OnClick="@ShowMessage">
Content of the child component is supplied
by the parent component.
</ChildComponent>

<p><b>@messageText</b></p>

@code {
private string messageText;

private void ShowMessage(UIMouseEventArgs e)

{
messageText = "Blaze a new trail with Blazor!";
}
}

When the button is selected in the ChildComponent :

The ParentComponent 's ShowMessage method is called. messageText is updated and displayed in the
ParentComponent .
A call to StateHasChanged isn't required in the callback's method ( ShowMessage ). StateHasChanged is called
automatically to rerender the ParentComponent , just as child events trigger component rerendering in event
handlers that execute within the child.
EventCallback and EventCallback<T> permit asynchronous delegates. EventCallback<T> is strongly typed and
requires a specific argument type. EventCallback is weakly typed and allows any argument type.
 <p><b>@messageText</b></p>

@{ var message = "Default Text"; }

<ChildComponent
OnClick="@(async () => { await Task.Yield(); messageText = "Blaze It!"; })" />

@code {
private string messageText;
}

Invoke an EventCallback or EventCallback<T> with InvokeAsync and await the Task:

await callback.InvokeAsync(arg);

Use EventCallback and EventCallback<T> for event handling and binding component parameters.
Prefer the strongly typed EventCallback<T> over EventCallback . EventCallback<T> provides better error feedback
to users of the component. Similar to other UI event handlers, specifying the event parameter is optional. Use
EventCallback when there's no value passed to the callback.

Capture references to components

Component references provide a way to reference a component instance so that you can issue commands to that
instance, such as Show or Reset . To capture a component reference, add a @ref attribute to the child component
and then define a field with the same name and the same type as the child component.

<MyLoginDialog @ref="loginDialog" ... />

@code {
private MyLoginDialog loginDialog;

private void OnSomething()

{
loginDialog.Show();
}
}

When the component is rendered, the loginDialog field is populated with the MyLoginDialog child component
instance. You can then invoke .NET methods on the component instance.

IMPORTANT
The loginDialog variable is only populated after the component is rendered and its output includes the MyLoginDialog
element. Until that point, there's nothing to reference. To manipulate components references after the component has
finished rendering, use the OnAfterRenderAsync or OnAfterRender methods.

While capturing component references use a similar syntax to capturing element references, it isn't a JavaScript
interop feature. Component references aren't passed to JavaScript code—they're only used in .NET code.

NOTE
Do not use component references to mutate the state of child components. Instead, use normal declarative parameters to
pass data to child components. Use of normal declarative parameters result in child components that rerender at the correct
times automatically.
Use @key to control the preservation of elements and components
When rendering a list of elements or components and the elements or components subsequently change, Blazor's
diffing algorithm must decide which of the previous elements or components can be retained and how model
objects should map to them. Normally, this process is automatic and can be ignored, but there are cases where
you may want to control the process.
Consider the following example:

@foreach (var person in People)

{
<DetailsEditor Details="@person.Details" />
}

@code {
[Parameter]
public IEnumerable<Person> People { get; set; }
}

The contents of the People collection may change with inserted, deleted, or re-ordered entries. When the
component rerenders, the <DetailsEditor> component may change to receive different Details parameter
values. This may cause more complex rerendering than expected. In some cases, rerendering can lead to visible
behavior differences, such as lost element focus.
The mapping process can be controlled with the @key directive attribute. @key causes the diffing algorithm to
guarantee preservation of elements or components based on the key's value:

@foreach (var person in People)

{
<DetailsEditor @key="@person" Details="@person.Details" />
}

@code {
[Parameter]
public IEnumerable<Person> People { get; set; }
}

When the People collection changes, the diffing algorithm retains the association between <DetailsEditor>
instances and person instances:
If a Person is deleted from the People list, only the corresponding <DetailsEditor> instance is removed from
the UI. Other instances are left unchanged.
If a Person is inserted at some position in the list, one new <DetailsEditor> instance is inserted at that
corresponding position. Other instances are left unchanged.
If Person entries are re-ordered, the corresponding <DetailsEditor> instances are preserved and re-ordered
in the UI.
In some scenarios, use of @key minimizes the complexity of rerendering and avoids potential issues with stateful
parts of the DOM changing, such as focus position.

IMPORTANT
Keys are local to each container element or component. Keys aren't compared globally across the document.

When to use @key

Typically, it makes sense to use @key whenever a list is rendered (for example, in a @foreach block) and a suitable
value exists to define the @key .
You can also use @key to prevent Blazor from preserving an element or component subtree when an object
changes:

<div @key="@currentPerson">
... content that depends on @currentPerson ...
</div>

If @currentPerson changes, the @key attribute directive forces Blazor to discard the entire <div> and its
descendants and rebuild the subtree within the UI with new elements and components. This can be useful if you
need to guarantee that no UI state is preserved when @currentPerson changes.
When not to use @key
There's a performance cost when diffing with @key . The performance cost isn't large, but only specify @key if
controlling the element or component preservation rules benefit the app.
Even if @key isn't used, Blazor preserves child element and component instances as much as possible. The only
advantage to using @key is control over how model instances are mapped to the preserved component instances,
instead of the diffing algorithm selecting the mapping.
What values to use for @key
Generally, it makes sense to supply one of the following kinds of value for @key :
Model object instances (for example, a Person instance as in the earlier example). This ensures preservation
based on object reference equality.
Unique identifiers (for example, primary key values of type int , string , or Guid ).
Ensure that values used for @key don't clash. If clashing values are detected within the same parent element,
Blazor throws an exception because it can't deterministically map old elements or components to new elements or
components. Only use distinct values, such as object instances or primary key values.

Lifecycle methods
OnInitAsync and OnInit execute code to initialize the component. To perform an asynchronous operation, use
OnInitAsync and the await keyword on the operation:

protected override async Task OnInitAsync()

{
await ...
}

For a synchronous operation, use OnInit :

protected override void OnInit()

{
...
}

OnParametersSetAsync and OnParametersSet are called when a component has received parameters from its
parent and the values are assigned to properties. These methods are executed after component initialization and
each time the component is rendered:
 protected override async Task OnParametersSetAsync()
{
await ...
}

protected override void OnParametersSet()

{
...
}

OnAfterRenderAsync and OnAfterRender are called after a component has finished rendering. Element and
component references are populated at this point. Use this stage to perform additional initialization steps using
the rendered content, such as activating third-party JavaScript libraries that operate on the rendered DOM
elements.

protected override async Task OnAfterRenderAsync()

{
await ...
}

protected override void OnAfterRender()

{
...
}

Handle incomplete async actions at render

Asynchronous actions performed in lifecycle events may not have completed before the component is rendered.
Objects might be null or incompletely populated with data while the lifecycle method is executing. Provide
rendering logic to confirm that objects are initialized. Render placeholder UI elements (for example, a loading
message) while objects are null .
In the FetchData component of the Blazor templates, OnInitAsync is overridden to asychronously receive
forecast data ( forecasts ). When forecasts is null , a loading message is displayed to the user. After the Task
returned by OnInitAsync completes, the component is rerendered with the updated state.
Pages/FetchData.razor:
 @page "/fetchdata"
@using MyBlazorApp.Data
@inject WeatherForecastService ForecastService

<h1>Weather forecast</h1>

<p>This component demonstrates fetching data from a service.</p>

@if (forecasts == null)

{
<p><em>Loading...</em></p>
}
else
{
<table class="table">
<!-- forecast data in table element content -->
</table>
}

@code {
private WeatherForecast[] forecasts;

protected override async Task OnInitAsync()

{
forecasts = await ForecastService.GetForecastAsync(DateTime.Now);
}
}

Execute code before parameters are set

SetParameters can be overridden to execute code before parameters are set:

public override void SetParameters(ParameterCollection parameters)

{
...

base.SetParameters(parameters);
}

If base.SetParameters isn't invoked, the custom code can interpret the incoming parameters value in any way
required. For example, the incoming parameters aren't required to be assigned to the properties on the class.
Suppress refreshing of the UI
ShouldRender can be overridden to suppress refreshing of the UI. If the implementation returns true , the UI is
refreshed. Even if ShouldRender is overridden, the component is always initially rendered.

protected override bool ShouldRender()

{
var renderUI = true;

return renderUI;
}

Component disposal with IDisposable

If a component implements IDisposable, the Dispose method is called when the component is removed from the
UI. The following component uses @implements IDisposable and the Dispose method:
 @using System
@implements IDisposable

...

@code {
public void Dispose()
{
...
}
}

Routing
Routing in Blazor is achieved by providing a route template to each accessible component in the app.
When a Razor file with an @page directive is compiled, the generated class is given a RouteAttribute specifying
the route template. At runtime, the router looks for component classes with a RouteAttribute and renders
whichever component has a route template that matches the requested URL.
Multiple route templates can be applied to a component. The following component responds to requests for
/BlazorRoute and /DifferentBlazorRoute :

@page "/BlazorRoute"
@page "/DifferentBlazorRoute"

<h1>Blazor routing</h1>

Route parameters
Components can receive route parameters from the route template provided in the @page directive. The router
uses route parameters to populate the corresponding component parameters.
Route Parameter component:

@page "/RouteParameter"
@page "/RouteParameter/{text}"

<h1>Blazor is @Text!</h1>

@code {
[Parameter]
public string Text { get; set; } = "fantastic";
}

Optional parameters aren't supported, so two @page directives are applied in the example above. The first
permits navigation to the component without a parameter. The second @page directive takes the {text} route
parameter and assigns the value to the Text property.

Base class inheritance for a "code-behind" experience

Component files mix HTML markup and C# processing code in the same file. The @inherits directive can be
used to provide Blazor apps with a "code-behind" experience that separates component markup from processing
code.
The sample app shows how a component can inherit a base class, BlazorRocksBase , to provide the component's
properties and methods.
Pages/BlazorRocks.razor:

@page "/BlazorRocks"
@*
The inherit directive provides the properties and methods
of the BlazorRocksBase class to this component.
*@
@inherits BlazorRocksBase

<h1>@BlazorRocksText</h1>

BlazorRocksBase.cs:

using Microsoft.AspNetCore.Components;

namespace BlazorSample
{
public class BlazorRocksBase : ComponentBase
{
public string BlazorRocksText { get; set; } =
"Blazor rocks the browser!";
}
}

The base class should derive from ComponentBase .

Import components
The namespace of a component authored with Razor is based on:
The project's RootNamespace .
The path from the project root to the component. For example, ComponentsSample/Pages/Index.razor is in the
namespace ComponentsSample.Pages . Components follow C# name binding rules. In the case of Index.razor, all
components in the same folder, Pages, and the parent folder, ComponentsSample, are in scope.
Components defined in a different namespace can be brought into scope using Razor's @using directive.
If another component, NavMenu.razor , exists in the folder ComponentsSample/Shared/ , the component can be used
in Index.razor with the following @using statement:

@using ComponentsSample.Shared

This is the Index page.

<NavMenu></NavMenu>

Components can also be referenced using their fully qualified names, which removes the need for the @using
directive:

This is the Index page.

<ComponentsSample.Shared.NavMenu></ComponentsSample.Shared.NavMenu>
 NOTE
The global:: qualification isn't supported.
Importing components with aliased using statements (for example, @using Foo = Bar ) isn't supported.
Partially qualified names aren't supported. For example, adding @using ComponentsSample and referencing
NavMenu.razor with <Shared.NavMenu></Shared.NavMenu> isn't supported.

Conditional HTML element attributes

HTML element attributes are conditionally rendered based on the .NET value. If the value is false or null , the
attribute isn't rendered. If the value is true , the attribute is rendered minimized.
In the following example, IsCompleted determines if checked is rendered in the element's markup:

<input type="checkbox" checked="@IsCompleted" />

@code {
[Parameter]
public bool IsCompleted { get; set; }
}

If IsCompleted is true , the check box is rendered as:

<input type="checkbox" checked />

If IsCompleted is false , the check box is rendered as:

<input type="checkbox" />

For more information, see Razor syntax reference for ASP.NET Core.

Raw HTML
Strings are normally rendered using DOM text nodes, which means that any markup they may contain is ignored
and treated as literal text. To render raw HTML, wrap the HTML content in a MarkupString value. The value is
parsed as HTML or SVG and inserted into the DOM.

WARNING
Rendering raw HTML constructed from any untrusted source is a security risk and should be avoided!

The following example shows using the MarkupString type to add a block of static HTML content to the rendered
output of a component:

@((MarkupString)myMarkup)

@code {
private string myMarkup =
"<p class='markup'>This is a <em>markup string</em>.</p>";
}
Templated components
Templated components are components that accept one or more UI templates as parameters, which can then be
used as part of the component's rendering logic. Templated components allow you to author higher-level
components that are more reusable than regular components. A couple of examples include:
A table component that allows a user to specify templates for the table's header, rows, and footer.
A list component that allows a user to specify a template for rendering items in a list.
Template parameters
A templated component is defined by specifying one or more component parameters of type RenderFragment or
RenderFragment<T> . A render fragment represents a segment of UI to render. RenderFragment<T> takes a type
parameter that can be specified when the render fragment is invoked.
TableTemplate component:

@typeparam TItem

<table class="table">
<thead>
<tr>@TableHeader</tr>
</thead>
<tbody>
@foreach (var item in Items)
{
<tr>@RowTemplate(item)</tr>
}
</tbody>
<tfoot>
<tr>@TableFooter</tr>
</tfoot>
</table>

@code {
[Parameter]
public RenderFragment TableHeader { get; set; }

[Parameter]
public RenderFragment<TItem> RowTemplate { get; set; }

[Parameter]
public RenderFragment TableFooter { get; set; }

[Parameter]
public IReadOnlyList<TItem> Items { get; set; }
}

When using a templated component, the template parameters can be specified using child elements that match
the names of the parameters ( TableHeader and RowTemplate in the following example):

<TableTemplate Items="@pets">
<TableHeader>
<th>ID</th>
<th>Name</th>
</TableHeader>
<RowTemplate>
<td>@context.PetId</td>
<td>@context.Name</td>
</RowTemplate>
</TableTemplate>
Template context parameters
Component arguments of type RenderFragment<T> passed as elements have an implicit parameter named
context (for example from the preceding code sample, @context.PetId ), but you can change the parameter name
using the Context attribute on the child element. In the following example, the RowTemplate element's Context
attribute specifies the pet parameter:

<TableTemplate Items="@pets">
<TableHeader>
<th>ID</th>
<th>Name</th>
</TableHeader>
<RowTemplate Context="pet">
<td>@pet.PetId</td>
<td>@pet.Name</td>
</RowTemplate>
</TableTemplate>

Alternatively, you can specify the Context attribute on the component element. The specified Context attribute
applies to all specified template parameters. This can be useful when you want to specify the content parameter
name for implicit child content (without any wrapping child element). In the following example, the Context
attribute appears on the TableTemplate element and applies to all template parameters:

<TableTemplate Items="@pets" Context="pet">

<TableHeader>
<th>ID</th>
<th>Name</th>
</TableHeader>
<RowTemplate>
<td>@pet.PetId</td>
<td>@pet.Name</td>
</RowTemplate>
</TableTemplate>

Generic-typed components
Templated components are often generically typed. For example, a generic ListViewTemplate component can be
used to render IEnumerable<T> values. To define a generic component, use the @typeparam directive to specify
type parameters:

@typeparam TItem

<ul>
@foreach (var item in Items)
{
@ItemTemplate(item)
}
</ul>

@code {
[Parameter]
public RenderFragment<TItem> ItemTemplate { get; set; }

[Parameter]
public IReadOnlyList<TItem> Items { get; set; }
}

When using generic-typed components, the type parameter is inferred if possible:

 <ListViewTemplate Items="@pets">
<ItemTemplate Context="pet">
<li>@pet.Name</li>
</ItemTemplate>
</ListViewTemplate>

Otherwise, the type parameter must be explicitly specified using an attribute that matches the name of the type
parameter. In the following example, TItem="Pet" specifies the type:

<ListViewTemplate Items="@pets" TItem="Pet">

<ItemTemplate Context="pet">
<li>@pet.Name</li>
</ItemTemplate>
</ListViewTemplate>

Cascading values and parameters

In some scenarios, it's inconvenient to flow data from an ancestor component to a descendent component using
component parameters, especially when there are several component layers. Cascading values and parameters
solve this problem by providing a convenient way for an ancestor component to provide a value to all of its
descendent components. Cascading values and parameters also provide an approach for components to
coordinate.
Theme example
In the following example from the sample app, the ThemeInfo class specifies the theme information to flow down
the component hierarchy so that all of the buttons within a given part of the app share the same style.
UIThemeClasses/ThemeInfo.cs:

public class ThemeInfo

{
public string ButtonClass { get; set; }
}

An ancestor component can provide a cascading value using the Cascading Value component. The
CascadingValue component wraps a subtree of the component hierarchy and supplies a single value to all
components within that subtree.
For example, the sample app specifies theme information ( ThemeInfo ) in one of the app's layouts as a cascading
parameter for all components that make up the layout body of the @Body property. ButtonClass is assigned a
value of btn-success in the layout component. Any descendent component can consume this property through
the ThemeInfo cascading object.
CascadingValuesParametersLayout component:
 @inherits LayoutComponentBase
@using BlazorSample.UIThemeClasses

<div class="container-fluid">
<div class="row">
<div class="col-sm-3">
<NavMenu />
</div>
<div class="col-sm-9">
<CascadingValue Value="@theme">
<div class="content px-4">
@Body
</div>
</CascadingValue>
</div>
</div>
</div>

@code {
private ThemeInfo theme = new ThemeInfo { ButtonClass = "btn-success" };
}

To make use of cascading values, components declare cascading parameters using the [CascadingParameter]
attribute or based on a string name value:

<CascadingValue Value=@PermInfo Name="UserPermissions">...</CascadingValue>

[CascadingParameter(Name = "UserPermissions")]
private PermInfo Permissions { get; set; }

Binding with a string name value is relevant if you have multiple cascading values of the same type and need to
differentiate them within the same subtree.
Cascading values are bound to cascading parameters by type.
In the sample app, the CascadingValuesParametersTheme component binds the ThemeInfo cascading value to a
cascading parameter. The parameter is used to set the CSS class for one of the buttons displayed by the
component.
CascadingValuesParametersTheme component:
 @page "/cascadingvaluesparameterstheme"
@layout CascadingValuesParametersLayout
@using BlazorSample.UIThemeClasses

<h1>Cascading Values & Parameters</h1>

<p>Current count: @currentCount</p>

<p>
<button class="btn" @onclick="IncrementCount">
Increment Counter (Unthemed)
</button>
</p>

<p>
<button class="btn @ThemeInfo.ButtonClass" @onclick="IncrementCount">
Increment Counter (Themed)
</button>
</p>

@code {
private int currentCount = 0;

[CascadingParameter]
protected ThemeInfo ThemeInfo { get; set; }

private void IncrementCount()

{
currentCount++;
}
}

TabSet example
Cascading parameters also enable components to collaborate across the component hierarchy. For example,
consider the following TabSet example in the sample app.
The sample app has an ITab interface that tabs implement:

using Microsoft.AspNetCore.Components;

namespace BlazorSample.UIInterfaces
{
public interface ITab
{
RenderFragment ChildContent { get; }
}
}

The CascadingValuesParametersTabSet component uses the TabSet component, which contains several Tab
components:
 <TabSet>
<Tab Title="First tab">
<h4>Greetings from the first tab!</h4>

<label>
<input type="checkbox" @bind="showThirdTab" />
Toggle third tab
</label>
</Tab>
<Tab Title="Second tab">
<h4>The second tab says Hello World!</h4>
</Tab>

@if (showThirdTab)
{
<Tab Title="Third tab">
<h4>Welcome to the disappearing third tab!</h4>
<p>Toggle this tab from the first tab.</p>
</Tab>
}
</TabSet>

The child Tab components aren't explicitly passed as parameters to the TabSet . Instead, the child Tab
components are part of the child content of the TabSet . However, the TabSet still needs to know about each
Tab component so that it can render the headers and the active tab. To enable this coordination without requiring
additional code, the TabSet component can provide itself as a cascading value that is then picked up by the
descendent Tab components.
TabSet component:
 @using BlazorSample.UIInterfaces

<!-- Display the tab headers -->

<CascadingValue Value=this>
<ul class="nav nav-tabs">
@ChildContent
</ul>
</CascadingValue>

<!-- Display body for only the active tab -->

<div class="nav-tabs-body p-4">
@ActiveTab?.ChildContent
</div>

@code {
[Parameter]
public RenderFragment ChildContent { get; set; }

public ITab ActiveTab { get; private set; }

public void AddTab(ITab tab)

{
if (ActiveTab == null)
{
SetActivateTab(tab);
}
}

public void RemoveTab(ITab tab)

{
if (ActiveTab == tab)
{
SetActivateTab(null);
}
}

public void SetActivateTab(ITab tab)

{
if (ActiveTab != tab)
{
ActiveTab = tab;
StateHasChanged();
}
}
}

The descendent Tab components capture the containing TabSet as a cascading parameter, so the Tab
components add themselves to the TabSet and coordinate on which tab is active.
Tab component:
 @using BlazorSample.UIInterfaces
@implements IDisposable
@implements ITab

<li>
<a @onclick="Activate" class="nav-link @TitleCssClass" role="button">
@Title
</a>
</li>

@code {
[CascadingParameter]
public TabSet ContainerTabSet { get; set; }

[Parameter]
public string Title { get; set; }

[Parameter]
public RenderFragment ChildContent { get; set; }

private string TitleCssClass => ContainerTabSet.ActiveTab == this ? "active" : null;

protected override void OnInitialized()

{
ContainerTabSet.AddTab(this);
}

public void Dispose()

{
ContainerTabSet.RemoveTab(this);
}

private void Activate()

{
ContainerTabSet.SetActivateTab(this);
}
}

Razor templates
Render fragments can be defined using Razor template syntax. Razor templates are a way to define a UI snippet
and assume the following format:

@<{HTML tag}>...</{HTML tag}>

The following example illustrates how to specify RenderFragment and RenderFragment<T> values and render
templates directly in a component. Render fragments can also be passed as arguments to templated components.
 @timeTemplate

@petTemplate(new Pet { Name = "Rex" })

@code {
private RenderFragment timeTemplate = @<p>The time is @DateTime.Now.</p>;
private RenderFragment<Pet> petTemplate =
(pet) => @<p>Your pet's name is @pet.Name.</p>;

private class Pet

{
public string Name { get; set; }
}
}

Rendered output of the preceding code:

<p>The time is 10/04/2018 01:26:52.</p>

<p>Your pet's name is Rex.</p>

Manual RenderTreeBuilder logic

Microsoft.AspNetCore.Components.RenderTree provides methods for manipulating components and elements,
including building components manually in C# code.

NOTE
Use of RenderTreeBuilder to create components is an advanced scenario. A malformed component (for example, an
unclosed markup tag) can result in undefined behavior.

Consider the following PetDetails component, which can be manually built into another component:

<h2>Pet Details Component</h2>

<p>@PetDetailsQuote</p>

@code
{
[Parameter]
public string PetDetailsQuote { get; set; }
}

In the following example, the loop in the CreateComponent method generates three PetDetails components.
When calling RenderTreeBuilder methods to create the components ( OpenComponent and AddAttribute ),
sequence numbers are source code line numbers. The Blazor difference algorithm relies on the sequence numbers
corresponding to distinct lines of code, not distinct call invocations. When creating a component with
RenderTreeBuilder methods, hardcode the arguments for sequence numbers. Using a calculation or counter to
generate the sequence number can lead to poor performance. For more information, see the Sequence
numbers relate to code line numbers and not execution order section.
BuiltContent component:
 @page "/BuiltContent"

<h1>Build a component</h1>

@CustomRender

<button type="button" @onclick="RenderComponent">

Create three Pet Details components
</button>

@code {
private RenderFragment CustomRender { get; set; }

private RenderFragment CreateComponent() => builder =>

{
for (var i = 0; i < 3; i++)
{
builder.OpenComponent(0, typeof(PetDetails));
builder.AddAttribute(1, "PetDetailsQuote", "Someone's best friend!");
builder.CloseComponent();
}
};

private void RenderComponent()

{
CustomRender = CreateComponent();
}
}

Sequence numbers relate to code line numbers and not execution order
Blazor .razor files are always compiled. This is potentially a great advantage for .razor because the compile
step can be used to inject information that improve app performance at runtime.
A key example of these improvements involve sequence numbers. Sequence numbers indicate to the runtime
which outputs came from which distinct and ordered lines of code. The runtime uses this information to generate
efficient tree diffs in linear time, which is far faster than is normally possible for a general tree diff algorithm.
Consider the following simple .razor file:

@if (someFlag)
{
<text>First</text>
}

Second

The preceding code compiles to something like the following:

if (someFlag)
{
builder.AddContent(0, "First");
}

builder.AddContent(1, "Second");

When the code executes for the first time, if someFlag is true , the builder receives:
 SEQUENCE TYPE DATA

0 Text node First

1 Text node Second

Imagine that someFlag becomes false , and the markup is rendered again. This time, the builder receives:

SEQUENCE TYPE DATA

1 Text node Second

When the runtime performs a diff, it sees that the item at sequence 0 was removed, so it generates the following
trivial edit script:
Remove the first text node.
What goes wrong if you generate sequence numbers programmatically
Imagine instead that you wrote the following render tree builder logic:

var seq = 0;

if (someFlag)
{
builder.AddContent(seq++, "First");
}

builder.AddContent(seq++, "Second");

Now, the first output is:

SEQUENCE TYPE DATA

0 Text node First

1 Text node Second

This outcome is identical to the prior case, so no negative issues exist. someFlag is false on the second
rendering, and the output is:

SEQUENCE TYPE DATA

0 Text node Second

This time, the diff algorithm sees that two changes have occurred, and the algorithm generates the following edit
script:
Change the value of the first text node to Second .
Remove the second text node.
Generating the sequence numbers has lost all the useful information about where the if/else branches and
loops were present in the original code. This results in a diff twice as long as before.
This is a trivial example. In more realistic cases with complex and deeply nested structures, and especially with
loops, the performance cost is more severe. Instead of immediately identifying which loop blocks or branches
have been inserted or removed, the diff algorithm has to recurse deeply into the render trees and usually build far
longer edit scripts because it is misinformed about how the old and new structures relate to each other.
Guidance and conclusions
App performance suffers if sequence numbers are generated dynamically.
The framework can't create its own sequence numbers automatically at runtime because the necessary
information doesn't exist unless it's captured at compile time.
Don't write long blocks of manually-implemented RenderTreeBuilder logic. Prefer .razor files and allow the
compiler to deal with the sequence numbers.
If sequence numbers are hardcoded, the diff algorithm only requires that sequence numbers increase in value.
The initial value and gaps are irrelevant. One legitimate option is to use the code line number as the sequence
number, or start from zero and increase by ones or hundreds (or any preferred interval).
Blazor uses sequence numbers, while other tree-diffing UI frameworks don't use them. Diffing is far faster
when sequence numbers are used, and Blazor has the advantage of a compile step that deals with sequence
numbers automatically for developers authoring .razor files.

Localization
Blazor server-side apps are localized using Localization Middleware. The middleware selects the appropriate
culture for users requesting resources from the app.
The culture can be set using one of the following approaches:
Cookies
Provide UI to choose the culture
For more information and examples, see Globalization and localization in ASP.NET Core.
Cookies
A localization culture cookie can persist the user's culture. The cookie is created by the OnGet method of the app's
host page (Pages/Host.cshtml.cs). The Localization Middleware reads the cookie on subsequent requests to set the
user's culture.
Use of a cookie ensures that the WebSocket connection can correctly propagate the culture. If localization
schemes are based on the URL path or query string, the scheme might not be able to work with WebSockets, thus
fail to persist the culture. Therefore, use of a localization culture cookie is the recommended approach.
Any technique can be used to assign a culture if the culture is persisted in a localization cookie. If the app already
has an established localization scheme for server-side ASP.NET Core, continue to use the app's existing
localization infrastructure and set the localization culture cookie within the app's scheme.
The following example shows how to set the current culture in a cookie that can be read by the Localization
Middleware. Create a Pages/Host.cshtml.cs file with the following contents in the Blazor server-side app:

public class HostModel : PageModel

{
public void OnGet()
{
HttpContext.Response.Cookies.Append(
CookieRequestCultureProvider.DefaultCookieName,
CookieRequestCultureProvider.MakeCookieValue(
new RequestCulture(
CultureInfo.CurrentCulture,
CultureInfo.CurrentUICulture)));
}
}

Localization is handled in the app:

1. The browser sends an initial HTTP request to the app.
2. The culture is assigned by the Localization Middleware.
3. The OnGet method in _Host.cshtml.cs persists the culture in a cookie as part of the response.
4. The browser opens a WebSocket connection to create an interactive Blazor server-side session.
5. The Localization Middleware reads the cookie and assigns the culture.
6. The Blazor server-side session begins with the correct culture.

Provide UI to choose the culture

To provide UI to allow a user to select a culture, a redirect-based approach is recommended. The process is
similar to what happens in a web app when a user attempts to access a secure resource—the user is redirected to
a sign-in page and then redirected back to the original resource.
The app persists the user's selected culture via a redirect to a controller. The controller sets the user's selected
culture into a cookie and redirects the user back to the original URI.
Establish an HTTP endpoint on the server to set the user's selected culture in a cookie and perform the redirect
back to the original URI:

[Route("[controller]/[action]")]
public class CultureController : Controller
{
public IActionResult SetCulture(string culture, string redirectUri)
{
if (culture != null)
{
HttpContext.Response.Cookies.Append(
CookieRequestCultureProvider.DefaultCookieName,
CookieRequestCultureProvider.MakeCookieValue(
new RequestCulture(culture)));
}

return LocalRedirect(redirectUri);
}
}

WARNING
Use the LocalRedirect action result to prevent open redirect attacks. For more information, see Prevent open redirect
attacks in ASP.NET Core.

The following component shows an example of how to perform the initial redirection when the user selects a
culture:
 @inject IUriHelper UriHelper

<h3>Select your language</h3>

<select @onchange="OnSelected">
<option>Select...</option>
<option value="en-US">English</option>
<option value="fr-FR">Français</option>
</select>

@code {
private double textNumber;

private void OnSelected(UIChangeEventArgs e)

{
var culture = (string)e.Value;
var uri = new Uri(UriHelper.GetAbsoluteUri())
.GetComponents(UriComponents.PathAndQuery, UriFormat.Unescaped);
var query = $"?culture={Uri.EscapeDataString(culture)}&" +
$"redirectUri={Uri.EscapeDataString(uri)}";

UriHelper.NavigateTo("/Culture/SetCulture" + query, forceLoad: true);

}
}

Use .NET localization scenarios in Blazor apps

Inside Blazor apps, the following .NET localization and globalization scenarios are available:
.NET's resources system
Culture-specific number and date formatting
Blazor's @bind functionality performs globalization based on the user's current culture. For more information, see
the Data binding section.
A limited set of ASP.NET Core's localization scenarios are currently supported:
IStringLocalizer<> is supported in Blazor apps.
IHtmlLocalizer<> , IViewLocalizer<> , and Data Annotations localization are ASP.NET Core MVC scenarios
and not supported in Blazor apps.
For more information, see Globalization and localization in ASP.NET Core.
 ASP.NET Core Blazor forms and validation
7/12/2019 • 3 minutes to read • Edit Online

By Daniel Roth and Luke Latham

Forms and validation are supported in Blazor using data annotations.

NOTE
Forms and validation scenarios are likely to change with each preview release.

The following ExampleModel type defines validation logic using data annotations:

using System.ComponentModel.DataAnnotations;

public class ExampleModel

{
[Required]
[StringLength(10, ErrorMessage = "Name is too long.")]
public string Name { get; set; }
}

A form is defined using the EditForm component. The following form demonstrates typical elements, components,
and Razor code:

<EditForm Model="@exampleModel" OnValidSubmit="@HandleValidSubmit">

<DataAnnotationsValidator />
<ValidationSummary />

<InputText id="name" @bind-Value="@exampleModel.Name" />

<button type="submit">Submit</button>
</EditForm>

@code {
private ExampleModel exampleModel = new ExampleModel();

private void HandleValidSubmit()

{
Console.WriteLine("OnValidSubmit");
}
}

The form validates user input in the name field using the validation defined in the ExampleModel type. The
model is created in the component's @code block and held in a private field ( exampleModel ). The field is
assigned to the Model attribute of the <EditForm> element.
The DataAnnotationsValidator component attaches validation support using data annotations.
The ValidationSummary component summarizes validation messages.
HandleValidSubmit is triggered when the form successfully submits (passes validation).

A set of built-in input components are available to receive and validate user input. Inputs are validated when
they're changed and when a form is submitted. Available input components are shown in the following table.
 INPUT COMPONENT RENDERED AS…

InputText <input>

InputTextArea <textarea>

InputSelect <select>

InputNumber <input type="number">

InputCheckbox <input type="checkbox">

InputDate <input type="date">

All of the input components, including EditForm , support arbitrary attributes. Any attribute that doesn't match a
component parameter is added to the rendered HTML element.
Input components provide default behavior for validating on edit and changing their CSS class to reflect the field
state. Some components include useful parsing logic. For example, InputDate and InputNumber handle
unparseable values gracefully by registering them as validation errors. Types that can accept null values also
support nullability of the target field (for example, int? ).
The following Starship type defines validation logic using a larger set of properties and data annotations than the
earlier ExampleModel :

using System;
using System.ComponentModel.DataAnnotations;

public class Starship

{
[Required]
[StringLength(16, ErrorMessage = "Identifier too long (16 character limit).")]
public string Identifier { get; set; }

public string Description { get; set; }

[Required]
public string Classification { get; set; }

[Range(1, 100000, ErrorMessage = "Accommodation invalid (1-100000).")]

public int MaximumAccommodation { get; set; }

[Required]
[Range(typeof(bool), "true", "true",
ErrorMessage = "This form disallows unapproved ships.")]
public bool IsValidatedDesign { get; set; }

[Required]
public DateTime ProductionDate { get; set; }
}

In the preceding example, Description is optional because no data annotations are present.
The following form validates user input using the validation defined in the Starship model:
 @page "/FormsValidation"

<h1>Starfleet Starship Database</h1>

<h2>New Ship Entry Form</h2>

<EditForm Model="@starship" OnValidSubmit="@HandleValidSubmit">

<DataAnnotationsValidator />
<ValidationSummary />

<p>
<label for="identifier">Identifier: </label>
<InputText id="identifier" @bind-Value="starship.Identifier" />
</p>
<p>
<label for="description">Description (optional): </label>
<InputTextArea Id="description" @bind-Value="starship.Description" />
</p>
<p>
<label for="classification">Primary Classification: </label>
<InputSelect id="classification" @bind-Value="starship.Classification">
<option value="">Select classification ...</option>
<option value="Exploration">Exploration</option>
<option value="Diplomacy">Diplomacy</option>
<option value="Defense">Defense</option>
</InputSelect>
</p>
<p>
<label for="accommodation">Maximum Accommodation: </label>
<InputNumber id="accommodation"
@bind-Value="starship.MaximumAccommodation" />
</p>
<p>
<label for="valid">Engineering Approval: </label>
<InputCheckbox id="valid" @bind-Value="starship.IsValidatedDesign" />
</p>
<p>
<label for="productionDate">Production Date: </label>
<InputDate Id="productionDate" @bind-Value="starship.ProductionDate" />
</p>

<button type="submit">Submit</button>

<p>
<a href="http://www.startrek.com/">Star Trek</a>,
&copy;1966-2019 CBS Studios, Inc. and
<a href="https://www.paramount.com">Paramount Pictures</a>
</p>
</EditForm>

@code {
private Starship starship = new Starship();

private void HandleValidSubmit()

{
Console.WriteLine("OnValidSubmit");
}
}

The EditForm creates an EditContext as a cascading value that tracks metadata about the edit process, including
which fields have been modified and the current validation messages. The EditForm also provides convenient
events for valid and invalid submits ( OnValidSubmit , OnInvalidSubmit ). Alternatively, use OnSubmit to trigger the
validation and check field values with custom validation code.
The DataAnnotationsValidator component attaches validation support using data annotations to the cascaded
EditContext . Enabling support for validation using data annotations currently requires this explicit gesture, but
we're considering making this the default behavior that you can then override. To use a different validation system
than data annotations, replace the DataAnnotationsValidator with a custom implementation. The ASP.NET Core
implementation is available for inspection in the reference source:
DataAnnotationsValidator/AddDataAnnotationsValidation. The ASP.NET Core implementation is subject to rapid
updates during the preview release period.
The ValidationSummary component summarizes all validation messages, which is similar to the Validation
Summary Tag Helper.
The ValidationMessage component displays validation messages for a specific field, which is similar to the
Validation Message Tag Helper. Specify the field for validation with the For attribute and a lambda expression
naming the model property:

<ValidationMessage For="@(() => starship.MaximumAccommodation)" />

The ValidationMessage and ValidationSummary components support arbitrary attributes. Any attribute that doesn't
match a component parameter is added to the generated <div> or <ul> element.
 ASP.NET Core Razor components class libraries
8/9/2019 • 3 minutes to read • Edit Online

By Simon Timms
Components can be shared in a Razor class library (RCL ) across projects. A Razor components class library can be
included from:
Another project in the solution.
A NuGet package.
A referenced .NET library.
Just as components are regular .NET types, components provided by an RCL are normal .NET assemblies.

Create an RCL
Follow the guidance in the Get started with ASP.NET Core Blazor article to configure your environment for Blazor.
Visual Studio
.NET Core CLI
1. Create a new project.
2. Select ASP.NET Core Web Application. Select Next.
3. Provide a project name in the Project name field or accept the default project name. The examples in this topic
use the project name MyComponentLib1 . Select Create.
4. In the Create a new ASP.NET Core Web Application dialog, confirm that .NET Core and ASP.NET Core
3.0 are selected.
5. Select the Razor Class Library template. Select Create.
6. Add the RCL to a solution:
a. Right-click the solution. Select Add > Existing Project.
b. Navigate to the RCL's project file.
c. Select the RCL's project file (.csproj).
7. Add a reference the RCL from the app:
a. Right-click the app project. Select Add > Reference.
b. Select the RCL project. Select OK.

RCLs not supported for client-side apps

In the current ASP.NET Core 3.0 Preview, Razor class libraries aren't compatible with Blazor client-side apps. For
Blazor client-side apps, use a Blazor component library created by the blazorlib template in a command shell:

dotnet new blazorlib -o MyComponentLib1

Component libraries using the blazorlib template can include static files, such as images, JavaScript, and
stylesheets. At build time, static files are embedded into the built assembly file (.dll), which allows consumption of
the components without having to worry about how to include their resources. Any files included in the content
directory are marked as an embedded resource.
Consume a library component
In order to consume components defined in a library in another project, use either of the following approaches:
Use the full type name with the namespace.
Use Razor's @using directive. Individual components can be added by name.
In the following examples, MyComponentLib1 is a component library containing a SalesReport component.
The SalesReport component can be referenced using its full type name with namespace:

<h1>Hello, world!</h1>

Welcome to your new app.

<MyComponentLib1.SalesReport />

The component can also be referenced if the library is brought into scope with an @using directive:

@using MyComponentLib1

<h1>Hello, world!</h1>

Welcome to your new app.

<SalesReport />

Include the @using MyComponentLib1 directive in the top-level _Import.razor file to make the library's components
available to an entire project. Add the directive to an _Import.razor file at any level to apply the namespace to a
single page or set of pages within a folder.

Build, pack, and ship to NuGet

Because component libraries are standard .NET libraries, packaging and shipping them to NuGet is no different
from packaging and shipping any library to NuGet. Packaging is performed using the dotnet pack command in a
command shell:

dotnet pack

Upload the package to NuGet using the dotnet nuget publish command in a command shell:

dotnet nuget publish

When using the blazorlib template, static resources are included in the NuGet package. Library consumers
automatically receive scripts and stylesheets, so consumers aren't required to manually install the resources.

Create a Razor components class library with static assets

An RCL can include static assets. The static assets are available to any app that consumes the library. For more
information, see Reusable Razor UI in class libraries with ASP.NET Core.

Additional resources
Reusable Razor UI in class libraries with ASP.NET Core
 ASP.NET Core Blazor layouts
7/3/2019 • 3 minutes to read • Edit Online

By Rainer Stropek
Some app elements, such as menus, copyright messages, and company logos, are usually part of app's overall
layout and used by every component in the app. Copying the code of these elements into all of the components of
an app isn't an efficient approach—every time one of the elements requires an update, every component must be
updated. Such duplication is difficult to maintain and can lead to inconsistent content over time. Layouts solve this
problem.
Technically, a layout is just another component. A layout is defined in a Razor template or in C# code and can use
data binding, dependency injection, and other component scenarios.
To turn a component into a layout, the component:
Inherits from LayoutComponentBase , which defines a Body property for the rendered content inside the layout.
Uses the Razor syntax @Body to specify the location in the layout markup where the content is rendered.
The following code sample shows the Razor template of a layout component, MainLayout.razor. The layout
inherits LayoutComponentBase and sets the @Body between the navigation bar and the footer:

@inherits LayoutComponentBase

<header>
<h1>Doctor Who&trade; Episode Database</h1>
</header>

<nav>
<a href="masterlist">Master Episode List</a>
<a href="search">Search</a>
<a href="new">Add Episode</a>
</nav>

@Body

<footer>
@TrademarkMessage
</footer>

@code {
public string TrademarkMessage { get; set; } =
"Doctor Who is a registered trademark of the BBC. " +
"https://www.doctorwho.tv/";
}

Specify a layout in a component

Use the Razor directive @layout to apply a layout to a component. The compiler converts @layout into a
LayoutAttribute , which is applied to the component class.

The content of the following component, MasterList.razor, is inserted into the MainLayout at the position of @Body :
 @layout MainLayout
@page "/masterlist"

<h1>Master Episode List</h1>

Centralized layout selection

Every folder of an app can optionally contain a template file named _Imports.razor. The compiler includes the
directives specified in the imports file in all of the Razor templates in the same folder and recursively in all of its
subfolders. Therefore, an _Imports.razor file containing @layout MainLayout ensures that all of the components in a
folder use MainLayout . There's no need to repeatedly add @layout MainLayout to all of the .razor files within the
folder and subfolders. @using directives are also applied to components in the same way.
The following _Imports.razor file imports:
MainLayout .
All Razor components in the same folder and any subfolders.
The BlazorApp1.Data namespace.

@layout MainLayout
@using Microsoft.AspNetCore.Components
@using BlazorApp1.Data

The _Imports.razor file is similar to the _ViewImports.cshtml file for Razor views and pages but applied specifically
to Razor component files.
The Blazor templates use _Imports.razor files for layout selection. An app created from a Blazor template contains
the _Imports.razor file in the root of the project and in the Pages folder.

Nested layouts
Apps can consist of nested layouts. A component can reference a layout which in turn references another layout.
For example, nesting layouts are used to create a multi-level menu structure.
The following example shows how to use nested layouts. The EpisodesComponent.razor file is the component to
display. The component references the MasterListLayout :

@layout MasterListLayout
@page "/masterlist/episodes"

<h1>Episodes</h1>

The MasterListLayout.razor file provides the MasterListLayout . The layout references another layout, MasterLayout
, where it's rendered. EpisodesComponent is rendered where @Body appears:

@layout MasterLayout
@inherits LayoutComponentBase

<nav>
<!-- Menu structure of master list -->
...
</nav>

@Body
Finally, MasterLayout in MasterLayout.razor contains the top-level layout elements, such as the header, main menu,
and footer. MasterListLayout with EpisodesComponent are rendered where @Body appears:

@inherits LayoutComponentBase

<header>...</header>
<nav>...</nav>

@Body

<footer>
@TrademarkMessage
</footer>

@code {
public string TrademarkMessage { get; set; } =
"Doctor Who is a registered trademark of the BBC. " +
"https://www.doctorwho.tv/";
}

Additional resources
Layout in ASP.NET Core
 ASP.NET Core Blazor dependency injection
8/6/2019 • 4 minutes to read • Edit Online

By Rainer Stropek
Blazor supports dependency injection (DI). Apps can use built-in services by injecting them into components.
Apps can also define and register custom services and make them available throughout the app via DI.
DI is a technique for accessing services configured in a central location. This can be useful in Blazor apps to:
Share a single instance of a service class across many components, known as a singleton service.
Decouple components from concrete service classes by using reference abstractions. For example, consider an
interface IDataAccess for accessing data in the app. The interface is implemented by a concrete DataAccess
class and registered as a service in the app's service container. When a component uses DI to receive an
IDataAccess implementation, the component isn't coupled to the concrete type. The implementation can be
swapped, perhaps for a mock implementation in unit tests.

Default services
Default services are automatically added to the app's service collection.

SERVICE LIFETIME DESCRIPTION

HttpClient Singleton Provides methods for sending HTTP

requests and receiving HTTP responses
from a resource identified by a URI.
Note that this instance of HttpClient
uses the browser for handling the HTTP
traffic in the background.
HttpClient.BaseAddress is automatically
set to the base URI prefix of the app.
For more information, see Call a web
API from ASP.NET Core Blazor.

IJSRuntime Singleton Represents an instance of a JavaScript

runtime where JavaScript calls are
dispatched. For more information, see
ASP.NET Core Blazor JavaScript interop.

IUriHelper Singleton Contains helpers for working with URIs

and navigation state. For more
information, see URI and navigation
state helpers.

A custom service provider doesn't automatically provide the default services listed in the table. If you use a
custom service provider and require any of the services shown in the table, add the required services to the new
service provider.

Add services to an app

After creating a new app, examine the Startup.ConfigureServices method:
 public void ConfigureServices(IServiceCollection services)
{
// Add custom services here
}

The ConfigureServices method is passed an IServiceCollection, which is a list of service descriptor objects
(ServiceDescriptor). Services are added by providing service descriptors to the service collection. The following
example demonstrates the concept with the IDataAccess interface and its concrete implementation DataAccess :

public void ConfigureServices(IServiceCollection services)

{
services.AddSingleton<IDataAccess, DataAccess>();
}

Services can be configured with the lifetimes shown in the following table.

LIFETIME DESCRIPTION

Scoped Blazor client-side doesn't currently have a concept of DI

scopes. Scoped -registered services behave like Singleton
services. However, the server-side hosting model supports
the Scoped lifetime. In a Razor component, a scoped service
registration is scoped to the connection. For this reason, using
scoped services is preferred for services that should be
scoped to the current user, even if the current intent is to run
client-side in the browser.

Singleton DI creates a single instance of the service. All components

requiring a Singleton service receive an instance of the
same service.

Transient Whenever a component obtains an instance of a Transient

service from the service container, it receives a new instance
of the service.

The DI system is based on the DI system in ASP.NET Core. For more information, see Dependency injection in
ASP.NET Core.

Request a service in a component

After services are added to the service collection, inject the services into the components using the @inject Razor
directive. @inject has two parameters:
Type – The type of the service to inject.
Property – The name of the property receiving the injected app service. The property doesn't require manual
creation. The compiler creates the property.
For more information, see Dependency injection into views in ASP.NET Core.
Use multiple @inject statements to inject different services.
The following example shows how to use @inject . The service implementing Services.IDataAccess is injected
into the component's property DataRepository . Note how the code is only using the IDataAccess abstraction:
 @page "/customer-list"
@using Services
@inject IDataAccess DataRepository

@if (Customers != null)

{
<ul>
@foreach (var customer in Customers)
{
<li>@customer.FirstName @customer.LastName</li>
}
</ul>
}

@code {
private IReadOnlyList<Customer> Customers;

protected override async Task OnInitAsync()

{
// The property DataRepository received an implementation
// of IDataAccess through dependency injection. Use
// DataRepository to obtain data from the server.
Customers = await DataRepository.GetAllCustomersAsync();
}
}

Internally, the generated property ( DataRepository ) is decorated with the InjectAttribute attribute. Typically, this
attribute isn't used directly. If a base class is required for components and injected properties are also required for
the base class, manually add the InjectAttribute :

public class ComponentBase : IComponent

{
// DI works even if using the InjectAttribute in a component's base class.
[Inject]
protected IDataAccess DataRepository { get; set; }
...
}

In components derived from the base class, the @inject directive isn't required. The InjectAttribute of the base
class is sufficient:

@page "/demo"
@inherits ComponentBase

<h1>Demo Component</h1>

Use DI in services
Complex services might require additional services. In the prior example, DataAccess might require the
HttpClient default service. @inject (or the InjectAttribute ) isn't available for use in services. Constructor
injection must be used instead. Required services are added by adding parameters to the service's constructor.
When DI creates the service, it recognizes the services it requires in the constructor and provides them
accordingly.
 public class DataAccess : IDataAccess
{
// The constructor receives an HttpClient via dependency
// injection. HttpClient is a default service.
public DataAccess(HttpClient client)
{
...
}
}

Prerequisites for constructor injection:

One constructor must exist whose arguments can all be fulfilled by DI. Additional parameters not covered by
DI are allowed if they specify default values.
The applicable constructor must be public.
One applicable constructor must exist. In case of an ambiguity, DI throws an exception.

Additional resources
Dependency injection in ASP.NET Core
Dependency injection into views in ASP.NET Core
 ASP.NET Core Blazor routing
7/23/2019 • 4 minutes to read • Edit Online

By Luke Latham
Learn how to route requests and how to use the NavLink component to create navigation links in Blazor apps.

ASP.NET Core endpoint routing integration

Blazor server-side is integrated into ASP.NET Core Endpoint Routing. An ASP.NET Core app is configured to
accept incoming connections for interactive components with MapBlazorHub in Startup.Configure :

app.UseRouting();

app.UseEndpoints(endpoints =>
{
endpoints.MapBlazorHub();
endpoints.MapFallbackToPage("/_Host");
});

Route templates
The Router component enables routing, and a route template is provided to each accessible component. The
Router component appears in the App.razor file:
In a Blazor server-side app:

<Router AppAssembly="typeof(Startup).Assembly" />

In a Blazor client-side app:

<Router AppAssembly="typeof(Program).Assembly" />

When a .razor file with an @page directive is compiled, the generated class is provided a RouteAttribute specifying
the route template. At runtime, the router looks for component classes with a RouteAttribute and renders the
component with a route template that matches the requested URL.
Multiple route templates can be applied to a component. The following component responds to requests for
/BlazorRoute and /DifferentBlazorRoute :

@page "/BlazorRoute"
@page "/DifferentBlazorRoute"

<h1>Blazor routing</h1>
 IMPORTANT
To generate routes properly, the app must include a <base> tag in its wwwroot/index.html file (Blazor client-side) or
Pages/_Host.cshtml file (Blazor server-side) with the app base path specified in the href attribute ( <base href="/"> ). For
more information, see Host and deploy ASP.NET Core Blazor client-side.

Provide custom content when content isn't found

The Router component allows the app to specify custom content if content isn't found for the requested route.
In the App.razor file, set custom content in the <NotFoundContent> element of the Router component:

<Router AppAssembly="typeof(Startup).Assembly">
<NotFoundContent>
<h1>Sorry</h1>
<p>Sorry, there's nothing at this address.</p> b
</NotFoundContent>
</Router>

The content of <NotFoundContent> can include arbitrary items, such as other interactive components.

Route parameters
The router uses route parameters to populate the corresponding component parameters with the same name (case
insensitive):

@page "/RouteParameter"
@page "/RouteParameter/{text}"

<h1>Blazor is @Text!</h1>

@code {
[Parameter]
public string Text { get; set; } = "fantastic";
}

Optional parameters aren't supported for Blazor apps in ASP.NET Core 3.0 Preview. Two @page directives are
applied in the previous example. The first permits navigation to the component without a parameter. The second
@page directive takes the {text} route parameter and assigns the value to the Text property.

Route constraints
A route constraint enforces type matching on a route segment to a component.
In the following example, the route to the Users component only matches if:
An Id route segment is present on the request URL.
The Id segment is an integer ( int ).
 @page "/Users/{Id:int}"

<h1>The user Id is @Id!</h1>

@code {
[Parameter]
public int Id { get; set; }
}

The route constraints shown in the following table are available. For the route constraints that match with the
invariant culture, see the warning below the table for more information.

INVARIANT
CULTURE
CONSTRAINT EXAMPLE EXAMPLE MATCHES MATCHING

bool {active:bool} true , FALSE No

datetime {dob:datetime} 2016-12-31 , Yes

2016-12-31 7:32pm

decimal {price:decimal} 49.99 , -1,000.01 Yes

double {weight:double} 1.234 , -1,001.01e8 Yes

float {weight:float} 1.234 , -1,001.01e8 Yes

guid {id:guid} CD2C1638-1638-72D5- No

1638-DEADBEEF1638
,
{CD2C1638-1638-72D5-
1638-DEADBEEF1638}

int {id:int} 123456789 , -123456789 Yes

long {ticks:long} 123456789 , -123456789 Yes

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.

NavLink component
Use a NavLink component in place of HTML hyperlink elements ( <a> ) when creating navigation links. A NavLink
component behaves like an <a> element, except it toggles an active CSS class based on whether its href
matches the current URL. The active class helps a user understand which page is the active page among the
navigation links displayed.
The following NavMenu component creates a Bootstrap navigation bar that demonstrates how to use NavLink
components:
 <div class="@NavMenuCssClass" @onclick="@ToggleNavMenu">
<ul class="nav flex-column">
<li class="nav-item px-3">
<NavLink class="nav-link" href="" Match="NavLinkMatch.All">
<span class="oi oi-home" aria-hidden="true"></span> Home
</NavLink>
</li>
<li class="nav-item px-3">
<NavLink class="nav-link" href="MyComponent" Match="NavLinkMatch.Prefix">
<span class="oi oi-plus" aria-hidden="true"></span> My Component
</NavLink>
</li>
</ul>
</div>

There are two NavLinkMatch options that you can assign to the Match attribute of the <NavLink> element:
NavLinkMatch.All – The NavLink is active when it matches the entire current URL.
NavLinkMatch.Prefix (default) – The NavLink is active when it matches any prefix of the current URL.

In the preceding example, the Home NavLink href="" matches the home URL and only receives the active CSS
class at the app's default base path URL (for example, https://localhost:5001/ ). The second NavLink receives the
active class when the user visits any URL with a MyComponent prefix (for example,
https://localhost:5001/MyComponent and https://localhost:5001/MyComponent/AnotherSegment ).

URI and navigation state helpers

Use Microsoft.AspNetCore.Components.IUriHelper to work with URIs and navigation in C# code. IUriHelper
provides the event and methods shown in the following table.

MEMBER DESCRIPTION

GetAbsoluteUri Gets the current absolute URI.

GetBaseUri Gets the base URI (with a trailing slash) that can be prepended
to relative URI paths to produce an absolute URI. Typically,
GetBaseUri corresponds to the href attribute on the
document's <base> element in wwwroot/index.html (Blazor
client-side) or Pages/_Host.cshtml (Blazor server-side).

NavigateTo Navigates to the specified URI. If forceLoad is true :

Client-side routing is bypassed.
The browser is forced to load the new page from the
server, whether or not the URI is normally handled by
the client-side router.

OnLocationChanged An event that fires when the navigation location has changed.

ToAbsoluteUri Converts a relative URI into an absolute URI.

ToBaseRelativePath Given a base URI (for example, a URI previously returned by

GetBaseUri ), converts an absolute URI into a URI relative to
the base URI prefix.

The following component navigates to the app's Counter component when the button is selected:
@page "/navigate"
@using Microsoft.AspNetCore.Components
@inject IUriHelper UriHelper

<h1>Navigate in Code Example</h1>

<button class="btn btn-primary" @onclick="NavigateToCounterComponent">

Navigate to the Counter component
</button>

@code {
private void NavigateToCounterComponent()
{
UriHelper.NavigateTo("counter");
}
}
 ASP.NET Core Blazor JavaScript interop
7/31/2019 • 13 minutes to read • Edit Online

By Javier Calvarro Nelson, Daniel Roth, and Luke Latham

A Blazor app can invoke JavaScript functions from .NET and .NET methods from JavaScript code.
View or download sample code (how to download)

Invoke JavaScript functions from .NET methods

There are times when .NET code is required to call a JavaScript function. For example, a JavaScript call can expose
browser capabilities or functionality from a JavaScript library to the app.
To call into JavaScript from .NET, use the IJSRuntime abstraction. The InvokeAsync<T> method takes an identifier
for the JavaScript function that you wish to invoke along with any number of JSON -serializable arguments. The
function identifier is relative to the global scope ( window ). If you wish to call window.someScope.someFunction , the
identifier is someScope.someFunction . There's no need to register the function before it's called. The return type T
must also be JSON serializable.
For server-side apps:
Multiple user requests are processed by the server-side app. Don't call JSRuntime.Current in a component to
invoke JavaScript functions.
Inject the IJSRuntime abstraction and use the injected object to issue JavaScript interop calls.
While a Blazor app is prerendering, calling into JavaScript isn't possible because a connection with the browser
hasn't been established. For more information, see the Detect when a Blazor app is prerendering section.
The following example is based on TextDecoder, an experimental JavaScript-based decoder. The example
demonstrates how to invoke a JavaScript function from a C# method. The JavaScript function accepts a byte array
from a C# method, decodes the array, and returns the text to the component for display.
Inside the <head> element of wwwroot/index.html (Blazor client-side) or Pages/_Host.cshtml (Blazor server-side),
provide a function that uses TextDecoder to decode a passed array:

<script>
window.ConvertArray = (win1251Array) => {
var win1251decoder = new TextDecoder('windows-1251');
var bytes = new Uint8Array(win1251Array);
var decodedArray = win1251decoder.decode(bytes);
console.log(decodedArray);
return decodedArray;
};
</script>

JavaScript code, such as the code shown in the preceding example, can also be loaded from a JavaScript file (.js)
with a reference to the script file:

<script src="exampleJsInterop.js"></script>

The following component:

Invokes the ConvertArray JavaScript function using JsRuntime when a component button (Convert Array) is
 selected.
After the JavaScript function is called, the passed array is converted into a string. The string is returned to the
component for display.

@page "/call-js-example"
@inject IJSRuntime JsRuntime;

<h1>Call JavaScript Function Example</h1>

<button type="button" class="btn btn-primary" @onclick="ConvertArray">

Convert Array
</button>

<p class="mt-2" style="font-size:1.6em">

<span class="badge badge-success">
@ConvertedText
</span>
</p>

@code {
// Quote (c)2005 Universal Pictures: Serenity
// https://www.uphe.com/movies/serenity
// David Krumholtz on IMDB: https://www.imdb.com/name/nm0472710/

private MarkupString ConvertedText =

new MarkupString("Select the <b>Convert Array</b> button.");

private uint[] QuoteArray = new uint[]

{
60, 101, 109, 62, 67, 97, 110, 39, 116, 32, 115, 116, 111, 112, 32,
116, 104, 101, 32, 115, 105, 103, 110, 97, 108, 44, 32, 77, 97,
108, 46, 60, 47, 101, 109, 62, 32, 45, 32, 77, 114, 46, 32, 85, 110,
105, 118, 101, 114, 115, 101, 10, 10,
};

private async void ConvertArray()

{
var text =
await JsRuntime.InvokeAsync<string>("ConvertArray", QuoteArray);

ConvertedText = new MarkupString(text);

StateHasChanged();
}
}

To use the IJSRuntime abstraction, adopt any of the following approaches:

Inject the IJSRuntime abstraction into the Razor component (.razor):
 @inject IJSRuntime JSRuntime

@code {
public override void OnInit()
{
StocksService.OnStockTickerUpdated += stockUpdate =>
{
JSRuntime.InvokeAsync<object>(
"handleTickerChanged",
stockUpdate.symbol,
stockUpdate.price);
};
}
}

Inject the IJSRuntime abstraction into a class (.cs):

public class JsInteropClasses

{
private readonly IJSRuntime _jsRuntime;

public JsInteropClasses(IJSRuntime jsRuntime)

{
_jsRuntime = jsRuntime;
}

public Task<string> TickerChanged(string data)

{
// The handleTickerChanged JavaScript method is implemented
// in a JavaScript file, such as 'wwwroot/tickerJsInterop.js'.
return _jsRuntime.InvokeAsync<object>(
"handleTickerChanged",
stockUpdate.symbol,
stockUpdate.price);
}
}

For dynamic content generation with BuildRenderTree, use the [Inject] attribute:

[Inject]
IJSRuntime JSRuntime { get; set; }

In the client-side sample app that accompanies this topic, two JavaScript functions are available to the client-side
app that interact with the DOM to receive user input and display a welcome message:
showPrompt – Produces a prompt to accept user input (the user's name) and returns the name to the caller.
displayWelcome – Assigns a welcome message from the caller to a DOM object with an id of welcome .

wwwroot/exampleJsInterop.js:
 window.exampleJsFunctions = {
showPrompt: function (text) {
return prompt(text, 'Type your name here');
},
displayWelcome: function (welcomeMessage) {
document.getElementById('welcome').innerText = welcomeMessage;
},
returnArrayAsyncJs: function () {
DotNet.invokeMethodAsync('BlazorSample', 'ReturnArrayAsync')
.then(data => {
data.push(4);
console.log(data);
});
},
sayHello: function (dotnetHelper) {
return dotnetHelper.invokeMethodAsync('SayHello')
.then(r => console.log(r));
}
};

Place the <script> tag that references the JavaScript file in the wwwroot/index.html file (Blazor client-side) or
Pages/_Host.cshtml file (Blazor server-side).
wwwroot/index.html (Blazor client-side):

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width" />
<title>Blazor Sample</title>
<base href="/" />
<link href="css/bootstrap/bootstrap.min.css" rel="stylesheet" />
<link href="css/site.css" rel="stylesheet" />
</head>
<body>
<app>Loading...</app>

<script src="_framework/blazor.webassembly.js"></script>
<script src="exampleJsInterop.js"></script>
</body>
</html>

Pages/_Host.cshtml (Blazor server-side):

 @page "/"
@namespace blazorsample.Pages
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Blazor Sample (Server-side Example)</title>
<base href="~/" />
<environment include="Development">
<link rel="stylesheet" href="css/bootstrap/bootstrap.min.css" />
</environment>
<environment exclude="Development">
<link rel="stylesheet"
href="{CDN PATH TO bootstrap.min.css}"
asp-fallback-href="css/bootstrap/bootstrap.min.css"
asp-fallback-test-class="sr-only" asp-fallback-test-property="position"
asp-fallback-test-value="absolute" crossorigin="anonymous"
integrity="{SHA384 HASH}"/>
</environment>
<link href="css/site.css" rel="stylesheet" />
</head>
<body>
<app>@(await Html.RenderComponentAsync<App>())</app>

<script src="_framework/blazor.server.js"></script>
<script src="exampleJsInterop.js"></script>
</body>
</html>

Don't place a <script> tag in a component file because the <script> tag can't be updated dynamically.
.NET methods interop with the JavaScript functions in the exampleJsInterop.js file by calling
IJSRuntime.InvokeAsync<T> .

The IJSRuntime abstraction is asynchronous to allow for server-side scenarios. If the app runs client-side and you
want to invoke a JavaScript function synchronously, downcast to IJSInProcessRuntime and call Invoke<T> instead.
We recommend that most JavaScript interop libraries use the async APIs to ensure that the libraries are available
in all scenarios, client-side or server-side.
The sample app includes a component to demonstrate JavaScript interop. The component:
Receives user input via a JavaScript prompt.
Returns the text to the component for processing.
Calls a second JavaScript function that interacts with the DOM to display a welcome message.
Pages/JSInterop.razor:
 @page "/JSInterop"
@using BlazorSample.JsInteropClasses
@inject IJSRuntime JSRuntime

<h1>JavaScript Interop</h1>

<h2>Invoke JavaScript functions from .NET methods</h2>

<button type="button" class="btn btn-primary" @onclick="TriggerJsPrompt">

Trigger JavaScript Prompt
</button>

<h3 id="welcome" style="color:green;font-style:italic"></h3>

@code {
public async void TriggerJsPrompt()
{
// showPrompt is implemented in wwwroot/exampleJsInterop.js
var name = await JSRuntime.InvokeAsync<string>(
"exampleJsFunctions.showPrompt",
"What's your name?");
// displayWelcome is implemented in wwwroot/exampleJsInterop.js
await JSRuntime.InvokeAsync<string>(
"exampleJsFunctions.displayWelcome",
$"Hello {name}! Welcome to Blazor!");
}
}

1. When TriggerJsPrompt is executed by selecting the component's Trigger JavaScript Prompt button, the
JavaScript showPrompt function provided in the wwwroot/exampleJsInterop.js file is called.
2. The showPrompt function accepts user input (the user's name), which is HTML -encoded and returned to the
component. The component stores the user's name in a local variable, name .
3. The string stored in name is incorporated into a welcome message, which is passed to a JavaScript function,
displayWelcome , which renders the welcome message into a heading tag.

Call a void JavaScript function

JavaScript functions that return void(0)/void 0 or undefined are called with IJSRuntime.InvokeAsync<object> ,
which returns null .

Detect when a Blazor app is prerendering

While a Blazor server-side app is prerendering, certain actions, such as calling into JavaScript, aren't possible
because a connection with the browser hasn't been established. Components may need to render differently when
prerendered.
To delay JavaScript interop calls until after the connection with the browser is established, you can use the
OnAfterRenderAsync component lifecycle event. This event is only called after the app is fully rendered and the
client connection is established.
 @using Microsoft.JSInterop
@inject IJSRuntime JSRuntime

<input @ref="myInput" value="Value set during render" />

@code {
private ElementRef myInput;

protected override void OnAfterRender()

{
JSRuntime.InvokeAsync<object>(
"setElementValue", myInput, "Value set after render");
}
}

The following component demonstrates how to use JavaScript interop as part of a component's initialization logic
in a way that's compatible with prerendering. The component shows that it's possible to trigger a rendering
update from inside OnAfterRenderAsync . The developer must avoid creating an infinite loop in this scenario.
Where JSRuntime.InvokeAsync is called, ElementRef is only used in OnAfterRenderAsync and not in any earlier
lifecycle method because there's no JavaScript element until after the component is rendered.
StateHasChanged is called to rerender the component with the new state obtained from the JavaScript interop call.
The code doesn't create an infinite loop because StateHasChanged is only called when infoFromJs is null .
 @page "/prerendered-interop"
@using Microsoft.AspNetCore.Components
@using Microsoft.JSInterop
@inject IComponentContext ComponentContext
@inject IJSRuntime JSRuntime

<p>
Get value via JS interop call:
<strong id="val-get-by-interop">@(infoFromJs ?? "No value yet")</strong>
</p>

<p>
Set value via JS interop call:
<input id="val-set-by-interop" @ref="myElem" />
</p>

@code {
private string infoFromJs;
private ElementRef myElem;

protected override async Task OnAfterRenderAsync()

{
// TEMPORARY: Currently we need this guard to avoid making the interop
// call during prerendering. Soon this will be unnecessary because we
// will change OnAfterRenderAsync so that it won't run during the
// prerendering phase.
if (!ComponentContext.IsConnected)
{
return;
}

if (infoFromJs == null)
{
infoFromJs = await JSRuntime.InvokeAsync<string>(
"setElementValue", myElem, "Hello from interop call");

StateHasChanged();
}
}
}

To conditionally render different content based on whether the app is currently prerendering content, use the
IsConnected property on the IComponentContext service. When running server -side, IsConnected only returns
true if there's an active connection to the client. It always returns true when running client-side.
 @page "/isconnected-example"
@using Microsoft.AspNetCore.Components.Services
@inject IComponentContext ComponentContext

<h1>IsConnected Example</h1>

<p>
Current state:
<strong id="connected-state">
@(ComponentContext.IsConnected ? "connected" : "not connected")
</strong>
</p>

<p>
Clicks:
<strong id="count">@count</strong>
<button id="increment-count" @onclick="@(() => count++)">Click me</button>
</p>

@code {
private int count;
}

Capture references to elements

Some JavaScript interop scenarios require references to HTML elements. For example, a UI library may require
an element reference for initialization, or you might need to call command-like APIs on an element, such as
focus or play .

You can capture references to HTML elements in a component using the following approach:
Add a @ref attribute to the HTML element.
Define a field of type ElementRef whose name matches the value of the @ref attribute.

The following example shows capturing a reference to the username <input> element:

<input @ref="username" ... />

@code {
ElementRef username;
}

NOTE
Do not use captured element references as a way of populating or manipulating the DOM when Blazor interacts with the
elements referenced. Doing so may interfere with the declarative rendering model.

As far as .NET code is concerned, an ElementRef is an opaque handle. The only thing you can do with ElementRef
is pass it through to JavaScript code via JavaScript interop. When you do so, the JavaScript-side code receives an
HTMLElement instance, which it can use with normal DOM APIs.

For example, the following code defines a .NET extension method that enables setting the focus on an element:
exampleJsInterop.js:
 window.exampleJsFunctions = {
focusElement : function (element) {
element.focus();
}
}

Use IJSRuntime.InvokeAsync<T> and call exampleJsFunctions.focusElement with an ElementRef to focus an

element:

@inject IJSRuntime JSRuntime

<input @ref="username" />

<button @onclick="SetFocus">Set focus on username</button>

@code {
private ElementRef username;

public async void SetFocus()

{
await JSRuntime.InvokeAsync<object>(
"exampleJsFunctions.focusElement", username);
}
}

To use an extension method to focus an element, create a static extension method that receives the IJSRuntime
instance:

public static Task Focus(this ElementRef elementRef, IJSRuntime jsRuntime)

{
return jsRuntime.InvokeAsync<object>(
"exampleJsFunctions.focusElement", elementRef);
}

The method is called directly on the object. The following example assumes that the static Focus method is
available from the JsInteropClasses namespace:

@inject IJSRuntime JSRuntime

@using JsInteropClasses

<input @ref="username" />

<button @onclick="SetFocus">Set focus on username</button>

@code {
private ElementRef username;

public async Task SetFocus()

{
await username.Focus(JSRuntime);
}
}

IMPORTANT
The username variable is only populated after the component is rendered. If an unpopulated ElementRef is passed to
JavaScript code, the JavaScript code receives a value of null . To manipulate element references after the component has
finished rendering (to set the initial focus on an element) use the OnAfterRenderAsync or OnAfterRender component
lifecycle methods.
Invoke .NET methods from JavaScript functions
Static .NET method call
To invoke a static .NET method from JavaScript, use the DotNet.invokeMethod or DotNet.invokeMethodAsync
functions. Pass in the identifier of the static method you wish to call, the name of the assembly containing the
function, and any arguments. The asynchronous version is preferred to support server-side scenarios. To invoke a
.NET method from JavaScript, the .NET method must be public, static, and have the [JSInvokable] attribute. By
default, the method identifier is the method name, but you can specify a different identifier using the
JSInvokableAttribute constructor. Calling open generic methods isn't currently supported.

The sample app includes a C# method to return an array of int s. The JSInvokable attribute is applied to the
method.
Pages/JsInterop.razor:

<button type="button" class="btn btn-primary"

onclick="exampleJsFunctions.returnArrayAsyncJs()">
Trigger .NET static method ReturnArrayAsync
</button>

@code {
[JSInvokable]
public static Task<int[]> ReturnArrayAsync()
{
return Task.FromResult(new int[] { 1, 2, 3 });
}
}

JavaScript served to the client invokes the C# .NET method.

wwwroot/exampleJsInterop.js:

window.exampleJsFunctions = {
showPrompt: function (text) {
return prompt(text, 'Type your name here');
},
displayWelcome: function (welcomeMessage) {
document.getElementById('welcome').innerText = welcomeMessage;
},
returnArrayAsyncJs: function () {
DotNet.invokeMethodAsync('BlazorSample', 'ReturnArrayAsync')
.then(data => {
data.push(4);
console.log(data);
});
},
sayHello: function (dotnetHelper) {
return dotnetHelper.invokeMethodAsync('SayHello')
.then(r => console.log(r));
}
};

When the Trigger .NET static method ReturnArrayAsync button is selected, examine the console output in the
browser's web developer tools.
The console output is:

Array(4) [ 1, 2, 3, 4 ]
The fourth array value is pushed to the array ( data.push(4); ) returned by ReturnArrayAsync .
Instance method call
You can also call .NET instance methods from JavaScript. To invoke a .NET instance method from JavaScript:
Pass the .NET instance to JavaScript by wrapping it in a DotNetObjectRef instance. The .NET instance is passed
by reference to JavaScript.
Invoke .NET instance methods on the instance using the invokeMethod or invokeMethodAsync functions. The
.NET instance can also be passed as an argument when invoking other .NET methods from JavaScript.

NOTE
The sample app logs messages to the client-side console. For the following examples demonstrated by the sample app,
examine the browser's console output in the browser's developer tools.

When the Trigger .NET instance method HelloHelper.SayHello button is selected,

ExampleJsInterop.CallHelloHelperSayHello is called and passes a name, Blazor , to the method.

Pages/JsInterop.razor:

<button type="button" class="btn btn-primary" @onclick="TriggerNetInstanceMethod">

Trigger .NET instance method HelloHelper.SayHello
</button>

@code {
public async void TriggerNetInstanceMethod()
{
var exampleJsInterop = new ExampleJsInterop(JSRuntime);
await exampleJsInterop.CallHelloHelperSayHello("Blazor");
}
}

CallHelloHelperSayHello invokes the JavaScript function sayHello with a new instance of HelloHelper .
JsInteropClasses/ExampleJsInterop.cs:

public class ExampleJsInterop

{
private readonly IJSRuntime _jsRuntime;

public ExampleJsInterop(IJSRuntime jsRuntime)

{
_jsRuntime = jsRuntime;
}

public Task CallHelloHelperSayHello(string name)

{
// sayHello is implemented in wwwroot/exampleJsInterop.js
return _jsRuntime.InvokeAsync<object>(
"exampleJsFunctions.sayHello",
DotNetObjectRef.Create(new HelloHelper(name)));
}
}

wwwroot/exampleJsInterop.js:
 window.exampleJsFunctions = {
showPrompt: function (text) {
return prompt(text, 'Type your name here');
},
displayWelcome: function (welcomeMessage) {
document.getElementById('welcome').innerText = welcomeMessage;
},
returnArrayAsyncJs: function () {
DotNet.invokeMethodAsync('BlazorSample', 'ReturnArrayAsync')
.then(data => {
data.push(4);
console.log(data);
});
},
sayHello: function (dotnetHelper) {
return dotnetHelper.invokeMethodAsync('SayHello')
.then(r => console.log(r));
}
};

The name is passed to HelloHelper 's constructor, which sets the HelloHelper.Name property. When the JavaScript
function sayHello is executed, HelloHelper.SayHello returns the Hello, {Name}! message, which is written to the
console by the JavaScript function.
JsInteropClasses/HelloHelper.cs:

public class HelloHelper

{
public HelloHelper(string name)
{
Name = name;
}

public string Name { get; set; }

[JSInvokable]
public string SayHello() => $"Hello, {Name}!";
}

Console output in the browser's web developer tools:

Hello, Blazor!

Share interop code in a class library

JavaScript interop code can be included in a class library, which allows you to share the code in a NuGet package.
The class library handles embedding JavaScript resources in the built assembly. The JavaScript files are placed in
the wwwroot folder. The tooling takes care of embedding the resources when the library is built.
The built NuGet package is referenced in the app's project file the same way that any NuGet package is
referenced. After the package is restored, app code can call into JavaScript as if it were C#.
For more information, see ASP.NET Core Razor components class libraries.
 ASP.NET Core Blazor authentication and
authorization
8/13/2019 • 10 minutes to read • Edit Online

By Steve Sanderson
ASP.NET Core supports the configuration and management of security in Blazor apps.
Security scenarios differ between Blazor server-side and client-side apps. Because Blazor server-side apps run on
the server, authorization checks are able to determine:
The UI options presented to a user (for example, which menu entries are available to a user).
Access rules for areas of the app and components.
Blazor client-side apps run on the client. Authorization is only used to determine which UI options to show. Since
client-side checks can be modified or bypassed by a user, a Blazor client-side app can't enforce authorization access
rules.

Authentication
Blazor uses the existing ASP.NET Core authentication mechanisms to establish the user's identity. The exact
mechanism depends on how the Blazor app is hosted, server-side or client-side.
Blazor server-side authentication
Blazor server-side apps operate over a real-time connection that's created using SignalR. Authentication in
SignalR -based apps is handled when the connection is established. Authentication can be based on a cookie or
some other bearer token.
The Blazor server-side project template can set up authentication for you when the project is created.
Visual Studio
Visual Studio Code
Follow the Visual Studio guidance in the Get started with ASP.NET Core Blazor article to create a new Blazor
server-side project with an authentication mechanism.
After choosing the Blazor Server App template in the Create a new ASP.NET Core Web Application dialog,
select Change under Authentication.
A dialog opens to offer the same set of authentication mechanisms available for other ASP.NET Core projects:
No Authentication
Individual User Accounts – User accounts can be stored:
Within the app using ASP.NET Core's Identity system.
With Azure AD B2C.
Work or School Accounts
Windows Authentication
Blazor client-side authentication
In Blazor client-side apps, authentication checks can be bypassed because all client-side code can be modified by
users. The same is true for all client-side app technologies, including JavaScript SPA frameworks or native apps for
any operating system.
Implementation of a custom AuthenticationStateProvider service for Blazor client-side apps is covered in the
following sections.

AuthenticationStateProvider service
Blazor server-side apps include a built-in AuthenticationStateProvider service that obtains authentication state
data from ASP.NET Core's HttpContext.User . This is how authentication state integrates with existing ASP.NET
Core server-side authentication mechanisms.
AuthenticationStateProvider is the underlying service used by the AuthorizeView component and
CascadingAuthenticationState component to get the authentication state.

You don't typically use AuthenticationStateProvider directly. Use the AuthorizeView component or Task
approaches described later in this article. The main drawback to using AuthenticationStateProvider directly is that
the component isn't notified automatically if the underlying authentication state data changes.
The AuthenticationStateProvider service can provide the current user's ClaimsPrincipal data, as shown in the
following example:

@page "/"
@inject AuthenticationStateProvider AuthenticationStateProvider

<button @onclick="@LogUsername">Write user info to console</button>

@code {
private async Task LogUsername()
{
var authState = await AuthenticationStateProvider.GetAuthenticationStateAsync();
var user = authState.User;

if (user.Identity.IsAuthenticated)
{
Console.WriteLine($"{user.Identity.Name} is authenticated.");
}
else
{
Console.WriteLine("The user is NOT authenticated.");
}
}
}

If user.Identity.IsAuthenticated is true and because the user is a ClaimsPrincipal, claims can be enumerated and
membership in roles evaluated.
For more information on dependency injection (DI) and services, see ASP.NET Core Blazor dependency injection
and Dependency injection in ASP.NET Core.

Implement a custom AuthenticationStateProvider

If you're building a Blazor client-side app or if your app's specification absolutely requires a custom provider,
implement a provider and override GetAuthenticationStateAsync :
 class CustomAuthStateProvider : AuthenticationStateProvider
{
public override Task<AuthenticationState> GetAuthenticationStateAsync()
{
var identity = new ClaimsIdentity(new[]
{
new Claim(ClaimTypes.Name, "mrfibuli"),
}, "Fake authentication type");

var user = new ClaimsPrincipal(identity);

return Task.FromResult(new AuthenticationState(user));

}
}

The CustomAuthStateProvider service is registered in Startup.ConfigureServices :

public void ConfigureServices(IServiceCollection services)

{
services.AddScoped<AuthenticationStateProvider, CustomAuthStateProvider>();
}

Using the CustomAuthStateProvider , all users are authenticated with the username mrfibuli .

Expose the authentication state as a cascading parameter

If authentication state data is required for procedural logic, such as when performing an action triggered by the
user, obtain the authentication state data by defining a cascading parameter of type Task<AuthenticationState> :

@page "/"

<button @onclick="@LogUsername">Log username</button>

@code {
[CascadingParameter]
private Task<AuthenticationState> authenticationStateTask { get; set; }

private async Task LogUsername()

{
var authState = await authenticationStateTask;
var user = authState.User;

if (user.Identity.IsAuthenticated)
{
Console.WriteLine($"{user.Identity.Name} is authenticated.");
}
else
{
Console.WriteLine("The user is NOT authenticated.");
}
}
}

If user.Identity.IsAuthenticated is true , claims can be enumerated and membership in roles evaluated.

Set up the Task<AuthenticationState> cascading parameter using the CascadingAuthenticationState component:
 <CascadingAuthenticationState>
<Router AppAssembly="typeof(Startup).Assembly">
<NotFoundContent>
<h1>Sorry</h1>
<p>Sorry, there's nothing at this address.</p>
</NotFoundContent>
</Router>
</CascadingAuthenticationState>

Authorization
After a user is authenticated, authorization rules are applied to control what the user can do.
Access is typically granted or denied based on whether:
A user is authenticated (signed in).
A user is in a role.
A user has a claim.
A policy is satisfied.
Each of these concepts is the same as in an ASP.NET Core MVC or Razor Pages app. For more information on
ASP.NET Core security, see the articles under ASP.NET Core Security and Identity.

AuthorizeView component
The AuthorizeView component selectively displays UI depending on whether the user is authorized to see it. This
approach is useful when you only need to display data for the user and don't need to use the user's identity in
procedural logic.
The component exposes a context variable of type AuthenticationState , which you can use to access information
about the signed-in user:

<AuthorizeView>
<h1>Hello, @context.User.Identity.Name!</h1>
<p>You can only see this content if you're authenticated.</p>
</AuthorizeView>

You can also supply different content for display if the user isn't authenticated:

<AuthorizeView>
<Authorized>
<h1>Hello, @context.User.Identity.Name!</h1>
<p>You can only see this content if you're authenticated.</p>
</Authorized>
<NotAuthorized>
<h1>Authentication Failure!</h1>
<p>You're not signed in.</p>
</NotAuthorized>
</AuthorizeView>

The content of <Authorized> and <NotAuthorized> can include arbitrary items, such as other interactive
components.
Authorization conditions, such as roles or policies that control UI options or access, are covered in the
Authorization section.
If authorization conditions aren't specified, AuthorizeView uses a default policy and treats:
 Authenticated (signed-in) users as authorized.
Unauthenticated (signed-out) users as unauthorized.
Role -based and policy-based authorization
The AuthorizeView component supports role-based or policy-based authorization.
For role-based authorization, use the Roles parameter:

<AuthorizeView Roles="admin, superuser">

<p>You can only see this if you're an admin or superuser.</p>
</AuthorizeView>

For more information, see Role-based authorization in ASP.NET Core.

For policy-based authorization, use the Policy parameter:

<AuthorizeView Policy="content-editor">
<p>You can only see this if you satisfy the "content-editor" policy.</p>
</AuthorizeView>

Claims-based authorization is a special case of policy-based authorization. For example, you can define a policy that
requires users to have a certain claim. For more information, see Policy-based authorization in ASP.NET Core.
These APIs can be used in either Blazor server-side or Blazor client-side apps.
If neither Roles nor Policy is specified, AuthorizeView uses the default policy.
Content displayed during asynchronous authentication
Blazor allows for authentication state to be determined asynchronously. The primary scenario for this approach is
in Blazor client-side apps that make a request to an external endpoint for authentication.
While authentication is in progress, AuthorizeView displays no content by default. To display content while
authentication occurs, use the <Authorizing> element:

<AuthorizeView>
<Authorized>
<h1>Hello, @context.User.Identity.Name!</h1>
<p>You can only see this content if you're authenticated.</p>
</Authorized>
<Authorizing>
<h1>Authentication in progress</h1>
<p>You can only see this content while authentication is in progress.</p>
</Authorizing>
</AuthorizeView>

This approach isn't normally applicable to Blazor server-side apps. Blazor server-side apps know the authentication
state as soon as the state is established. Authorizing content can be provided in a Blazor server-side app's
AuthorizeView component, but the content is never displayed.

[Authorize] attribute
Just like an app can use [Authorize] with an MVC controller or Razor page, [Authorize] can also be used with
Razor Components:
 @page "/"
@attribute [Authorize]

You can only see this if you're signed in.

IMPORTANT
Only use [Authorize] on @page components reached via the Blazor Router. Authorization is only performed as an aspect
of routing and not for child components rendered within a page. To authorize the display of specific parts within a page, use
AuthorizeView instead.

You may need to add @using Microsoft.AspNetCore.Authorization either to the component or to the _Imports.razor
file in order for the component to compile.
The [Authorize] attribute also supports role-based or policy-based authorization. For role-based authorization,
use the Roles parameter:

@page "/"
@attribute [Authorize(Roles = "admin, superuser")]

<p>You can only see this if you're in the 'admin' or 'superuser' role.</p>

For policy-based authorization, use the Policy parameter:

@page "/"
@attribute [Authorize(Policy = "content-editor")]

<p>You can only see this if you satisfy the 'content-editor' policy.</p>

If neither Roles nor Policy is specified, [Authorize] uses the default policy, which by default is to treat:
Authenticated (signed-in) users as authorized.
Unauthenticated (signed-out) users as unauthorized.

Customize unauthorized content with the Router component

The Router component allows the app to specify custom content if:
Content isn't found.
The user fails an [Authorize] condition applied to the component. The [Authorize] attribute is covered in the
[Authorize] attribute section.
Asynchronous authentication is in progress.
In the default Blazor server-side project template, the App.razor file demonstrates how to set custom content:
 <CascadingAuthenticationState>
<Router AppAssembly="typeof(Startup).Assembly">
<NotFoundContent>
<h1>Sorry</h1>
<p>Sorry, there's nothing at this address.</p>
</NotFoundContent>
<NotAuthorizedContent>
<h1>Sorry</h1>
<p>You're not authorized to reach this page.</p>
<p>You may need to log in as a different user.</p>
</NotAuthorizedContent>
<AuthorizingContent>
<h1>Authentication in progress</h1>
<p>Only visible while authentication is in progress.</p>
</AuthorizingContent>
</Router>
</CascadingAuthenticationState>

The content of <NotFoundContent> , <NotAuthorizedContent> , and <AuthorizingContent> can include arbitrary items,
such as other interactive components.
If <NotAuthorizedContent> isn't specified, the router uses the following fallback message:

Not authorized.

Notification about authentication state changes

If the app determines that the underlying authentication state data has changed (for example, because the user
signed out or another user has changed their roles), a custom AuthenticationStateProvider can optionally invoke
the method NotifyAuthenticationStateChanged on the AuthenticationStateProvider base class. This notifies
consumers of the authentication state data (for example, AuthorizeView ) to rerender using the new data.

Procedural logic
If the app is required to check authorization rules as part of procedural logic, use a cascaded parameter of type
Task<AuthenticationState> to obtain the user's ClaimsPrincipal. Task<AuthenticationState> can be combined with
other services, such as IAuthorizationService , to evaluate policies.
 @inject IAuthorizationService AuthorizationService

<button @onclick="@DoSomething">Do something important</button>

@code {
[CascadingParameter]
private Task<AuthenticationState> authenticationStateTask { get; set; }

private async Task DoSomething()

{
var user = (await authenticationStateTask).User;

if (user.Identity.IsAuthenticated)
{
// Perform an action only available to authenticated (signed-in) users.
}

if (user.IsInRole("admin"))
{
// Perform an action only available to users in the 'admin' role.
}

if ((await AuthorizationService.AuthorizeAsync(user, "content-editor"))

.Succeeded)
{
// Perform an action only available to users satisfying the
// 'content-editor' policy.
}
}
}

Authorization in Blazor client-side apps

In Blazor client-side apps, authorization checks can be bypassed because all client-side code can be modified by
users. The same is true for all client-side app technologies, including JavaScript SPA frameworks or native apps for
any operating system.
Always perform authorization checks on the server within any API endpoints accessed by your client-
side app.

Troubleshoot errors
Common errors:
Authorization requires a cascading parameter of type Task<AuthenticationState>. Consider using
CascadingAuthenticationState to supply this.
null value is received for authenticationStateTask

It's likely that the project wasn't created using a Blazor server-side template with authentication enabled. Wrap a
<CascadingAuthenticationState> around some part of the UI tree, for example in App.razor as follows:

<CascadingAuthenticationState>
<Router AppAssembly="typeof(Startup).Assembly">
...
</Router>
</CascadingAuthenticationState>

The CascadingAuthenticationState supplies the Task<AuthenticationState> cascading parameter, which in turn it

receives from the underlying AuthenticationStateProvider DI service.
Additional resources
Overview of ASP.NET Core Security
Configure Windows Authentication in ASP.NET Core
 ASP.NET Core Blazor state management
8/7/2019 • 12 minutes to read • Edit Online

By Steve Sanderson
Blazor server-side is a stateful app framework. Most of the time, the app maintains an ongoing connection to the
server. The user's state is held in the server's memory in a circuit.
Examples of state held for a user's circuit include:
The rendered UI—the hierarchy of component instances and their most recent render output.
The values of any fields and properties in component instances.
Data held in dependency injection (DI) service instances that are scoped to the circuit.

NOTE
This article addresses state persistence in Blazor server-side apps. Blazor client-side apps can take advantage of client-side
state persistence in the browser but require custom solutions or 3rd party packages beyond the scope of this article.

Blazor circuits
If a user experiences a temporary network connection loss, Blazor attempts to reconnect the user to their original
circuit so they can continue to use the app. However, reconnecting a user to their original circuit in the server's
memory isn't always possible:
The server can't retain a disconnected circuit forever. The server must release a disconnected circuit after a
timeout or when the server is under memory pressure.
In multiserver, load-balanced deployment environments, any server processing requests may become
unavailable at any given time. Individual servers may fail or be automatically removed when no longer required
to handle the overall volume of requests. The original server may not be available when the user attempts to
reconnect.
The user might close and re-open their browser or reload the page, which removes any state held in the
browser's memory. For example, values set through JavaScript interop calls are lost.
When a user can't be reconnected to their original circuit, the user receives a new circuit with an empty state. This is
equivalent to closing and re-opening a desktop app.

Preserve state across circuits

In some scenarios, preserving state across circuits is desirable. An app can retain important data for a user if:
The web server becomes unavailable.
The user's browser is forced to start a new circuit with a new web server.
In general, maintaining state across circuits applies to scenarios where users are actively creating data, not simply
reading data that already exists.
To preserve state beyond a single circuit, don't merely store the data in the server's memory. The app must persist
the data to some other storage location. State persistence isn't automatic—you must take steps when developing
the app to implement stateful data persistence.
Data persistence is typically only required for high-value state that users have expended effort to create. In the
following examples, persisting state either saves time or aids in commercial activities:
Multistep webform – It's time-consuming for a user to re-enter data for several completed steps of a multistep
process if their state is lost. A user loses state in this scenario if they navigate away from the multistep form and
return to the form later.
Shopping cart – Any commercially important component of an app that represents potential revenue can be
maintained. A user who loses their state, and thus their shopping cart, may purchase fewer products or services
when they return to the site later.
It's usually not necessary to preserve easily-recreated state, such as the username entered into a sign-in dialog that
hasn't been submitted.

IMPORTANT
An app can only persist app state. UIs can't be persisted, such as component instances and their render trees. Components
and render trees aren't generally serializable. To persist something similar to UI state, such as the expanded nodes of a
TreeView, the app must have custom code to model the behavior as serializable app state.

Where to persist state

Three common locations exist for persisting state in a Blazor server-side app. Each approach is best suited to
different scenarios and has different caveats:
Server-side in a database
URL
Client-side in the browser
Server-side in a database
For permanent data persistence or for any data that must span multiple users or devices, an independent server-
side database is almost certainly the best choice. Options include:
Relational SQL database
Key-value store
Blob store
Table store
After data is saved in the database, a new circuit can be started by a user at any time. The user's data is retained
and available in any new circuit.
For more information on Azure data storage options, see the Azure Storage Documentation and Azure Databases.
URL
For transient data representing navigation state, model the data as a part of the URL. Examples of state modeled in
the URL include:
The ID of a viewed entity.
The current page number in a paged grid.
The contents of the browser's address bar are retained:
If the user manually reloads the page.
If the web server becomes unavailable—the user is forced to reload the page in order to connect to a different
server.
For information on defining URL patterns with the @page directive, see ASP.NET Core Blazor routing.
Client-side in the browser
For transient data that the user is actively creating, a common backing store is the browser's localStorage and
sessionStorage collections. The app isn't required to manage or clear the stored state if the circuit is abandoned,
which is an advantage over server-side storage.

NOTE
"Client-side" in this section refers to client-side scenarios in the browser, not the Blazor client-side hosting model.
localStorage and sessionStorage can be used in Blazor client-side apps but only by writing custom code or using a 3rd
party package.

localStorage and sessionStorage differ as follows:

localStorage is scoped to the user's browser. If the user reloads the page or closes and re-opens the browser,
the state persists. If the user opens multiple browser tabs, the state is shared across the tabs. Data persists in
localStorage until explicitly cleared.
sessionStorage is scoped to the user's browser tab. If the user reloads the tab, the state persists. If the user
closes the tab or the browser, the state is lost. If the user opens multiple browser tabs, each tab has its own
independent version of the data.
Generally, sessionStorage is safer to use. sessionStorage avoids the risk that a user opens multiple tabs and
encounters the following:
Bugs in state storage across tabs.
Confusing behavior when a tab overwrites the state of other tabs.
localStorage is the better choice if the app must persist state across closing and re-opening the browser.
Caveats for using browser storage:
Similar to the use of a server-side database, loading and saving data are asynchronous.
Unlike a server-side database, storage isn't available during prerendering because the requested page doesn't
exist in the browser during the prerendering stage.
Storage of a few kilobytes of data is reasonable to persist for Blazor server-side apps. Beyond a few kilobytes,
you must consider the performance implications because the data is loaded and saved across the network.
Users may view or tamper with the data. ASP.NET Core Data Protection can mitigate the risk.

Third-party browser storage solutions

Third-party NuGet packages provide APIs for working with localStorage and sessionStorage .
It's worth considering choosing a package that transparently uses ASP.NET Core's Data Protection. ASP.NET Core
Data Protection encrypts stored data and reduces the potential risk of tampering with stored data. If JSON -
serialized data is stored in plaintext, users can see the data using browser developer tools and also modify the
stored data. Securing data isn't always a problem because the data might be trivial in nature. For example, reading
or modifying the stored color of a UI element isn't a significant security risk to the user or the organization. Avoid
allowing users to inspect or tamper with sensitive data.

Protected Browser Storage experimental package

An example of a NuGet package that provides Data Protection for localStorage and sessionStorage is
Microsoft.AspNetCore.ProtectedBrowserStorage.
 WARNING
Microsoft.AspNetCore.ProtectedBrowserStorage is an unsupported experimental package unsuitable for production use
at this time.

Installation
To install the Microsoft.AspNetCore.ProtectedBrowserStorage package:
1. In the Blazor server-side app project, add a package reference to
Microsoft.AspNetCore.ProtectedBrowserStorage.
2. In the top-level HTML (for example, in the Pages/_Host.cshtml file in the default project template), add the
following <script> tag:

<script src="_content/Microsoft.AspNetCore.ProtectedBrowserStorage/protectedBrowserStorage.js"></script>

3. In the Startup.ConfigureServices method, call AddProtectedBrowserStorage to add localStorage and

sessionStorage services to the service collection:

services.AddProtectedBrowserStorage();

Save and load data within a component

In any component that requires loading or saving data to browser storage, use @inject to inject an instance of
either of the following:
ProtectedLocalStorage
ProtectedSessionStorage

The choice depends on which backing store you wish to use. In the following example, sessionStorage is used:

@using Microsoft.AspNetCore.ProtectedBrowserStorage
@inject ProtectedSessionStorage ProtectedSessionStore

The @using statement can be placed into an _Imports.razor file instead of in the component. Use of the
_Imports.razor file makes the namespace available to larger segments of the app or the whole app.
To persist the currentCount value in the Counter component of the project template, modify the IncrementCount
method to use ProtectedSessionStore.SetAsync :

private async Task IncrementCount()

{
currentCount++;
await ProtectedSessionStore.SetAsync("count", currentCount);
}

In larger, more realistic apps, storage of individual fields is an unlikely scenario. Apps are more likely to store entire
model objects that include complex state. ProtectedSessionStore automatically serializes and deserializes JSON
data.
In the preceding code example, the currentCount data is stored as sessionStorage['count'] in the user's browser.
The data isn't stored in plaintext but rather is protected using ASP.NET Core's Data Protection. The encrypted data
can be seen if sessionStorage['count'] is evaluated in the browser's developer console.
To recover the currentCount data if the user returns to the Counter component later (including if they're on an
entirely new circuit), use ProtectedSessionStore.GetAsync :

protected override async Task OnInitializedAsync()

{
currentCount = await ProtectedSessionStore.GetAsync<int>("count");
}

If the component's parameters include navigation state, call ProtectedSessionStore.GetAsync and assign the result
in OnParametersSetAsync , not OnInitializedAsync . OnInitializedAsync is only called one time when the component
is first instantiated. OnInitializedAsync isn't called again later if the user navigates to a different URL while
remaining on the same page.

WARNING
The examples in this section only work if the server doesn't have prerendering enabled. With prerendering enabled, an error is
generated similar to:

JavaScript interop calls cannot be issued at this time. This is because the component is being prerendered.

Either disable prerendering or add additional code to work with prerendering. To learn more about writing code that works
with prerendering, see the Handle prerendering section.

Handle the loading state

Since browser storage is asynchronous (accessed over a network connection), there's always a period of time
before the data is loaded and available for use by a component. For the best results, render a loading-state
message while loading is in progress instead of displaying blank or default data.
One approach is to track whether the data is null (still loading) or not. In the default Counter component, the
count is held in an int . Make currentCount nullable by adding a question mark ( ? ) to the type ( int ):

private int? currentCount;

Instead of unconditionally displaying the count and Increment button, choose to display these elements only if the
data is loaded:

@if (currentCount.HasValue)
{
<p>Current count: <strong>@currentCount</strong></p>

<button @onclick="IncrementCount">Increment</button>
}
else
{
<p>Loading...</p>
}

Handle prerendering
During prerendering:
An interactive connection to the user's browser doesn't exist.
The browser doesn't yet have a page in which it can run JavaScript code.
localStorage or sessionStorage aren't available during prerendering. If the component attempts to interact with
storage, an error is generated similar to:

JavaScript interop calls cannot be issued at this time. This is because the component is being prerendered.

One way to resolve the error is to disable prerendering. This is usually the best choice if the app makes heavy use
of browser-based storage. Prerendering adds complexity and doesn't benefit the app because the app can't
prerender any useful content until localStorage or sessionStorage are available.
To disable prerendering:
1. Open the Pages/_Host.cshtml file and remove the call to Html.RenderComponentAsync .
2. Open the Startup.cs file and replace the call to endpoints.MapBlazorHub() with
endpoints.MapBlazorHub<App>("app") . App is the type of the root component. "app" is a CSS selector specifying
the location for the root component.
Prerendering might be useful for other pages that don't use localStorage or sessionStorage . To keep
prerendering enabled, defer the loading operation until the browser is connected to the circuit. The following is an
example for storing a counter value:
 @using Microsoft.AspNetCore.ProtectedBrowserStorage
@inject ProtectedLocalStorage ProtectedLocalStore
@inject IComponentContext ComponentContext

... rendering code goes here ...

@code {
private int? currentCount;
private bool isWaitingForConnection;

protected override async Task OnInitAsync()

{
if (ComponentContext.IsConnected)
{
// It looks like the app isn't prerendering, so the data can be
// immediately loaded from browser storage.
await LoadStateAsync();
}
else
{
// Prerendering is in progress, so the app defers the load operation
// until later.
isWaitingForConnection = true;
}
}

protected override async Task OnAfterRenderAsync()

{
// By this stage, the client has connected back to the server, and
// browser services are available. If the app didn't load the data earlier,
// the app should do so now and then trigger a new render.
if (isWaitingForConnection)
{
isWaitingForConnection = false;
await LoadStateAsync();
StateHasChanged();
}
}

private async Task LoadStateAsync()

{
currentCount = await ProtectedLocalStore.GetAsync<int>("prerenderedCount");
}

private async Task IncrementCount()

{
currentCount++;
await ProtectedSessionStore.SetAsync("count", currentCount);
}
}

Factor out the state preservation to a common location

If many components rely on browser-based storage, re-implementing state provider code many times creates code
duplication. One option for avoiding code duplication is to create a state provider parent component that
encapsulates the state provider logic. Child components can work with persisted data without regard to the state
persistence mechanism.
In the following example of a CounterStateProvider component, counter data is persisted:
 @using Microsoft.AspNetCore.ProtectedBrowserStorage
@inject ProtectedSessionStorage ProtectedSessionStore

@if (hasLoaded)
{
<CascadingValue Value="@this">
@ChildContent
</CascadingValue>
}
else
{
<p>Loading...</p>
}

@code {
private bool hasLoaded;

[Parameter]
public RenderFragment ChildContent { get; set; }

public int CurrentCount { get; set; }

protected override async Task OnInitAsync()

{
CurrentCount = await ProtectedSessionStore.GetAsync<int>("count");
hasLoaded = true;
}

public async Task SaveChangesAsync()

{
await ProtectedSessionStore.SetAsync("count", CurrentCount);
}
}

The CounterStateProvider component handles the loading phase by not rendering its child content until loading is
complete.
To use the CounterStateProvider component, wrap an instance of the component around any other component
that requires access to the counter state. To make the state accessible to all components in an app, wrap the
CounterStateProvider component around the Router in the App component ( App.razor):

<CounterStateProvider>
<Router AppAssembly="typeof(Startup).Assembly">
...
</Router>
</CounterStateProvider>

Wrapped components receive and can modify the persisted counter state. The following Counter component
implements the pattern:
 @page "/counter"

<p>Current count: <strong>@CounterStateProvider.CurrentCount</strong></p>

<button @onclick="IncrementCount">Increment</button>

@code {
[CascadingParameter]
private CounterStateProvider CounterStateProvider { get; set; }

private async Task IncrementCount()

{
CounterStateProvider.CurrentCount++;
await CounterStateProvider.SaveChangesAsync();
}
}

The preceding component isn't required to interact with ProtectedBrowserStorage , nor does it deal with a "loading"
phase.
To deal with prerendering as described earlier, CounterStateProvider can be amended so that all of the components
that consume the counter data automatically work with prerendering. See the Handle prerendering section for
details.
In general, state provider parent component pattern is recommended:
To consume state in many other components.
If there's just one top-level state object to persist.
To persist many different state objects and consume different subsets of objects in different places, it's better to
avoid handling the loading and saving of state globally.
 Handle errors in ASP.NET Core Blazor apps
8/9/2019 • 10 minutes to read • Edit Online

By Steve Sanderson
This article describes how Blazor manages unhandled exceptions and how to develop apps that detect and handle
errors.

How the Blazor framework reacts to unhandled exceptions

Blazor server-side is a stateful framework. While users interact with an app, they maintain a connection to the
server known as a circuit. The circuit holds active component instances, plus many other aspects of state, such as:
The most recent rendered output of components.
The current set of event-handling delegates that could be triggered by client-side events.
If a user opens the app in multiple browser tabs, they have multiple independent circuits.
Blazor treats most unhandled exceptions as fatal to the circuit where they occur. If a circuit is terminated due to an
unhandled exception, the user can only continue to interact with the app by reloading the page to create a new
circuit. Circuits outside of the one that's terminated, which are circuits for other users or other browser tabs, aren't
affected. This scenario is similar to a desktop app that crashes—the crashed app must be restarted, but other apps
aren't affected.
A circuit is terminated when an unhandled exception occurs for the following reasons:
An unhandled exception often leaves the circuit in an undefined state.
The app's normal operation can't be guaranteed after an unhandled exception.
Security vulnerabilities may appear in the app if the circuit continues.

Manage unhandled exceptions in developer code

For an app to continue after an error, the app must have error handling logic. Later sections of this article describe
potential sources of unhandled exceptions.
In production, don't render framework exception messages or stack traces in the UI. Rendering exception messages
or stack traces could:
Disclose sensitive information to end users.
Help a malicious user discover weaknesses in an app that can compromise the security of the app, server, or
network.

Log errors with a persistent provider

If an unhandled exception occurs, the exception is logged to ILogger instances configured in the service container.
By default, Blazor apps log to console output with the Console Logging Provider. Consider logging to a more
permanent location with a provider that manages log size and log rotation. For more information, see Logging in
.NET Core and ASP.NET Core.
During development, Blazor usually sends the full details of exceptions to the browser's console to aid in
debugging. In production, detailed errors in the browser's console are disabled by default, which means that errors
aren't sent to clients but the exception's full details are still logged server-side. For more information, see Handle
errors in ASP.NET Core.
You must decide which incidents to log and the level of severity of logged incidents. Hostile users might be able to
trigger errors deliberately. For example, don't log an incident from an error where an unknown ProductId is
supplied in the URL of a component that displays product details. Not all errors should be treated as high-severity
incidents for logging.

Places where errors may occur

Framework and app code may trigger unhandled exceptions in any of the following locations:
Component instantiation
Lifecycle methods
Rendering logic
Event handlers
Component disposal
JavaScript interop
Circuit handlers
Circuit disposal
Prerendering
The preceding unhandled exceptions are described in the following sections of this article.
Component instantiation
When Blazor creates an instance of a component:
The component's constructor is invoked.
The constructors of any non-singleton DI services supplied to the component's constructor via the @inject
directive or the [Inject] attribute are invoked.
A circuit fails when any executed constructor or a setter for any [Inject] property throws an unhandled exception.
The exception is fatal because the framework can't instantiate the component. If constructor logic may throw
exceptions, the app should trap the exceptions using a try-catch statement with error handling and logging.
Lifecycle methods
During the lifetime of a component, Blazor invokes lifecycle methods:
OnInitialized / OnInitializedAsync
OnParametersSet / OnParametersSetAsync
ShouldRender / ShouldRenderAsync
OnAfterRender / OnAfterRenderAsync

If any lifecycle method throws an exception, synchronously or asynchronously, the exception is fatal to the circuit.
For components to deal with errors in lifecycle methods, add error handling logic.
In the following example where OnParametersSetAsync calls a method to obtain a product:
An exception thrown in the ProductRepository.GetProductByIdAsync method is handled by a try-catch
statement.
When the catch block is executed:
loadFailed is set to true , which is used to display an error message to the user.
The error is logged.
 @page "/product-details/{ProductId:int}"
@using Microsoft.Extensions.Logging
@inject IProductRepository ProductRepository
@inject ILogger<ProductDetails> Logger

@if (details != null)

{
<h1>@details.ProductName</h1>
<p>@details.Description</p>
}
else if (loadFailed)
{
<h1>Sorry, we could not load this product due to an error.</h1>
}
else
{
<h1>Loading...</h1>
}

@code {
private ProductDetails details;
private bool loadFailed;

[Parameter]
public int ProductId { get; set; }

protected override async Task OnParametersSetAsync()

{
try
{
loadFailed = false;
details = await ProductRepository.GetProductByIdAsync(ProductId);
}
catch (Exception ex)
{
loadFailed = true;
Logger.LogWarning(ex, "Failed to load product {ProductId}", ProductId);
}
}
}

Rendering logic
The declarative markup in a .razor component file is compiled into a C# method called BuildRenderTree . When a
component renders, BuildRenderTree executes and builds up a data structure describing the elements, text, and
child components of the rendered component.
Rendering logic can throw an exception. An example of this scenario occurs when @someObject.PropertyName is
evaluated but @someObject is null . An unhandled exception thrown by rendering logic is fatal to the circuit.
To prevent a null reference exception in rendering logic, check for a null object before accessing its members. In
the following example, person.Address properties aren't accessed if person.Address is null :

@if (person.Address != null)

{
<div>@person.Address.Line1</div>
<div>@person.Address.Line2</div>
<div>@person.Address.City</div>
<div>@person.Address.Country</div>
}

The preceding code assumes that person isn't null . Often, the structure of the code guarantees that an object
exists at the time the component is rendered. In those cases, it isn't necessary to check for null in rendering logic.
In the prior example, person might be guaranteed to exist because person is created when the component is
instantiated.
Event handlers
Client-side code triggers invocations of C# code when event handlers are created using:
@onclick
@onchange
Other @on... attributes
@bind

Event handler code might throw an unhandled exception in these scenarios.

If an event handler throws an unhandled exception (for example, a database query fails), the exception is fatal to the
circuit. If the app calls code that could fail for external reasons, trap exceptions using a try-catch statement with
error handling and logging.
If user code doesn't trap and handle the exception, the framework logs the exception and terminates the circuit.
Component disposal
A component may be removed from the UI, for example, because the user has navigated to another page. When a
component that implements System.IDisposable is removed from the UI, the framework calls the component's
Dispose method.
If the component's Dispose method throws an unhandled exception, the exception is fatal to the circuit. If disposal
logic may throw exceptions, the app should trap the exceptions using a try-catch statement with error handling and
logging.
For more information on component disposal, see Create and use ASP.NET Core Razor components.
JavaScript interop
IJSRuntime.InvokeAsync<T> allows .NET code to make asynchronous calls to the JavaScript runtime in the user's
browser.
The following conditions apply to error handling with InvokeAsync<T> :
If a call to InvokeAsync<T> fails synchronously, a .NET exception occurs. A call to InvokeAsync<T> my fail, for
example, because the supplied arguments can't be serialized. Developer code must catch the exception. If app
code in an event handler or component lifecycle method doesn't handle an exception, the resulting exception is
fatal to the circuit.
If a call to InvokeAsync<T> fails asynchronously, the .NET Task fails. A call to InvokeAsync<T> may fail, for
example, because the JavaScript-side code throws an exception or returns a Promise that completed as
rejected . Developer code must catch the exception. If using the await operator, consider wrapping the method
call in a try-catch statement with error handling and logging. Otherwise, the failing code results in an unhandled
exception that's fatal to the circuit.
By default, calls to InvokeAsync<T> must complete within a certain period or else the call times out. The default
timeout period is one minute. The timeout protects the code against a loss in network connectivity or JavaScript
code that never sends back a completion message. If the call times out, the resulting Task fails with an
OperationCanceledException. Trap and process the exception with logging.
Similarly, JavaScript code may initiate calls to .NET methods indicated by the [JSInvokable] attribute. If these .NET
methods throw an unhandled exception:
The exception isn't treated as fatal to the circuit.
The JavaScript-side Promise is rejected.
You have the option of using error handling code on either the .NET side or the JavaScript side of the method call.
For more information, see ASP.NET Core Blazor JavaScript interop.
Circuit handlers
Blazor allows code to define a circuit handler, which receives notifications when the state of a user's circuit changes.
The following states are used:
initialized
connected
disconnected
disposed

Notifications are managed by registering a DI service that inherits from the CircuitHandler abstract base class.
If a custom circuit handler's methods throw an unhandled exception, the exception is fatal to the circuit. To tolerate
exceptions in a handler's code or called methods, wrap the code in one or more try-catch statements with error
handling and logging.
Circuit disposal
When a circuit ends because a user has disconnected and the framework is cleaning up the circuit state, the
framework disposes of the circuit's DI scope. Disposing the scope disposes any circuit-scoped DI services that
implement System.IDisposable. If any DI service throws an unhandled exception during disposal, the framework
logs the exception.
Prerendering
Blazor components can be prerendered using Html.RenderComponentAsync so that their rendered HTML markup is
returned as part of the user's initial HTTP request. This works by:
Creating a new circuit containing all of the prerendered components that are part of the same page.
Generating the initial HTML.
Treating the circuit as disconnected until the user's browser establishes a SignalR connection back to the same
server to resume interactivity on the circuit.
If any component throws an unhandled exception during prerendering, for example, during a lifecycle method or in
rendering logic:
The exception is fatal to the circuit.
The exception is thrown up the call stack from the Html.RenderComponentAsync call. Therefore, the entire HTTP
request fails unless the exception is explicitly caught by developer code.
Under normal circumstances when prerendering fails, continuing to build and render the component doesn't make
sense because a working component can't be rendered.
To tolerate errors that may occur during prerendering, error handling logic must be placed inside a component that
may throw exceptions. Use try-catch statements with error handling and logging. Instead of wrapping the call to
RenderComponentAsync in a try-catch statement, place error handling logic in the component rendered by
RenderComponentAsync .

Advanced scenarios
Recursive rendering
Components can be nested recursively. This is useful for representing recursive data structures. For example, a
TreeNode component can render more TreeNode components for each of the node's children.

When rendering recursively, avoid coding patterns that result in infinite recursion:
 Don't recursively render a data structure that contains a cycle. For example, don't render a tree node whose
children includes itself.
Don't create a chain of layouts that contain a cycle. For example, don't create a layout whose layout is itself.
Don't allow an end user to violate recursion invariants (rules) through malicious data entry or JavaScript
interop calls.
Infinite loops during rendering:
Causes the rendering process to continue forever.
Is equivalent to creating an unterminated loop.
In these scenarios, the affected circuit hangs, and the thread usually attempts to:
Consume as much CPU time as permitted by the operating system, indefinitely.
Consume an unlimited amount of server memory. Consuming unlimited memory is equivalent to the scenario
where an unterminated loop adds entries to a collection on every iteration.
To avoid infinite recursion patterns, ensure that recursive rendering code contains suitable stopping conditions.
Custom render tree logic
Most Blazor components are implemented as .razor files and are compiled to produce logic that operates on a
RenderTreeBuilder to render their output. A developer may manually implement RenderTreeBuilder logic using
procedural C# code. For more information, see Create and use ASP.NET Core Razor components.

WARNING
Use of manual render tree builder logic is considered an advanced and unsafe scenario, not recommended for general
component development.

If RenderTreeBuilder code is written, the developer must guarantee the correctness of the code. For example, the
developer must ensure that:
Calls to OpenElement and CloseElement are correctly balanced.
Attributes are only added in the correct places.
Incorrect manual render tree builder logic can cause arbitrary undefined behavior, including crashes, server hangs,
and security vulnerabilities.
Consider manual render tree builder logic on the same level of complexity and with the same level of danger as
writing assembly code or MSIL instructions by hand.
 Debug ASP.NET Core Blazor
8/1/2019 • 2 minutes to read • Edit Online

Daniel Roth
Early support exists for debugging Blazor client-side apps running on WebAssembly in Chrome.
Debugger capabilities are limited. Available scenarios include:
Set and remove breakpoints.
Single-step ( F10 ) through the code or resume ( F8 ) code execution.
In the Locals display, observe the values of any local variables of type int , string , and bool .
See the call stack, including call chains that go from JavaScript into .NET and from .NET to JavaScript.
You can't:
Observe the values of any locals that aren't an int , string , or bool .
Observe the values of any class properties or fields.
Hover over variables to see their values.
Evaluate expressions in the console.
Step across async calls.
Perform most other ordinary debugging scenarios.
Development of further debugging scenarios is an on-going focus of the engineering team.

Prerequisites
Debugging requires either of the following browsers:
Google Chrome (version 70 or later)
Microsoft Edge preview (Edge Dev Channel)

Procedure
1. Run a Blazor client-side app in Debug configuration. Pass the --configuration Debug option to the dotnet run
command: dotnet run --configuration Debug .
2. Access the app in the browser.
3. Place the keyboard focus on the app, not the developer tools panel. The developer tools panel can be closed
when debugging is initiated.
4. Select the following Blazor-specific keyboard shortcut:
Shift+Alt+D on Windows/Linux
Shift+Cmd+D on macOS

Enable remote debugging

If remote debugging is disabled, an Unable to find debuggable browser tab error page is generated by
Chrome. The error page contains instructions for running Chrome with the debugging port open so that the Blazor
debugging proxy can connect to the app. Close all Chrome instances and restart Chrome as instructed.
Debug the app
Once Chrome is running with remote debugging enabled, the debugging keyboard shortcut opens a new
debugger tab. After a moment, the Sources tab shows a list of the .NET assemblies in the app. Expand each
assembly and find the .cs/.razor source files available for debugging. Set breakpoints, switch back to the app's tab,
and the breakpoints are hit when the code executes. After a breakpoint is hit, single-step ( F10 ) through the code or
resume ( F8 ) code execution normally.
Blazor provides a debugging proxy that implements the Chrome DevTools Protocol and augments the protocol
with .NET-specific information. When debugging keyboard shortcut is pressed, Blazor points the Chrome DevTools
at the proxy. The proxy connects to the browser window you're seeking to debug (hence the need to enable remote
debugging).

Browser source maps

Browser source maps allow the browser to map compiled files back to their original source files and are commonly
used for client-side debugging. However, Blazor doesn't currently map C# directly to JavaScript/WASM. Instead,
Blazor does IL interpretation within the browser, so source maps aren't relevant.

Troubleshooting tip
If you're running into errors, the following tip may help:
In the Debugger tab, open the developer tools in your browser. In the console, execute localStorage.clear() to
remove any breakpoints.
 Call a web API from ASP.NET Core Blazor
6/26/2019 • 5 minutes to read • Edit Online

By Luke Latham and Daniel Roth

Blazor client-side apps call web APIs using a preconfigured HttpClient service. Compose requests, which can
include JavaScript Fetch API options, using Blazor JSON helpers or with HttpRequestMessage.
Blazor server-side apps call web APIs using HttpClient instances typically created using IHttpClientFactory. For
more information, see Make HTTP requests using IHttpClientFactory in ASP.NET Core.
View or download sample code (how to download)
For Blazor client-side examples, see the following components in the sample app:
Call Web API (Pages/CallWebAPI.razor)
HTTP Request Tester (Components/HTTPRequestTester.razor)

HttpClient and JSON helpers

In Blazor client-side apps, HttpClient is available as a preconfigured service for making requests back to the origin
server. HttpClient and JSON helpers are also used to call third-party web API endpoints. HttpClient is
implemented using the browser Fetch API and is subject to its limitations, including enforcement of the same
origin policy.
The client's base address is set to the originating server's address. Inject an HttpClient instance using the
@inject directive:

@using System.Net.Http
@inject HttpClient Http

In the following examples, a Todo web API processes create, read, update, and delete (CRUD ) operations. The
examples are based on a TodoItem class that stores the:
ID ( Id , long ) – Unique ID of the item.
Name ( Name , string ) – Name of the item.
Status ( IsComplete , bool ) – Indication if the Todo item is finished.

private class TodoItem

{
public long Id { get; set; }
public string Name { get; set; }
public bool IsComplete { get; set; }
}

JSON helper methods send requests to a URI (a web API in the following examples) and process the response:
GetJsonAsync – Sends an HTTP GET request and parses the JSON response body to create an object.
In the following code, the _todoItems are displayed by the component. The GetTodoItems method is
triggered when the component is finished rendering (OnInitAsync). See the sample app for a complete
example.
 @using System.Net.Http
@inject HttpClient Http

@code {
private TodoItem[] _todoItems;

protected override async Task OnInitAsync() =>

_todoItems = await Http.GetJsonAsync<TodoItem[]>("api/todo");
}

PostJsonAsync– Sends an HTTP POST request, including JSON -encoded content, and parses the JSON
response body to create an object.
In the following code, _newItemName is provided by a bound element of the component. The AddItem
method is triggered by selecting a <button> element. See the sample app for a complete example.

@using System.Net.Http
@inject HttpClient Http

<input @bind="_newItemName" placeholder="New Todo Item" />

<button @onclick="@AddItem">Add</button>

@code {
private string _newItemName;

private async Task AddItem()

{
var addItem = new TodoItem { Name = _newItemName, IsComplete = false };
await Http.PostJsonAsync("api/todo", addItem);
}
}

PutJsonAsync – Sends an HTTP PUT request, including JSON -encoded content.

In the following code, _editItem values for Name and IsCompleted are provided by bound elements of the
component. The item's Id is set when the item is selected in another part of the UI and EditItem is called.
The SaveItem method is triggered by selecting the Save <button> element. See the sample app for a
complete example.

@using System.Net.Http
@inject HttpClient Http

<input type="checkbox" @bind="_editItem.IsComplete" />

<input @bind="_editItem.Name" />
<button @onclick="@SaveItem">Save</button>

@code {
private TodoItem _editItem = new TodoItem();

private void EditItem(long id)

{
var editItem = _todoItems.Single(i => i.Id == id);
_editItem = new TodoItem { Id = editItem.Id, Name = editItem.Name,
IsComplete = editItem.IsComplete };
}

private async Task SaveItem() =>

await Http.PutJsonAsync($"api/todo/{_editItem.Id}, _editItem);
}

System.Net.Http includes additional extension methods for sending HTTP requests and receiving HTTP responses.
HttpClient.DeleteAsync is used to send an HTTP DELETE request to a web API.
In the following code, the Delete <button> element calls the DeleteItem method. The bound <input> element
supplies the id of the item to delete. See the sample app for a complete example.

@using System.Net.Http
@inject HttpClient Http

<input @bind="_id" />

<button @onclick="@DeleteItem">Delete</button>

@code {
private long _id;

private async Task DeleteItem() =>

await Http.DeleteAsync($"api/todo/{_id}");
}

Cross-origin resource sharing (CORS)

Browser security prevents a webpage from making requests to a different domain than the one that served the
webpage. This restriction is called the same-origin policy. The same-origin policy prevents a malicious site from
reading sensitive data from another site. To make requests from the browser to an endpoint with a different origin,
the endpoint must enable cross-origin resource sharing (CORS ).
The sample app demonstrates the use of CORS in the Call Web API component (Pages/CallWebAPI.razor).
To allow other sites to make cross-origin resource sharing (CORS ) requests to your app, see Enable Cross-Origin
Requests (CORS ) in ASP.NET Core.

HttpClient and HttpRequestMessage with Fetch API request options

When running on WebAssembly in a Blazor client-side app, use HttpClient and HttpRequestMessage to customize
requests. For example, you can specify the request URI, HTTP method, and any desired request headers.
Supply request options to the underlying JavaScript Fetch API using the WebAssemblyHttpMessageHandler.FetchArgs
property on the request. As shown in the following example, the credentials property is set to any of the
following values:
FetchCredentialsOption.Include ("include") – Advises the browser to send credentials (such as cookies or HTTP
authentication headers) even for cross-origin requests. Only allowed when the CORS policy is configured to
allow credentials.
FetchCredentialsOption.Omit ("omit") – Advises the browser never to send credentials (such as cookies or HTTP
auth headers).
FetchCredentialsOption.SameOrigin ("same-origin") – Advises the browser to send credentials (such as cookies
or HTTP auth headers) only if the target URL is on the same origin as the calling application.
 @using System.Net.Http
@using System.Net.Http.Headers
@inject HttpClient Http

@code {
private async Task PostRequest()
{
Http.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "{OAUTH TOKEN}");

var requestMessage = new HttpRequestMessage()

{
Method = new HttpMethod("POST"),
RequestUri = new Uri("https://localhost:10000/api/todo"),
Content =
new StringContent(
@"{""name"":""A New Todo Item"",""isComplete"":false}")
};

requestMessage.Content.Headers.ContentType =
new System.Net.Http.Headers.MediaTypeHeaderValue(
"application/json");

requestMessage.Content.Headers.TryAddWithoutValidation(
"x-custom-header", "value");

requestMessage.Properties[WebAssemblyHttpMessageHandler.FetchArgs] = new
{
credentials = FetchCredentialsOption.Include
};

var response = await Http.SendAsync(requestMessage);

var responseStatusCode = response.StatusCode;
var responseBody = await response.Content.ReadAsStringAsync();
}
}

For more information on Fetch API options, see MDN web docs:
WindowOrWorkerGlobalScope.fetch():Parameters.
When sending credentials (authorization cookies/headers) on CORS requests, the Authorization header must be
allowed by the CORS policy.
The following policy includes configuration for:
Request origins ( http://localhost:5000 , https://localhost:5001 ).
Any method (verb).
Content-Type and Authorization headers. To allow a custom header (for example, x-custom-header ), list the
header when calling WithHeaders.
Credentials set by client-side JavaScript code ( credentials property set to include ).

app.UseCors(policy =>
policy.WithOrigins("http://localhost:5000", "https://localhost:5001")
.AllowAnyMethod()
.WithHeaders(HeaderNames.ContentType, HeaderNames.Authorization, "x-custom-header")
.AllowCredentials());

For more information, see Enable Cross-Origin Requests (CORS ) in ASP.NET Core and the sample app's HTTP
Request Tester component (Components/HTTPRequestTester.razor).
Additional resources
Make HTTP requests using IHttpClientFactory in ASP.NET Core
Cross Origin Resource Sharing (CORS ) at W3C
 Host and deploy ASP.NET Core Blazor
8/9/2019 • 2 minutes to read • Edit Online

By Luke Latham, Rainer Stropek, and Daniel Roth

Publish the app

Apps are published for deployment in Release configuration.
Visual Studio
.NET Core CLI
1. Select Build > Publish {APPLICATION } from the navigation bar.
2. Select the publish target. To publish locally, select Folder.
3. Accept the default location in the Choose a folder field or specify a different location. Select the Publish
button.
Publishing the app triggers a restore of the project's dependencies and builds the project before creating the assets
for deployment. As part of the build process, unused methods and assemblies are removed to reduce app
download size and load times.
A Blazor client-side app is published to the /bin/Release/{TARGET FRAMEWORK }/publish/{ASSEMBLY NAME }/dist
folder. A Blazor server-side app is published to the /bin/Release/{TARGET FRAMEWORK }/publish folder.
The assets in the folder are deployed to the web server. Deployment might be a manual or automated process
depending on the development tools in use.

Deployment
For deployment guidance, see the following topics:
Host and deploy ASP.NET Core Blazor client-side
Host and deploy ASP.NET Core Blazor server-side

Blazor serverless hosting with Azure Storage

Blazor client-side apps can be served from Azure Storage as static content directly from a storage container.
For more information, see Host and deploy ASP.NET Core Blazor client-side (Standalone deployment): Azure
Storage.
 Host and deploy ASP.NET Core Blazor client-side
8/13/2019 • 11 minutes to read • Edit Online

By Luke Latham, Rainer Stropek, and Daniel Roth

Host configuration values

Blazor apps that use the client-side hosting model can accept the following host configuration values as command-
line arguments at runtime in the development environment.
Content Root
The --contentroot argument sets the absolute path to the directory that contains the app's content files. In the
following examples, /content-root-path is the app's content root path.
Pass the argument when running the app locally at a command prompt. From the app's directory, execute:

dotnet run --contentroot=/content-root-path

Add an entry to the app's launchSettings.json file in the IIS Express profile. This setting is used when the
app is run with the Visual Studio Debugger and from a command prompt with dotnet run .

"commandLineArgs": "--contentroot=/content-root-path"

In Visual Studio, specify the argument in Properties > Debug > Application arguments. Setting the
argument in the Visual Studio property page adds the argument to the launchSettings.json file.

--contentroot=/content-root-path

Path base
The --pathbase argument sets the app base path for an app run locally with a non-root virtual path (the <base>
tag href is set to a path other than / for staging and production). In the following examples, /virtual-path is the
app's path base. For more information, see the App base path section.

IMPORTANT
Unlike the path provided to href of the <base> tag, don't include a trailing slash ( / ) when passing the --pathbase
argument value. If the app base path is provided in the <base> tag as <base href="/CoolApp/"> (includes a trailing slash),
pass the command-line argument value as --pathbase=/CoolApp (no trailing slash).

Pass the argument when running the app locally at a command prompt. From the app's directory, execute:

dotnet run --pathbase=/virtual-path

Add an entry to the app's launchSettings.json file in the IIS Express profile. This setting is used when
running the app with the Visual Studio Debugger and from a command prompt with dotnet run .
 "commandLineArgs": "--pathbase=/virtual-path"

In Visual Studio, specify the argument in Properties > Debug > Application arguments. Setting the
argument in the Visual Studio property page adds the argument to the launchSettings.json file.

--pathbase=/virtual-path

URLs
The --urls argument sets the IP addresses or host addresses with ports and protocols to listen on for requests.
Pass the argument when running the app locally at a command prompt. From the app's directory, execute:

dotnet run --urls=http://127.0.0.1:0

Add an entry to the app's launchSettings.json file in the IIS Express profile. This setting is used when
running the app with the Visual Studio Debugger and from a command prompt with dotnet run .

"commandLineArgs": "--urls=http://127.0.0.1:0"

In Visual Studio, specify the argument in Properties > Debug > Application arguments. Setting the
argument in the Visual Studio property page adds the argument to the launchSettings.json file.

--urls=http://127.0.0.1:0

Deployment
With the client-side hosting model:
The Blazor app, its dependencies, and the .NET runtime are downloaded to the browser.
The app is executed directly on the browser UI thread. Either of the following strategies is supported:
The Blazor app is served by an ASP.NET Core app. This strategy is covered in the Hosted deployment
with ASP.NET Core section.
The Blazor app is placed on a static hosting web server or service, where .NET isn't used to serve the
Blazor app. This strategy is covered in the Standalone deployment section.

Configure the Linker

Blazor performs Intermediate Language (IL ) linking on each build to remove unnecessary IL from the output
assemblies. Assembly linking can be controlled on build. For more information, see Configure the Linker for
ASP.NET Core Blazor.

Rewrite URLs for correct routing

Routing requests for page components in a client-side app isn't as simple as routing requests to a server-side,
hosted app. Consider a client-side app with two components:
Main.razor – Loads at the root of the app and contains a link to the About component ( href="About" ).
About.razor – About component.

When the app's default document is requested using the browser's address bar (for example,
https://www.contoso.com/ ):
1. The browser makes a request.
2. The default page is returned, which is usually index.html.
3. index.html bootstraps the app.
4. Blazor's router loads, and the Razor Main component is rendered.

In the Main page, selecting the link to the About component works on the client because the Blazor router stops
the browser from making a request on the Internet to www.contoso.com for About and serves the rendered About
component itself. All of the requests for internal endpoints within the client-side app work the same way: Requests
don't trigger browser-based requests to server-hosted resources on the Internet. The router handles the requests
internally.
If a request is made using the browser's address bar for www.contoso.com/About , the request fails. No such resource
exists on the app's Internet host, so a 404 - Not Found response is returned.
Because browsers make requests to Internet-based hosts for client-side pages, web servers and hosting services
must rewrite all requests for resources not physically on the server to the index.html page. When index.html is
returned, the app's client-side router takes over and responds with the correct resource.

App base path

The app base path is the virtual app root path on the server. For example, an app that resides on the Contoso
server in a virtual folder at /CoolApp/ is reached at https://www.contoso.com/CoolApp and has a virtual base path of
/CoolApp/ . By setting the app base path to the virtual path ( <base href="/CoolApp/"> ), the app is made aware of
where it virtually resides on the server. The app can use the app base path to construct URLs relative to the app
root from a component that isn't in the root directory. This allows components that exist at different levels of the
directory structure to build links to other resources at locations throughout the app. The app base path is also used
to intercept hyperlink clicks where the href target of the link is within the app base path URI space—the Blazor
router handles the internal navigation.
In many hosting scenarios, the server's virtual path to the app is the root of the app. In these cases, the app base
path is a forward slash ( <base href="/" /> ), which is the default configuration for an app. In other hosting
scenarios, such as GitHub Pages and IIS virtual directories or sub-applications, the app base path must be set to the
server's virtual path to the app. To set the app's base path, update the <base> tag within the <head> tag elements
of the wwwroot/index.html file. Set the href attribute value to /virtual-path/ (the trailing slash is required),
where /virtual-path/ is the full virtual app root path on the server for the app. In the preceding example, the
virtual path is set to /CoolApp/ : <base href="/CoolApp/"> .
For an app with a non-root virtual path configured (for example, <base href="/CoolApp/"> ), the app fails to find its
resources when run locally. To overcome this problem during local development and testing, you can supply a path
base argument that matches the href value of the <base> tag at runtime.
To pass the path base argument with the root path ( / ) when running the app locally, execute the dotnet run
command from the app's directory with the --pathbase option:

dotnet run --pathbase=/{Virtual Path (no trailing slash)}

For an app with a virtual base path of /CoolApp/ ( <base href="/CoolApp/"> ), the command is:

dotnet run --pathbase=/CoolApp

The app responds locally at http://localhost:port/CoolApp .

For more information, see the section on the path base host configuration value.
If an app uses the client-side hosting model (based on the Blazor WebAssembly App project template, the
blazorwasm template when using the dotnet new command) and is hosted as an IIS sub-app in an ASP.NET Core
app, it's important to disable the inherited ASP.NET Core Module handler or make sure the root (parent) app's
<handlers> section in the web.config file isn't inherited by the sub-app.

Remove the handler in the app's published web.config file by adding a <handlers> section to the file:

<handlers>
<remove name="aspNetCore" />
</handlers>

Alternatively, disable inheritance of the root (parent) app's <system.webServer> section using a <location> element
with inheritInChildApplications set to false :

<?xml version="1.0" encoding="utf-8"?>

<configuration>
<location path="." inheritInChildApplications="false">
<system.webServer>
<handlers>
<add name="aspNetCore" ... />
</handlers>
<aspNetCore ... />
</system.webServer>
</location>
</configuration>

Removing the handler or disabling inheritance is performed in addition to configuring the app's base path as
described in this section. Set the app base path in the app's index.html file to the IIS alias used when configuring the
sub-app in IIS.

Hosted deployment with ASP.NET Core

A hosted deployment serves the Blazor client-side app to browsers from an ASP.NET Core app that runs on a web
server.
The Blazor app is included with the ASP.NET Core app in the published output so that the two apps are deployed
together. A web server that is capable of hosting an ASP.NET Core app is required. For a hosted deployment,
Visual Studio includes the Blazor WebAssembly App project template ( blazorwasm template when using the
dotnet new command) with the Hosted option selected.
For more information on ASP.NET Core app hosting and deployment, see Host and deploy ASP.NET Core.
For information on deploying to Azure App Service, see Publish an ASP.NET Core app to Azure with Visual Studio.

Standalone deployment
A standalone deployment serves the Blazor client-side app as a set of static files that are requested directly by
clients. Any static file server is able to serve the Blazor app.
Standalone deployment assets are published to the bin/Release/{TARGET FRAMEWORK }/publish/{ASSEMBLY
NAME }/dist folder.
IIS
IIS is a capable static file server for Blazor apps. To configure IIS to host Blazor, see Build a Static Website on IIS.
Published assets are created in the /bin/Release/{TARGET FRAMEWORK }/publish folder. Host the contents of the
publish folder on the web server or hosting service.
web.config
When a Blazor project is published, a web.config file is created with the following IIS configuration:
MIME types are set for the following file extensions:
.dll – application/octet-stream
.json – application/json
.wasm – application/wasm
.woff – application/font-woff
.woff2 – application/font-woff
HTTP compression is enabled for the following MIME types:
application/octet-stream
application/wasm
URL Rewrite Module rules are established:
Serve the sub-directory where the app's static assets reside ({ASSEMBLY NAME }/dist/{PATH
REQUESTED }).
Create SPA fallback routing so that requests for non-file assets are redirected to the app's default
document in its static assets folder ({ASSEMBLY NAME }/dist/index.html).
Install the URL Rewrite Module
The URL Rewrite Module is required to rewrite URLs. The module isn't installed by default, and it isn't available for
install as a Web Server (IIS ) role service feature. The module must be downloaded from the IIS website. Use the
Web Platform Installer to install the module:
1. Locally, navigate to the URL Rewrite Module downloads page. For the English version, select WebPI to
download the WebPI installer. For other languages, select the appropriate architecture for the server (x86/x64)
to download the installer.
2. Copy the installer to the server. Run the installer. Select the Install button and accept the license terms. A server
restart isn't required after the install completes.
Configure the website
Set the website's Physical path to the app's folder. The folder contains:
The web.config file that IIS uses to configure the website, including the required redirect rules and file content
types.
The app's static asset folder.
Troubleshooting
If a 500 - Internal Server Error is received and IIS Manager throws errors when attempting to access the website's
configuration, confirm that the URL Rewrite Module is installed. When the module isn't installed, the web.config file
can't be parsed by IIS. This prevents the IIS Manager from loading the website's configuration and the website
from serving Blazor's static files.
For more information on troubleshooting deployments to IIS, see Troubleshoot ASP.NET Core on Azure App
Service and IIS.
Azure Storage
Azure Storage static file hosting allows serverless Blazor app hosting. Custom domain names, the Azure Content
Delivery Network (CDN ), and HTTPS are supported.
When the blob service is enabled for static website hosting on a storage account:
Set the Index document name to index.html .
 Set the Error document path to index.html . Razor components and other non-file endpoints don't reside at
physical paths in the static content stored by the blob service. When a request for one of these resources is
received that the Blazor router should handle, the 404 - Not Found error generated by the blob service routes
the request to the Error document path. The index.html blob is returned, and the Blazor router loads and
processes the path.
For more information, see Static website hosting in Azure Storage.
Nginx
The following nginx.conf file is simplified to show how to configure Nginx to send the index.html file whenever it
can't find a corresponding file on disk.

events { }
http {
server {
listen 80;

location / {
root /usr/share/nginx/html;
try_files $uri $uri/ /index.html =404;
}
}
}

For more information on production Nginx web server configuration, see Creating NGINX Plus and NGINX
Configuration Files.
Nginx in Docker
To host Blazor in Docker using Nginx, setup the Dockerfile to use the Alpine-based Nginx image. Update the
Dockerfile to copy the nginx.config file into the container.
Add one line to the Dockerfile, as shown in the following example:

FROM nginx:alpine
COPY ./bin/Release/netstandard2.0/publish /usr/share/nginx/html/
COPY nginx.conf /etc/nginx/nginx.conf

GitHub Pages
To handle URL rewrites, add a 404.html file with a script that handles redirecting the request to the index.html page.
For an example implementation provided by the community, see Single Page Apps for GitHub Pages (rafrex/spa-
github-pages on GitHub). An example using the community approach can be seen at blazor-demo/blazor-
demo.github.io on GitHub (live site).
When using a project site instead of an organization site, add or update the <base> tag in index.html. Set the href
attribute value to the GitHub repository name with a trailing slash (for example, my-repository/ .
 Host and deploy Blazor server-side
7/15/2019 • 2 minutes to read • Edit Online

By Luke Latham, Rainer Stropek, and Daniel Roth

Host configuration values

Server-side apps that use the server-side hosting model can accept Generic Host configuration values.

Deployment
With the server-side hosting model, Blazor is executed on the server from within an ASP.NET Core app. UI
updates, event handling, and JavaScript calls are handled over a SignalR connection.
A web server capable of hosting an ASP.NET Core app is required. Visual Studio includes the Blazor Server App
project template ( blazorserverside template when using the dotnet new command).

Connection scale out

Blazor server-side apps require one active SignalR connection for each user. A production Blazor server-side
deployment requires a solution for supporting as many concurrent connections as required by the app. The Azure
SignalR Service handles the scaling of connections and is recommended as a scaling solution for Blazor server-side
apps. For more information, see Publish an ASP.NET Core SignalR app to Azure App Service.

SignalR configuration
SignalR is configured by ASP.NET Core for the most common Blazor server-side scenarios. For custom and
advanced scenarios, consult the SignalR articles in the Additional resources section.

Additional resources
Introduction to ASP.NET Core SignalR
Azure SignalR Service Documentation
Quickstart: Create a chat room by using SignalR Service
Host and deploy ASP.NET Core
Publish an ASP.NET Core app to Azure with Visual Studio
Deploy ASP.NET Core preview release to Azure App Service
 Configure the Linker for ASP.NET Core Blazor
7/3/2019 • 2 minutes to read • Edit Online

By Luke Latham
Blazor performs Intermediate Language (IL ) linking during a Release build to remove unnecessary IL from the
app's output assemblies.
Control assembly linking using either of the following approaches:
Disable linking globally with a MSBuild property.
Control linking on a per-assembly basis with a configuration file.

Disable linking with a MSBuild property

Linking is enabled by default in Release mode when an app is built, which includes publishing. To disable linking for
all assemblies, set the BlazorLinkOnBuild MSBuild property to false in the project file:

<PropertyGroup>
<BlazorLinkOnBuild>false</BlazorLinkOnBuild>
</PropertyGroup>

Control linking with a configuration file

Control linking on a per-assembly basis by providing an XML configuration file and specifying the file as a MSBuild
item in the project file:

<ItemGroup>
<BlazorLinkerDescriptor Include="Linker.xml" />
</ItemGroup>

Linker.xml:
 <?xml version="1.0" encoding="UTF-8" ?>
<!--
This file specifies which parts of the BCL or Blazor packages must not be
stripped by the IL Linker even if they aren't referenced by user code.
-->
<linker>
<assembly fullname="mscorlib">
<!--
Preserve the methods in WasmRuntime because its methods are called by
JavaScript client-side code to implement timers.
Fixes: https://github.com/aspnet/Blazor/issues/239
-->
<type fullname="System.Threading.WasmRuntime" />
</assembly>
<assembly fullname="System.Core">
<!--
System.Linq.Expressions* is required by Json.NET and any
expression.Compile caller. The assembly isn't stripped.
-->
<type fullname="System.Linq.Expressions*" />
</assembly>
<!--
In this example, the app's entry point assembly is listed. The assembly
isn't stripped by the IL Linker.
-->
<assembly fullname="MyCoolBlazorApp" />
</linker>

For more information, see IL Linker: Syntax of xml descriptor.

 Use the Angular project template with ASP.NET Core
4/26/2019 • 6 minutes to read • Edit Online

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 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 rendering (SSR )).
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.
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
}

Additional resources
Introduction to authentication for Single Page Apps on ASP.NET Core
 Use the React project template with ASP.NET Core
4/26/2019 • 3 minutes to read • Edit Online

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 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. Add a .env file to the ClientApp subdirectory with the following setting:

BROWSER=none

This will prevent your web browser from opening when starting the CRA server externally.
2. In a command prompt, switch to the ClientApp subdirectory, and launch the CRA development server:

cd ClientApp
npm start

3. 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.

IMPORTANT
"Server-side rendering" is not a supported feature of this template. Our goal with this template is to meet parity with
"create-react-app". As such, scenarios and features not included in a "create-react-app" project (such as SSR) are not
supported and are left as an exercise for the user.

Additional resources
Introduction to authentication for Single Page Apps on ASP.NET Core
 Use the React-with-Redux project template with
ASP.NET Core
4/26/2019 • 2 minutes to read • Edit Online

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.
For information on configuring a React-with-Redux sub-application in IIS, see ReactRedux Template 2.1: Unable to
use SPA on IIS (aspnet/Templating #555).
 Use JavaScript Services to Create Single Page
Applications in ASP.NET Core
7/11/2019 • 11 minutes to read • Edit Online

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 such as
ASP.NET Core can be difficult. JavaScript Services was developed to reduce friction in the integration process. It
enables seamless operation between the different client and server technology stacks.

What is JavaScript Services

JavaScript Services 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.
JavaScript Services consists of two distinct NuGet packages:
Microsoft.AspNetCore.NodeServices (NodeServices)
Microsoft.AspNetCore.SpaServices (SpaServices)
These packages are useful in the following scenarios:
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 developers 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:
 node -v && npm -v

If deploying to an Azure web site, no action is required—Node.js is installed and available in the
server environments.
.NET Core SDK 2.0 or later
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.
Server-side prerendering prerequisites
Install the aspnet-prerendering npm package:

npm i -S aspnet-prerendering

Server-side 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>

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();
});
});
});
});
});

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:
 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) => {

const result = `<h1>Hello, ${params.data.userName}</h1>`;

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: result
});
moduleRef.destroy();
});
});
});
});
});

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:
 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) => {

const result = `<h1>Hello, ${params.data.userName}</h1>`;

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: result,
globals: {
postList: [
'Introduction to ASP.NET Core',
'Making apps with Angular and ASP.NET Core'
]
}
});
moduleRef.destroy();
});
});
});
});
});

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",

Webpack Dev Middleware prerequisites

Install the aspnet-webpack npm package:

npm i -D aspnet-webpack

Webpack Dev Middleware configuration

Webpack Dev Middleware is registered into the HTTP request pipeline via the following code in the Startup.cs file's
Configure method:

if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseWebpackDevMiddleware();
}
else
{
app.UseExceptionHandler("/Home/Error");
}

// Call UseWebpackDevMiddleware before UseStaticFiles

app.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.
Hot Module Replacement prerequisites
Install the webpack-hot-middleware npm package:

npm i -D webpack-hot-middleware

Hot Module Replacement 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, client-side routing is often desired 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—
generally returning a 404 HTTP status code is desired.
Routing helpers prerequisites
Install the client-side routing npm package. Using Angular as an example:

npm i -S @angular/router

Routing helpers configuration

An extension method named MapSpaFallbackRoute is used in the Configure method:
 app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");

routes.MapSpaFallbackRoute(
name: "spa-fallback",
defaults: new { controller = "Home", action = "Index" });
});

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.

Create a new project

JavaScript Services provide 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 and minification.
ASP.NET Core uses an environment variable named ASPNETCORE_ENVIRONMENT to store the configuration mode. For
more information, see Set the environment.
Run 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.

Run 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.

Test 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'
],

Publish the app

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">

<!-- As part of publishing, ensure the JS resources are freshly built in production mode -->
<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" />

<!-- Include the newly-built files in the publish output -->

<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

Additional resources
Angular Docs
 Client-side library acquisition in ASP.NET Core with
LibMan
4/26/2019 • 2 minutes to read • Edit Online

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.

Additional resources
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
4/26/2019 • 8 minutes to read • Edit Online

By Scott Addie
The LibMan CLI is a cross-platform tool that's supported everywhere .NET Core is supported.

Prerequisites
.NET Core 2.1 SDK or later

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

Show help information.

--verbosity <LEVEL>

Set the verbosity of the output. Replace <LEVEL> with one of the following values:
quiet
normal
detailed

Examples
Consider the following libman.json file:

{
"version": "1.0",
"defaultProvider": "cdnjs",
"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",
"defaultProvider": "cdnjs",
"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",
"defaultProvider": "cdnjs",
"libraries": [
{
"library": "[email protected]",
"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

Show help information.

--verbosity <LEVEL>

Set the verbosity of the output. Replace <LEVEL> with one of the following values:
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

Show help information.

--verbosity <LEVEL>

Set the verbosity of the output. Replace <LEVEL> with one of the following values:
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

Show help information.

--verbosity <LEVEL>

Set the verbosity of the output. Replace <LEVEL> with one of the following values:
quiet
normal
detailed

Examples
Consider the following libman.json file:
 {
"version": "1.0",
"defaultProvider": "cdnjs",
"libraries": [
{
"library": "[email protected]",
"files": [
"jquery.min.js",
"jquery.js",
"jquery.min.map"
],
"destination": "wwwroot/lib/jquery/"
},
{
"provider": "unpkg",
"library": "[email protected]",
"destination": "wwwroot/lib/bootstrap/"
},
{
"provider": "filesystem",
"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

Show help information.

--verbosity <LEVEL>

Set the verbosity of the output. Replace <LEVEL> with one of the following values:
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

Show help information.

--verbosity <LEVEL>

Set the verbosity of the output. Replace <LEVEL> with one of the following values:
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:
<list omitted for brevity>
vue:
<list omitted for brevity>
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)

Additional resources
Install a Global Tool
Use LibMan with ASP.NET Core in Visual Studio
LibMan GitHub repository
 Use LibMan with ASP.NET Core in Visual Studio
7/11/2019 • 7 minutes to read • Edit Online

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.
View or download sample code (how to download)

Prerequisites
Visual Studio 2019 with the ASP.NET and web development workload

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 https://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",
"defaultProvider": "cdnjs",
"libraries": [
{
"library": "[email protected]",
"files": [
"jquery.min.js",
"jquery.js",
"jquery.min.map"
],
"destination": "wwwroot/lib/jquery/"
},
{
"provider": "unpkg",
"library": "[email protected]",
"destination": "wwwroot/lib/bootstrap/"
},
{
"provider": "filesystem",
"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.

Additional resources
Use the LibMan command-line interface (CLI) with ASP.NET Core
LibMan GitHub repository
 Use Grunt in ASP.NET Core
7/11/2019 • 8 minutes to read • Edit Online

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.
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 <major>.<minor>.<patch>. 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.

"devDependencies": {
"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 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 JavaScript File item template, change the
name to Gruntfile.js, and click the Add button.
2. Add the following code to Gruntfile.js. The initConfig function sets options for each package, and the
remainder of the module loads and register tasks.

module.exports = function (grunt) {

grunt.initConfig({
});
};

3. Inside the initConfig function, 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/"],
});
};

4. Below the initConfig function, add a call to grunt.loadNpmTasks . This will make the task runnable from
Visual Studio.

grunt.loadNpmTasks("grunt-contrib-clean");

5. Save Gruntfile.js. The file should look something like the screenshot below.

6. Right-click Gruntfile.js and select Task Runner Explorer from the context menu. The Task Runner
Explorer window will open.

7. Verify that clean shows under Tasks in the Task Runner Explorer.
 8. 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.

9. In the initConfig function, 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.

10. 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.

11. 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'
}
},

12. Under the call to 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');

13. Save Gruntfile.js. The file should look something like the example below.

14. 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.
 Manage client-side packages with Bower in ASP.NET
Core
7/11/2019 • 5 minutes to read • Edit Online

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" check box 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.

<environment names="Development">
<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
<link rel="stylesheet" href="~/css/site.css" />
<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:

@{
ViewData["Title"] = "About";
}

<div class="list-group">
<a class="list-group-item" href="#"><i class="fa fa-home fa-fw" aria-hidden="true"></i>&nbsp; Home</a>
<a class="list-group-item" href="#"><i class="fa fa-book fa-fw" aria-hidden="true"></i>&nbsp; Library</a>
<a class="list-group-item" href="#"><i class="fa fa-pencil fa-fw" aria-hidden="true"></i>&nbsp;
Applications</a>
<a class="list-group-item" href="#"><i class="fa fa-cog fa-fw" aria-hidden="true"></i>&nbsp; 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 .

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;

public class Startup

{
public void Configure(IApplicationBuilder app)
{
app.UseStaticFiles();

app.Run(async (context) =>

{
await context.Response.WriteAsync("Hello World!");
});
}
}

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>
<meta charset="utf-8" />
<title>Bower Example</title>
<link href="lib/bootstrap/dist/css/bootstrap.css" rel="stylesheet" />
</head>
<body>
<div class="jumbotron">
<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.
 Bundle and minify static assets in ASP.NET Core
7/11/2019 • 10 minutes to read • Edit Online

By Scott Addie and David Pine

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 that 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(t,a){var r=$(t,a);r.attr("alt",r.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 Grunt task runner, 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

In ASP.NET Core 2.0 or earlier, the MVC and Razor Pages project templates provide a bundleconfig.json
configuration file that defines the options for each bundle:
In ASP.NET Core 2.1 or later, add a new JSON file, named bundleconfig.json, to the MVC or Razor Pages project
root. Include the following JSON in that file as a starting point:
 [
{
"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
}
]

The bundleconfig.json file defines the options for each bundle. In the preceding example, a single bundle
configuration is defined for the custom JavaScript (wwwroot/js/site.js) and stylesheet (wwwroot/css/site.css) files.
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
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

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:

<environment include="Development">
<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
<link rel="stylesheet" href="~/css/site.css" />
</environment>

<environment names="Development">
<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
<link rel="stylesheet" href="~/css/site.css" />
</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:
 <environment exclude="Development">
<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>

<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>

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';

var gulp = require('gulp'),

concat = require('gulp-concat'),
cssmin = require('gulp-cssmin'),
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:

WARNING
The gulp-uglify module doesn't support ECMAScript (ES) 2015 / ES6 and later. Install gulp-terser instead of
gulp-uglify to use ES2015 / ES6 or later.

"devDependencies": {
"del": "^3.0.0",
"gulp": "^4.0.0",
"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';

var gulp = require('gulp'),

concat = require('gulp-concat'),
cssmin = require('gulp-cssmin'),
htmlmin = require('gulp-htmlmin'),
uglify = require('gulp-uglify'),
merge = require('merge-stream'),
del = require('del'),
bundleconfig = require('./bundleconfig.json');

const regex = {
css: /\.css$/,
html: /\.(html|htm)$/,
js: /\.js$/
 js: /\.js$/
};

gulp.task('min:js', async function () {

merge(getBundles(regex.js).map(bundle => {
return gulp.src(bundle.inputFiles, { base: '.' })
.pipe(concat(bundle.outputFileName))
.pipe(uglify())
.pipe(gulp.dest('.'));
}))
});

gulp.task('min:css', async function () {

merge(getBundles(regex.css).map(bundle => {
return gulp.src(bundle.inputFiles, { base: '.' })
.pipe(concat(bundle.outputFileName))
.pipe(cssmin())
.pipe(gulp.dest('.'));
}))
});

gulp.task('min:html', async function () {

merge(getBundles(regex.html).map(bundle => {
return gulp.src(bundle.inputFiles, { base: '.' })
.pipe(concat(bundle.outputFileName))
.pipe(htmlmin({ collapseWhitespace: true, minifyCSS: true, minifyJS: true }))
.pipe(gulp.dest('.'));
}))
});

gulp.task('min', gulp.series(['min:js', 'min:css', 'min:html']));

gulp.task('clean', () => {
return del(bundleconfig.map(bundle => bundle.outputFileName));
});

gulp.task('watch', () => {
getBundles(regex.js).forEach(
bundle => gulp.watch(bundle.inputFiles, gulp.series(["min:js"])));

getBundles(regex.css).forEach(
bundle => gulp.watch(bundle.inputFiles, gulp.series(["min:css"])));

getBundles(regex.html).forEach(
bundle => gulp.watch(bundle.inputFiles, gulp.series(['min:html'])));
});

const getBundles = (regexPattern) => {

return bundleconfig.filter(bundle => {
return regexPattern.test(bundle.outputFileName);
});
};

gulp.task('default', gulp.series("min"));

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
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

Additional resources
Use Grunt
Use multiple environments
Tag Helpers
 Browser Link in ASP.NET Core
4/26/2019 • 3 minutes to read • Edit Online

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:

app.UseBrowserLink();

Usually the code is inside an if block that only enables Browser Link in the Development environment, as shown
here:

if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseBrowserLink();
}

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:

<!-- Visual Studio Browser Link -->

<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>
<!-- End Browser Link -->
</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.
 Session and app state in ASP.NET Core
7/11/2019 • 15 minutes to read • Edit Online

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.
View or download sample code (how to download)

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. Critical
application data should be stored in the user database and cached in session only as a performance optimization.

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.
The ASP.NET Core MVC and Razor pages templates include support for General Data Protection Regulation
(GDPR ). Session state cookies aren't marked essential by default, so session state isn't functional unless
tracking is permitted by the site visitor. For more information, see General Data Protection Regulation (GDPR )
support in ASP.NET Core.

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 Distributed caching in ASP.NET Core.
The session cookie is encrypted via IDataProtector. Data Protection must be properly configured to read
session cookies on each machine. For more information, see ASP.NET Core Data Protection 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:
Any of the IDistributedCache memory caches. The IDistributedCache implementation is used as a backing
store for session. For more information, see Distributed caching in ASP.NET Core.
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 :

public class Startup

{
public void ConfigureServices(IServiceCollection services)
{
services.AddDistributedMemoryCache();

services.AddSession(options =>
{
// Set a short timeout for easy testing.
options.IdleTimeout = TimeSpan.FromSeconds(10);
options.Cookie.HttpOnly = true;
// Make the session cookie essential
options.Cookie.IsEssential = true;
});

services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseSession();
app.UseHttpContextItemsMiddleware();
app.UseMvc();
}
}

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 .

IdleTimeout The IdleTimeout indicates how long the session can be idle
before its contents are abandoned. Each session access resets
the timeout. This setting only applies to the content of the
session, not the cookie. The default is 20 minutes.

IOTimeout The maximum amount of time allowed to load a session from

the store or to commit it back to the store. This setting 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 ).
To override cookie session defaults, use SessionOptions :

public void ConfigureServices(IServiceCollection services)

{
services.Configure<CookiePolicyOptions>(options =>
{
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddDistributedMemoryCache();

services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

services.AddSession(options =>
{
options.Cookie.Name = ".AdventureWorks.Session";
options.IdleTimeout = TimeSpan.FromSeconds(10);
options.Cookie.IsEssential = true;
});
}

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 retrieve 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
Microsoft.AspNetCore.App metapackage.
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 class IndexModel : PageModel
{
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);

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);
}
}

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);
}

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
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.
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 ASP.NET Core 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:
 public void ConfigureServices(IServiceCollection services)
{
services.Configure<CookiePolicyOptions>(options =>
{
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2)
.AddSessionStateTempDataProvider();

services.AddSession();
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseDatabaseErrorPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseCookiePolicy();
app.UseSession();
app.UseMvc();
}

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.

app.Use(async (context, next) =>

{
// perform some verification
context.Items["isVerified"] = true;
await next.Invoke();
});

Later in the pipeline, another middleware can access the value of isVerified :

app.Run(async (context) =>

{
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

{
private readonly RequestDelegate _next;
public static readonly object HttpContextItemsMiddlewareKey = new Object();

public HttpContextItemsMiddleware(RequestDelegate next)

{
_next = next;
}

public async Task Invoke(HttpContext httpContext)

{
httpContext.Items[HttpContextItemsMiddlewareKey] = "K-9";

await _next(httpContext);
}
}

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!";

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 Response caching in ASP.NET Core.

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 :

public void ConfigureServices(IServiceCollection services)

{
services.AddSingleton<MyAppData>();
}

3. Consume the data service class:

public class IndexModel : PageModel

{
public IndexModel(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 Distributed caching in ASP.NET Core and Cache in-memory in ASP.NET Core.
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.

Additional resources
Host ASP.NET Core in a web farm
 Layout in ASP.NET Core
7/30/2019 • 5 minutes to read • Edit Online

By Steve Smith and Dave Brock

Pages and views frequently share visual and programmatic elements. This article demonstrates how to:
Use common layouts.
Share directives.
Run common code before rendering pages or views.
This document discusses layouts for the two different approaches to ASP.NET Core MVC: Razor Pages
and controllers with views. For this topic, the differences are minimal:
Razor Pages are in the Pages folder.
Controllers with views uses a Views folder for views.

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.
By convention, the default layout for an ASP.NET Core app is named _Layout.cshtml. The layout files for
new ASP.NET Core projects created with the templates are:
Razor Pages: Pages/Shared/_Layout.cshtml
 Controller with views: Views/Shared/_Layout.cshtml

The layout defines a top level template for views in the app. Apps don't require a layout. Apps can define
more than one layout, with different views specifying different layouts.
The following code shows the layout file for a template created project with a controller and views:

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@ViewData["Title"] - WebApplication1</title>

<environment include="Development">
<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
<link rel="stylesheet" href="~/css/site.css" />
</environment>
<environment exclude="Development">
<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>
</head>
<body>
<nav class="navbar navbar-inverse navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-
target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a asp-page="/Index" class="navbar-brand">WebApplication1</a>
</div>
<div class="navbar-collapse collapse">
 <ul class="nav navbar-nav">
<li><a asp-page="/Index">Home</a></li>
<li><a asp-page="/About">About</a></li>
<li><a asp-page="/Contact">Contact</a></li>
</ul>
</div>
</div>
</nav>

<partial name="_CookieConsentPartial" />

<div class="container body-content">

@RenderBody()
<hr />
<footer>
<p>&copy; 2018 - WebApplication1</p>
</footer>
</div>

<environment include="Development">
<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>
<environment exclude="Development">
<script src="https://ajax.aspnetcdn.com/ajax/jquery/jquery-3.3.1.min.js"
asp-fallback-src="~/lib/jquery/dist/jquery.min.js"
asp-fallback-test="window.jQuery"
crossorigin="anonymous"
integrity="sha384-tsQFqpEReu7ZLhBV2VZlAu7zcOV+rXbYlF2cqB8txI/8aZajjp4Bqd+V6D5IgvKT">
</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"
crossorigin="anonymous"
integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa">
</script>
<script src="~/js/site.min.js" asp-append-version="true"></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 (for example, /Pages/Shared/_Layout.cshtml or
/Views/Shared/_Layout.cshtml) or a partial name (example: _Layout ). When a partial name is provided,
the Razor view engine searches for the layout file using its standard discovery process. The folder where
the handler method (or controller) exists is searched first, followed by the Shared folder. This discovery
process is identical to the process 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:

@section Scripts {
@RenderSection("Scripts", required: false)
}

If a required section isn't found, an exception is thrown. Individual views specify the content to be rendered
within a section using the @section Razor syntax. If a page or view defines a section, it must be rendered
(or an error will occur).
An example @section definition in Razor Pages view:

@section Scripts {
<script type="text/javascript" src="/scripts/main.js"></script>
}

In the preceding code, scripts/main.js is added to the scripts section on a page or view. Other pages or
views in the same app might not require this script and wouldn't define a scripts section.
The following markup uses the Partial Tag Helper to render _ValidationScriptsPartial.cshtml:

@section Scripts {
<partial name="_ValidationScriptsPartial" />
}

The preceding markup was generated by scaffolding Identity.

Sections defined in a page or 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 and pages can use Razor directives to importing namespaces and use 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
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

The _ViewImports.cshtml file for an ASP.NET Core MVC app is typically placed in the Pages (or Views)
folder. A _ViewImports.cshtml file can be placed within any folder, in which case it will only be applied to
pages or 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 page or view itself. _ViewImports settings
specified at the root level may be overridden at the folder level.
For example, suppose:
The root level _ViewImports.cshtml file includes @model MyModel1 and @addTagHelper *, MyTagHelper1 .
A subfolder _ViewImports.cshtml file includes @model MyModel2 and @addTagHelper *, MyTagHelper2 .

Pages and views in the subfolder will have access to both Tag Helpers and the MyModel2 model.
If multiple _ViewImports.cshtml files are found in the file hierarchy, the combined behavior of the directives
are:
@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

Code that needs to run before each view or page should be placed in the _ViewStart.cshtml file. By
convention, the _ViewStart.cshtml file is located in the Pages (or 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 view or
pages folder, it will be run after the one defined in the root of the Pages (or Views) folder (if any).
A sample _ViewStart.cshtml file:

@{
Layout = "_Layout";
}

The file above specifies that all views will use the _Layout.cshtml layout.
_ViewStart.cshtml and _ViewImports.cshtml are not typically placed in the /Pages/Shared (or
/Views/Shared) folder. The app-level versions of these files should be placed directly in the /Pages (or
/Views) folder.
 Razor syntax reference for ASP.NET Core
8/6/2019 • 17 minutes to read • Edit Online

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. Razor is also
found in Razor components files (.razor).

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>")

The code renders the following HTML:

&lt;span&gt;Hello World&lt;/span&gt;

The HTML is shown in the browser as:

<span>Hello World</span>

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>")

The code renders the following HTML:

<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>

The code renders the following HTML:

<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>

In code blocks, declare local functions with markup to serve as templating methods:
 @{
void RenderName(string name)
{
<p>Name: <strong>@name</strong></p>
}

RenderName("Mahatma Gandhi");
RenderName("Martin Luther King, Jr.");
}

The code renders the following HTML:

<p>Name: <strong>Mahatma Gandhi</strong></p>

<p>Name: <strong>Martin Luther King, Jr.</strong></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:

@for (var i = 0; i < people.Length; i++)

{
var person = people[i];
@:Name: @person.Name
}

Without the @: in the code, a Razor runtime error is generated.

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
 @for (var i = 0; i < people.Length; i++)
{
var person = people[i];
<p>Name: @person.Name</p>
<p>Age: @person.Age</p>
}

@foreach

@foreach (var person in people)

{
<p>Name: @person.Name</p>
<p>Age: @person.Age</p>
}

@while

@{ var i = 0; }
@while (i < people.Length)
{
var person = people[i];
<p>Name: @person.Name</p>
<p>Age: @person.Age</p>

i++;
}

@do while

@{ var i = 0; }
@do
{
var person = people[i];
<p>Name: @person.Name</p>
<p>Age: @person.Age</p>

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>
}

@try, catch, finally

Exception handling is similar to C#:
 @try
{
throw new InvalidOperationException("You did something invalid.");
}
catch (Exception ex)
{
<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
}
<!-- HTML comment -->

The code renders the following HTML:

<!-- HTML 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
}
<!-- HTML 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 Inspect the Razor C# class generated for a view explains how to view this
generated class.
@attribute
The @attribute directive adds the given attribute to the class of the generated page or view. The following
example adds the [Authorize] attribute:

@attribute [Authorize]

@code
This scenario only applies to Razor components (.razor ).
The @code block enables a Razor component to add C# members (fields, properties, and methods) to a
component:

@code {
// C# members (fields, properties, and methods)
}

For Razor components, @code is an alias of @functions and recommended over @functions . More than one
@code block is permissible.

@functions
The @functions directive enables adding C# members (fields, properties, and methods) to the generated
class:

@functions {
// C# members (fields, properties, and methods)
}

In Razor components, use @code over @functions to add C# members.

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 System.Threading.Tasks;
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

@functions methods serve as templating methods when they have markup:

@{
RenderName("Mahatma Gandhi");
RenderName("Martin Luther King, Jr.");
}

@functions {
private void RenderName(string name)
{
<p>Name: <strong>@name</strong></p>
}
}

The code renders the following HTML:

<p>Name: <strong>Mahatma Gandhi</strong></p>

<p>Name: <strong>Martin Luther King, Jr.</strong></p>

@implements
The @implements directive implements an interface for the generated class.
The following example implements System.IDisposable so that the Dispose method can be called:
 @implements IDisposable

<h1>Example</h1>

@functions {
private bool _isDisposed;

...

public void Dispose() => _isDisposed = true;

}

@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>

The code renders the following HTML:

<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:

@inherits CustomRazorPage<TModel>

The following code is an example of a strongly-typed view:

@inherits CustomRazorPage<TModel>

<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.
@layout
This scenario only applies to Razor components (.razor ).
The @layout directive specifies a layout for a Razor component. Layout components are used to avoid code
duplication and inconsistency. For more information, see ASP.NET Core Blazor layouts.
@model
This scenario only applies to MVC views and Razor Pages (.cshtml).
The @model directive specifies the type of the model passed to a view or page:

@model TypeNameOfModel

In an ASP.NET Core MVC or Razor Pages app created with individual user accounts,
Views/Account/Login.cshtml 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 the Model 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 . For more information, see Strongly typed models and the @model keyword.
@namespace
The @namespace directive:
Sets the namespace of the class of the generated Razor page, MVC view, or Razor component.
Sets the root derived namespaces of a pages, views, or components classes from the closest imports file in
the directory tree, _ViewImports.cshtml (views or pages) or _Imports.razor (Razor components).

@namespace Your.Namespace.Here

For the Razor Pages example shown in the following table:

Each page imports Pages/_ViewImports.cshtml.
 Pages/_ViewImports.cshtml contains @namespace Hello.World .
Each page has Hello.World as the root of it's namespace.

PAGE NAMESPACE

Pages/Index.cshtml Hello.World

Pages/MorePages/Page.cshtml Hello.World.MorePages

Pages/MorePages/EvenMorePages/Page.cshtml Hello.World.MorePages.EvenMorePages

The preceding relationships apply to import files used with MVC views and Razor components.
When multiple import files have a @namespace directive, the file closest to the page, view, or component in the
directory tree is used to set the root namespace.
If the EvenMorePages folder in the preceding example has an imports file with @namespace Another.Planet (or
the Pages/MorePages/EvenMorePages/Page.cshtml file contains @namespace Another.Planet ), the result is
shown in the following table.

PAGE NAMESPACE

Pages/Index.cshtml Hello.World

Pages/MorePages/Page.cshtml Hello.World.MorePages

Pages/MorePages/EvenMorePages/Page.cshtml Another.Planet

@page
The @page directive has different effects depending on the type of the file where it appears. The directive:
In in a .cshtml file indicates that the file is a Razor Page. For more information, see Introduction to Razor
Pages in ASP.NET Core.
Specifies that a Razor component should handle requests directly. For more information, see ASP.NET
Core Blazor routing.
The @page directive on the first line of a .cshtml file indicates that the file is a Razor Page. For more
information, see Introduction to Razor Pages in ASP.NET Core.
@section
This scenario only applies to MVC views and Razor Pages (.cshtml).
The @section directive is used in conjunction with MVC and Razor Pages layouts to enable views or pages to
render content in different parts of the HTML page. For more information, see Layout in ASP.NET Core.
@using
The @using directive adds the C# using directive to the generated view:

@using System.IO
@{
var dir = Directory.GetCurrentDirectory();
}
<p>@dir</p>
In Razor components, @using also controls which components are in scope.

Directive attributes
@attributes
This scenario only applies to Razor components (.razor ).
@attributesallows a component to render non-declared attributes. For more information, see Create and
use ASP.NET Core Razor components.
@bind
This scenario only applies to Razor components (.razor ).
Data binding in components is accomplished with the @bind attribute. For more information, see Create and
use ASP.NET Core Razor components.
@on{event}
This scenario only applies to Razor components (.razor ).
Razor provides event handling features for components. For more information, see Create and use ASP.NET
Core Razor components.
@key
This scenario only applies to Razor components (.razor ).
The @key directive attribute causes the components diffing algorithm to guarantee preservation of elements
or components based on the key's value. For more information, see Create and use ASP.NET Core Razor
components.
@ref
This scenario only applies to Razor components (.razor ).
Component references ( @ref ) provide a way to reference a component instance so that you can issue
commands to that instance. For more information, see Create and use ASP.NET Core Razor components.

Templated Razor delegates

Razor templates allow you to define a UI snippet with the following format:

@<tag>...</tag>

The following example illustrates how to specify a templated Razor delegate as a Func<T,TResult>. The
dynamic type is specified for the parameter of the method that the delegate encapsulates. An object type is
specified as the return value of the delegate. The template is used with a List<T> of Pet that has a Name
property.

public class Pet

{
public string Name { get; set; }
}
 @{
Func<dynamic, object> petTemplate = @<p>You have a pet named <strong>@item.Name</strong>.</p>;

var pets = new List<Pet>

{
new Pet { Name = "Rin Tin Tin" },
new Pet { Name = "Mr. Bigglesworth" },
new Pet { Name = "K-9" }
};
}

The template is rendered with pets supplied by a foreach statement:

@foreach (var pet in pets)

{
@petTemplate(pet)
}

Rendered output:

<p>You have a pet named <strong>Rin Tin Tin</strong>.</p>

<p>You have a pet named <strong>Mr. Bigglesworth</strong>.</p>
<p>You have a pet named <strong>K-9</strong>.</p>

You can also supply an inline Razor template as an argument to a method. In the following example, the
Repeat method receives a Razor template. The method uses the template to produce HTML content with
repeats of items supplied from a list:

@using Microsoft.AspNetCore.Html

@functions {
public static IHtmlContent Repeat(IEnumerable<dynamic> items, int times,
Func<dynamic, IHtmlContent> template)
{
var html = new HtmlContentBuilder();

foreach (var item in items)

{
for (var i = 0; i < times; i++)
{
html.AppendHtml(template(item));
}
}

return html;
}
}

Using the list of pets from the prior example, the Repeat method is called with:
List<T> of Pet .
Number of times to repeat each pet.
Inline template to use for the list items of an unordered list.

<ul>
@Repeat(pets, 3, @<li>@item.Name</li>)
</ul>
Rendered output:

<ul>
<li>Rin Tin Tin</li>
<li>Rin Tin Tin</li>
<li>Rin Tin Tin</li>
<li>Mr. Bigglesworth</li>
<li>Mr. Bigglesworth</li>
<li>Mr. Bigglesworth</li>
<li>K-9</li>
<li>K-9</li>
<li>K-9</li>
</ul>

Tag Helpers
This scenario only applies to MVC views and Razor Pages (.cshtml).
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.1 or 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

Inspect the Razor C# class generated for a view

With .NET Core SDK 2.1 or later, the Razor SDK handles compilation of Razor files. When building a project,
the Razor SDK generates an obj/<build_configuration>/<target_framework_moniker>/Razor directory in
the project root. The directory structure within the Razor directory mirrors the project's directory structure.
Consider the following directory structure in an ASP.NET Core 2.1 Razor Pages project targeting .NET Core
2.1:
Areas/
Admin/
Pages/
Index.cshtml
Index.cshtml.cs
Pages/
Shared/
_Layout.cshtml
_ViewImports.cshtml
_ViewStart.cshtml
Index.cshtml
Index.cshtml.cs
Building the project in Debug configuration yields the following obj directory:
obj/
Debug/
netcoreapp2.1/
Razor/
Areas/
Admin/
Pages/
Index.g.cshtml.cs
Pages/
Shared/
_Layout.g.cshtml.cs
_ViewImports.g.cshtml.cs
_ViewStart.g.cshtml.cs
Index.g.cshtml.cs
To view the generated class for Pages/Index.cshtml, open
obj/Debug/netcoreapp2.1/Razor/Pages/Index.g.cshtml.cs.
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;
}
}

In Startup.ConfigureServices , override the RazorTemplateEngine added by MVC with the

CustomTemplateEngine class:

public void ConfigureServices(IServiceCollection services)

{
services.AddMvc();
services.AddSingleton<RazorTemplateEngine, CustomTemplateEngine>();
}

Set a breakpoint on the return csharpDocument; statement of CustomTemplateEngine . When program

execution stops at the breakpoint, 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.
 Create reusable UI using the Razor class library
project in ASP.NET Core
7/25/2019 • 6 minutes to read • Edit Online

By Rick Anderson
Razor views, pages, controllers, page models, Razor components, 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
View or download sample code (how to download)

Create a class library containing Razor UI

Visual Studio
.NET Core CLI
From the Visual Studio File menu, select New > Project.
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.
An RCL 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 an
RCL that exposes content in ~/Pages rather than ~/Areas/Pages .

Referencing RCL 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 an RCL 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 an RCL
In this section, an RCL is created. Razor files are added to the RCL.
Visual Studio
.NET Core CLI
Create the RCL project:
From the Visual Studio File menu, select New > Project.
Select ASP.NET Core Web Application.
Name the app RazorUIClassLib > OK.
Verify ASP.NET Core 2.1 or later is selected.
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
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

<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.
Select ASP.NET Core Web Application.
Name the app WebApp1.
Verify ASP.NET Core 2.1 or later is selected.
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 in use:
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 RCL, 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 RCL.
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>

Create an RCL with static assets

An RCL may require companion static assets that can be referenced by the consuming app of the RCL. ASP.NET
Core allows creating RCLs that include static assets that are available to a consuming app.
To include companion assets as part of an RCL, create a wwwroot folder in the class library and include any
required files in that folder.
When packing an RCL, all companion assets in the wwwroot folder are included in the package automatically
and are made available to apps referencing the package.
Consume content from a referenced RCL
The files included in the wwwroot folder of the RCL are exposed to the consuming app under the prefix
_content/{LIBRARY NAME}/ . For example, a library named Razor.Class.Lib results in a path to static content at
_content/Razor.Class.Lib/ .

The consuming app references static assets provided by the library with <script> , <style> , <img> , and other
HTML tags. The consuming app must have static file support enabled.
Multi-project development flow
When the consuming app runs:
The assets in the RCL stay in their original folders. The assets aren't moved to the consuming app.
Any change within the RCL's wwwroot folder is reflected in the consuming app after the RCL is rebuilt and
without rebuilding the consuming app.
When the RCL is built, a manifest is produced that describes the static web asset locations. The consuming app
reads the manifest at runtime to consume the assets from referenced projects and packages. When a new asset is
added to an RCL, the RCL must be rebuilt to update its manifest before a consuming app can access the new
asset.
Publish
When the app is published, the companion assets from all referenced projects and packages are copied into the
wwwroot folder of the published app under _content/{LIBRARY NAME}/ .
 ASP.NET Core built-in Tag Helpers
7/12/2019 • 2 minutes to read • Edit Online

By Peter Kellner
For an overview of Tag Helpers, see Tag Helpers in ASP.NET Core.
There are built-in Tag Helpers which aren't listed in this document. The unlisted Tag Helpers are used internally by
the Razor view engine. The Tag Helper for the ~ (tilde) character is unlisted. The tilde Tag Helper expands to the
root path of the website.

Built-in ASP.NET Core Tag Helpers

Anchor Tag Helper
Cache Tag Helper
Distributed Cache Tag Helper
Environment Tag Helper
FormActionTagHelper
Form Tag Helper
Form Action 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

Additional resources
Tag Helpers in ASP.NET Core
Tag Helper Components in ASP.NET Core
 Tag Helpers in ASP.NET Core
7/11/2019 • 11 minutes to read • Edit Online

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

{
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; }
}

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 *, Microsoft.AspNetCore.Mvc.TagHelpers
@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
subfolders; 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 subdirectory. 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
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, 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:

@using AuthoringTagHelpers
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@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 subdirectories. 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 .

Self-closing Tag Helpers

Many Tag Helpers can't be used as self-closing tags. Some Tag Helpers are designed to be self-
closing tags. Using a Tag Helper that was not designed to be self-closing suppresses the
rendered output. Self-closing a Tag Helper results in a self-closing tag in the rendered output.
For more information, see this note in Authoring Tag Helpers.

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:

<label class="caption" asp-for="FirstName"></label>

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 following code image shows the Form portion of the Views/Account/Register.cshtml Razor
view generated from the ASP.NET 4.5.x MVC template included with Visual Studio.
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:

<div class="form-group">
<label asp-for="Email" class="col-md-2 control-label"></label>
<div class="col-md-10">
<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:
Built-in ASP.NET Core Tag Helpers
Anchor Tag Helper
Cache Tag Helper
Distributed Cache Tag Helper
Environment Tag Helper
FormActionTagHelper
Form Tag Helper
Form Action 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

Additional resources
Author Tag Helpers
Working with Forms
TagHelperSamples on GitHub contains Tag Helper samples for working with Bootstrap.
 Author Tag Helpers in ASP.NET Core
7/11/2019 • 16 minutes to read • Edit Online

By Rick Anderson
View or download sample code (how to download)

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;
using System.Threading.Tasks;

namespace AuthoringTagHelpers.TagHelpers
{
public class EmailTagHelper : TagHelper
{
public override void Process(TagHelperContext context, TagHelperOutput output)
{
output.TagName = "a"; // Replaces <email> with <a> tag
}
}
}

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:

@using AuthoringTagHelpers
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, AuthoringTagHelpers

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:

@using AuthoringTagHelpers
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@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, not
necessarily the namespace ). 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.
1. Update the markup in the Views/Home/Contact.cshtml file with these changes:
 @{
ViewData["Title"] = "Contact";
}
<h2>@ViewData["Title"].</h2>
<h3>@ViewData["Message"]</h3>

<address>
One Microsoft Way<br />
Redmond, WA 98052<br />
<abbr title="Phone">P:</abbr>
425.555.0100
</address>

<address>
<strong>Support:</strong><email>Support</email><br />
<strong>Marketing:</strong><email>Marketing</email>
</address>

2. 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:

public class EmailTagHelper : TagHelper

{
private const string EmailDomain = "contoso.com";

// Can be passed via <email mail-to="..." />.

// PascalCase gets translated into kebab-case.
public string MailTo { get; set; }

public override void Process(TagHelperContext context, TagHelperOutput output)

{
output.TagName = "a"; // Replaces <email> with <a> tag

var address = MailTo + "@" + EmailDomain;

output.Attributes.SetAttribute("href", "mailto:" + address);
output.Content.SetContent(address);
}
}

Pascal-cased class and property names for tag helpers are translated into their 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:
 public override void Process(TagHelperContext context, TagHelperOutput output)
{
output.TagName = "a"; // Replaces <email> with <a> tag

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";
}
<h2>@ViewData["Title"].</h2>
<h3>@ViewData["Message"]</h3>

<address>
One Microsoft Way Copy Version <br />
Redmond, WA 98052-6399<br />
<abbr title="Phone">P:</abbr>
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
{
private const string EmailDomain = "contoso.com";
// 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 class EmailTagHelper : TagHelper
{
private const string EmailDomain = "contoso.com";
public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
{
output.TagName = "a"; // Replaces <email> with <a> tag
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.

@{
ViewData["Title"] = "Contact";
}
<h2>@ViewData["Title"].</h2>
<h3>@ViewData["Message"]</h3>

<address>
One Microsoft Way<br />
Redmond, WA 98052<br />
<abbr title="Phone">P:</abbr>
425.555.0100
</address>

<address>
<strong>Support:</strong><email>Support</email><br />
<strong>Marketing:</strong><email>Marketing</email>
</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.

using Microsoft.AspNetCore.Razor.TagHelpers;

namespace AuthoringTagHelpers.TagHelpers
{
[HtmlTargetElement(Attributes = "bold")]
public class BoldTagHelper : TagHelper
{
public override void Process(TagHelperContext context, TagHelperOutput output)
{
output.Attributes.RemoveAll("bold");
output.PreContent.SetHtmlContent("<strong>");
output.PostContent.SetHtmlContent("</strong>");
}
}
}
 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.

@{
ViewData["Title"] = "About";
}
<h2>@ViewData["Title"].</h2>
<h3>@ViewData["Message"]</h3>

<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
{
public override void Process(TagHelperContext context, TagHelperOutput output)
{
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;
using Microsoft.AspNetCore.Razor.TagHelpers;

namespace AuthoringTagHelpers.TagHelpers
{
public class WebsiteInformationTagHelper : TagHelper
{
public WebsiteContext Info { get; set; }

public override void Process(TagHelperContext context, TagHelperOutput output)

{
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;
}
}
}

As mentioned previously, tag helpers translates Pascal-cased C# class names and properties for tag
helpers into 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 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
@{
ViewData["Title"] = "About";
WebsiteContext webContext = new WebsiteContext {
Version = new Version(1, 3),
CopyrightYear = 1638,
Approved = true,
TagsToShow = 131 };
}
<h2>@ViewData["Title"].</h2>
<h3>@ViewData["Message"]</h3>

<p bold>Use this area to provide additional information.</p>

<bold> Is this bold?</bold>

<h3> web site info </h3>

<website-information info="webContext" />

NOTE
In the Razor markup shown below:

<website-information info="webContext" />

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:

<website-information info="webContext" >

</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.

using Microsoft.AspNetCore.Razor.TagHelpers;

namespace AuthoringTagHelpers.TagHelpers
{
[HtmlTargetElement(Attributes = nameof(Condition))]
public class ConditionTagHelper : TagHelper
{
public bool Condition { get; set; }

public override void Process(TagHelperContext context, TagHelperOutput output)

{
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,
CopyrightYear = 2015,
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; }

public override void Process(TagHelperContext context, TagHelperOutput output)

{
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
{
public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
{
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:

 @{
ViewData["Title"] = "Contact";
}
<h2>@ViewData["Title"].</h2>
<h3>@ViewData["Message"]</h3>

<address>
One Microsoft Way<br />
Redmond, WA 98052<br />
<abbr title="Phone">P:</abbr>
425.555.0100
</address>

<address>
<strong>Support:</strong><email>Support</email><br />
<strong>Marketing:</strong><email>Marketing</email>
</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:

[HtmlTargetElement("p")]
public class AutoLinkerHttpTagHelper : TagHelper
{
public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
{
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}
}
}

[HtmlTargetElement("p")]
public class AutoLinkerWwwTagHelper : TagHelper
{
public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
{
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(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:
 public class AutoLinkerHttpTagHelper : TagHelper
{
public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
{
var childContent = output.Content.IsModified ? output.Content.GetContent() :
(await output.GetChildContentAsync()).GetContent();

// Find Urls in the content and replace them with their anchor tag equivalent.
output.Content.SetHtmlContent(Regex.Replace(
childContent,
@"\b(?:https?://)(\S+)\b",
"<a target=\"_blank\" href=\"$0\">$0</a>")); // http link version}
}
}

[HtmlTargetElement("p")]
public class AutoLinkerWwwTagHelper : TagHelper
{
public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
{
var childContent = output.Content.IsModified ? output.Content.GetContent() :
(await output.GetChildContentAsync()).GetContent();

// Find Urls in the content and replace them with their anchor tag equivalent.
output.Content.SetHtmlContent(Regex.Replace(
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:

var childContent = await output.GetChildContentAsync();

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:

var childContent = output.Content.IsModified ? output.Content.GetContent() :

(await output.GetChildContentAsync()).GetContent();

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.
 public class AutoLinkerHttpTagHelper : TagHelper
{
// 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 preceding code guarantees 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:

public class AutoLinkerHttpTagHelper : TagHelper

{
public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
{
var childContent = output.Content.IsModified ? output.Content.GetContent() :
(await output.GetChildContentAsync()).GetContent();

// Find Urls in the content and replace them with their anchor tag equivalent.
output.Content.SetHtmlContent(Regex.Replace(
childContent,
@"\b(?:https?://)(\S+)\b",
"<a target=\"_blank\" href=\"$0\">$0</a>")); // http link version}
}
}

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.

Load minified partial view TagHelper

In production environments, performance can be improved by loading minified partial views. To take advantage
of minified partial view in production:
Create/set up a pre-build process that minifies partial views.
Use the following code to load minified partial views in non-development environments.
public class MinifiedVersionPartialTagHelper : PartialTagHelper
{
public MinifiedVersionPartialTagHelper(ICompositeViewEngine viewEngine,
IViewBufferScope viewBufferScope)
: base(viewEngine, viewBufferScope)
{

public override Task ProcessAsync(TagHelperContext context, TagHelperOutput output)

{
// Append ".min" to load the minified partial view.
if (!IsDevelopment())
{
Name += ".min";
}

return base.ProcessAsync(context, output);

}

private bool IsDevelopment()

{
return Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT")
== EnvironmentName.Development;
}
}
 Tag Helpers in forms in ASP.NET Core
8/2/2019 • 18 minutes to read • Edit Online

By Rick Anderson, N. Taylor Mullen, 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">

<!-- Input and Submit elements -->
</form>

The Form Tag Helper above generates the following HTML:

<form method="post" action="/Demo/Register">

<!-- Input and Submit elements -->
<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">
<!-- Input and Submit elements -->
</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"]"
method="post" class="form-horizontal" role="form">

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 Form Action Tag Helper

The Form Action Tag Helper generates the formaction attribute on the generated <button ...> or
<input type="image" ...> tag. The formaction attribute controls where a form submits its data. It binds to <input>
elements of type image and <button> elements. The Form Action Tag Helper enables the usage of several
AnchorTagHelper asp- attributes to control what formaction link is generated for the corresponding element.
Supported AnchorTagHelper attributes to control the value of formaction :

ATTRIBUTE DESCRIPTION

asp-controller The name of the controller.

asp-action The name of the action method.

asp-area The name of the area.

asp-page The name of the Razor page.

asp-page-handler The name of the Razor page handler.

asp-route The name of the route.

asp-route-{value} A single URL route value. For example, asp-route-id="1234"

.

asp-all-route-data All route values.

asp-fragment The URL fragment.

Submit to controller example

The following markup submits the form to the Index action of HomeController when the input or button are
selected:
 <form method="post">
<button asp-controller="Home" asp-action="Index">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-controller="Home"
asp-action="Index">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/Home">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/Home">
</form>

Submit to page example

The following markup submits the form to the About Razor Page:

<form method="post">
<button asp-page="About">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-page="About">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/About">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/About">
</form>

Submit to route example

Consider the /Home/Test endpoint:

public class HomeController : Controller

{
[Route("/Home/Test", Name = "Custom")]
public string Test()
{
return "This is the test page";
}
}

The following markup submits the form to the /Home/Test endpoint.

<form method="post">
<button asp-route="Custom">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-route="Custom">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/Home/Test">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/Home/Test">
</form>
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 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
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-local"

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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class RegisterViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }

[Required]
[DataType(DataType.Password)]
public string Password { get; set; }
}
}

@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>
<button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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 string Email { get; set; }

[DataType(DataType.Password)]
public string Password { get; set; }

public AddressViewModel Address { get; set; }

}

In the view, we bind to Address.AddressLine1 :

@model RegisterAddressViewModel

<form asp-controller="Demo" asp-action="RegisterAddress" method="post">

Email: <input asp-for="Email" /> <br />
Password: <input asp-for="Password" /><br />
Address: <input asp-for="Address.AddressLine1" /><br />
<button type="submit">Register</button>
</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 class ToDoItem

{
public string Name { get; set; }

public bool IsDone { get; set; }

}

The following Razor shows how to iterate over a collection:

@model List<ToDoItem>

<form asp-controller="ToDo" asp-action="Edit" method="post">

<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>
<button type="submit">Save</button>
</form>

The Views/Shared/EditorTemplates/ToDoItem.cshtml template:

 @model ToDoItem

<td>
<label asp-for="@Model.Name"></label>
@Html.DisplayFor(model => model.Name)
</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>
*@

foreach should be used if possible when the value is going to be used in an asp-for or Html.DisplayFor
equivalent context. In general, for is better than foreach (if the scenario allows it) because it doesn't need to
allocate an enumerator; however, 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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class DescriptionViewModel
{
[MinLength(5)]
[MaxLength(1024)]
public string Description { get; set; }
}
}
 @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
&#x27;1024&#x27;."
data-val-maxlength-max="1024"
data-val-minlength="The field Description must be a string or array type with a minimum length of
&#x27;5&#x27;."
data-val-minlength-min="5"
id="Description" name="Description">
</textarea>
<button type="submit">Test</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</form>

The Label Tag Helper

Generates the label caption and for attribute on a <label> 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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class SimpleViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }
}
}
 @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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class RegisterViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }

[Required]
[DataType(DataType.Password)]
public string Password { get; set; }
}
}

@model RegisterViewModel

<form asp-controller="Demo" asp-action="RegisterValidation" method="post">

<div asp-validation-summary="ModelOnly"></div>
Email: <input asp-for="Email" /> <br />
<span asp-validation-for="Email"></span><br />
Password: <input asp-for="Password" /><br />
<span asp-validation-for="Password"></span><br />
<button type="submit">Register</button>
</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>
<span class="field-validation-valid" data-valmsg-replace="true"
data-valmsg-for="Password"></span><br>
<button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

namespace FormsTagHelper.ViewModels
{
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 Index()

{
var model = new CountryViewModel();
model.Country = "CA";
return View(model);
}

The HTTP POST Index method displays the selection:

 [HttpPost]
[ValidateAntiForgeryToken]
public IActionResult Index(CountryViewModel model)
{
if (ModelState.IsValid)
{
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">

<select asp-for="Country" asp-items="Model.Countries"></select>
<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>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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 )

<select asp-for="Country" asp-items="Model.Countries"></select>

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; }
}
}

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
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>
<br /><button type="submit">Register</button>
</form>

You can decorate your enumerator list with the Display attribute to get a richer UI:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public enum CountryEnum
{
[Display(Name = "United Mexican States")]
Mexico,
[Display(Name = "United States of America")]
USA,
Canada,
France,
Germany,
Spain
}
}

The following HTML is generated:

 <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>
<br /><button type="submit">Register</button>
<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:
 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",
Group = NorthAmericaGroup
},
new SelectListItem
{
Value = "US",
Text = "USA",
Group = NorthAmericaGroup
},
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 string Country { get; set; }

public List<SelectListItem> Countries { get; }

The two groups are shown below:

The generated HTML:

<form method="post" action="/Home/IndexGroup">

<select id="Country" name="Country">
<optgroup label="North America">
<option value="MEX">Mexico</option>
<option value="CAN">Canada</option>
<option value="US">USA</option>
</optgroup>
<optgroup label="Europe">
<option value="FR">France</option>
<option value="ES">Spain</option>
<option value="DE">Germany</option>
</optgroup>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

namespace FormsTagHelper.ViewModels
{
public class CountryViewModelIEnumerable
{
public IEnumerable<string> CountryCodes { 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" },
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>
<br /><button type="submit">Register</button>
</form>

Generates the following HTML:

<form method="post" action="/Home/IndexMultiSelect">

<select id="CountryCodes"
multiple="multiple"
name="CountryCodes"><option value="MX">Mexico</option>
<option value="CA">Canada</option>
<option value="US">USA</option>
<option value="FR">France</option>
<option value="ES">Spain</option>
<option value="DE">Germany</option>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

@model CountryViewModel

<form asp-controller="Home" asp-action="IndexEmpty" method="post">

@Html.EditorForModel()
<br /><button type="submit">Register</button>
</form>

The Views/Shared/EditorTemplates/CountryViewModel.cshtml template:

@model CountryViewModel

<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:

public IActionResult IndexNone()

{
var model = new CountryViewModel();
model.Insert(0, new SelectListItem("<none>", ""));
return View(model);
}
 @model CountryViewModel

<form asp-controller="Home" asp-action="IndexEmpty" method="post">

<select asp-for="Country">
<option value="">&lt;none&gt;</option>
<option value="MX">Mexico</option>
<option value="CA">Canada</option>
<option value="US">USA</option>
</select>
<br /><button type="submit">Register</button>
</form>

The correct <option> element will be selected ( contain the selected="selected" attribute) depending on the
current Country value.

public IActionResult IndexOption(int id)

{
var model = new CountryViewModel();
model.Country = "CA";
return View(model);
}

<form method="post" action="/Home/IndexEmpty">

<select id="Country" name="Country">
<option value="">&lt;none&gt;</option>
<option value="MX">Mexico</option>
<option value="CA" selected="selected">Canada</option>
<option value="US">USA</option>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</form>

Additional resources
Tag Helpers in ASP.NET Core
HTML Form element
Request Verification Token
Model Binding in ASP.NET Core
Model validation in ASP.NET Core MVC
IAttributeAdapter Interface
Code snippets for this document
 Tag Helper Components in ASP.NET Core
6/12/2019 • 5 minutes to read • Edit Online

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.
View or download sample code (how to download)

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;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Razor.TagHelpers;

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);
}

return Task.CompletedTask;
}
}
}

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;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Razor.TagHelpers;

namespace RazorPagesSample.TagHelpers
{
public class AddressScriptTagHelperComponent : TagHelperComponent
{
public override int Order => 2;

public override async Task ProcessAsync(TagHelperContext context,

TagHelperOutput output)
{
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:
Tag Helper Components in ASP.NET Core
 Use cases
Inject into HTML head element
Inject into HTML body element
Register a Component
Registration via services container
Registration via Razor file
Registration via Page Model or controller
Create a Component
Additional resources
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:

public void ConfigureServices(IServiceCollection services)

{
services.Configure<CookiePolicyOptions>(options =>
{
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

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));

}

In the preceding code:

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:

public override async Task ProcessAsync(TagHelperContext context,

TagHelperOutput output)
{
if (string.Equals(context.TagName, "address",
StringComparison.OrdinalIgnoreCase) &&
output.Attributes.ContainsName("printable"))
{
TagHelperContent childContent = await output.GetChildContentAsync();
string content = childContent.GetContent();
output.Content.SetHtmlContent(
$"<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 Microsoft.AspNetCore.Mvc.RazorPages;
using RazorPagesSample.TagHelpers;

public class IndexModel : PageModel

{
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));
}
}

In the preceding code:

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;
using Microsoft.AspNetCore.Mvc.Razor.TagHelpers;
using Microsoft.AspNetCore.Razor.TagHelpers;
using Microsoft.Extensions.Logging;

namespace RazorPagesSample.TagHelpers
{
[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>";

public override int Order => 3;

public override async Task ProcessAsync(TagHelperContext context,

TagHelperOutput output)
{
if (string.Equals(context.TagName, "address",
StringComparison.OrdinalIgnoreCase) &&
output.Attributes.ContainsName("printable"))
{
var content = await output.GetChildContentAsync();
output.Content.SetHtmlContent(
$"<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>
One Microsoft Way<br />
Redmond, WA 98052-6399<br />
<abbr title="Phone">P:</abbr>
425.555.0100
</address>
Additional resources
Dependency injection in ASP.NET Core
Dependency injection into views in ASP.NET Core
ASP.NET Core built-in Tag Helpers
 Anchor Tag Helper in ASP.NET Core
7/12/2019 • 6 minutes to read • Edit Online

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.
For an overview of Tag Helpers, see Tag Helpers in ASP.NET Core.
View or download sample code (how to download)
SpeakerController is used in samples throughout this document:

using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;
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; }
}

Anchor Tag Helper attributes

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:

<a asp-controller="Speaker"
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:

 app.UseMvc(routes =>
{
// need route and attribute on controller: [Area("Blogs")]
routes.MapRoute(name: "mvcAreaRoute",
template: "{area:exists}/{controller=Home}/{action=Index}");

// default route for non-areas

routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});

The MVC view uses the model, provided by the action, as follows:

@model Speaker
<!DOCTYPE html>
<html>
<body>
<a asp-controller="Speaker"
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>
<a asp-controller="Speaker"
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:

<a asp-controller="Speaker"
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 examples depict
how the asp-area attribute causes a remapping of routes.
Usage in Razor Pages
Razor Pages areas are supported in ASP.NET Core 2.1 or later.
Consider the following directory hierarchy:
{Project name}
wwwroot
Areas
Sessions
Pages
_ViewStart.cshtml
Index.cshtml
Index.cshtml.cs
Pages
The markup to reference the Sessions area Index Razor Page is:

<a asp-area="Sessions"
asp-page="/Index">View Sessions</a>

The generated HTML:

<a href="/Sessions">View Sessions</a>

TIP
To support areas in a Razor Pages app, do one of the following in Startup.ConfigureServices :
Set the compatibility version to 2.1 or later.
Set the RazorPagesOptions.AllowAreas property to true :

services.AddMvc()
.AddRazorPagesOptions(options => options.AllowAreas = true);

Usage in MVC
Consider the following directory hierarchy:
{Project name}
wwwroot
Areas
 Blogs
Controllers
HomeController.cs
Views
Home
AboutBlog.cshtml
Index.cshtml
_ViewStart.cshtml
Controllers
Setting asp-area to "Blogs" prefixes the directory Areas/Blogs to the routes of the associated controllers
and views for this anchor tag. The markup to reference the AboutBlog view 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
To support areas 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:

app.UseMvc(routes =>
{
// need route and attribute on controller: [Area("Blogs")]
routes.MapRoute(name: "mvcAreaRoute",
template: "{area:exists}/{controller=Home}/{action=Index}");

// default route for non-areas

routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});

asp-protocol
The asp-protocol attribute is for specifying a protocol (such as https ) in your URL. For example:

<a asp-protocol="https"
asp-controller="Home"
asp-action="About">About</a>

The generated HTML:

<a href="https://localhost/Home/About">About</a>

The host name in the example is localhost. 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-controller="Home"
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 the On<Verb> prefix of
the page handler method name is omitted in the asp-page-handler attribute value. When the method is
asynchronous, the Async suffix is 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>

Additional resources
Areas in ASP.NET Core
Introduction to Razor Pages in ASP.NET Core
Compatibility version for ASP.NET Core MVC
 Cache Tag Helper in ASP.NET Core MVC
7/12/2019 • 4 minutes to read • Edit Online

By Peter Kellner and Luke Latham

The Cache Tag Helper provides the ability to improve the performance of your ASP.NET Core app by caching its
content to the internal ASP.NET Core cache provider.
For an overview of Tag Helpers, see Tag Helpers in ASP.NET Core.
The following Razor markup caches the current date:

<cache>@DateTime.Now</cache>

The first request to the page that contains the Tag Helper displays the current date. Additional requests show the
cached value until the cache expires (default 20 minutes) or until the cached date is evicted from the cache.

Cache Tag Helper Attributes

enabled
ATTRIBUTE TYPE EXAMPLES DEFAULT

Boolean true , false true

enabled determines if the content enclosed by the Cache Tag Helper is cached. The default is true . If set to
false , the rendered output is not cached.

Example:

<cache enabled="true">
Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

expires-on
ATTRIBUTE TYPE EXAMPLE

DateTimeOffset @new DateTime(2025,1,29,17,02,0)

expires-on sets an absolute expiration date for the cached item.

The following example caches the contents of the Cache Tag Helper until 5:02 PM on January 29, 2025:

<cache expires-on="@new DateTime(2025,1,29,17,02,0)">

Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

expires-after
 ATTRIBUTE TYPE EXAMPLE DEFAULT

TimeSpan @TimeSpan.FromSeconds(120) 20 minutes

expires-after sets the length of time from the first request time to cache the contents.
Example:

<cache expires-after="@TimeSpan.FromSeconds(120)">
Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

The Razor View Engine sets the default expires-after value to twenty minutes.
expires-sliding
ATTRIBUTE TYPE EXAMPLE

TimeSpan @TimeSpan.FromSeconds(60)

Sets the time that a cache entry should be evicted if its value hasn't been accessed.
Example:

<cache expires-sliding="@TimeSpan.FromSeconds(60)">
Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

vary-by-header
ATTRIBUTE TYPE EXAMPLES

String User-Agent , User-Agent,content-encoding

vary-by-header accepts a comma-delimited list of header values that trigger a cache refresh when they change.
The following example monitors the header value User-Agent . The example caches the content for every
different User-Agent presented to the web server:

<cache vary-by-header="User-Agent">
Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

vary-by-query
ATTRIBUTE TYPE EXAMPLES

String Make , Make,Model

vary-by-query accepts a comma-delimited list of Keys in a query string ( Query) that trigger a cache refresh when
the value of any listed key changes.
The following example monitors the values of Make and Model . The example caches the content for every
different Make and Model presented to the web server:
 <cache vary-by-query="Make,Model">
Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

vary-by-route
ATTRIBUTE TYPE EXAMPLES

String Make , Make,Model

vary-by-route accepts a comma-delimited list of route parameter names that trigger a cache refresh when the
route data parameter value changes.
Example:
Startup.cs:

routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{Make?}/{Model?}");

Index.cshtml:

<cache vary-by-route="Make,Model">
Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

vary-by-cookie
ATTRIBUTE TYPE EXAMPLES

String .AspNetCore.Identity.Application ,
.AspNetCore.Identity.Application,HairColor

vary-by-cookie accepts a comma-delimited list of cookie names that trigger a cache refresh when the cookie
values change.
The following example monitors the cookie associated with ASP.NET Core Identity. When a user is
authenticated, a change in the Identity cookie triggers a cache refresh:

<cache vary-by-cookie=".AspNetCore.Identity.Application">
Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

vary-by-user
ATTRIBUTE TYPE EXAMPLES DEFAULT

Boolean true , false true

vary-by-user specifies whether or not the cache resets when the signed-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 monitors the current logged in user to trigger a cache refresh:

<cache vary-by-user="true">
Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

Using this attribute maintains the contents in cache through a sign-in and sign-out cycle. When the value is set to
true , an authentication cycle invalidates the cache for the authenticated user. The cache is invalidated because a
new unique cookie value is generated when a user is authenticated. Cache is maintained for the anonymous state
when no cookie is present or the cookie has expired. If the user is not authenticated, the cache is maintained.
vary-by
ATTRIBUTE TYPE EXAMPLE

String @Model

vary-by allows for customization of what data is 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, this results in a scenario where 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 the sum as the single model property. When this sum
changes, the content of the Cache Tag Helper is rendered and cached again.
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">
Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

priority
ATTRIBUTE TYPE EXAMPLES DEFAULT

CacheItemPriority High , Low , NeverRemove , Normal Normal

priority provides cache eviction guidance to the built-in cache provider. The web server evicts Low cache
entries first when it's under memory pressure.
Example:
 <cache priority="High">
Current Time Inside Cache Tag Helper: @DateTime.Now
</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 cached items are always retained. See
the topics in the Additional Resources section for more information.
The Cache Tag Helper is dependent on the memory cache service. The Cache Tag Helper adds the service if it
hasn't been added.

Additional resources
Cache in-memory in ASP.NET Core
Introduction to Identity on ASP.NET Core
 Distributed Cache Tag Helper in ASP.NET Core
7/12/2019 • 2 minutes to read • Edit Online

By Peter Kellner and Luke Latham

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.
For an overview of Tag Helpers, see Tag Helpers in ASP.NET Core.
The Distributed Cache Tag Helper inherits from the same base class as the Cache Tag Helper. All of the Cache Tag
Helper attributes are available to the Distributed Tag Helper.
The Distributed Cache Tag Helper uses constructor injection. The IDistributedCache interface is passed into the
Distributed Cache Tag Helper's constructor. If no concrete implementation of IDistributedCache is created in
Startup.ConfigureServices ( Startup.cs), the Distributed Cache Tag Helper uses the same in-memory provider for
storing cached data as the Cache Tag Helper.

Distributed Cache Tag Helper Attributes

Attributes shared with the Cache Tag Helper
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

The Distributed Cache Tag Helper inherits from the same class as Cache Tag Helper. For descriptions of these
attributes, see the Cache Tag Helper.
name
ATTRIBUTE TYPE EXAMPLE

String my-distributed-cache-unique-key-101

name is required. The name attribute is used as a key for each stored cache instance. Unlike the Cache Tag Helper
that assigns a cache key to each instance based on the Razor page name and location in the Razor page, the
Distributed Cache Tag Helper only bases its key on the attribute name .
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 Distributed caching in ASP.NET
Core. Both implementations involve setting an instance of IDistributedCache in Startup .
There are no tag attributes specifically associated with using any specific implementation of IDistributedCache .

Additional resources
Cache Tag Helper in ASP.NET Core MVC
Dependency injection in ASP.NET Core
Distributed caching 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
7/12/2019 • 2 minutes to read • Edit Online

By Peter Kellner, Hisham Bin Ateya, and Luke Latham

The Environment Tag Helper conditionally renders its enclosed content based on the current hosting environment.
The Environment Tag Helper's single attribute, names , is a comma-separated list of environment names. If any of
the provided environment names match the current environment, the enclosed content is rendered.
For an overview of Tag Helpers, see Tag Helpers in ASP.NET Core.

Environment Tag Helper Attributes

names
names accepts a single hosting environment name or a comma-separated list of hosting environment names that
trigger the rendering of the enclosed content.
Environment values are compared to the current value returned by IHostingEnvironment.EnvironmentName. The
comparison ignores case.
The following example uses an Environment Tag Helper. The content is rendered if the hosting environment is
Staging or Production:

<environment names="Staging,Production">
<strong>HostingEnvironment.EnvironmentName is Staging or Production</strong>
</environment>

include and exclude attributes

include & exclude attributes control rendering the enclosed content based on the included or excluded hosting
environment names.
include
The include property exhibits similar behavior to the names attribute. An environment listed in the include
attribute value must match the app's hosting environment (IHostingEnvironment.EnvironmentName) to render
the content of the <environment> tag.

<environment include="Staging,Production">
<strong>HostingEnvironment.EnvironmentName is Staging or Production</strong>
</environment>

exclude
In contrast to the include attribute, the content of the <environment> tag is rendered when the hosting
environment doesn't match an environment listed in the exclude attribute value.

<environment exclude="Development">
<strong>HostingEnvironment.EnvironmentName is not Development</strong>
</environment>
Additional resources
Use multiple environments in ASP.NET Core
 Tag Helpers in forms in ASP.NET Core
8/2/2019 • 18 minutes to read • Edit Online

By Rick Anderson, N. Taylor Mullen, 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">

<!-- Input and Submit elements -->
</form>

The Form Tag Helper above generates the following HTML:

<form method="post" action="/Demo/Register">

<!-- Input and Submit elements -->
<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">
<!-- Input and Submit elements -->
</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"]"
method="post" class="form-horizontal" role="form">

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 Form Action Tag Helper

The Form Action Tag Helper generates the formaction attribute on the generated <button ...> or
<input type="image" ...> tag. The formaction attribute controls where a form submits its data. It binds to <input>
elements of type image and <button> elements. The Form Action Tag Helper enables the usage of several
AnchorTagHelper asp- attributes to control what formaction link is generated for the corresponding element.
Supported AnchorTagHelper attributes to control the value of formaction :

ATTRIBUTE DESCRIPTION

asp-controller The name of the controller.

asp-action The name of the action method.

asp-area The name of the area.

asp-page The name of the Razor page.

asp-page-handler The name of the Razor page handler.

asp-route The name of the route.

asp-route-{value} A single URL route value. For example, asp-route-id="1234"

.

asp-all-route-data All route values.

asp-fragment The URL fragment.

Submit to controller example

The following markup submits the form to the Index action of HomeController when the input or button are
selected:
 <form method="post">
<button asp-controller="Home" asp-action="Index">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-controller="Home"
asp-action="Index">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/Home">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/Home">
</form>

Submit to page example

The following markup submits the form to the About Razor Page:

<form method="post">
<button asp-page="About">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-page="About">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/About">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/About">
</form>

Submit to route example

Consider the /Home/Test endpoint:

public class HomeController : Controller

{
[Route("/Home/Test", Name = "Custom")]
public string Test()
{
return "This is the test page";
}
}

The following markup submits the form to the /Home/Test endpoint.

<form method="post">
<button asp-route="Custom">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-route="Custom">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/Home/Test">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/Home/Test">
</form>
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 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
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-local"

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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class RegisterViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }

[Required]
[DataType(DataType.Password)]
public string Password { get; set; }
}
}

@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>
<button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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 string Email { get; set; }

[DataType(DataType.Password)]
public string Password { get; set; }

public AddressViewModel Address { get; set; }

}

In the view, we bind to Address.AddressLine1 :

@model RegisterAddressViewModel

<form asp-controller="Demo" asp-action="RegisterAddress" method="post">

Email: <input asp-for="Email" /> <br />
Password: <input asp-for="Password" /><br />
Address: <input asp-for="Address.AddressLine1" /><br />
<button type="submit">Register</button>
</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 class ToDoItem

{
public string Name { get; set; }

public bool IsDone { get; set; }

}

The following Razor shows how to iterate over a collection:

@model List<ToDoItem>

<form asp-controller="ToDo" asp-action="Edit" method="post">

<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>
<button type="submit">Save</button>
</form>

The Views/Shared/EditorTemplates/ToDoItem.cshtml template:

 @model ToDoItem

<td>
<label asp-for="@Model.Name"></label>
@Html.DisplayFor(model => model.Name)
</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>
*@

foreach should be used if possible when the value is going to be used in an asp-for or Html.DisplayFor
equivalent context. In general, for is better than foreach (if the scenario allows it) because it doesn't need to
allocate an enumerator; however, 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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class DescriptionViewModel
{
[MinLength(5)]
[MaxLength(1024)]
public string Description { get; set; }
}
}
 @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
&#x27;1024&#x27;."
data-val-maxlength-max="1024"
data-val-minlength="The field Description must be a string or array type with a minimum length of
&#x27;5&#x27;."
data-val-minlength-min="5"
id="Description" name="Description">
</textarea>
<button type="submit">Test</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</form>

The Label Tag Helper

Generates the label caption and for attribute on a <label> 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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class SimpleViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }
}
}
 @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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class RegisterViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }

[Required]
[DataType(DataType.Password)]
public string Password { get; set; }
}
}

@model RegisterViewModel

<form asp-controller="Demo" asp-action="RegisterValidation" method="post">

<div asp-validation-summary="ModelOnly"></div>
Email: <input asp-for="Email" /> <br />
<span asp-validation-for="Email"></span><br />
Password: <input asp-for="Password" /><br />
<span asp-validation-for="Password"></span><br />
<button type="submit">Register</button>
</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>
<span class="field-validation-valid" data-valmsg-replace="true"
data-valmsg-for="Password"></span><br>
<button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

namespace FormsTagHelper.ViewModels
{
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 Index()

{
var model = new CountryViewModel();
model.Country = "CA";
return View(model);
}

The HTTP POST Index method displays the selection:

 [HttpPost]
[ValidateAntiForgeryToken]
public IActionResult Index(CountryViewModel model)
{
if (ModelState.IsValid)
{
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">

<select asp-for="Country" asp-items="Model.Countries"></select>
<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>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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 )

<select asp-for="Country" asp-items="Model.Countries"></select>

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; }
}
}

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
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>
<br /><button type="submit">Register</button>
</form>

You can decorate your enumerator list with the Display attribute to get a richer UI:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public enum CountryEnum
{
[Display(Name = "United Mexican States")]
Mexico,
[Display(Name = "United States of America")]
USA,
Canada,
France,
Germany,
Spain
}
}

The following HTML is generated:

 <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>
<br /><button type="submit">Register</button>
<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:
 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",
Group = NorthAmericaGroup
},
new SelectListItem
{
Value = "US",
Text = "USA",
Group = NorthAmericaGroup
},
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 string Country { get; set; }

public List<SelectListItem> Countries { get; }

The two groups are shown below:

The generated HTML:

<form method="post" action="/Home/IndexGroup">

<select id="Country" name="Country">
<optgroup label="North America">
<option value="MEX">Mexico</option>
<option value="CAN">Canada</option>
<option value="US">USA</option>
</optgroup>
<optgroup label="Europe">
<option value="FR">France</option>
<option value="ES">Spain</option>
<option value="DE">Germany</option>
</optgroup>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

namespace FormsTagHelper.ViewModels
{
public class CountryViewModelIEnumerable
{
public IEnumerable<string> CountryCodes { 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" },
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>
<br /><button type="submit">Register</button>
</form>

Generates the following HTML:

<form method="post" action="/Home/IndexMultiSelect">

<select id="CountryCodes"
multiple="multiple"
name="CountryCodes"><option value="MX">Mexico</option>
<option value="CA">Canada</option>
<option value="US">USA</option>
<option value="FR">France</option>
<option value="ES">Spain</option>
<option value="DE">Germany</option>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

@model CountryViewModel

<form asp-controller="Home" asp-action="IndexEmpty" method="post">

@Html.EditorForModel()
<br /><button type="submit">Register</button>
</form>

The Views/Shared/EditorTemplates/CountryViewModel.cshtml template:

@model CountryViewModel

<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:

public IActionResult IndexNone()

{
var model = new CountryViewModel();
model.Insert(0, new SelectListItem("<none>", ""));
return View(model);
}
 @model CountryViewModel

<form asp-controller="Home" asp-action="IndexEmpty" method="post">

<select asp-for="Country">
<option value="">&lt;none&gt;</option>
<option value="MX">Mexico</option>
<option value="CA">Canada</option>
<option value="US">USA</option>
</select>
<br /><button type="submit">Register</button>
</form>

The correct <option> element will be selected ( contain the selected="selected" attribute) depending on the
current Country value.

public IActionResult IndexOption(int id)

{
var model = new CountryViewModel();
model.Country = "CA";
return View(model);
}

<form method="post" action="/Home/IndexEmpty">

<select id="Country" name="Country">
<option value="">&lt;none&gt;</option>
<option value="MX">Mexico</option>
<option value="CA" selected="selected">Canada</option>
<option value="US">USA</option>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</form>

Additional resources
Tag Helpers in ASP.NET Core
HTML Form element
Request Verification Token
Model Binding in ASP.NET Core
Model validation in ASP.NET Core MVC
IAttributeAdapter Interface
Code snippets for this document
 Image Tag Helper in ASP.NET Core
7/12/2019 • 2 minutes to read • Edit Online

By Peter Kellner
The Image Tag Helper enhances the <img> tag to provide cache-busting behavior for static image files.
A cache-busting string is a unique value representing the hash of the static image file appended to the asset's URL.
The unique string prompts clients (and some proxies) to reload the image from the host web server and not from
the client's cache.
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.
If the file on the host web server changes, a unique request URL is generated that includes the updated request
parameter.
For an overview of Tag Helpers, see Tag Helpers in ASP.NET Core.

Image Tag Helper Attributes

src
To activate the Image Tag Helper, the src attribute is required on the <img> element.
The image source ( src ) must point to a physical static file on the server. If the src is a remote URI, the cache-
busting query string parameter isn't generated.
asp-append-version
When asp-append-version is specified with a true value along with a src attribute, the Image Tag Helper is
invoked.
The following example uses an Image Tag Helper:

<img src="~/images/asplogo.png" asp-append-version="true">

If the static file exists in the directory /wwwroot/images/, 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 asplogo.png file on disk. If the web server is
unable to obtain read access to the static file, no v parameter is added to the src attribute in the rendered
markup.

Hash caching behavior

The Image Tag Helper uses the cache provider on the local web server to store the calculated Sha512 hash of a
given file. If the file is requested multiple times, the hash isn't recalculated. The cache is invalidated by a file
watcher that's attached to the file when the file's Sha512 hash is calculated. When the file changes on disk, a new
hash is calculated and cached.
Additional resources
Cache in-memory in ASP.NET Core
 Tag Helpers in forms in ASP.NET Core
8/2/2019 • 18 minutes to read • Edit Online

By Rick Anderson, N. Taylor Mullen, 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">

<!-- Input and Submit elements -->
</form>

The Form Tag Helper above generates the following HTML:

<form method="post" action="/Demo/Register">

<!-- Input and Submit elements -->
<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">
<!-- Input and Submit elements -->
</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"]"
method="post" class="form-horizontal" role="form">

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 Form Action Tag Helper

The Form Action Tag Helper generates the formaction attribute on the generated <button ...> or
<input type="image" ...> tag. The formaction attribute controls where a form submits its data. It binds to <input>
elements of type image and <button> elements. The Form Action Tag Helper enables the usage of several
AnchorTagHelper asp- attributes to control what formaction link is generated for the corresponding element.
Supported AnchorTagHelper attributes to control the value of formaction :

ATTRIBUTE DESCRIPTION

asp-controller The name of the controller.

asp-action The name of the action method.

asp-area The name of the area.

asp-page The name of the Razor page.

asp-page-handler The name of the Razor page handler.

asp-route The name of the route.

asp-route-{value} A single URL route value. For example, asp-route-id="1234"

.

asp-all-route-data All route values.

asp-fragment The URL fragment.

Submit to controller example

The following markup submits the form to the Index action of HomeController when the input or button are
selected:
 <form method="post">
<button asp-controller="Home" asp-action="Index">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-controller="Home"
asp-action="Index">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/Home">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/Home">
</form>

Submit to page example

The following markup submits the form to the About Razor Page:

<form method="post">
<button asp-page="About">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-page="About">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/About">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/About">
</form>

Submit to route example

Consider the /Home/Test endpoint:

public class HomeController : Controller

{
[Route("/Home/Test", Name = "Custom")]
public string Test()
{
return "This is the test page";
}
}

The following markup submits the form to the /Home/Test endpoint.

<form method="post">
<button asp-route="Custom">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-route="Custom">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/Home/Test">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/Home/Test">
</form>
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 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
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-local"

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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class RegisterViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }

[Required]
[DataType(DataType.Password)]
public string Password { get; set; }
}
}

@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>
<button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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 string Email { get; set; }

[DataType(DataType.Password)]
public string Password { get; set; }

public AddressViewModel Address { get; set; }

}

In the view, we bind to Address.AddressLine1 :

@model RegisterAddressViewModel

<form asp-controller="Demo" asp-action="RegisterAddress" method="post">

Email: <input asp-for="Email" /> <br />
Password: <input asp-for="Password" /><br />
Address: <input asp-for="Address.AddressLine1" /><br />
<button type="submit">Register</button>
</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 class ToDoItem

{
public string Name { get; set; }

public bool IsDone { get; set; }

}

The following Razor shows how to iterate over a collection:

@model List<ToDoItem>

<form asp-controller="ToDo" asp-action="Edit" method="post">

<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>
<button type="submit">Save</button>
</form>

The Views/Shared/EditorTemplates/ToDoItem.cshtml template:

 @model ToDoItem

<td>
<label asp-for="@Model.Name"></label>
@Html.DisplayFor(model => model.Name)
</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>
*@

foreach should be used if possible when the value is going to be used in an asp-for or Html.DisplayFor
equivalent context. In general, for is better than foreach (if the scenario allows it) because it doesn't need to
allocate an enumerator; however, 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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class DescriptionViewModel
{
[MinLength(5)]
[MaxLength(1024)]
public string Description { get; set; }
}
}
 @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
&#x27;1024&#x27;."
data-val-maxlength-max="1024"
data-val-minlength="The field Description must be a string or array type with a minimum length of
&#x27;5&#x27;."
data-val-minlength-min="5"
id="Description" name="Description">
</textarea>
<button type="submit">Test</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</form>

The Label Tag Helper

Generates the label caption and for attribute on a <label> 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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class SimpleViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }
}
}
 @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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class RegisterViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }

[Required]
[DataType(DataType.Password)]
public string Password { get; set; }
}
}

@model RegisterViewModel

<form asp-controller="Demo" asp-action="RegisterValidation" method="post">

<div asp-validation-summary="ModelOnly"></div>
Email: <input asp-for="Email" /> <br />
<span asp-validation-for="Email"></span><br />
Password: <input asp-for="Password" /><br />
<span asp-validation-for="Password"></span><br />
<button type="submit">Register</button>
</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>
<span class="field-validation-valid" data-valmsg-replace="true"
data-valmsg-for="Password"></span><br>
<button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

namespace FormsTagHelper.ViewModels
{
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 Index()

{
var model = new CountryViewModel();
model.Country = "CA";
return View(model);
}

The HTTP POST Index method displays the selection:

 [HttpPost]
[ValidateAntiForgeryToken]
public IActionResult Index(CountryViewModel model)
{
if (ModelState.IsValid)
{
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">

<select asp-for="Country" asp-items="Model.Countries"></select>
<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>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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 )

<select asp-for="Country" asp-items="Model.Countries"></select>

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; }
}
}

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
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>
<br /><button type="submit">Register</button>
</form>

You can decorate your enumerator list with the Display attribute to get a richer UI:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public enum CountryEnum
{
[Display(Name = "United Mexican States")]
Mexico,
[Display(Name = "United States of America")]
USA,
Canada,
France,
Germany,
Spain
}
}

The following HTML is generated:

 <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>
<br /><button type="submit">Register</button>
<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:
 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",
Group = NorthAmericaGroup
},
new SelectListItem
{
Value = "US",
Text = "USA",
Group = NorthAmericaGroup
},
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 string Country { get; set; }

public List<SelectListItem> Countries { get; }

The two groups are shown below:

The generated HTML:

<form method="post" action="/Home/IndexGroup">

<select id="Country" name="Country">
<optgroup label="North America">
<option value="MEX">Mexico</option>
<option value="CAN">Canada</option>
<option value="US">USA</option>
</optgroup>
<optgroup label="Europe">
<option value="FR">France</option>
<option value="ES">Spain</option>
<option value="DE">Germany</option>
</optgroup>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

namespace FormsTagHelper.ViewModels
{
public class CountryViewModelIEnumerable
{
public IEnumerable<string> CountryCodes { 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" },
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>
<br /><button type="submit">Register</button>
</form>

Generates the following HTML:

<form method="post" action="/Home/IndexMultiSelect">

<select id="CountryCodes"
multiple="multiple"
name="CountryCodes"><option value="MX">Mexico</option>
<option value="CA">Canada</option>
<option value="US">USA</option>
<option value="FR">France</option>
<option value="ES">Spain</option>
<option value="DE">Germany</option>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

@model CountryViewModel

<form asp-controller="Home" asp-action="IndexEmpty" method="post">

@Html.EditorForModel()
<br /><button type="submit">Register</button>
</form>

The Views/Shared/EditorTemplates/CountryViewModel.cshtml template:

@model CountryViewModel

<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:

public IActionResult IndexNone()

{
var model = new CountryViewModel();
model.Insert(0, new SelectListItem("<none>", ""));
return View(model);
}
 @model CountryViewModel

<form asp-controller="Home" asp-action="IndexEmpty" method="post">

<select asp-for="Country">
<option value="">&lt;none&gt;</option>
<option value="MX">Mexico</option>
<option value="CA">Canada</option>
<option value="US">USA</option>
</select>
<br /><button type="submit">Register</button>
</form>

The correct <option> element will be selected ( contain the selected="selected" attribute) depending on the
current Country value.

public IActionResult IndexOption(int id)

{
var model = new CountryViewModel();
model.Country = "CA";
return View(model);
}

<form method="post" action="/Home/IndexEmpty">

<select id="Country" name="Country">
<option value="">&lt;none&gt;</option>
<option value="MX">Mexico</option>
<option value="CA" selected="selected">Canada</option>
<option value="US">USA</option>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</form>

Additional resources
Tag Helpers in ASP.NET Core
HTML Form element
Request Verification Token
Model Binding in ASP.NET Core
Model validation in ASP.NET Core MVC
IAttributeAdapter Interface
Code snippets for this document
 Tag Helpers in forms in ASP.NET Core
8/2/2019 • 18 minutes to read • Edit Online

By Rick Anderson, N. Taylor Mullen, 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">

<!-- Input and Submit elements -->
</form>

The Form Tag Helper above generates the following HTML:

<form method="post" action="/Demo/Register">

<!-- Input and Submit elements -->
<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">
<!-- Input and Submit elements -->
</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"]"
method="post" class="form-horizontal" role="form">

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 Form Action Tag Helper

The Form Action Tag Helper generates the formaction attribute on the generated <button ...> or
<input type="image" ...> tag. The formaction attribute controls where a form submits its data. It binds to <input>
elements of type image and <button> elements. The Form Action Tag Helper enables the usage of several
AnchorTagHelper asp- attributes to control what formaction link is generated for the corresponding element.
Supported AnchorTagHelper attributes to control the value of formaction :

ATTRIBUTE DESCRIPTION

asp-controller The name of the controller.

asp-action The name of the action method.

asp-area The name of the area.

asp-page The name of the Razor page.

asp-page-handler The name of the Razor page handler.

asp-route The name of the route.

asp-route-{value} A single URL route value. For example, asp-route-id="1234"

.

asp-all-route-data All route values.

asp-fragment The URL fragment.

Submit to controller example

The following markup submits the form to the Index action of HomeController when the input or button are
selected:
 <form method="post">
<button asp-controller="Home" asp-action="Index">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-controller="Home"
asp-action="Index">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/Home">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/Home">
</form>

Submit to page example

The following markup submits the form to the About Razor Page:

<form method="post">
<button asp-page="About">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-page="About">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/About">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/About">
</form>

Submit to route example

Consider the /Home/Test endpoint:

public class HomeController : Controller

{
[Route("/Home/Test", Name = "Custom")]
public string Test()
{
return "This is the test page";
}
}

The following markup submits the form to the /Home/Test endpoint.

<form method="post">
<button asp-route="Custom">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-route="Custom">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/Home/Test">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/Home/Test">
</form>
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 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
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-local"

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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class RegisterViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }

[Required]
[DataType(DataType.Password)]
public string Password { get; set; }
}
}

@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>
<button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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 string Email { get; set; }

[DataType(DataType.Password)]
public string Password { get; set; }

public AddressViewModel Address { get; set; }

}

In the view, we bind to Address.AddressLine1 :

@model RegisterAddressViewModel

<form asp-controller="Demo" asp-action="RegisterAddress" method="post">

Email: <input asp-for="Email" /> <br />
Password: <input asp-for="Password" /><br />
Address: <input asp-for="Address.AddressLine1" /><br />
<button type="submit">Register</button>
</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 class ToDoItem

{
public string Name { get; set; }

public bool IsDone { get; set; }

}

The following Razor shows how to iterate over a collection:

@model List<ToDoItem>

<form asp-controller="ToDo" asp-action="Edit" method="post">

<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>
<button type="submit">Save</button>
</form>

The Views/Shared/EditorTemplates/ToDoItem.cshtml template:

 @model ToDoItem

<td>
<label asp-for="@Model.Name"></label>
@Html.DisplayFor(model => model.Name)
</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>
*@

foreach should be used if possible when the value is going to be used in an asp-for or Html.DisplayFor
equivalent context. In general, for is better than foreach (if the scenario allows it) because it doesn't need to
allocate an enumerator; however, 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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class DescriptionViewModel
{
[MinLength(5)]
[MaxLength(1024)]
public string Description { get; set; }
}
}
 @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
&#x27;1024&#x27;."
data-val-maxlength-max="1024"
data-val-minlength="The field Description must be a string or array type with a minimum length of
&#x27;5&#x27;."
data-val-minlength-min="5"
id="Description" name="Description">
</textarea>
<button type="submit">Test</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</form>

The Label Tag Helper

Generates the label caption and for attribute on a <label> 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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class SimpleViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }
}
}
 @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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class RegisterViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }

[Required]
[DataType(DataType.Password)]
public string Password { get; set; }
}
}

@model RegisterViewModel

<form asp-controller="Demo" asp-action="RegisterValidation" method="post">

<div asp-validation-summary="ModelOnly"></div>
Email: <input asp-for="Email" /> <br />
<span asp-validation-for="Email"></span><br />
Password: <input asp-for="Password" /><br />
<span asp-validation-for="Password"></span><br />
<button type="submit">Register</button>
</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>
<span class="field-validation-valid" data-valmsg-replace="true"
data-valmsg-for="Password"></span><br>
<button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

namespace FormsTagHelper.ViewModels
{
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 Index()

{
var model = new CountryViewModel();
model.Country = "CA";
return View(model);
}

The HTTP POST Index method displays the selection:

 [HttpPost]
[ValidateAntiForgeryToken]
public IActionResult Index(CountryViewModel model)
{
if (ModelState.IsValid)
{
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">

<select asp-for="Country" asp-items="Model.Countries"></select>
<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>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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 )

<select asp-for="Country" asp-items="Model.Countries"></select>

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; }
}
}

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
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>
<br /><button type="submit">Register</button>
</form>

You can decorate your enumerator list with the Display attribute to get a richer UI:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public enum CountryEnum
{
[Display(Name = "United Mexican States")]
Mexico,
[Display(Name = "United States of America")]
USA,
Canada,
France,
Germany,
Spain
}
}

The following HTML is generated:

 <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>
<br /><button type="submit">Register</button>
<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:
 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",
Group = NorthAmericaGroup
},
new SelectListItem
{
Value = "US",
Text = "USA",
Group = NorthAmericaGroup
},
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 string Country { get; set; }

public List<SelectListItem> Countries { get; }

The two groups are shown below:

The generated HTML:

<form method="post" action="/Home/IndexGroup">

<select id="Country" name="Country">
<optgroup label="North America">
<option value="MEX">Mexico</option>
<option value="CAN">Canada</option>
<option value="US">USA</option>
</optgroup>
<optgroup label="Europe">
<option value="FR">France</option>
<option value="ES">Spain</option>
<option value="DE">Germany</option>
</optgroup>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

namespace FormsTagHelper.ViewModels
{
public class CountryViewModelIEnumerable
{
public IEnumerable<string> CountryCodes { 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" },
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>
<br /><button type="submit">Register</button>
</form>

Generates the following HTML:

<form method="post" action="/Home/IndexMultiSelect">

<select id="CountryCodes"
multiple="multiple"
name="CountryCodes"><option value="MX">Mexico</option>
<option value="CA">Canada</option>
<option value="US">USA</option>
<option value="FR">France</option>
<option value="ES">Spain</option>
<option value="DE">Germany</option>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

@model CountryViewModel

<form asp-controller="Home" asp-action="IndexEmpty" method="post">

@Html.EditorForModel()
<br /><button type="submit">Register</button>
</form>

The Views/Shared/EditorTemplates/CountryViewModel.cshtml template:

@model CountryViewModel

<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:

public IActionResult IndexNone()

{
var model = new CountryViewModel();
model.Insert(0, new SelectListItem("<none>", ""));
return View(model);
}
 @model CountryViewModel

<form asp-controller="Home" asp-action="IndexEmpty" method="post">

<select asp-for="Country">
<option value="">&lt;none&gt;</option>
<option value="MX">Mexico</option>
<option value="CA">Canada</option>
<option value="US">USA</option>
</select>
<br /><button type="submit">Register</button>
</form>

The correct <option> element will be selected ( contain the selected="selected" attribute) depending on the
current Country value.

public IActionResult IndexOption(int id)

{
var model = new CountryViewModel();
model.Country = "CA";
return View(model);
}

<form method="post" action="/Home/IndexEmpty">

<select id="Country" name="Country">
<option value="">&lt;none&gt;</option>
<option value="MX">Mexico</option>
<option value="CA" selected="selected">Canada</option>
<option value="US">USA</option>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</form>

Additional resources
Tag Helpers in ASP.NET Core
HTML Form element
Request Verification Token
Model Binding in ASP.NET Core
Model validation in ASP.NET Core MVC
IAttributeAdapter Interface
Code snippets for this document
 Partial Tag Helper in ASP.NET Core
4/26/2019 • 3 minutes to read • Edit Online

By Scott Addie
For an overview of Tag Helpers, see Tag Helpers in ASP.NET Core.
View or download sample code (how to download)

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; }

public string Name { get; set; }

public string Description { 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 following markup loads _ProductPartial.cshtml:

<partial name="_ProductPartial" for="Product">

The partial view is bound to the associated page model's Product property:

using Microsoft.AspNetCore.Mvc.RazorPages;
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

<div class="form-group">
<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>
<div class="form-group">
<label asp-for="Name"></label>
<input asp-for="Name" type="text" class="form-control" />
</div>
<div class="form-group">
<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" />
}

Additional resources
Partial views in ASP.NET Core
Views in ASP.NET Core MVC
 Tag Helpers in forms in ASP.NET Core
8/2/2019 • 18 minutes to read • Edit Online

By Rick Anderson, N. Taylor Mullen, 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">

<!-- Input and Submit elements -->
</form>

The Form Tag Helper above generates the following HTML:

<form method="post" action="/Demo/Register">

<!-- Input and Submit elements -->
<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">
<!-- Input and Submit elements -->
</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"]"
method="post" class="form-horizontal" role="form">

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 Form Action Tag Helper

The Form Action Tag Helper generates the formaction attribute on the generated <button ...> or
<input type="image" ...> tag. The formaction attribute controls where a form submits its data. It binds to <input>
elements of type image and <button> elements. The Form Action Tag Helper enables the usage of several
AnchorTagHelper asp- attributes to control what formaction link is generated for the corresponding element.
Supported AnchorTagHelper attributes to control the value of formaction :

ATTRIBUTE DESCRIPTION

asp-controller The name of the controller.

asp-action The name of the action method.

asp-area The name of the area.

asp-page The name of the Razor page.

asp-page-handler The name of the Razor page handler.

asp-route The name of the route.

asp-route-{value} A single URL route value. For example, asp-route-id="1234"

.

asp-all-route-data All route values.

asp-fragment The URL fragment.

Submit to controller example

The following markup submits the form to the Index action of HomeController when the input or button are
selected:
 <form method="post">
<button asp-controller="Home" asp-action="Index">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-controller="Home"
asp-action="Index">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/Home">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/Home">
</form>

Submit to page example

The following markup submits the form to the About Razor Page:

<form method="post">
<button asp-page="About">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-page="About">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/About">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/About">
</form>

Submit to route example

Consider the /Home/Test endpoint:

public class HomeController : Controller

{
[Route("/Home/Test", Name = "Custom")]
public string Test()
{
return "This is the test page";
}
}

The following markup submits the form to the /Home/Test endpoint.

<form method="post">
<button asp-route="Custom">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-route="Custom">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/Home/Test">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/Home/Test">
</form>
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 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
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-local"

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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class RegisterViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }

[Required]
[DataType(DataType.Password)]
public string Password { get; set; }
}
}

@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>
<button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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 string Email { get; set; }

[DataType(DataType.Password)]
public string Password { get; set; }

public AddressViewModel Address { get; set; }

}

In the view, we bind to Address.AddressLine1 :

@model RegisterAddressViewModel

<form asp-controller="Demo" asp-action="RegisterAddress" method="post">

Email: <input asp-for="Email" /> <br />
Password: <input asp-for="Password" /><br />
Address: <input asp-for="Address.AddressLine1" /><br />
<button type="submit">Register</button>
</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 class ToDoItem

{
public string Name { get; set; }

public bool IsDone { get; set; }

}

The following Razor shows how to iterate over a collection:

@model List<ToDoItem>

<form asp-controller="ToDo" asp-action="Edit" method="post">

<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>
<button type="submit">Save</button>
</form>

The Views/Shared/EditorTemplates/ToDoItem.cshtml template:

 @model ToDoItem

<td>
<label asp-for="@Model.Name"></label>
@Html.DisplayFor(model => model.Name)
</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>
*@

foreach should be used if possible when the value is going to be used in an asp-for or Html.DisplayFor
equivalent context. In general, for is better than foreach (if the scenario allows it) because it doesn't need to
allocate an enumerator; however, 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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class DescriptionViewModel
{
[MinLength(5)]
[MaxLength(1024)]
public string Description { get; set; }
}
}
 @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
&#x27;1024&#x27;."
data-val-maxlength-max="1024"
data-val-minlength="The field Description must be a string or array type with a minimum length of
&#x27;5&#x27;."
data-val-minlength-min="5"
id="Description" name="Description">
</textarea>
<button type="submit">Test</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</form>

The Label Tag Helper

Generates the label caption and for attribute on a <label> 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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class SimpleViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }
}
}
 @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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class RegisterViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }

[Required]
[DataType(DataType.Password)]
public string Password { get; set; }
}
}

@model RegisterViewModel

<form asp-controller="Demo" asp-action="RegisterValidation" method="post">

<div asp-validation-summary="ModelOnly"></div>
Email: <input asp-for="Email" /> <br />
<span asp-validation-for="Email"></span><br />
Password: <input asp-for="Password" /><br />
<span asp-validation-for="Password"></span><br />
<button type="submit">Register</button>
</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>
<span class="field-validation-valid" data-valmsg-replace="true"
data-valmsg-for="Password"></span><br>
<button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

namespace FormsTagHelper.ViewModels
{
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 Index()

{
var model = new CountryViewModel();
model.Country = "CA";
return View(model);
}

The HTTP POST Index method displays the selection:

 [HttpPost]
[ValidateAntiForgeryToken]
public IActionResult Index(CountryViewModel model)
{
if (ModelState.IsValid)
{
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">

<select asp-for="Country" asp-items="Model.Countries"></select>
<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>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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 )

<select asp-for="Country" asp-items="Model.Countries"></select>

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; }
}
}

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
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>
<br /><button type="submit">Register</button>
</form>

You can decorate your enumerator list with the Display attribute to get a richer UI:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public enum CountryEnum
{
[Display(Name = "United Mexican States")]
Mexico,
[Display(Name = "United States of America")]
USA,
Canada,
France,
Germany,
Spain
}
}

The following HTML is generated:

 <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>
<br /><button type="submit">Register</button>
<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:
 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",
Group = NorthAmericaGroup
},
new SelectListItem
{
Value = "US",
Text = "USA",
Group = NorthAmericaGroup
},
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 string Country { get; set; }

public List<SelectListItem> Countries { get; }

The two groups are shown below:

The generated HTML:

<form method="post" action="/Home/IndexGroup">

<select id="Country" name="Country">
<optgroup label="North America">
<option value="MEX">Mexico</option>
<option value="CAN">Canada</option>
<option value="US">USA</option>
</optgroup>
<optgroup label="Europe">
<option value="FR">France</option>
<option value="ES">Spain</option>
<option value="DE">Germany</option>
</optgroup>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

namespace FormsTagHelper.ViewModels
{
public class CountryViewModelIEnumerable
{
public IEnumerable<string> CountryCodes { 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" },
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>
<br /><button type="submit">Register</button>
</form>

Generates the following HTML:

<form method="post" action="/Home/IndexMultiSelect">

<select id="CountryCodes"
multiple="multiple"
name="CountryCodes"><option value="MX">Mexico</option>
<option value="CA">Canada</option>
<option value="US">USA</option>
<option value="FR">France</option>
<option value="ES">Spain</option>
<option value="DE">Germany</option>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

@model CountryViewModel

<form asp-controller="Home" asp-action="IndexEmpty" method="post">

@Html.EditorForModel()
<br /><button type="submit">Register</button>
</form>

The Views/Shared/EditorTemplates/CountryViewModel.cshtml template:

@model CountryViewModel

<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:

public IActionResult IndexNone()

{
var model = new CountryViewModel();
model.Insert(0, new SelectListItem("<none>", ""));
return View(model);
}
 @model CountryViewModel

<form asp-controller="Home" asp-action="IndexEmpty" method="post">

<select asp-for="Country">
<option value="">&lt;none&gt;</option>
<option value="MX">Mexico</option>
<option value="CA">Canada</option>
<option value="US">USA</option>
</select>
<br /><button type="submit">Register</button>
</form>

The correct <option> element will be selected ( contain the selected="selected" attribute) depending on the
current Country value.

public IActionResult IndexOption(int id)

{
var model = new CountryViewModel();
model.Country = "CA";
return View(model);
}

<form method="post" action="/Home/IndexEmpty">

<select id="Country" name="Country">
<option value="">&lt;none&gt;</option>
<option value="MX">Mexico</option>
<option value="CA" selected="selected">Canada</option>
<option value="US">USA</option>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</form>

Additional resources
Tag Helpers in ASP.NET Core
HTML Form element
Request Verification Token
Model Binding in ASP.NET Core
Model validation in ASP.NET Core MVC
IAttributeAdapter Interface
Code snippets for this document
 Tag Helpers in forms in ASP.NET Core
8/2/2019 • 18 minutes to read • Edit Online

By Rick Anderson, N. Taylor Mullen, 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">

<!-- Input and Submit elements -->
</form>

The Form Tag Helper above generates the following HTML:

<form method="post" action="/Demo/Register">

<!-- Input and Submit elements -->
<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">
<!-- Input and Submit elements -->
</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"]"
method="post" class="form-horizontal" role="form">

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 Form Action Tag Helper

The Form Action Tag Helper generates the formaction attribute on the generated <button ...> or
<input type="image" ...> tag. The formaction attribute controls where a form submits its data. It binds to <input>
elements of type image and <button> elements. The Form Action Tag Helper enables the usage of several
AnchorTagHelper asp- attributes to control what formaction link is generated for the corresponding element.
Supported AnchorTagHelper attributes to control the value of formaction :

ATTRIBUTE DESCRIPTION

asp-controller The name of the controller.

asp-action The name of the action method.

asp-area The name of the area.

asp-page The name of the Razor page.

asp-page-handler The name of the Razor page handler.

asp-route The name of the route.

asp-route-{value} A single URL route value. For example, asp-route-id="1234"

.

asp-all-route-data All route values.

asp-fragment The URL fragment.

Submit to controller example

The following markup submits the form to the Index action of HomeController when the input or button are
selected:
 <form method="post">
<button asp-controller="Home" asp-action="Index">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-controller="Home"
asp-action="Index">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/Home">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/Home">
</form>

Submit to page example

The following markup submits the form to the About Razor Page:

<form method="post">
<button asp-page="About">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-page="About">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/About">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/About">
</form>

Submit to route example

Consider the /Home/Test endpoint:

public class HomeController : Controller

{
[Route("/Home/Test", Name = "Custom")]
public string Test()
{
return "This is the test page";
}
}

The following markup submits the form to the /Home/Test endpoint.

<form method="post">
<button asp-route="Custom">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-route="Custom">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/Home/Test">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/Home/Test">
</form>
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 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
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-local"

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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class RegisterViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }

[Required]
[DataType(DataType.Password)]
public string Password { get; set; }
}
}

@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>
<button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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 string Email { get; set; }

[DataType(DataType.Password)]
public string Password { get; set; }

public AddressViewModel Address { get; set; }

}

In the view, we bind to Address.AddressLine1 :

@model RegisterAddressViewModel

<form asp-controller="Demo" asp-action="RegisterAddress" method="post">

Email: <input asp-for="Email" /> <br />
Password: <input asp-for="Password" /><br />
Address: <input asp-for="Address.AddressLine1" /><br />
<button type="submit">Register</button>
</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 class ToDoItem

{
public string Name { get; set; }

public bool IsDone { get; set; }

}

The following Razor shows how to iterate over a collection:

@model List<ToDoItem>

<form asp-controller="ToDo" asp-action="Edit" method="post">

<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>
<button type="submit">Save</button>
</form>

The Views/Shared/EditorTemplates/ToDoItem.cshtml template:

 @model ToDoItem

<td>
<label asp-for="@Model.Name"></label>
@Html.DisplayFor(model => model.Name)
</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>
*@

foreach should be used if possible when the value is going to be used in an asp-for or Html.DisplayFor
equivalent context. In general, for is better than foreach (if the scenario allows it) because it doesn't need to
allocate an enumerator; however, 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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class DescriptionViewModel
{
[MinLength(5)]
[MaxLength(1024)]
public string Description { get; set; }
}
}
 @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
&#x27;1024&#x27;."
data-val-maxlength-max="1024"
data-val-minlength="The field Description must be a string or array type with a minimum length of
&#x27;5&#x27;."
data-val-minlength-min="5"
id="Description" name="Description">
</textarea>
<button type="submit">Test</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</form>

The Label Tag Helper

Generates the label caption and for attribute on a <label> 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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class SimpleViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }
}
}
 @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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class RegisterViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }

[Required]
[DataType(DataType.Password)]
public string Password { get; set; }
}
}

@model RegisterViewModel

<form asp-controller="Demo" asp-action="RegisterValidation" method="post">

<div asp-validation-summary="ModelOnly"></div>
Email: <input asp-for="Email" /> <br />
<span asp-validation-for="Email"></span><br />
Password: <input asp-for="Password" /><br />
<span asp-validation-for="Password"></span><br />
<button type="submit">Register</button>
</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>
<span class="field-validation-valid" data-valmsg-replace="true"
data-valmsg-for="Password"></span><br>
<button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

namespace FormsTagHelper.ViewModels
{
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 Index()

{
var model = new CountryViewModel();
model.Country = "CA";
return View(model);
}

The HTTP POST Index method displays the selection:

 [HttpPost]
[ValidateAntiForgeryToken]
public IActionResult Index(CountryViewModel model)
{
if (ModelState.IsValid)
{
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">

<select asp-for="Country" asp-items="Model.Countries"></select>
<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>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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 )

<select asp-for="Country" asp-items="Model.Countries"></select>

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; }
}
}

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
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>
<br /><button type="submit">Register</button>
</form>

You can decorate your enumerator list with the Display attribute to get a richer UI:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public enum CountryEnum
{
[Display(Name = "United Mexican States")]
Mexico,
[Display(Name = "United States of America")]
USA,
Canada,
France,
Germany,
Spain
}
}

The following HTML is generated:

 <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>
<br /><button type="submit">Register</button>
<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:
 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",
Group = NorthAmericaGroup
},
new SelectListItem
{
Value = "US",
Text = "USA",
Group = NorthAmericaGroup
},
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 string Country { get; set; }

public List<SelectListItem> Countries { get; }

The two groups are shown below:

The generated HTML:

<form method="post" action="/Home/IndexGroup">

<select id="Country" name="Country">
<optgroup label="North America">
<option value="MEX">Mexico</option>
<option value="CAN">Canada</option>
<option value="US">USA</option>
</optgroup>
<optgroup label="Europe">
<option value="FR">France</option>
<option value="ES">Spain</option>
<option value="DE">Germany</option>
</optgroup>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

namespace FormsTagHelper.ViewModels
{
public class CountryViewModelIEnumerable
{
public IEnumerable<string> CountryCodes { 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" },
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>
<br /><button type="submit">Register</button>
</form>

Generates the following HTML:

<form method="post" action="/Home/IndexMultiSelect">

<select id="CountryCodes"
multiple="multiple"
name="CountryCodes"><option value="MX">Mexico</option>
<option value="CA">Canada</option>
<option value="US">USA</option>
<option value="FR">France</option>
<option value="ES">Spain</option>
<option value="DE">Germany</option>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

@model CountryViewModel

<form asp-controller="Home" asp-action="IndexEmpty" method="post">

@Html.EditorForModel()
<br /><button type="submit">Register</button>
</form>

The Views/Shared/EditorTemplates/CountryViewModel.cshtml template:

@model CountryViewModel

<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:

public IActionResult IndexNone()

{
var model = new CountryViewModel();
model.Insert(0, new SelectListItem("<none>", ""));
return View(model);
}
 @model CountryViewModel

<form asp-controller="Home" asp-action="IndexEmpty" method="post">

<select asp-for="Country">
<option value="">&lt;none&gt;</option>
<option value="MX">Mexico</option>
<option value="CA">Canada</option>
<option value="US">USA</option>
</select>
<br /><button type="submit">Register</button>
</form>

The correct <option> element will be selected ( contain the selected="selected" attribute) depending on the
current Country value.

public IActionResult IndexOption(int id)

{
var model = new CountryViewModel();
model.Country = "CA";
return View(model);
}

<form method="post" action="/Home/IndexEmpty">

<select id="Country" name="Country">
<option value="">&lt;none&gt;</option>
<option value="MX">Mexico</option>
<option value="CA" selected="selected">Canada</option>
<option value="US">USA</option>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</form>

Additional resources
Tag Helpers in ASP.NET Core
HTML Form element
Request Verification Token
Model Binding in ASP.NET Core
Model validation in ASP.NET Core MVC
IAttributeAdapter Interface
Code snippets for this document
 Tag Helpers in forms in ASP.NET Core
8/2/2019 • 18 minutes to read • Edit Online

By Rick Anderson, N. Taylor Mullen, 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">

<!-- Input and Submit elements -->
</form>

The Form Tag Helper above generates the following HTML:

<form method="post" action="/Demo/Register">

<!-- Input and Submit elements -->
<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">
<!-- Input and Submit elements -->
</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"]"
method="post" class="form-horizontal" role="form">

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 Form Action Tag Helper

The Form Action Tag Helper generates the formaction attribute on the generated <button ...> or
<input type="image" ...> tag. The formaction attribute controls where a form submits its data. It binds to <input>
elements of type image and <button> elements. The Form Action Tag Helper enables the usage of several
AnchorTagHelper asp- attributes to control what formaction link is generated for the corresponding element.
Supported AnchorTagHelper attributes to control the value of formaction :

ATTRIBUTE DESCRIPTION

asp-controller The name of the controller.

asp-action The name of the action method.

asp-area The name of the area.

asp-page The name of the Razor page.

asp-page-handler The name of the Razor page handler.

asp-route The name of the route.

asp-route-{value} A single URL route value. For example, asp-route-id="1234"

.

asp-all-route-data All route values.

asp-fragment The URL fragment.

Submit to controller example

The following markup submits the form to the Index action of HomeController when the input or button are
selected:
 <form method="post">
<button asp-controller="Home" asp-action="Index">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-controller="Home"
asp-action="Index">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/Home">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/Home">
</form>

Submit to page example

The following markup submits the form to the About Razor Page:

<form method="post">
<button asp-page="About">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-page="About">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/About">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/About">
</form>

Submit to route example

Consider the /Home/Test endpoint:

public class HomeController : Controller

{
[Route("/Home/Test", Name = "Custom")]
public string Test()
{
return "This is the test page";
}
}

The following markup submits the form to the /Home/Test endpoint.

<form method="post">
<button asp-route="Custom">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-route="Custom">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/Home/Test">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/Home/Test">
</form>
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 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
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-local"

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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class RegisterViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }

[Required]
[DataType(DataType.Password)]
public string Password { get; set; }
}
}

@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>
<button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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 string Email { get; set; }

[DataType(DataType.Password)]
public string Password { get; set; }

public AddressViewModel Address { get; set; }

}

In the view, we bind to Address.AddressLine1 :

@model RegisterAddressViewModel

<form asp-controller="Demo" asp-action="RegisterAddress" method="post">

Email: <input asp-for="Email" /> <br />
Password: <input asp-for="Password" /><br />
Address: <input asp-for="Address.AddressLine1" /><br />
<button type="submit">Register</button>
</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 class ToDoItem

{
public string Name { get; set; }

public bool IsDone { get; set; }

}

The following Razor shows how to iterate over a collection:

@model List<ToDoItem>

<form asp-controller="ToDo" asp-action="Edit" method="post">

<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>
<button type="submit">Save</button>
</form>

The Views/Shared/EditorTemplates/ToDoItem.cshtml template:

 @model ToDoItem

<td>
<label asp-for="@Model.Name"></label>
@Html.DisplayFor(model => model.Name)
</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>
*@

foreach should be used if possible when the value is going to be used in an asp-for or Html.DisplayFor
equivalent context. In general, for is better than foreach (if the scenario allows it) because it doesn't need to
allocate an enumerator; however, 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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class DescriptionViewModel
{
[MinLength(5)]
[MaxLength(1024)]
public string Description { get; set; }
}
}
 @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
&#x27;1024&#x27;."
data-val-maxlength-max="1024"
data-val-minlength="The field Description must be a string or array type with a minimum length of
&#x27;5&#x27;."
data-val-minlength-min="5"
id="Description" name="Description">
</textarea>
<button type="submit">Test</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</form>

The Label Tag Helper

Generates the label caption and for attribute on a <label> 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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class SimpleViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }
}
}
 @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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class RegisterViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }

[Required]
[DataType(DataType.Password)]
public string Password { get; set; }
}
}

@model RegisterViewModel

<form asp-controller="Demo" asp-action="RegisterValidation" method="post">

<div asp-validation-summary="ModelOnly"></div>
Email: <input asp-for="Email" /> <br />
<span asp-validation-for="Email"></span><br />
Password: <input asp-for="Password" /><br />
<span asp-validation-for="Password"></span><br />
<button type="submit">Register</button>
</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>
<span class="field-validation-valid" data-valmsg-replace="true"
data-valmsg-for="Password"></span><br>
<button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

namespace FormsTagHelper.ViewModels
{
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 Index()

{
var model = new CountryViewModel();
model.Country = "CA";
return View(model);
}

The HTTP POST Index method displays the selection:

 [HttpPost]
[ValidateAntiForgeryToken]
public IActionResult Index(CountryViewModel model)
{
if (ModelState.IsValid)
{
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">

<select asp-for="Country" asp-items="Model.Countries"></select>
<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>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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 )

<select asp-for="Country" asp-items="Model.Countries"></select>

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; }
}
}

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
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>
<br /><button type="submit">Register</button>
</form>

You can decorate your enumerator list with the Display attribute to get a richer UI:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public enum CountryEnum
{
[Display(Name = "United Mexican States")]
Mexico,
[Display(Name = "United States of America")]
USA,
Canada,
France,
Germany,
Spain
}
}

The following HTML is generated:

 <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>
<br /><button type="submit">Register</button>
<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:
 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",
Group = NorthAmericaGroup
},
new SelectListItem
{
Value = "US",
Text = "USA",
Group = NorthAmericaGroup
},
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 string Country { get; set; }

public List<SelectListItem> Countries { get; }

The two groups are shown below:

The generated HTML:

<form method="post" action="/Home/IndexGroup">

<select id="Country" name="Country">
<optgroup label="North America">
<option value="MEX">Mexico</option>
<option value="CAN">Canada</option>
<option value="US">USA</option>
</optgroup>
<optgroup label="Europe">
<option value="FR">France</option>
<option value="ES">Spain</option>
<option value="DE">Germany</option>
</optgroup>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

namespace FormsTagHelper.ViewModels
{
public class CountryViewModelIEnumerable
{
public IEnumerable<string> CountryCodes { 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" },
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>
<br /><button type="submit">Register</button>
</form>

Generates the following HTML:

<form method="post" action="/Home/IndexMultiSelect">

<select id="CountryCodes"
multiple="multiple"
name="CountryCodes"><option value="MX">Mexico</option>
<option value="CA">Canada</option>
<option value="US">USA</option>
<option value="FR">France</option>
<option value="ES">Spain</option>
<option value="DE">Germany</option>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

@model CountryViewModel

<form asp-controller="Home" asp-action="IndexEmpty" method="post">

@Html.EditorForModel()
<br /><button type="submit">Register</button>
</form>

The Views/Shared/EditorTemplates/CountryViewModel.cshtml template:

@model CountryViewModel

<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:

public IActionResult IndexNone()

{
var model = new CountryViewModel();
model.Insert(0, new SelectListItem("<none>", ""));
return View(model);
}
 @model CountryViewModel

<form asp-controller="Home" asp-action="IndexEmpty" method="post">

<select asp-for="Country">
<option value="">&lt;none&gt;</option>
<option value="MX">Mexico</option>
<option value="CA">Canada</option>
<option value="US">USA</option>
</select>
<br /><button type="submit">Register</button>
</form>

The correct <option> element will be selected ( contain the selected="selected" attribute) depending on the
current Country value.

public IActionResult IndexOption(int id)

{
var model = new CountryViewModel();
model.Country = "CA";
return View(model);
}

<form method="post" action="/Home/IndexEmpty">

<select id="Country" name="Country">
<option value="">&lt;none&gt;</option>
<option value="MX">Mexico</option>
<option value="CA" selected="selected">Canada</option>
<option value="US">USA</option>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</form>

Additional resources
Tag Helpers in ASP.NET Core
HTML Form element
Request Verification Token
Model Binding in ASP.NET Core
Model validation in ASP.NET Core MVC
IAttributeAdapter Interface
Code snippets for this document
 Tag Helpers in forms in ASP.NET Core
8/2/2019 • 18 minutes to read • Edit Online

By Rick Anderson, N. Taylor Mullen, 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">

<!-- Input and Submit elements -->
</form>

The Form Tag Helper above generates the following HTML:

<form method="post" action="/Demo/Register">

<!-- Input and Submit elements -->
<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">

<!-- Input and Submit elements -->
</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"]"
method="post" class="form-horizontal" role="form">

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 Form Action Tag Helper

The Form Action Tag Helper generates the formaction attribute on the generated <button ...> or
<input type="image" ...> tag. The formaction attribute controls where a form submits its data. It
binds to <input> elements of type image and <button> elements. The Form Action Tag Helper
enables the usage of several AnchorTagHelper asp- attributes to control what formaction link is
generated for the corresponding element.
Supported AnchorTagHelper attributes to control the value of formaction :

ATTRIBUTE DESCRIPTION

asp-controller The name of the controller.

asp-action The name of the action method.

asp-area The name of the area.

asp-page The name of the Razor page.

asp-page-handler The name of the Razor page handler.

asp-route The name of the route.

asp-route-{value} A single URL route value. For example,

asp-route-id="1234" .

asp-all-route-data All route values.

asp-fragment The URL fragment.

Submit to controller example

The following markup submits the form to the Index action of HomeController when the input or
button are selected:

<form method="post">
<button asp-controller="Home" asp-action="Index">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-controller="Home"
asp-action="Index">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/Home">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/Home">
</form>

Submit to page example

The following markup submits the form to the About Razor Page:

<form method="post">
<button asp-page="About">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-page="About">
</form>

The previous markup generates following HTML:

<form method="post">
<button formaction="/About">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/About">
</form>

Submit to route example

Consider the /Home/Test endpoint:

public class HomeController : Controller

{
[Route("/Home/Test", Name = "Custom")]
public string Test()
{
return "This is the test page";
}
}

The following markup submits the form to the /Home/Test endpoint.

<form method="post">
<button asp-route="Custom">Click Me</button>
<input type="image" src="..." alt="Or Click Me" asp-route="Custom">
</form>

The previous markup generates following HTML:

 <form method="post">
<button formaction="/Home/Test">Click Me</button>
<input type="image" src="..." alt="Or Click Me" formaction="/Home/Test">
</form>

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 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
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-local"

Byte type="number"
 .NET TYPE INPUT TYPE

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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class RegisterViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }

[Required]
[DataType(DataType.Password)]
public string Password { get; set; }
}
}

@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>
<button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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 string Email { get; set; }

[DataType(DataType.Password)]
public string Password { get; set; }

public AddressViewModel Address { get; set; }

}

In the view, we bind to Address.AddressLine1 :

@model RegisterAddressViewModel

<form asp-controller="Demo" asp-action="RegisterAddress" method="post">

Email: <input asp-for="Email" /> <br />
Password: <input asp-for="Password" /><br />
Address: <input asp-for="Address.AddressLine1" /><br />
<button type="submit">Register</button>
</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 class ToDoItem

{
public string Name { get; set; }

public bool IsDone { get; set; }

}

The following Razor shows how to iterate over a collection:

 @model List<ToDoItem>

<form asp-controller="ToDo" asp-action="Edit" method="post">

<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>
<button type="submit">Save</button>
</form>

The Views/Shared/EditorTemplates/ToDoItem.cshtml template:

@model ToDoItem

<td>
<label asp-for="@Model.Name"></label>
@Html.DisplayFor(model => model.Name)
</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>
*@

foreach should be used if possible when the value is going to be used in an asp-for or
Html.DisplayFor equivalent context. In general, for is better than foreach (if the scenario allows it)
because it doesn't need to allocate an enumerator; however, 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:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class DescriptionViewModel
{
[MinLength(5)]
[MaxLength(1024)]
public string Description { get; set; }
}
}

@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 &#x27;1024&#x27;."
data-val-maxlength-max="1024"
data-val-minlength="The field Description must be a string or array type with a minimum length
of &#x27;5&#x27;."
data-val-minlength-min="5"
id="Description" name="Description">
</textarea>
<button type="submit">Test</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</form>

The Label Tag Helper

Generates the label caption and for attribute on a <label> 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:
 using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class SimpleViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }
}
}

@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:
 using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public class RegisterViewModel
{
[Required]
[EmailAddress]
[Display(Name = "Email Address")]
public string Email { get; set; }

[Required]
[DataType(DataType.Password)]
public string Password { get; set; }
}
}

@model RegisterViewModel

<form asp-controller="Demo" asp-action="RegisterValidation" method="post">

<div asp-validation-summary="ModelOnly"></div>
Email: <input asp-for="Email" /> <br />
<span asp-validation-for="Email"></span><br />
Password: <input asp-for="Password" /><br />
<span asp-validation-for="Password"></span><br />
<button type="submit">Register</button>
</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>
<span class="field-validation-valid" data-valmsg-replace="true"
data-valmsg-for="Password"></span><br>
<button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:
 using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

namespace FormsTagHelper.ViewModels
{
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 Index()

{
var model = new CountryViewModel();
model.Country = "CA";
return View(model);
}

The HTTP POST Index method displays the selection:

[HttpPost]
[ValidateAntiForgeryToken]
public IActionResult Index(CountryViewModel model)
{
if (ModelState.IsValid)
{
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">

<select asp-for="Country" asp-items="Model.Countries"></select>
<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>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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 )

<select asp-for="Country" asp-items="Model.Countries"></select>

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; }
}
}

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
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>
<br /><button type="submit">Register</button>
</form>

You can decorate your enumerator list with the Display attribute to get a richer UI:

using System.ComponentModel.DataAnnotations;

namespace FormsTagHelper.ViewModels
{
public enum CountryEnum
{
[Display(Name = "United Mexican States")]
Mexico,
[Display(Name = "United States of America")]
USA,
Canada,
France,
Germany,
Spain
}
}

The following HTML is generated:

<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>
<br /><button type="submit">Register</button>
<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:
 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",
Group = NorthAmericaGroup
},
new SelectListItem
{
Value = "US",
Text = "USA",
Group = NorthAmericaGroup
},
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 string Country { get; set; }

public List<SelectListItem> Countries { get; }

The two groups are shown below:

The generated HTML:

<form method="post" action="/Home/IndexGroup">

<select id="Country" name="Country">
<optgroup label="North America">
<option value="MEX">Mexico</option>
<option value="CAN">Canada</option>
<option value="US">USA</option>
</optgroup>
<optgroup label="Europe">
<option value="FR">France</option>
<option value="ES">Spain</option>
<option value="DE">Germany</option>
</optgroup>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

using Microsoft.AspNetCore.Mvc.Rendering;
using System.Collections.Generic;

namespace FormsTagHelper.ViewModels
{
public class CountryViewModelIEnumerable
{
public IEnumerable<string> CountryCodes { 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" },
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>
<br /><button type="submit">Register</button>
</form>

Generates the following HTML:

<form method="post" action="/Home/IndexMultiSelect">

<select id="CountryCodes"
multiple="multiple"
name="CountryCodes"><option value="MX">Mexico</option>
<option value="CA">Canada</option>
<option value="US">USA</option>
<option value="FR">France</option>
<option value="ES">Spain</option>
<option value="DE">Germany</option>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</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:

@model CountryViewModel

<form asp-controller="Home" asp-action="IndexEmpty" method="post">

@Html.EditorForModel()
<br /><button type="submit">Register</button>
</form>

The Views/Shared/EditorTemplates/CountryViewModel.cshtml template:

@model CountryViewModel

<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:

public IActionResult IndexNone()

{
var model = new CountryViewModel();
model.Insert(0, new SelectListItem("<none>", ""));
return View(model);
}
 @model CountryViewModel

<form asp-controller="Home" asp-action="IndexEmpty" method="post">

<select asp-for="Country">
<option value="">&lt;none&gt;</option>
<option value="MX">Mexico</option>
<option value="CA">Canada</option>
<option value="US">USA</option>
</select>
<br /><button type="submit">Register</button>
</form>

The correct <option> element will be selected ( contain the selected="selected" attribute)
depending on the current Country value.

public IActionResult IndexOption(int id)

{
var model = new CountryViewModel();
model.Country = "CA";
return View(model);
}

<form method="post" action="/Home/IndexEmpty">

<select id="Country" name="Country">
<option value="">&lt;none&gt;</option>
<option value="MX">Mexico</option>
<option value="CA" selected="selected">Canada</option>
<option value="US">USA</option>
</select>
<br /><button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>">
</form>

Additional resources
Tag Helpers in ASP.NET Core
HTML Form element
Request Verification Token
Model Binding in ASP.NET Core
Model validation in ASP.NET Core MVC
IAttributeAdapter Interface
Code snippets for this document
 View components in ASP.NET Core
7/30/2019 • 11 minutes to read • Edit Online

By Rick Anderson
View or download sample code (how to download)

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
controllers and views, 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 .
When considering if view components meet an app's specifications, consider using Razor Components instead.
Razor Components also combine markup with C# code to produce reusable UI units. Razor Components are
designed for developer productivity when providing client-side UI logic and composition. For more information,
see Create and use ASP.NET Core Razor components.

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 a Task<IViewComponentResult> or in a
synchronous Invoke 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 a Task<IViewComponentResult> or a synchronous Invoke 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:
/Views/{Controller Name}/Components/{View Component Name}/{View Name}
/Views/Shared/Components/{View Component Name}/{View Name}
/Pages/Shared/Components/{View Component Name}/{View Name}
The search path applies to projects using controllers + views and Razor Pages.
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:

@await 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 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:

@await Component.InvokeAsync("PriorityList", new { maxPriority = 4, isDone = true })

In Tag Helper markup:

<vc:priority-list max-priority="2" is-done="false">

</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 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 Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
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.

public async Task<IViewComponentResult> InvokeAsync(

int maxPriority, bool isDone)
{
string MyView = "Default";
// If asking for all completed tasks, render with the "PVC" view.
if (maxPriority > 3 && isDone == true)
{
MyView = "PVC";
}
var items = await GetItemsAsync(maxPriority, isDone);
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/ToDo/Index.cshtml:

@await Component.InvokeAsync("PriorityList", new { maxPriority = 4, isDone = true })

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:

An unhandled exception occurred while processing the request.

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 hard-coded 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 Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using ViewComponentSample.Models;

namespace ViewComponentSample.ViewComponents
{
public class PriorityList : ViewComponent
{
private readonly ToDoContext db;

public PriorityList(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();
}
}
}

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>
<!-- Markup removed for brevity. -->

<div>

@*
Note:
To use the below line, you need to #define no_suffix in ViewComponents/PriorityList.cs or it
won't compile.
By doing so it will cause a problem to index as there will be multiple viewcomponents
with the same name after the compiler removes the suffix "ViewComponent"
*@

@*@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>
@foreach (var item in Model)
{
<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 max-priority="999" is-done="false">

</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.

All view component parameters are required

Each parameter in a view component is a required attribute. See this GitHub issue. If any parameter is omitted:
The InvokeAsync method signature won't match, therefore the method won't execute.
The ViewComponent won't render any markup.
No errors will be thrown.

Additional resources
Dependency injection into views
 Razor file compilation in ASP.NET Core
6/21/2019 • 3 minutes to read • Edit Online

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.
Razor files are compiled at both build and publish time using the Razor SDK. Runtime compilation may be
optionally enabled by configuring your application.

Razor compilation
Build- and publish-time compilation of Razor files is enabled by default by the Razor SDK. When enabled, runtime
compilation complements build-time compilation, allowing Razor files to be updated if they are edited.
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 or
references assemblies required to compile Razor files are deployed with your app.

IMPORTANT
The precompilation tool has been deprecated, and 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 has been deprecated, and 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:

<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>netcoreapp1.1</TargetFramework>
<MvcRazorCompileOnPublish>true</MvcRazorCompileOnPublish>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore" Version="1.1.0" />
<PackageReference Include="Microsoft.AspNetCore.Mvc" Version="1.1.0" />
<PackageReference Include="Microsoft.AspNetCore.StaticFiles" 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:

Runtime compilation
Build-time compilation is supplemented by runtime compilation of Razor files. ASP.NET Core MVC will recompile
Razor files when the contents of a .cshtml file change.
Build-time compilation is supplemented by runtime compilation of Razor files. The RazorViewEngineOptions
AllowRecompilingViewsOnFileChange gets or sets a value that determines if Razor files (Razor views and Razor
Pages) are recompiled and updated if files change on disk.
The default value is true for:
If the app's compatibility version is set to Version_2_1 or earlier
 If the app's compatibility version is set to Version_2_2 or later and the app is in the Development environment
IsDevelopment. In other words, Razor files would not recompile in non-Development environment unless
AllowRecompilingViewsOnFileChange is explicitly set.
For guidance and examples of setting the app's compatibility version, see Compatibility version for ASP.NET Core
MVC.
Runtime compilation is enabled using the Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation package. To enable
runtime compilation, apps must:
Install the Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation NuGet package.
Update the project's Startup.ConfigureServices method to include a call to AddRazorRuntimeCompilation :

services
.AddControllersWithViews()
.AddRazorRuntimeCompilation();

Additional resources
Views in ASP.NET Core MVC
Introduction to Razor Pages in ASP.NET Core
Views in ASP.NET Core MVC
Introduction to Razor Pages in ASP.NET Core
Views in ASP.NET Core MVC
ASP.NET Core Razor SDK
 Work with the application model in ASP.NET Core
7/11/2019 • 10 minutes to read • Edit Online

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.

using Microsoft.AspNetCore.Mvc.ApplicationModels;

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 .

public void ConfigureServices(IServiceCollection services)

{
services.AddMvc(options =>
{
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;
using Microsoft.AspNetCore.Mvc.ApplicationModels;

namespace AppModelSample.Conventions
{
public class ControllerDescriptionAttribute : Attribute, IControllerModelConvention
{
private readonly string _description;

public ControllerDescriptionAttribute(string description)

{
_description = 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
{
public string Index()
{
return "Description: " + ControllerContext.ActionDescriptor.Properties["description"];
}

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;
using Microsoft.AspNetCore.Mvc.ApplicationModels;

namespace AppModelSample.Conventions
{
public class ActionDescriptionAttribute : Attribute, IActionModelConvention
{
private readonly string _description;

public ActionDescriptionAttribute(string description)

{
_description = 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
{
public string Index()
{
return "Description: " + ControllerContext.ActionDescriptor.Properties["description"];
}

[ActionDescription("Action Description")]
public string UseActionDescriptionAttribute()
{
return "Description: " + ControllerContext.ActionDescriptor.Properties["description"];
}
}

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;
using Microsoft.AspNetCore.Mvc.ApplicationModels;
using Microsoft.AspNetCore.Mvc.ModelBinding;

namespace AppModelSample.Conventions
{
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;
using Microsoft.AspNetCore.Mvc.ApplicationModels;

namespace AppModelSample.Conventions
{
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 Microsoft.AspNetCore.Mvc.ApplicationModels;
using System.Linq;

namespace AppModelSample.Conventions
{
public class NamespaceRoutingConvention : IApplicationModelConvention
{
public void Apply(ApplicationModel application)
{
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.

public void ConfigureServices(IServiceCollection services)

{
services.AddMvc(options =>
{
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:
 using Microsoft.AspNetCore.Mvc;

namespace AppModelSample.Controllers
{
public class NamespaceRoutingController : Controller
{
// using NamespaceRoutingConvention
// route: /AppModelSample/Controllers/NamespaceRouting/Index
public string 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:

using Microsoft.AspNetCore.Mvc.ApplicationModels;

namespace AppModelSample.Conventions
{
public class EnableApiExplorerApplicationConvention : IApplicationModelConvention
{
public void Apply(ApplicationModel application)
{
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
7/12/2019 • 21 minutes to read • Edit Online

By Kirk Larkin, Rick Anderson, Tom Dykstra, and Steve Smith

Filters in ASP.NET Core allow code to be run before or after specific stages in the request processing pipeline.
Built-in filters handle tasks such as:
Authorization (preventing access to resources a user isn't authorized for).
Response caching (short-circuiting the request pipeline to return a cached response).
Custom filters can be created to handle cross-cutting concerns. Examples of cross-cutting concerns include error
handling, caching, configuration, authorization, and logging. Filters avoid duplicating code. For example, an error
handling exception filter could consolidate error handling.
This document applies to Razor Pages, API controllers, and controllers with views.
View or download sample (how to download).

How filters work

Filters run within the ASP.NET Core action invocation pipeline, sometimes referred to as the filter pipeline. The
filter pipeline runs after ASP.NET Core 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 user is authorized for the request.
Authorization filters short-circuit the pipeline if the request is unauthorized.
Resource filters:
Run after authorization.
OnResourceExecuting can run code before the rest of the filter pipeline. For example,
OnResourceExecuting can run code before model binding.
OnResourceExecuted can run code after the rest of the pipeline has completed.
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.
Action filters are not supported in Razor Pages.
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 filter types interact in the filter pipeline.

Implementation
Filters support both synchronous and asynchronous implementations through different interface definitions.
Synchronous filters can run code before ( On-Stage-Executing ) and after ( On-Stage-Executed ) their pipeline
stage. For example, OnActionExecuting is called before the action method is called. OnActionExecuted is called
after the action method returns.
 public class MySampleActionFilter : 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 an On-Stage-ExecutionAsync method:

public class SampleAsyncActionFilter : IAsyncActionFilter

{
public async Task OnActionExecutionAsync(
ActionExecutingContext context,
ActionExecutionDelegate next)
{
// Do something before the action executes.

// next() calls the action method.

var resultContext = await next();
// resultContext.Result is set.
// Do something after the action executes.
}
}

In the preceding code, the SampleAsyncActionFilter has an ActionExecutionDelegate ( next ) that executes the
action method. Each of the On-Stage-ExecutionAsync methods take a FilterType-ExecutionDelegate that
executes the filter's pipeline stage.
Multiple filter stages
Interfaces for multiple filter stages can be implemented in a single class. For example, the ActionFilterAttribute
class implements IActionFilter , IResultFilter , and their async equivalents.
Implement either the synchronous or the async version of a filter interface, not both. The runtime 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 asynchronous and synchronous interfaces are implemented in one class, only the async
method is called. When using abstract classes like ActionFilterAttribute override only the synchronous methods
or the async method for each filter type.
Built-in filter attributes
ASP.NET Core includes built-in attribute-based filters that can be subclassed and customized. For example, the
following result 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 });
base.OnResultExecuting(context);
}
}

Attributes allow filters to accept arguments, as shown in the preceding example. Apply the AddHeaderAttribute
to a controller or action method and specify the name and value of the HTTP header:

[AddHeader("Author", "Joe Smith")]

public class SampleController : Controller
{
public IActionResult Index()
{
return Content("Examine the headers using the F12 developer tools.");
}

[ShortCircuitingResourceFilter]
public IActionResult SomeResource()
{
return Content("Successful access to resource - header is set.");
}

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

Filter scopes and order of execution

A filter can be added to the pipeline at one of three scopes:
Using an attribute on an action.
Using an attribute on a controller.
Globally for all controllers and actions as shown in the following code:
 public void ConfigureServices(IServiceCollection services)
{
services.AddMvc(options =>
{
options.Filters.Add(new AddHeaderAttribute("GlobalAddHeader",
"Result filter added to MvcOptions.Filters")); // An instance
options.Filters.Add(typeof(MySampleActionFilter)); // By type
options.Filters.Add(new SampleGlobalActionFilter()); // An instance
}).SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}

The preceding code adds three filters globally using the MvcOptions.Filters collection.
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.
As a result of filter nesting, the after code of filters runs in the reverse order of the before code. The filter
sequence:
The before code of global filters.
The before code of controller filters.
The before code of action method filters.
The after code of action method filters.
The after code of controller filters.
The after code of global filters.
The following 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.
Controller and Razor Page level filters
Every controller that inherits from the Controller base class includes Controller.OnActionExecuting,
Controller.OnActionExecutionAsync, and Controller.OnActionExecuted OnActionExecuted methods. These
methods:
Wrap the filters that run for a given action.
OnActionExecuting is called before any of the action's filters.
 is called after all of the action filters.
OnActionExecuted
OnActionExecutionAsync is called before any of the action's filters. Code in the filter after next runs after the
action method.
For example, in the download sample, MySampleActionFilter is applied globally in startup.
The TestController :
Applies the SampleActionFilterAttribute ( [SampleActionFilter] ) to the FilterTest2 action:
Overrides OnActionExecuting and OnActionExecuted .

public class TestController : Controller

{
[SampleActionFilter]
public IActionResult FilterTest2()
{
return Content($"From FilterTest2");
}

public override void OnActionExecuting(ActionExecutingContext context)

{
// Do something before the action executes.
base.OnActionExecuting(context);
}

public override void OnActionExecuted(ActionExecutedContext context)

{
// Do something after the action executes.
base.OnActionExecuted(context);
}
}

Navigating to https://localhost:5001/Test/FilterTest2 runs the following code:

TestController.OnActionExecuting
MySampleActionFilter.OnActionExecuting
SampleActionFilterAttribute.OnActionExecuting
TestController.FilterTest2
SampleActionFilterAttribute.OnActionExecuted
MySampleActionFilter.OnActionExecuted
TestController.OnActionExecuted

For Razor Pages, see Implement Razor Page filters by overriding filter methods.
Overriding the default order
The default sequence of execution can be overridden by implementing IOrderedFilter. IOrderedFilter exposes
the Order property that takes precedence over scope to determine the order of execution. A filter with a lower
Order value:

Runs the before code before that of a filter with a higher value of Order .
Runs the after code after that of a filter with a higher Order value.

The Order property can be set with a constructor parameter:

[MyFilter(Name = "Controller Level Attribute", Order=1)]

Consider the same 3 action filters shown in the preceding example. If the Order property of the controller and
global filters is set to 1 and 2 respectively, the order of execution is 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 overrides scope when determining the order in which filters 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 Order is set to a non-zero value.

Cancellation and short-circuiting

The filter pipeline can be short-circuited by setting the Result property on the ResourceExecutingContext
parameter provided to the filter method. For instance, the following Resource filter prevents the rest of the
pipeline from executing:

public class ShortCircuitingResourceFilterAttribute : Attribute, IResourceFilter

{
public void OnResourceExecuting(ResourceExecutingContext context)
{
context.Result = new ContentResult()
{
Content = "Resource unavailable - header not 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", "Joe Smith")]
public class SampleController : Controller
{
public IActionResult Index()
{
return Content("Examine the headers using the F12 developer tools.");
}

[ShortCircuitingResourceFilter]
public IActionResult SomeResource()
{
return Content("Successful access to resource - header is set.");
}

Dependency injection
Filters can be added by type or by instance. If an instance is added, that instance is used for every request. If a
type is added, it's type-activated. A type-activated filter means:
An instance is created for each request.
Any constructor dependencies are populated by dependency injection (DI).
Filters that are implemented as attributes and added directly to controller classes or action methods cannot have
constructor dependencies provided by dependency injection (DI). Constructor dependencies cannot be provided
by DI because:
Attributes must have their constructor parameters supplied where they're applied.
This is a limitation of how attributes work.
The following filters support constructor dependencies provided from DI:
ServiceFilterAttribute
TypeFilterAttribute
IFilterFactory implemented on the attribute.
The preceding filters can be applied to a controller or action method:
Loggers are available from DI. However, avoid creating and using filters purely for logging purposes. The built-
in framework logging typically provides what's needed for logging. Logging added to filters:
Should focus on business domain concerns or behavior specific to the filter.
Should not log actions or other framework events. The built in filters log actions and framework events.
ServiceFilterAttribute
Service filter implementation types are registered in ConfigureServices . A ServiceFilterAttribute retrieves an
instance of the filter from DI.
The following code shows the AddHeaderResultServiceFilter :
 public class AddHeaderResultServiceFilter : IResultFilter
{
private ILogger _logger;
public AddHeaderResultServiceFilter(ILoggerFactory loggerFactory)
{
_logger = loggerFactory.CreateLogger<AddHeaderResultServiceFilter>();
}

public void OnResultExecuting(ResultExecutingContext context)

{
var headerName = "OnResultExecuting";
context.HttpContext.Response.Headers.Add(
headerName, new string[] { "ResultExecutingSuccessfully" });
_logger.LogInformation($"Header added: {headerName}");
}

public void OnResultExecuted(ResultExecutedContext context)

{
// Can't add to headers here because response has started.
}
}

In the following code, AddHeaderResultServiceFilter is added to the DI container:

public void ConfigureServices(IServiceCollection services)

{
// Add service filters.
services.AddScoped<AddHeaderResultServiceFilter>();
services.AddScoped<SampleActionFilterAttribute>();

services.AddMvc(options =>
{
options.Filters.Add(new AddHeaderAttribute("GlobalAddHeader",
"Result filter added to MvcOptions.Filters")); // An instance
options.Filters.Add(typeof(MySampleActionFilter)); // By type
options.Filters.Add(new SampleGlobalActionFilter()); // An instance
}).SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}

In the following code, the ServiceFilter attribute retrieves an instance of the AddHeaderResultServiceFilter
filter from DI:

[ServiceFilter(typeof(AddHeaderResultServiceFilter))]
public IActionResult Index()
{
return View();
}

When using ServiceFilterAttribute , setting ServiceFilterAttribute.IsReusable:

Provides a hint that the filter instance may be reused outside of the request scope it was created within.
The ASP.NET Core runtime doesn't guarantee:
That a single instance of the filter will be created.
The filter will not be re-requested from the DI container at some later point.
Should not be used with a filter that depends on services with a lifetime other than singleton.
ServiceFilterAttribute implements IFilterFactory. IFilterFactory exposes the CreateInstance method for
creating an IFilterMetadata instance. CreateInstance loads the specified type from 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 TypeFilterAttribute types aren't resolved directly from the DI container:
Types that are referenced using the TypeFilterAttribute don't need to be registered with the DI container.
They do have their dependencies fulfilled by the DI container.
TypeFilterAttribute can optionally accept constructor arguments for the type.

When using TypeFilterAttribute , setting TypeFilterAttribute.IsReusable:

Provides hint that the filter instance may be reused outside of the request scope it was created within.
The ASP.NET Core runtime provides no guarantees that a single instance of the filter will be created.
Should not be used with a filter that depends on services with a lifetime other than singleton.
The following example shows how to pass arguments to a type using TypeFilterAttribute :

[TypeFilter(typeof(LogConstantFilter),
Arguments = new object[] { "Method 'Hi' called" })]
public IActionResult Hi(string name)
{
return Content($"Hi {name}");
}

public class LogConstantFilter : IActionFilter

{
private readonly string _value;
private readonly ILogger<LogConstantFilter> _logger;

public LogConstantFilter(string value, ILogger<LogConstantFilter> logger)

{
_logger = logger;
_value = value;
}

public void OnActionExecuting(ActionExecutingContext context)

{
_logger.LogInformation(_value);
}

public void OnActionExecuted(ActionExecutedContext context)

{ }
}

Authorization filters
Authorization filters:
Are the first filters run in the filter pipeline.
Control access to action methods.
Have a before method, but no after method.
Custom authorization filters require a custom authorization framework. Prefer configuring the authorization
policies or writing a custom authorization policy over writing a custom filter. The built-in authorization filter:
Calls the authorization system.
Does not authorize requests.
Do not throw exceptions within authorization filters:
The exception will not be handled.
Exception filters will not handle the exception.
Consider issuing a challenge when an exception occurs in an authorization filter.
Learn more about Authorization.

Resource filters
Resource filters:
Implement either the IResourceFilter or IAsyncResourceFilter interface.
Execution wraps most of the filter pipeline.
Only Authorization filters run before resource filters.
Resource filters are useful to short-circuit most of the pipeline. For example, a caching filter can avoid the rest of
the pipeline on a cache hit.
Resource filter examples:
The short-circuiting resource filter shown previously.
DisableFormValueModelBindingAttribute:
Prevents model binding from accessing the form data.
Used for large file uploads to prevent the form data from being read into memory.

Action filters
IMPORTANT
Action filters do not apply to Razor Pages. Razor Pages supports IPageFilter and IAsyncPageFilter . For more information,
see Filter methods for Razor Pages.

Action filters:
Implement either the IActionFilter or IAsyncActionFilter interface.
Their execution surrounds the execution of action methods.
The following code shows a sample action filter:

public class MySampleActionFilter : IActionFilter

{
public void OnActionExecuting(ActionExecutingContext context)
{
// Do something before the action executes.
}

public void OnActionExecuted(ActionExecutedContext context)

{
// Do something after the action executes.
}
}

The ActionExecutingContext provides the following properties:

 ActionArguments - enables the inputs to an action method be read.
Controller - enables manipulating the controller instance.
Result - setting Result short-circuits execution of the action method and subsequent action filters.

Throwing an exception in an action method:

Prevents running of subsequent filters.
Unlike setting Result , is treated as a failure instead of a successful result.
The ActionExecutedContext provides Controller and Result plus the following properties:
Canceled - True if the action execution was short-circuited by another filter.
Exception - Non-null if the action or a previously run action filter threw an exception. Setting this
property to null:
Effectively handles the exception.
Result is executed as if it was returned from the action method.

For an IAsyncActionFilter , a call to the ActionExecutionDelegate:

Executes any subsequent action filters and the action method.
Returns ActionExecutedContext .

To short-circuit, assign Microsoft.AspNetCore.Mvc.Filters.ActionExecutingContext.Result to a result instance and

don't call next (the ActionExecutionDelegate ).
The framework provides an abstract ActionFilterAttribute that can be subclassed.
The OnActionExecuting action filter can be used to:
Validate model state.
Return an error 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 Result property.
Canceled is set to true if the action execution was short-circuited by another filter.
Exception is set to a non-null value if the action or a subsequent action filter threw an exception. Setting
Exception to null:

Effectively handles an exception.

ActionExecutedContext.Result is executed as if it were returned normally from the action method.
 public class ValidateModelAttribute : ActionFilterAttribute
{
public override void OnActionExecuting(ActionExecutingContext context)
{
if (!context.ModelState.IsValid)
{
context.Result = new BadRequestObjectResult(context.ModelState);
}
}

public override void OnActionExecuted(ActionExecutedContext context)

{
var result = context.Result;
// Do something with Result.
if (context.Canceled == true)
{
// Action execution was short-circuited by another filter.
}

if(context.Exception != null)
{
// Exception thrown by action or action filter.
// Set to null to handle the exception.
context.Exception = null;
}
base.OnActionExecuted(context);
}
}

Exception filters
Exception filters:
Implement IExceptionFilter or IAsyncExceptionFilter.
Can be used to implement common error handling policies.
The following sample exception filter uses a custom 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())
{
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 Razor Page or 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 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.
Exception filters:
Are good for trapping exceptions that occur within actions.
Are not as flexible as error handling middleware.
Prefer middleware for exception handling. Use exception filters only where error handling differs based on
which action method is called. For example, an 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.

Result filters
Result filters:
Implement an interface:
IResultFilter or IAsyncResultFilter
IAlwaysRunResultFilter or IAsyncAlwaysRunResultFilter
Their execution surrounds the execution of action results.
IResultFilter and IAsyncResultFilter
The following code shows a result filter that adds an HTTP header:

public class AddHeaderResultServiceFilter : IResultFilter

{
private ILogger _logger;
public AddHeaderResultServiceFilter(ILoggerFactory loggerFactory)
{
_logger = loggerFactory.CreateLogger<AddHeaderResultServiceFilter>();
}

public void OnResultExecuting(ResultExecutingContext context)

{
var headerName = "OnResultExecuting";
context.HttpContext.Response.Headers.Add(
headerName, new string[] { "ResultExecutingSuccessfully" });
_logger.LogInformation($"Header added: {headerName}");
}

public void OnResultExecuted(ResultExecutedContext context)

{
// Can't add to headers here because response has started.
}
}

The kind of result being executed depends on the action. An 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 Microsoft.AspNetCore.Mvc.Filters.IResultFilter.OnResultExecuting method can short-circuit execution of the
action result and subsequent result filters by setting
Microsoft.AspNetCore.Mvc.Filters.ResultExecutingContext.Cancel to true . Write to the response object when
short-circuiting to avoid generating an empty response. Throwing an exception in
IResultFilter.OnResultExecuting will:

Prevent execution of the action result and subsequent filters.

Be treated as a failure instead of a successful result.
When the Microsoft.AspNetCore.Mvc.Filters.IResultFilter.OnResultExecuted method runs:
The response has likely been sent to the client and cannot be changed.
If an exception was thrown, the response body is not sent.
ResultExecutedContext.Canceled is set to true if the action result execution was short-circuited by another filter.
ResultExecutedContext.Exception is 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 ASP.NET Core later in the pipeline. There is no reliable way to write data to a response when
handling an exception in a result filter. If the headers have been flushed to the client when an action result
throws an exception, 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
ResultExecutionDelegate :
 public class MyAsyncResponseFilter : IAsyncResultFilter
{
public async Task OnResultExecutionAsync(ResultExecutingContext context,
ResultExecutionDelegate next)
{
if (!(context.Result is EmptyResult))
{
await next();
}
else
{
context.Cancel = true;
}

}
}

The framework provides an abstract ResultFilterAttribute that can be subclassed. The AddHeaderAttribute
class shown previously is an example of a result filter attribute.
IAlwaysRunResultFilter and IAsyncAlwaysRunResultFilter
The IAlwaysRunResultFilter and IAsyncAlwaysRunResultFilter interfaces declare an IResultFilter
implementation that runs for all action results. The filter is applied to all action results unless:
An IExceptionFilter or IAuthorizationFilter applies and short-circuits the response.
An exception filter handles an exception by producing an action result.
Filters other than IExceptionFilter and IAuthorizationFilter don't short-circuit IAlwaysRunResultFilter and
IAsyncAlwaysRunResultFilter .
For example, the following filter always runs and sets an action result (ObjectResult) with a 422 Unprocessable
Entity status code when content negotiation fails:

public class UnprocessableResultFilter : Attribute, IAlwaysRunResultFilter

{
public void OnResultExecuting(ResultExecutingContext context)
{
if (context.Result is StatusCodeResult statusCodeResult &&
statusCodeResult.StatusCode == 415)
{
context.Result = new ObjectResult("Can't process this!")
{
StatusCode = 422,
};
}
}

public void OnResultExecuted(ResultExecutedContext context)

{
}
}

IFilterFactory
IFilterFactory implements IFilterMetadata. Therefore, an IFilterFactory instance can be used as an
IFilterMetadata instance anywhere in the filter pipeline. When the runtime 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 is invoked. This provides a flexible design, since the precise filter pipeline doesn't
need to be set explicitly when the app starts.
 IFilterFactory can be implemented using custom 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

{
public void OnResultExecuting(ResultExecutingContext context)
{
context.HttpContext.Response.Headers.Add(
"Internal", new string[] { "My header" });
}

public void OnResultExecuted(ResultExecutedContext context)

{
}
}

public bool IsReusable

{
get
{
return false;
}
}
}

The preceding code can be tested by running the download sample:

Invoke the F12 developer tools.
Navigate to https://localhost:5001/Sample/HeaderWithFactory
The F12 developer tools display the following response headers added by the sample code:
author: Joe Smith
globaladdheader: Result filter added to MvcOptions.Filters
internal: My header

The preceding code creates the internal: My header response header.

IFilterFactory implemented on an attribute
Filters that implement IFilterFactory are useful for filters that:
Don't require passing parameters.
Have constructor dependencies that need to be filled by DI.
TypeFilterAttribute implements IFilterFactory. IFilterFactory exposes the CreateInstance method for creating
an IFilterMetadata instance. CreateInstance loads the specified type from the services container (DI).
 public class SampleActionFilterAttribute : TypeFilterAttribute
{
public SampleActionFilterAttribute():base(typeof(SampleActionFilterImpl))
{
}

private class SampleActionFilterImpl : IActionFilter

{
private readonly ILogger _logger;
public SampleActionFilterImpl(ILoggerFactory loggerFactory)
{
_logger = loggerFactory.CreateLogger<SampleActionFilterAttribute>();
}

public void OnActionExecuting(ActionExecutingContext context)

{
_logger.LogInformation("Business action starting...");
// perform some business logic work

public void OnActionExecuted(ActionExecutedContext context)

{
// perform some business logic work
_logger.LogInformation("Business action completed.");
}
}
}

The following code shows three approaches to applying the [SampleActionFilter] :

[SampleActionFilter]
public IActionResult FilterTest()
{
return Content($"From FilterTest");
}

[TypeFilter(typeof(SampleActionFilterAttribute))]
public IActionResult TypeFilterTest()
{
return Content($"From ServiceFilterTest");
}

// ServiceFilter must be registered in ConfigureServices or

// System.InvalidOperationException: No service for type '<filter>' has been registered.
// Is thrown.
[ServiceFilter(typeof(SampleActionFilterAttribute))]
public IActionResult ServiceFilterTest()
{
return Content($"From ServiceFilterTest");
}

In the preceding code, decorating the method with [SampleActionFilter] is the preferred approach to applying
the SampleActionFilter .

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 the ASP.NET Core runtime, which means that
they have access to ASP.NET Core context and constructs.
To use middleware as a filter, create a type with a Configure method that specifies the middleware to inject into
the filter pipeline. The following example uses the localization middleware to establish the current culture for a
request:

public class LocalizationPipeline

{
public void Configure(IApplicationBuilder applicationBuilder)
{
var supportedCultures = new[]
{
new CultureInfo("en-US"),
new CultureInfo("fr")
};

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);
}
}

Use the MiddlewareFilterAttribute to run the middleware:

[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
See Filter methods for Razor Pages
To experiment with filters, download, test, and modify the GitHub sample.
 Areas in ASP.NET Core
8/7/2019 • 7 minutes to read • Edit Online

By Dhananjay Kumar and Rick Anderson

Areas are an ASP.NET 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 or a Razor Page page .
Areas provide a way to partition an ASP.NET Core Web app into smaller functional groups, each with its own
set of Razor Pages, controllers, views, and models. An area is effectively a structure inside an app. In an
ASP.NET Core web project, logical components like Pages, Model, Controller, and View are kept in different
folders. The ASP.NET Core runtime 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. Each of these units have their own area to contain views, controllers, Razor Pages, and models.
Consider using Areas in a project when:
The app is made of multiple high-level functional components that can be logically separated.
You want to partition the app so that each functional area can be worked on independently.
View or download sample code (how to download). The download sample provides a basic app for testing
areas.
If you're using Razor Pages, see Areas with Razor Pages in this document.

Areas for controllers with views

A typical ASP.NET Core web app using areas, controllers, and views contains the following:
An Area folder structure.
Controllers decorated with the [Area] attribute to associate the controller with the area:

[Area("Products")]
public class ManageController : Controller
{

The area route added to startup:

app.UseMvc(routes =>
{
routes.MapRoute(
name: "MyArea",
template: "{area:exists}/{controller=Home}/{action=Index}/{id?}");

routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});

Area folder structure

Consider an app that has two logical groups, Products and Services. Using areas, the folder structure would be
similar to the following:
Project name
Areas
Products
Controllers
HomeController.cs
ManageController.cs
Views
Home
Index.cshtml
Manage
Index.cshtml
About.cshtml
Services
Controllers
HomeController.cs
Views
Home
Index.cshtml
While the preceding layout is typical when using Areas, only the view files are required to use this folder
structure. View discovery searches for a matching area view file in the following order:

/Areas/<Area-Name>/Views/<Controller-Name>/<Action-Name>.cshtml
/Areas/<Area-Name>/Views/Shared/<Action-Name>.cshtml
/Views/Shared/<Action-Name>.cshtml
/Pages/Shared/<Action-Name>.cshtml

The location of non-view folders like Controllers and Models does not matter. For example, the Controllers
and Models folder are not required. The content of Controllers and Models is code which gets compiled into a
.dll. The content of the Views isn't compiled until a request to that view has been made.
Associate the controller with an Area
Area controllers are designated with the [Area] attribute:
 using Microsoft.AspNetCore.Mvc;

namespace MVCareas.Areas.Products.Controllers
{
[Area("Products")]
public class ManageController : Controller
{
public IActionResult Index()
{
return View();
}

public IActionResult About()

{
return View();
}
}
}

Add Area route

Area routes typically use conventional routing rather than attribute routing. 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.
{area:...} can be used as a token in route templates if url space is uniform across all areas:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Home/Error");
app.UseHsts();
}

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

app.UseMvc(routes =>
{
routes.MapRoute(
name: "MyArea",
template: "{area:exists}/{controller=Home}/{action=Index}/{id?}");

routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});
}

In the preceding code, exists applies a constraint that the route must match an area. Using {area:...} is
the least complicated mechanism to adding routing to areas.
The following code uses MapAreaRoute to create two named area routes:
 public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Home/Error");
app.UseHsts();
}

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

app.UseMvc(routes =>
{
routes.MapAreaRoute(
name: "MyAreaProducts",
areaName:"Products",
template: "Products/{controller=Home}/{action=Index}/{id?}");

routes.MapAreaRoute(
name: "MyAreaServices",
areaName: "Services",
template: "Services/{controller=Home}/{action=Index}/{id?}");

routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});
}

When using MapAreaRoute with ASP.NET Core 2.2, see this GitHub issue.
For more information, see Area routing.
Link generation with MVC areas
The following code from the sample download shows link generation with the area specified:
 <li>Anchor Tag Helper links</li>
<ul>
<li>
<a asp-area="Products" asp-controller="Home" asp-action="About">
Products/Home/About
</a>
</li>
<li>
<a asp-area="Services" asp-controller="Home" asp-action="About">
Services About
</a>
</li>
<li>
<a asp-area="" asp-controller="Home" asp-action="About">
/Home/About
</a>
</li>
</ul>
<li>Html.ActionLink generated links</li>
<ul>
<li>
@Html.ActionLink("Product/Manage/About", "About", "Manage",
new { area = "Products" })
</li>
</ul>
<li>Url.Action generated links</li>
<ul>
<li>
<a href='@Url.Action("About", "Manage", new { area = "Products" })'>
Products/Manage/About
</a>
</li>
</ul>

The links generated with the preceding code are valid anywhere in the app.
The sample download includes a partial view that contains the preceding links and the same links without
specifying the area. The partial view is referenced in the layout file, so every page in the app displays the
generated links. The links generated without specifying the area are only valid when referenced from a page
in the same area and controller.
When the area or controller is not specified, routing depends on the ambient values. The current route values
of the current request are considered ambient values for link generation. In many cases for the sample app,
using the ambient values generates incorrect links.
For more information, see Routing to controller actions.
Shared layout for Areas using the _ViewStart.cshtml file
To share a common layout for the entire app, move the _ViewStart.cshtml to the application root folder.
_ViewImports.cshtml
In its standard location, /Views/_ViewImports.cshtml doesn't apply to areas. To use common Tag Helpers,
@using , or @inject in your area, ensure a proper _ViewImports.cshtml file applies to your area views. If you
want the same behavior in all your views, move /Views/_ViewImports.cshtml to the application root.
Change default area folder where views are stored
The following code changes the default area folder from "Areas" to "MyAreas" :
 public void ConfigureServices(IServiceCollection services)
{
services.Configure<RazorViewEngineOptions>(options =>
{
options.AreaViewLocationFormats.Clear();
options.AreaViewLocationFormats.Add("/MyAreas/{2}/Views/{1}/{0}.cshtml");
options.AreaViewLocationFormats.Add("/MyAreas/{2}/Views/Shared/{0}.cshtml");
options.AreaViewLocationFormats.Add("/Views/Shared/{0}.cshtml");
});

services.AddMvc();
}

Areas with Razor Pages

Areas with Razor Pages require and Areas/<area name>/Pages folder in the root of the app. The following
folder structure is used with the sample download
Project name
Areas
Products
Pages
_ViewImports
About
Index
Services
Pages
Manage
About
Index
Link generation with Razor Pages and areas
The following code from the sample download shows link generation with the area specified (for example,
asp-area="Products" ):
 <li>Anchor Tag Helper links</li>
<ul>
<li>
<a asp-area="Products" asp-page="/About">
Products/About
</a>
</li>
<li>
<a asp-area="Services" asp-page="/Manage/About">
Services/Manage/About
</a>
</li>
<li>
<a asp-area="" asp-page="/About">
/About
</a>
</li>
</ul>
<li>Url.Page generated links</li>
<ul>
<li>
<a href='@Url.Page("/Manage/About", new { area = "Services" })'>
Services/Manage/About
</a>
</li>
<li>
<a href='@Url.Page("/About", new { area = "Products" })'>
Products/About
</a>
</li>
</ul>

The links generated with the preceding code are valid anywhere in the app.
The sample download includes a partial view that contains the preceding links and the same links without
specifying the area. The partial view is referenced in the layout file, so every page in the app displays the
generated links. The links generated without specifying the area are only valid when referenced from a page
in the same area.
When the area is not specified, routing depends on the ambient values. The current route values of the
current request are considered ambient values for link generation. In many cases for the sample app, using
the ambient values generates incorrect links. For example, consider the links generated from the following
code:

<li>
<a asp-page="/Manage/About">
Services/Manage/About
</a>
</li>
<li>
<a asp-page="/About">
/About
</a>
</li>

For the preceding code:

The link generated from <a asp-page="/Manage/About"> is correct only when the last request was for a page
in Services area. For example, /Services/Manage/ , /Services/Manage/Index , or /Services/Manage/About .
The link generated from <a asp-page="/About"> is correct only when the last request was for a page in
/Home .
 The code is from the sample download.
Import namespace and Tag Helpers with _ViewImports file
A _ViewImports.cshtml file can be added to each area Pages folder to import the namespace and Tag Helpers
to each Razor Page in the folder.
Consider the Services area of the sample code, which doesn't contain a _ViewImports.cshtml file. The
following markup shows the /Services/Manage/About Razor Page:

@page
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@model RPareas.Areas.Services.Pages.Manage.AboutModel
@{
ViewData["Title"] = "Srv Mng About";
}

<h2>/Services/Manage/About</h2>

<a asp-area="Products" asp-page="/Index">

Products/Index
</a>

In the preceding markup:

The fully qualified domain name must be used to specify the model (
@model RPareas.Areas.Services.Pages.Manage.AboutModel ).
Tag Helpers are enabled by @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

In the sample download, the Products area contains the following _ViewImports.cshtml file:

@namespace RPareas.Areas.Products.Pages
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

The following markup shows the /Products/About Razor Page:

@page
@model AboutModel
@{
ViewData["Title"] = "Prod About";
}

<h2>Products/About</h2>

<a asp-area="Services" asp-page="/Manage/About">

Services/Manage/About
</a>

In the preceding file, the namespace and @addTagHelper directive is imported to the file by the
Areas/Products/Pages/_ViewImports.cshtml file.
For more information, see Managing Tag Helper scope and Importing Shared Directives.
Shared layout for Razor Pages Areas
To share a common layout for the entire app, move the _ViewStart.cshtml to the application root folder.
Publishing Areas
All *.cshtml files and files within the wwwroot directory are published to output when
<Project Sdk="Microsoft.NET.Sdk.Web"> is included in the *.csproj file.
 Application Parts in ASP.NET Core
7/11/2019 • 4 minutes to read • Edit Online

View or download sample code (how to download)

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 Microsoft.AspNetCore.Mvc.ApplicationModels;
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:

 using Microsoft.AspNetCore.Mvc;

namespace AppPartsSample
{
[GenericControllerNameConvention] // Sets the controller name based on typeof(T).Name
public class GenericController<T> : Controller
{
public IActionResult Index()
{
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;
using Microsoft.AspNetCore.Mvc.ApplicationParts;
using Microsoft.AspNetCore.Mvc.Controllers;
using System.Linq;
using Microsoft.AspNetCore.Mvc.Razor.Compilation;
using Microsoft.AspNetCore.Mvc.Razor.TagHelpers;
using Microsoft.AspNetCore.Mvc.ViewComponents;

namespace AppPartsSample.Controllers
{
public class FeaturesController : Controller
{
private readonly ApplicationPartManager _partManager;

public FeaturesController(ApplicationPartManager partManager)

{
_partManager = partManager;
}

public IActionResult Index()

{
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();

return View(viewModel);
}
}
}

Example output:
 dotnet aspnet-codegenerator
7/31/2019 • 4 minutes to read • Edit Online

By Rick Anderson
dotnet aspnet-codegenerator - Runs the ASP.NET Core scaffolding engine. dotnet aspnet-codegenerator is only
required to scaffold from the command line, it's not needed to use scaffolding with Visual Studio.
This article applies to .NET Core 2.1 SDK and later.

Installing aspnet-codegenerator
dotnet-aspnet-codegenerator is a global tool that must be installed. The following command installs the latest
stable version of the dotnet-aspnet-codegenerator tool:

dotnet tool install -g dotnet-aspnet-codegenerator

The following command updates dotnet-aspnet-codegenerator to the latest stable version available from the
installed .NET Core SDKs:

dotnet tool update -g dotnet-aspnet-codegenerator

Synopsis
dotnet aspnet-codegenerator [arguments] [-p|--project] [-n|--nuget-package-dir] [-c|--configuration] [-tfm|-
-target-framework] [-b|--build-base-path] [--no-build]
dotnet aspnet-codegenerator [-h|--help]

Description
The dotnet aspnet-codegenerator global command runs the ASP.NET Core code generator and scaffolding
engine.

Arguments
generator

The code generator to run. The following generators are available:

GENERATOR OPERATION

area Scaffolds an Area

controller Scaffolds a controller

identity Scaffolds Identity

razorpage Scaffolds Razor Pages

 GENERATOR OPERATION

view Scaffolds a view

Options
-n|--nuget-package-dir

Specifies the NuGet package directory.

-c|--configuration {Debug|Release}

Defines the build configuration. The default value is Debug .

-tfm|--target-framework

Target Framework to use. For example, net46 .

-b|--build-base-path

The build base path.

-h|--help

Prints out a short help for the command.

--no-build

Doesn't build the project before running. It also implicitly sets the --no-restore flag.
-p|--project <PATH>

Specifies the path of the project file to run (folder name or full path). If not specified, it defaults to the current
directory.

Generator options
The following sections detail the options available for the supported generators:
Area
Controller
Identity
Razorpage
View
Area options
This tool is intended for ASP.NET Core web projects with controllers and views. It's not intended for Razor
Pages apps.
Usage: dotnet aspnet-codegenerator area AreaNameToGenerate

The preceding command generates the following folders:

Areas
AreaNameToGenerate
Controllers
Data
Models
 Views
Controller options
The following table lists options for aspnet-codegenerator controller and razorpage :

OPTION DESCRIPTION

--model or -m Model class to use.

--dataContext or -dc The DbContext class to use.

--bootstrapVersion or -b Specifies the bootstrap version. Valid values are 3 or 4 .

Default is 4 . If needed and not present, a wwwroot
directory is created that includes the bootstrap files of the
specified version.

--referenceScriptLibraries or -scripts Reference script libraries in the generated views. Adds

_ValidationScriptsPartial to Edit and Create pages.

--layout or -l Custom Layout page to use.

--useDefaultLayout or -udl Use the default layout for the views.

--force or -f Overwrite existing files.

--relativeFolderPath or -outDir The relative output folder path from project where the file
are generated. If not specified, files are generated in the
project folder.

The following table lists options unique to aspnet-codegenerator controller :

OPTION DESCRIPTION

--controllerName or -name Name of the controller.

--useAsyncActions or -async Generate async controller actions.

--noViews or -nv Generate no views.

--restWithNoViews or -api Generate a Controller with REST style API. noViews is

assumed and any view related options are ignored.

--readWriteActions or -actions Generate controller with read/write actions without a model.

Use the -h switch for help on the aspnet-codegenerator controller command:

dotnet aspnet-codegenerator controller -h

See Scaffold the movie model for an example of dotnet aspnet-codegenerator controller .
Razorpage
Razor Pages can be individually scaffolded by specifying the name of the new page and the template to use. The
supported templates are:
 Empty
Create
Edit
Delete
Details
List

For example, the following command uses the Edit template to generate MyEdit.cshtml and MyEdit.cshtml.cs:

dotnet aspnet-codegenerator razorpage MyEdit Edit -m Movie -dc RazorPagesMovieContext -outDir Pages/Movies

Typically, the template and generated file name is not specified, and the following templates are created:
Create
Edit
Delete
Details
List

The following table lists options for aspnet-codegenerator razorpage and controller :

OPTION DESCRIPTION

--model or -m Model class to use.

--dataContext or -dc The DbContext class to use.

--bootstrapVersion or -b Specifies the bootstrap version. Valid values are 3 or 4 .

Default is 4 . If needed and not present, a wwwroot
directory is created that includes the bootstrap files of the
specified version.

--referenceScriptLibraries or -scripts Reference script libraries in the generated views. Adds

_ValidationScriptsPartial to Edit and Create pages.

--layout or -l Custom Layout page to use.

--useDefaultLayout or -udl Use the default layout for the views.

--force or -f Overwrite existing files.

--relativeFolderPath or -outDir The relative output folder path from project where the file
are generated. If not specified, files are generated in the
project folder.

The following table lists options unique to aspnet-codegenerator razorpage :

OPTION DESCRIPTION

--namespaceName or -namespace The name of the namespace to use for the generated
PageModel
 OPTION DESCRIPTION

--partialView or -partial Generate a partial view. Layout options -l and -udl are
ignored if this is specified.

--noPageModel or -npm Switch to not generate a PageModel class for Empty

template

Use the -h switch for help on the aspnet-codegenerator razorpage command:

dotnet aspnet-codegenerator razorpage -h

See Scaffold the movie model for an example of dotnet aspnet-codegenerator razorpage .
Identity
See Scaffold Identity
 Create web APIs with ASP.NET Core
7/8/2019 • 8 minutes to read • Edit Online

By Scott Addie and Tom Dykstra

ASP.NET Core supports creating RESTful services, also known as web APIs, using C#. To handle requests, a web
API uses controllers. Controllers in a web API are classes that derive from ControllerBase . This article shows
how to use controllers for handling API requests.
View or download sample code. (How to download).

ControllerBase class
A web API has one or more controller classes that derive from ControllerBase. For example, the web API project
template creates a Values controller:

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase

Don't create a web API controller by deriving from the Controller class. Controller derives from
ControllerBase and adds support for views, so it's for handling web pages, not web API requests. There's an
exception to this rule: if you plan to use the same controller for both views and APIs, derive it from Controller .
The ControllerBase class provides many properties and methods that are useful for handling HTTP requests.
For example, ControllerBase.CreatedAtAction returns a 201 status code:

[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<Pet> Create(Pet pet)
{
pet.Id = _petsInMemoryStore.Any() ? _petsInMemoryStore.Max(p => p.Id) + 1 : 1;
_petsInMemoryStore.Add(pet);

return CreatedAtAction(nameof(GetById),
new { id = pet.Id }, pet);
}

Here are some more examples of methods that ControllerBase provides.

METHOD NOTES

BadRequest Returns 400 status code.

NotFound Returns 404 status code.

PhysicalFile Returns a file.

TryUpdateModelAsync Invokes model binding.

TryValidateModel Invokes model validation.

 METHOD NOTES

For a list of all available methods and properties, see ControllerBase.

Attributes
The Microsoft.AspNetCore.Mvc namespace provides attributes that can be used to configure the behavior of
web API controllers and action methods. The following example uses attributes to specify the HTTP method
accepted and the status codes returned:

[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<Pet> Create(Pet pet)
{
pet.Id = _petsInMemoryStore.Any() ? _petsInMemoryStore.Max(p => p.Id) + 1 : 1;
_petsInMemoryStore.Add(pet);

return CreatedAtAction(nameof(GetById),
new { id = pet.Id }, pet);
}

Here are some more examples of attributes that are available.

ATTRIBUTE NOTES

[Route] Specifies URL pattern for a controller or action.

[Bind] Specifies prefix and properties to include for model binding.

[HttpGet] Identifies an action that supports the HTTP GET method.

[Consumes] Specifies data types that an action accepts.

[Produces] Specifies data types that an action returns.

For a list that includes the available attributes, see the Microsoft.AspNetCore.Mvc namespace.

ApiController attribute
The [ApiController] attribute can be applied to a controller class to enable API-specific behaviors:
Attribute routing requirement
Automatic HTTP 400 responses
Binding source parameter inference
Multipart/form-data request inference
Problem details for error status codes
These features require a compatibility version of 2.1 or later.
ApiController on specific controllers
The [ApiController] attribute can be applied to specific controllers, as in the following example from the project
template:
 [Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase

ApiController on multiple controllers

One approach to using the attribute on more than one controller is to create a custom base controller class
annotated with the [ApiController] attribute. Here's an example showing a custom base class and a controller
that derives from it:

[ApiController]
public class MyControllerBase : ControllerBase
{
}

[Produces("application/json")]
[Route("api/[controller]")]
public class PetsController : MyControllerBase

ApiController on an assembly
If compatibility version is set to 2.2 or later, the [ApiController] attribute can be applied to an assembly.
Annotation in this manner applies web API behavior to all controllers in the assembly. There's no way to opt out
for individual controllers. Apply the assembly-level attribute to the Startup class as shown in the following
example:

[assembly: ApiController]
namespace WebApiSample
{
public class Startup
{
...
}
}

Attribute routing requirement

The ApiController attribute makes attribute routing a requirement. For example:

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase

Actions are inaccessible via conventional routes defined by UseMvc or UseMvcWithDefaultRoute in

Startup.Configure .

Automatic HTTP 400 responses

The ApiController attribute makes model validation errors automatically trigger an HTTP 400 response.
Consequently, the following code is unnecessary in an action method:
 if (!ModelState.IsValid)
{
return BadRequest(ModelState);
}

Default BadRequest response

With a compatibility version of 2.2 or later, the default response type for HTTP 400 responses is
ValidationProblemDetails. The ValidationProblemDetails type complies with the RFC 7807 specification.
To change the default response to SerializableError, set the
SuppressUseValidationProblemDetailsForInvalidModelStateResponses property to true in
Startup.ConfigureServices , as shown in the following example:

services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2)
.ConfigureApiBehaviorOptions(options =>
{
options.SuppressConsumesConstraintForFormFileParameters = true;
options.SuppressInferBindingSourcesForParameters = true;
options.SuppressModelStateInvalidFilter = true;
options.SuppressMapClientErrors = true;
options.SuppressUseValidationProblemDetailsForInvalidModelStateResponses = true;
options.ClientErrorMapping[404].Link =
"https://httpstatuses.com/404";
});

Customize BadRequest response

To customize the response that results from a validation error, use InvalidModelStateResponseFactory. Add the
following highlighted code after services.AddMvc().SetCompatibilityVersion :

services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2)
.ConfigureApiBehaviorOptions(options =>
{
options.InvalidModelStateResponseFactory = context =>
{
var problemDetails = new ValidationProblemDetails(context.ModelState)
{
Type = "https://contoso.com/probs/modelvalidation",
Title = "One or more model validation errors occurred.",
Status = StatusCodes.Status400BadRequest,
Detail = "See the errors property for details.",
Instance = context.HttpContext.Request.Path
};

return new BadRequestObjectResult(problemDetails)

{
ContentTypes = { "application/problem+json" }
};
};
});

Log automatic 400 responses

See How to log automatic 400 responses on model validation errors (aspnet/AspNetCore.Docs #12157).
Disable automatic 400
To disable the automatic 400 behavior, set the SuppressModelStateInvalidFilter property to true . Add the
following highlighted code in Startup.ConfigureServices after services.AddMvc().SetCompatibilityVersion :
 services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2)
.ConfigureApiBehaviorOptions(options =>
{
options.SuppressConsumesConstraintForFormFileParameters = true;
options.SuppressInferBindingSourcesForParameters = true;
options.SuppressModelStateInvalidFilter = true;
options.SuppressMapClientErrors = true;
options.SuppressUseValidationProblemDetailsForInvalidModelStateResponses = true;
options.ClientErrorMapping[404].Link =
"https://httpstatuses.com/404";
});

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 or binding source attributes like [FromQuery] , the ASP.NET Core runtime
attempts to use the complex object model binder. The complex object model binder pulls data from value
providers in a defined order.
In the following example, the [FromQuery] attribute indicates that the discontinuedOnly parameter value is
provided in the request URL's query string:
 [HttpGet]
public ActionResult<List<Product>> Get(
[FromQuery] bool discontinuedOnly = false)
{
List<Product> products = null;

if (discontinuedOnly)
{
products = _productsInMemoryStore.Where(p => p.IsDiscontinued).ToList();
}
else
{
products = _productsInMemoryStore;
}

return products;
}

The [ApiController] attribute applies inference rules for the default data sources of action parameters. These
rules save you from having to identify binding sources manually by applying attributes to the action parameters.
The binding source inference rules behave as follows:
[FromBody] is inferred for complex type parameters. An exception to the [FromBody] inference 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.
[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.

FromBody inference notes

[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 needed.
When an action has more than one parameter bound from the request body, an exception is thrown. For
example, all of the following action method signatures cause an exception:
[FromBody] inferred on both because they're complex types.

[HttpPost]
public IActionResult Action1(Product product, Order order)

[FromBody] attribute on one, inferred on the other because it's a complex type.

[HttpPost]
public IActionResult Action2(Product product, [FromBody] Order order)

[FromBody] attribute on both.

[HttpPost]
public IActionResult Action3([FromBody] Product product, [FromBody] Order order)
 NOTE
In ASP.NET Core 2.1, collection type parameters such as lists and arrays are incorrectly inferred as [FromQuery] . The
[FromBody] attribute should be used for these parameters if they are to be bound from the request body. This behavior
is corrected in ASP.NET Core 2.2 or later, where collection type parameters are inferred to be bound from the body by
default.

Disable inference rules

To disable binding source inference, set SuppressInferBindingSourcesForParameters to true . Add the following
code in Startup.ConfigureServices after services.AddMvc().SetCompatibilityVersion :

services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2)
.ConfigureApiBehaviorOptions(options =>
{
options.SuppressConsumesConstraintForFormFileParameters = true;
options.SuppressInferBindingSourcesForParameters = true;
options.SuppressModelStateInvalidFilter = true;
options.SuppressMapClientErrors = true;
options.SuppressUseValidationProblemDetailsForInvalidModelStateResponses = true;
options.ClientErrorMapping[404].Link =
"https://httpstatuses.com/404";
});

Multipart/form-data request inference

The [ApiController] attribute applies an inference rule when an action parameter is annotated with the
[FromForm] attribute: the multipart/form-data request content type is inferred.
To disable the default behavior, set SuppressConsumesConstraintForFormFileParameters to true in
Startup.ConfigureServices , as shown in the following example:

services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2)
.ConfigureApiBehaviorOptions(options =>
{
options.SuppressConsumesConstraintForFormFileParameters = true;
options.SuppressInferBindingSourcesForParameters = true;
options.SuppressModelStateInvalidFilter = true;
options.SuppressMapClientErrors = true;
options.SuppressUseValidationProblemDetailsForInvalidModelStateResponses = true;
options.ClientErrorMapping[404].Link =
"https://httpstatuses.com/404";
});

Problem details for error status codes

When the compatibility version is 2.2 or later, MVC transforms an error result (a result with status code 400 or
higher) to a result with ProblemDetails. The ProblemDetails type is based on the RFC 7807 specification for
providing machine-readable error details in an HTTP response.
Consider the following code in a controller action:
 if (pet == null)
{
return NotFound();
}

The HTTP response for NotFound has a 404 status code with a ProblemDetails body. For example:

{
type: "https://tools.ietf.org/html/rfc7231#section-6.5.4",
title: "Not Found",
status: 404,
traceId: "0HLHLV31KRN83:00000001"
}

Customize ProblemDetails response

Use the ClientErrorMapping property to configure the contents of the ProblemDetails response. For example,
the following code updates the type property for 404 responses:

services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2)
.ConfigureApiBehaviorOptions(options =>
{
options.SuppressConsumesConstraintForFormFileParameters = true;
options.SuppressInferBindingSourcesForParameters = true;
options.SuppressModelStateInvalidFilter = true;
options.SuppressMapClientErrors = true;
options.SuppressUseValidationProblemDetailsForInvalidModelStateResponses = true;
options.ClientErrorMapping[404].Link =
"https://httpstatuses.com/404";
});

Disable ProblemDetails response

The automatic creation of ProblemDetails is disabled when the SuppressMapClientErrors property is set to true
. Add the following code in Startup.ConfigureServices :

services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2)
.ConfigureApiBehaviorOptions(options =>
{
options.SuppressConsumesConstraintForFormFileParameters = true;
options.SuppressInferBindingSourcesForParameters = true;
options.SuppressModelStateInvalidFilter = true;
options.SuppressMapClientErrors = true;
options.SuppressUseValidationProblemDetailsForInvalidModelStateResponses = true;
options.ClientErrorMapping[404].Link =
"https://httpstatuses.com/404";
});

Additional resources
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
 Tutorial: Create a web API with ASP.NET Core
8/9/2019 • 28 minutes to read • Edit Online

By Rick Anderson and Mike Wasson

This tutorial teaches the basics of building a web API with ASP.NET Core.
In this tutorial, you learn how to:
Create a web API project.
Add a model class and a database context.
Scaffold a controller with CRUD methods.
Configure routing, URL paths, and return values.
Call the web API with Postman.
At the end, you have a web API that can manage "to-do" items stored in a database.

Overview
This tutorial creates the following API:

API DESCRIPTION REQUEST BODY RESPONSE BODY

GET /api/TodoItems Get all to-do items None Array of to-do items

GET /api/TodoItems/{id} Get an item by ID None To-do item

POST /api/TodoItems Add a new item To-do item To-do item

PUT /api/TodoItems/{id} Update an existing item To-do item None

DELETE /api/TodoItems/{id} Delete an item None None

The following diagram shows the design of the app.

Prerequisites
Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 3.0 Preview

Create a web project

Visual Studio
Visual Studio Code
Visual Studio for Mac
From the File menu, select New > Project.
Select the ASP.NET Core Web Application template and click Next.
Name the project TodoApi and click Create.
In the Create a new ASP.NET Core Web Application dialog, confirm that .NET Core and ASP.NET Core
3.0 are selected. Select the API template and click Create. Don't select Enable Docker Support.

Test the API

The project template creates a WeatherForecast API. Call the Get method from a browser to test the app.
Visual Studio
Visual Studio Code
Visual Studio for Mac
Press Ctrl+F5 to run the app. Visual Studio launches a browser and navigates to
https://localhost:<port>/WeatherForecast , where <port> is a randomly chosen port number.
If you get a dialog box that asks if you should trust the IIS Express certificate, select Yes. In the Security
Warning dialog that appears next, select Yes.
JSON similar to the following is returned:

[
{
"date": "2019-07-16T19:04:05.7257911-06:00",
"temperatureC": 52,
"temperatureF": 125,
"summary": "Mild"
},
{
"date": "2019-07-17T19:04:05.7258461-06:00",
"temperatureC": 36,
"temperatureF": 96,
"summary": "Warm"
},
{
"date": "2019-07-18T19:04:05.7258467-06:00",
"temperatureC": 39,
"temperatureF": 102,
"summary": "Cool"
},
{
"date": "2019-07-19T19:04:05.7258471-06:00",
"temperatureC": 10,
"temperatureF": 49,
"summary": "Bracing"
},
{
"date": "2019-07-20T19:04:05.7258474-06:00",
"temperatureC": -1,
"temperatureF": 31,
"summary": "Chilly"
}
]

Add a model class

A model is a set of classes that represent the data that the app manages. The model for this app is a single
TodoItem class.

Visual Studio
Visual Studio Code
Visual Studio for Mac
In Solution Explorer, right-click the project. Select Add > New Folder. Name the folder Models.
Right-click the Models folder and select Add > Class. Name the class TodoItem and select Add.
Replace the template code with the following code:
 namespace TodoApi.Models
{
public class TodoItem
{
public long Id { get; set; }
public string Name { get; set; }
public bool IsComplete { get; set; }
}
}

The Id property functions as the unique key in a relational database.

Model classes can go anywhere in the project, but the Models folder is used by convention.

Add a database context

The database context is the main class that coordinates Entity Framework functionality for a data model. This
class is created by deriving from the Microsoft.EntityFrameworkCore.DbContext class.
Visual Studio
Visual Studio Code / Visual Studio for Mac
Add Microsoft.EntityFrameworkCore.SqlServer
From the Tools menu, select NuGet Package Manager > Manage NuGet Packages for Solution.
Select the Include prerelease checkbox.
Select the Browse tab, and then enter Microsoft.EntityFrameworkCore.SqlServer in the search box.
Select Microsoft.EntityFrameworkCore.SqlServer V3.0.0-preview in the left pane.
Select the Project check box in the right pane and then select Install.
Use the preceding instructions to add the Microsoft.EntityFrameworkCore.InMemory NuGet package.
Add the TodoContext database context
Right-click the Models folder and select Add > Class. Name the class TodoContext and click Add.
Enter the following code:

using Microsoft.EntityFrameworkCore;

namespace TodoApi.Models
{
public class TodoContext : DbContext
{
public TodoContext(DbContextOptions<TodoContext> options)
: base(options)
{
}

public DbSet<TodoItem> TodoItems { get; set; }

}
}

Register the database context

In ASP.NET Core, services such as the DB context must be registered with the dependency injection (DI)
container. The container provides the service to controllers.
Update Startup.cs with the following highlighted code:

// Unused usings removed

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi
{
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}

public IConfiguration Configuration { get; }

public void ConfigureServices(IServiceCollection services)

{
services.AddDbContext<TodoContext>(opt =>
opt.UseInMemoryDatabase("TodoList"));
services.AddControllers();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)

{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}

app.UseHttpsRedirection();

app.UseRouting();

app.UseAuthorization();

app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
}
}
}

The preceding code:

Removes unused using declarations.
Adds the database context to the DI container.
Specifies that the database context will use an in-memory database.

Scaffold a controller
Visual Studio
Visual Studio Code / Visual Studio for Mac
Right-click the Controllers folder.
Select Add > New Scaffolded Item.
 Select API Controller with actions, using Entity Framework, and then select Add.
In the Add API Controller with actions, using Entity Framework dialog:
Select TodoItem (TodoAPI.Models) in the Model class.
Select TodoContext (TodoAPI.Models) in the Data context class.
Select Add
The generated code:
Defines an API controller class without methods.
Decorates the class with the [ApiController] attribute. This attribute indicates that the controller responds to
web API requests. For information about specific behaviors that the attribute enables, see Create web APIs
with ASP.NET Core.
Uses DI to inject the database context ( TodoContext ) into the controller. The database context is used in each
of the CRUD methods in the controller.

Examine the PostTodoItem create method

Replace the return statement in the PostTodoItem to use the nameof operator:

// POST: api/TodoItems
[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
_context.TodoItems.Add(todoItem);
await _context.SaveChangesAsync();

//return CreatedAtAction("GetTodoItem", new { id = todoItem.Id }, todoItem);

return CreatedAtAction(nameof(GetTodoItem), new { id = todoItem.Id }, todoItem);
}

The preceding code is an HTTP POST method, as indicated by the [HttpPost] attribute. The method gets the
value of the to-do item from the body of the HTTP request.
The CreatedAtAction method:
Returns an HTTP 201 status code if successful. 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. For more information, see 10.2.2 201 Created.
References the GetTodoItem action to create the Location header's URI. The C# nameof keyword is used to
avoid hard-coding the action name in the CreatedAtAction call.
Install Postman
This tutorial uses Postman to test the web API.
Install Postman
Start the web app.
Start Postman.
Disable SSL certificate verification
From File > Settings (*General tab), disable SSL certificate verification.
 WARNING
Re-enable SSL certificate verification after testing the controller.

Test PostTodoItem with Postman

Create a new request.
Set the HTTP method to POST .
Select the Body tab.
Select the raw radio button.
Set the type to JSON (application/json).
In the request body enter JSON for a to-do item:

{
"name":"walk dog",
"isComplete":true
}

Select Send.

Test the location header URI

Select the Headers tab in the Response pane.
Copy the Location header value:
 Set the method to GET.
Paste the URI (for example, https://localhost:5001/api/TodoItems/1 )
Select Send.

Examine the GET methods

These methods implement two GET endpoints:
GET /api/TodoItems
GET /api/TodoItems/{id}

Test the app by calling the two endpoints from a browser or Postman. For example:
https://localhost:5001/api/TodoItems
https://localhost:5001/api/TodoItems/1
A response similar to the following is produced by the call to GetTodoItems :

[
{
"id": 1,
"name": "Item1",
"isComplete": false
}
]

Test Get with Postman

Create a new request.
Set the HTTP method to GET.
Set the request URL to https://localhost:<port>/api/TodoItems . For example,
https://localhost:5001/api/TodoItems .
Set Two pane view in Postman.
Select Send.
This app uses an in-memory database. If the app is stopped and started, the preceding GET request will not
return any data. If no data is returned, POST data to the app.

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:
Start with the template string in the controller's Route attribute:

[Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase
{
private readonly TodoContext _context;

public TodoItemsController(TodoContext context)

{
_context = context;
}

Replace [controller] with the name of the controller, which by convention is the controller class name
minus the "Controller" suffix. For this sample, the controller class name is TodoItemsController, so the
controller name is "TodoItems". ASP.NET Core routing is case insensitive.
If the [HttpGet] attribute has a route template (for example, [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 GetTodoItem method, "{id}" is a placeholder variable for the unique identifier of the to-do
item. When GetTodoItem is invoked, the value of "{id}" in the URL is provided to the method in its id
parameter.

// GET: api/TodoItems/5
[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
var todoItem = await _context.TodoItems.FindAsync(id);

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

return todoItem;
}

Return values
The return type of the GetTodoItems and GetTodoItem methods is ActionResult<T> type. ASP.NET Core
automatically serializes the object to JSON and writes the JSON into the body of the response message. The
response code for this return type is 200, assuming there are no unhandled exceptions. Unhandled exceptions
are translated into 5xx errors.
ActionResult return types can represent a wide range of HTTP status codes. For example, GetTodoItem can
return two different status values:
If no item matches the requested ID, the method returns a 404 NotFound error code.
Otherwise, the method returns 200 with a JSON response body. Returning item results in an HTTP 200
 response.

The PutTodoItem method

Examine the PutTodoItem method:

// PUT: api/TodoItems/5
[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
if (id != todoItem.Id)
{
return BadRequest();
}

_context.Entry(todoItem).State = EntityState.Modified;

try
{
await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
if (!TodoItemExists(id))
{
return NotFound();
}
else
{
throw;
}
}

return NoContent();
}

PutTodoItem is similar to PostTodoItem , 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
changes. To support partial updates, use HTTP PATCH.
If you get an error calling PutTodoItem , call GET to ensure there's an item in the database.
Test the PutTodoItem method
This sample uses an in-memory database that must be initialed each time the app is started. There must be an
item in the database before you make a PUT call. Call GET to insure there's an item in the database before
making a PUT call.
Update the to-do item that has ID = 1 and set its name to "feed fish":

{
"ID":1,
"name":"feed fish",
"isComplete":true
}

The following image shows the Postman update:

The DeleteTodoItem method
Examine the DeleteTodoItem method:

// DELETE: api/TodoItems/5
[HttpDelete("{id}")]
public async Task<ActionResult<TodoItem>> DeleteTodoItem(long id)
{
var todoItem = await _context.TodoItems.FindAsync(id);
if (todoItem == null)
{
return NotFound();
}

_context.TodoItems.Remove(todoItem);
await _context.SaveChangesAsync();

return todoItem;
}

The DeleteTodoItem response is 204 (No Content).

Test the DeleteTodoItem method
Use Postman to delete a to-do item:
Set the method to DELETE .
Set the URI of the object to delete, for example https://localhost:5001/api/TodoItems/1
Select Send

Call the API from jQuery

See Tutorial: Call an ASP.NET Core web API with jQuery.
In this tutorial, you learn how to:
 Create a web API project.
Add a model class and a database context.
Add a controller.
Add CRUD methods.
Configure routing and URL paths.
Specify return values.
Call the web API with Postman.
Call the web API with jQuery.
At the end, you have a web API that can manage "to-do" items stored in a relational database.

Overview
This tutorial creates the following API:

API DESCRIPTION REQUEST BODY RESPONSE BODY

GET /api/TodoItems Get all to-do items None Array of to-do items

GET /api/TodoItems/{id} Get an item by ID None To-do item

POST /api/TodoItems Add a new item To-do item To-do item

PUT /api/TodoItems/{id} Update an existing item To-do item None

DELETE /api/TodoItems/{id} Delete an item None None

The following diagram shows the design of the app.

Prerequisites
Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 2.2 or later
 WARNING
If you use Visual Studio 2017, see dotnet/sdk issue #3124 for information about .NET Core SDK versions that don't work
with Visual Studio.

Create a web project

Visual Studio
Visual Studio Code
Visual Studio for Mac
From the File menu, select New > Project.
Select the ASP.NET Core Web Application template and click Next.
Name the project TodoApi and click Create.
In the Create a new ASP.NET Core Web Application dialog, confirm that .NET Core and ASP.NET Core
2.2 are selected. Select the API template and click Create. Don't select Enable Docker Support.

Test the API

The project template creates a values API. Call the Get method from a browser to test the app.
Visual Studio
Visual Studio Code
Visual Studio for Mac
Press Ctrl+F5 to run the app. Visual Studio launches a browser and navigates to
https://localhost:<port>/api/values , where <port> is a randomly chosen port number.

If you get a dialog box that asks if you should trust the IIS Express certificate, select Yes. In the Security
Warning dialog that appears next, select Yes.
The following JSON is returned:

["value1","value2"]

Add a model class

A model is a set of classes that represent the data that the app manages. The model for this app is a single
TodoItem class.

Visual Studio
Visual Studio Code
Visual Studio for Mac
In Solution Explorer, right-click the project. Select Add > New Folder. Name the folder Models.
Right-click the Models folder and select Add > Class. Name the class TodoItem and select Add.
Replace the template code with the following code:

namespace TodoApi.Models
{
public class TodoItem
{
public long Id { get; set; }
public string Name { get; set; }
public bool IsComplete { get; set; }
}
}

The Id property functions as the unique key in a relational database.

Model classes can go anywhere in the project, but the Models folder is used by convention.

Add a database context

The database context is the main class that coordinates Entity Framework functionality for a data model. This
class is created by deriving from the Microsoft.EntityFrameworkCore.DbContext class.
Visual Studio
Visual Studio Code / Visual Studio for Mac
Right-click the Models folder and select Add > Class. Name the class TodoContext and click Add.
Replace the template code with the following code:
 using Microsoft.EntityFrameworkCore;

namespace TodoApi.Models
{
public class TodoContext : DbContext
{
public TodoContext(DbContextOptions<TodoContext> options)
: base(options)
{
}

public DbSet<TodoItem> TodoItems { get; set; }

}
}

Register the database context

In ASP.NET Core, services such as the DB context must be registered with the dependency injection (DI)
container. The container provides the service to controllers.
Update Startup.cs with the following highlighted code:
 // Unused usings removed
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using TodoApi.Models;

namespace TodoApi
{
public class Startup
{
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.
public void ConfigureServices(IServiceCollection services)
{
services.AddDbContext<TodoContext>(opt =>
opt.UseInMemoryDatabase("TodoList"));
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}

// 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
{
// The default HSTS value is 30 days. You may want to change this for
// production scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}

app.UseHttpsRedirection();
app.UseMvc();
}
}
}

The preceding code:

Removes unused using declarations.
Adds the database context to the DI container.
Specifies that the database context will use an in-memory database.

Add a controller
Visual Studio
Visual Studio Code / Visual Studio for Mac
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 select Add.

Replace the template code with the following code:

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using TodoApi.Models;

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

public TodoController(TodoContext context)

{
_context = context;

if (_context.TodoItems.Count() == 0)
{
// Create a new TodoItem if collection is empty,
// which means you can't delete all TodoItems.
_context.TodoItems.Add(new TodoItem { Name = "Item1" });
_context.SaveChanges();
}
}
}
}

The preceding code:

 Defines an API controller class without methods.
Decorates the class with the [ApiController] attribute. This attribute indicates that the controller responds to
web API requests. For information about specific behaviors that the attribute enables, see Create web APIs
with ASP.NET Core.
Uses DI to inject the database context ( TodoContext ) into the controller. The database context is used in each
of the CRUD methods in the controller.
Adds an item named Item1 to the database if the database is empty. This code is in the constructor, so it runs
every time there's a new HTTP request. If you delete all items, the constructor creates Item1 again the next
time an API method is called. So it may look like the deletion didn't work when it actually did work.

Add Get methods

To provide an API that retrieves to-do items, add the following methods to the TodoController class:

// GET: api/Todo
[HttpGet]
public async Task<ActionResult<IEnumerable<TodoItem>>> GetTodoItems()
{
return await _context.TodoItems.ToListAsync();
}

// GET: api/Todo/5
[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
var todoItem = await _context.TodoItems.FindAsync(id);

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

return todoItem;
}

These methods implement two GET endpoints:

GET /api/todo
GET /api/todo/{id}

Stop the app if it's still running. Then run it again to include the latest changes.
Test the app by calling the two endpoints from a browser. For example:
https://localhost:<port>/api/todo
https://localhost:<port>/api/todo/1

The following HTTP response is produced by the call to GetTodoItems :

[
{
"id": 1,
"name": "Item1",
"isComplete": false
}
]
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:
Start with the template string in the controller's Route attribute:

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

Replace [controller] with the name of the controller, which by convention is the controller class name
minus the "Controller" suffix. For this sample, the controller class name is TodoController, so the
controller name is "todo". ASP.NET Core routing is case insensitive.
If the [HttpGet] attribute has a route template (for example, [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 GetTodoItem method, "{id}" is a placeholder variable for the unique identifier of the to-do
item. When GetTodoItem is invoked, the value of "{id}" in the URL is provided to the method in its id
parameter.

// GET: api/Todo/5
[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
var todoItem = await _context.TodoItems.FindAsync(id);

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

return todoItem;
}

Return values
The return type of the GetTodoItems and GetTodoItem methods is ActionResult<T> type. ASP.NET Core
automatically serializes the object to JSON and writes the JSON into the body of the response message. The
response code for this return type is 200, assuming there are no unhandled exceptions. Unhandled exceptions
are translated into 5xx errors.
ActionResult return types can represent a wide range of HTTP status codes. For example, GetTodoItem can
return two different status values:
If no item matches the requested ID, the method returns a 404 NotFound error code.
Otherwise, the method returns 200 with a JSON response body. Returning item results in an HTTP 200
response.

Test the GetTodoItems method

This tutorial uses Postman to test the web API.
Install Postman
Start the web app.
Start Postman.
Disable SSL certificate verification
Visual Studio
Visual Studio Code / Visual Studio for Mac
From File > Settings (General tab), disable SSL certificate verification.

WARNING
Re-enable SSL certificate verification after testing the controller.

Create a new request.

Set the HTTP method to GET.
Set the request URL to https://localhost:<port>/api/todo . For example,
https://localhost:5001/api/todo .
Set Two pane view in Postman.
Select Send.

Add a Create method

Add the following PostTodoItem method inside of Controllers/TodoController.cs:
 // POST: api/Todo
[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem item)
{
_context.TodoItems.Add(item);
await _context.SaveChangesAsync();

return CreatedAtAction(nameof(GetTodoItem), new { id = item.Id }, item);

}

The preceding code is an HTTP POST method, as indicated by the [HttpPost] attribute. The method gets the
value of the to-do item from the body of the HTTP request.
The CreatedAtAction method:
Returns an HTTP 201 status code, if successful. 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. For more information, see 10.2.2 201 Created.
References the GetTodoItem action to create the Location header's URI. The C# nameof keyword is used
to avoid hard-coding the action name in the CreatedAtAction call.

// GET: api/Todo/5
[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
var todoItem = await _context.TodoItems.FindAsync(id);

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

return todoItem;
}

Test the PostTodoItem method

Build the project.
In Postman, set the HTTP method to POST .
Select the Body tab.
Select the raw radio button.
Set the type to JSON (application/json).
In the request body enter JSON for a to-do item:

{
"name":"walk dog",
"isComplete":true
}

Select Send.
 If you get a 405 Method Not Allowed error, it's probably the result of not compiling the project after
adding the PostTodoItem method.
Test the location header URI
Select the Headers tab in the Response pane.
Copy the Location header value:

Set the method to GET.

Paste the URI (for example, https://localhost:5001/api/Todo/2 )
Select Send.

Add a PutTodoItem method

Add the following PutTodoItem method:

// PUT: api/Todo/5
[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem item)
{
if (id != item.Id)
{
return BadRequest();
}

_context.Entry(item).State = EntityState.Modified;
await _context.SaveChangesAsync();

return NoContent();
}

PutTodoItem is similar to PostTodoItem , 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
changes. To support partial updates, use HTTP PATCH.
If you get an error calling PutTodoItem , call GET to ensure there's an item in the database.
Test the PutTodoItem method
This sample uses an in-memory database that must be initialed each time the app is started. There must be an
item in the database before you make a PUT call. Call GET to insure there's an item in the database before
making a PUT call.
Update the to-do item that has id = 1 and set its name to "feed fish":

{
"ID":1,
"name":"feed fish",
"isComplete":true
}

The following image shows the Postman update:

Add a DeleteTodoItem method
Add the following DeleteTodoItem method:

// DELETE: api/Todo/5
[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
var todoItem = await _context.TodoItems.FindAsync(id);

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

_context.TodoItems.Remove(todoItem);
await _context.SaveChangesAsync();

return NoContent();
}

The DeleteTodoItem response is 204 (No Content).

Test the DeleteTodoItem method
Use Postman to delete a to-do item:
Set the method to DELETE .
Set the URI of the object to delete, for example https://localhost:5001/api/todo/1
Select Send
The sample app allows you to delete all the items. However, when the last item is deleted, a new one is created by
the model class constructor the next time the API is called.

Call the 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 app to serve static files and enable default file mapping by updating Startup.cs with the following
highlighted code:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
// The default HSTS value is 30 days. You may want to change this for
// production scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}

app.UseDefaultFiles();
app.UseStaticFiles();
app.UseHttpsRedirection();
app.UseMvc();
}
Create a wwwroot folder in the project directory.
Add an HTML file named index.html to the 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="Save">
<a onclick="closeInput()" aria-label="Close">&#10006;</a>
</form>
</div>

<p id="counter"></p>

<table>
<tr>
<th>Is Complete</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="
 integrity="sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8="
crossorigin="anonymous"></script>
<script src="site.js"></script>
</body>
</html>

Add a JavaScript file named site.js to the 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.text("No " + name);
}
}

$(document).ready(function() {
getData();
});

function getData() {
$.ajax({
type: "GET",
url: uri,
cache: false,
success: function(data) {
const tBody = $("#todos");

$(tBody).empty();

getCount(data.length);

$.each(data, function(key, item) {

const tr = $("<tr></tr>")
.append(
$("<td></td>").append(
$("<input/>", {
type: "checkbox",
disabled: true,
checked: item.isComplete
})
)
)
.append($("<td></td>").text(item.name))
.append(
$("<td></td>").append(
$("<button>Edit</button>").on("click", function() {
editItem(item.id);
})
)
)
.append(
$("<td></td>").append(
$("<button>Delete</button>").on("click", function() {
deleteItem(item.id);
})
)
);

tr.appendTo(tBody);
});
 });

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("Something went wrong!");
},
success: function(result) {
getData();
$("#add-name").val("");
}
});
}

function deleteItem(id) {
$.ajax({
url: uri + "/" + id,
type: "DELETE",
success: function(result) {
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",
accepts: "application/json",
contentType: "application/json",
data: JSON.stringify(item),
success: function(result) {
getData();
}
});

closeInput();
return false;
 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 Properties\launchSettings.json.
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 calls all of the CRUD methods of the API. Following are explanations of the calls to the API.
Get a list of to -do items
The jQuery ajax function sends a GET request to the API, which returns JSON representing an array of to-do
items. The success callback function is invoked if the request succeeds. In the callback, the DOM is updated with
the to-do information.
 $(document).ready(function() {
getData();
});

function getData() {
$.ajax({
type: "GET",
url: uri,
cache: false,
success: function(data) {
const tBody = $("#todos");

$(tBody).empty();

getCount(data.length);

$.each(data, function(key, item) {

const tr = $("<tr></tr>")
.append(
$("<td></td>").append(
$("<input/>", {
type: "checkbox",
disabled: true,
checked: item.isComplete
})
)
)
.append($("<td></td>").text(item.name))
.append(
$("<td></td>").append(
$("<button>Edit</button>").on("click", function() {
editItem(item.id);
})
)
)
.append(
$("<td></td>").append(
$("<button>Delete</button>").on("click", function() {
deleteItem(item.id);
})
)
);

tr.appendTo(tBody);
});

todos = data;
}
});
}

Add a to -do item

The ajax function sends a POST request with the to-do item in the request body. The accepts and contentType
options are set to application/json to specify the media type being received and sent. The to-do item is
converted to JSON by using JSON.stringify. When the API returns a successful status code, the getData
function is invoked to update the HTML table.
 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("Something went wrong!");
},
success: function(result) {
getData();
$("#add-name").val("");
}
});
}

Update a to -do item

Updating a to-do item is similar to adding one. The url changes to add the unique identifier of the item, and the
type is PUT .

$.ajax({
url: uri + "/" + $("#edit-id").val(),
type: "PUT",
accepts: "application/json",
contentType: "application/json",
data: JSON.stringify(item),
success: function(result) {
getData();
}
});

Delete a to -do item

Deleting a to-do item is accomplished by setting the type on the AJAX call to DELETE and specifying the item's
unique identifier in the URL.

$.ajax({
url: uri + "/" + id,
type: "DELETE",
success: function(result) {
getData();
}
});

Additional resources
View or download sample code for this tutorial. See how to download.
For more information, see the following resources:
Create web APIs with ASP.NET Core
ASP.NET Core Web API help pages with Swagger / OpenAPI
<xref:data/ef-rp/index>
Routing to controller actions in ASP.NET Core
Controller action return types in ASP.NET Core Web API
Deploy ASP.NET Core apps to Azure App Service
Host and deploy ASP.NET Core
YouTube version of this tutorial
 Create a web API with ASP.NET Core and MongoDB
7/11/2019 • 10 minutes to read • Edit Online

By Pratik Khandelwal and Scott Addie

This tutorial creates a web API that performs Create, Read, Update, and Delete (CRUD ) operations on a MongoDB
NoSQL database.
In this tutorial, you learn how to:
Configure MongoDB
Create a MongoDB database
Define a MongoDB collection and schema
Perform MongoDB CRUD operations from a web API
Customize JSON serialization
View or download sample code (how to download)

Prerequisites
Visual Studio
Visual Studio Code
Visual Studio for Mac
.NET Core SDK 2.2 or later
Visual Studio 2019 with the ASP.NET and web development workload
MongoDB

Configure MongoDB
If using Windows, MongoDB is installed at C:\Program Files\MongoDB by default. Add C:\Program
Files\MongoDB\Server\<version_number>\bin to the Path environment variable. This change enables MongoDB
access from anywhere on your development machine.
Use the mongo Shell in the following steps to create a database, make collections, and store documents. For more
information on mongo Shell commands, see Working with the mongo Shell.
1. Choose a directory on your development machine for storing the data. For example, C:\BooksData on
Windows. Create the directory if it doesn't exist. The mongo Shell doesn't create new directories.
2. Open a command shell. Run the following command to connect to MongoDB on default port 27017.
Remember to replace <data_directory_path> with the directory you chose in the previous step.

mongod --dbpath <data_directory_path>

3. Open another command shell instance. Connect to the default test database by running the following
command:

mongo
4. Run the following in a command shell:

use BookstoreDb

If it doesn't already exist, a database named BookstoreDb is created. If the database does exist, its
connection is opened for transactions.
5. Create a Books collection using following command:

db.createCollection('Books')

The following result is displayed:

{ "ok" : 1 }

6. Define a schema for the Books collection and insert two documents using the following command:

db.Books.insertMany([{'Name':'Design Patterns','Price':54.93,'Category':'Computers','Author':'Ralph
Johnson'}, {'Name':'Clean Code','Price':43.15,'Category':'Computers','Author':'Robert C. Martin'}])

The following result is displayed:

{
"acknowledged" : true,
"insertedIds" : [
ObjectId("5bfd996f7b8e48dc15ff215d"),
ObjectId("5bfd996f7b8e48dc15ff215e")
]
}

NOTE
The ID's shown in this article will not match the IDs when you run this sample.

1. View the documents in the database using the following command:

db.Books.find({}).pretty()

The following result is displayed:

 {
"_id" : ObjectId("5bfd996f7b8e48dc15ff215d"),
"Name" : "Design Patterns",
"Price" : 54.93,
"Category" : "Computers",
"Author" : "Ralph Johnson"
}
{
"_id" : ObjectId("5bfd996f7b8e48dc15ff215e"),
"Name" : "Clean Code",
"Price" : 43.15,
"Category" : "Computers",
"Author" : "Robert C. Martin"
}

The schema adds an autogenerated _id property of type ObjectId for each document.
The database is ready. You can start creating the ASP.NET Core web API.

Create the ASP.NET Core web API project

Visual Studio
Visual Studio Code
Visual Studio for Mac
1. Go to File > New > Project.
2. Select the ASP.NET Core Web Application project type, and select Next.
3. Name the project BooksApi, and select Create.
4. Select the .NET Core target framework and ASP.NET Core 2.2. Select the API project template, and select
Create.
5. Visit the NuGet Gallery: MongoDB.Driver to determine the latest stable version of the .NET driver for
MongoDB. In the Package Manager Console window, navigate to the project root. Run the following
command to install the .NET driver for MongoDB:

Install-Package MongoDB.Driver -Version {VERSION}

Add an entity model

1. Add a Models directory to the project root.
2. Add a Book class to the Models directory with the following code:
 using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;

namespace BooksApi.Models
{
public class Book
{
[BsonId]
[BsonRepresentation(BsonType.ObjectId)]
public string Id { get; set; }

[BsonElement("Name")]
public string BookName { get; set; }

public decimal Price { get; set; }

public string Category { get; set; }

public string Author { get; set; }

}
}

In the preceding class, the Id property:

Is required for mapping the Common Language Runtime (CLR ) object to the MongoDB collection.
Is annotated with [BsonId] to designate this property as the document's primary key.
Is annotated with [BsonRepresentation(BsonType.ObjectId)] to allow passing the parameter as type
string instead of an ObjectId structure. Mongo handles the conversion from string to ObjectId .
The BookName property is annotated with the [BsonElement] attribute. The attribute's value of Name
represents the property name in the MongoDB collection.

Add a configuration model

1. Add the following database configuration values to appsettings.json:

{
"BookstoreDatabaseSettings": {
"BooksCollectionName": "Books",
"ConnectionString": "mongodb://localhost:27017",
"DatabaseName": "BookstoreDb"
},
"Logging": {
"IncludeScopes": false,
"Debug": {
"LogLevel": {
"Default": "Warning"
}
},
"Console": {
"LogLevel": {
"Default": "Warning"
}
}
}
}

2. Add a BookstoreDatabaseSettings.cs file to the Models directory with the following code:
 namespace BooksApi.Models
{
public class BookstoreDatabaseSettings : IBookstoreDatabaseSettings
{
public string BooksCollectionName { get; set; }
public string ConnectionString { get; set; }
public string DatabaseName { get; set; }
}

public interface IBookstoreDatabaseSettings

{
string BooksCollectionName { get; set; }
string ConnectionString { get; set; }
string DatabaseName { get; set; }
}
}

The preceding BookstoreDatabaseSettings class is used to store the appsettings.json file's

BookstoreDatabaseSettings property values. The JSON and C# property names are named identically to
ease the mapping process.
3. Add the following highlighted code to Startup.ConfigureServices :

public void ConfigureServices(IServiceCollection services)

{
services.Configure<BookstoreDatabaseSettings>(
Configuration.GetSection(nameof(BookstoreDatabaseSettings)));

services.AddSingleton<IBookstoreDatabaseSettings>(sp =>
sp.GetRequiredService<IOptions<BookstoreDatabaseSettings>>().Value);

services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}

In the preceding code:

The configuration instance to which the appsettings.json file's BookstoreDatabaseSettings section binds is
registered in the Dependency Injection (DI) container. For example, a BookstoreDatabaseSettings object's
ConnectionString property is populated with the BookstoreDatabaseSettings:ConnectionString property
in appsettings.json.
The IBookstoreDatabaseSettings interface is registered in DI with a singleton service lifetime. When
injected, the interface instance resolves to a BookstoreDatabaseSettings object.
4. Add the following code to the top of Startup.cs to resolve the BookstoreDatabaseSettings and
IBookstoreDatabaseSettings references:

using BooksApi.Models;

Add a CRUD operations service

1. Add a Services directory to the project root.
2. Add a BookService class to the Services directory with the following code:
 using BooksApi.Models;
using MongoDB.Driver;
using System.Collections.Generic;
using System.Linq;

namespace BooksApi.Services
{
public class BookService
{
private readonly IMongoCollection<Book> _books;

public BookService(IBookstoreDatabaseSettings settings)

{
var client = new MongoClient(settings.ConnectionString);
var database = client.GetDatabase(settings.DatabaseName);

_books = database.GetCollection<Book>(settings.BooksCollectionName);
}

public List<Book> Get() =>

_books.Find(book => true).ToList();

public Book Get(string id) =>

_books.Find<Book>(book => book.Id == id).FirstOrDefault();

public Book Create(Book book)

{
_books.InsertOne(book);
return book;
}

public void Update(string id, Book bookIn) =>

_books.ReplaceOne(book => book.Id == id, bookIn);

public void Remove(Book bookIn) =>

_books.DeleteOne(book => book.Id == bookIn.Id);

public void Remove(string id) =>

_books.DeleteOne(book => book.Id == id);
}
}

In the preceding code, an IBookstoreDatabaseSettings instance is retrieved from DI via constructor injection.
This technique provides access to the appsettings.json configuration values that were added in the Add a
configuration model section.
3. Add the following highlighted code to Startup.ConfigureServices :

public void ConfigureServices(IServiceCollection services)

{
services.Configure<BookstoreDatabaseSettings>(
Configuration.GetSection(nameof(BookstoreDatabaseSettings)));

services.AddSingleton<IBookstoreDatabaseSettings>(sp =>
sp.GetRequiredService<IOptions<BookstoreDatabaseSettings>>().Value);

services.AddSingleton<BookService>();

services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}

In the preceding code, the BookService class is registered with DI to support constructor injection in
 consuming classes. The singleton service lifetime is most appropriate because BookService takes a direct
dependency on MongoClient . Per the official Mongo Client reuse guidelines, MongoClient should be
registered in DI with a singleton service lifetime.
4. Add the following code to the top of Startup.cs to resolve the BookService reference:

using BooksApi.Services;

The BookService class uses the following MongoDB.Driver members to perform CRUD operations against the
database:
MongoClient – Reads the server instance for performing database operations. The constructor of this class
is provided the MongoDB connection string:

public BookService(IBookstoreDatabaseSettings settings)

{
var client = new MongoClient(settings.ConnectionString);
var database = client.GetDatabase(settings.DatabaseName);

_books = database.GetCollection<Book>(settings.BooksCollectionName);
}

IMongoDatabase – Represents the Mongo database for performing operations. This tutorial uses the
generic GetCollection<TDocument>(collection) method on the interface to gain access to data in a specific
collection. Perform CRUD operations against the collection after this method is called. In the
GetCollection<TDocument>(collection) method call:

collection represents the collection name.

TDocument represents the CLR object type stored in the collection.

GetCollection<TDocument>(collection) returns a MongoCollection object representing the collection. In this

tutorial, the following methods are invoked on the collection:
DeleteOne – Deletes a single document matching the provided search criteria.
Find<TDocument> – Returns all documents in the collection matching the provided search criteria.
InsertOne – Inserts the provided object as a new document in the collection.
ReplaceOne – Replaces the single document matching the provided search criteria with the provided object.

Add a controller
Add a BooksController class to the Controllers directory with the following code:

using BooksApi.Models;
using BooksApi.Services;
using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;

namespace BooksApi.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class BooksController : ControllerBase
{
private readonly BookService _bookService;

public BooksController(BookService bookService)

{
_bookService = bookService;
 _bookService = bookService;
}

[HttpGet]
public ActionResult<List<Book>> Get() =>
_bookService.Get();

[HttpGet("{id:length(24)}", Name = "GetBook")]

public ActionResult<Book> Get(string id)
{
var book = _bookService.Get(id);

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

return book;
}

[HttpPost]
public ActionResult<Book> Create(Book book)
{
_bookService.Create(book);

return CreatedAtRoute("GetBook", new { id = book.Id.ToString() }, book);

}

[HttpPut("{id:length(24)}")]
public IActionResult Update(string id, Book bookIn)
{
var book = _bookService.Get(id);

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

_bookService.Update(id, bookIn);

return NoContent();
}

[HttpDelete("{id:length(24)}")]
public IActionResult Delete(string id)
{
var book = _bookService.Get(id);

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

_bookService.Remove(book.Id);

return NoContent();
}
}
}

The preceding web API controller:

Uses the BookService class to perform CRUD operations.
Contains action methods to support GET, POST, PUT, and DELETE HTTP requests.
Calls CreatedAtRoute in the Create action method to return an HTTP 201 response. Status code 201 is 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 book.

Test the web API

1. Build and run the app.
2. Navigate to http://localhost:<port>/api/books to test the controller's parameterless Get action method.
The following JSON response is displayed:

[
{
"id":"5bfd996f7b8e48dc15ff215d",
"bookName":"Design Patterns",
"price":54.93,
"category":"Computers",
"author":"Ralph Johnson"
},
{
"id":"5bfd996f7b8e48dc15ff215e",
"bookName":"Clean Code",
"price":43.15,
"category":"Computers",
"author":"Robert C. Martin"
}
]

3. Navigate to http://localhost:<port>/api/books/{id here} to test the controller's overloaded Get action

method. The following JSON response is displayed:

{
"id":"{ID}",
"bookName":"Clean Code",
"price":43.15,
"category":"Computers",
"author":"Robert C. Martin"
}

Configure JSON serialization options

There are two details to change about the JSON responses returned in the Test the web API section:
The property names' default camel casing should be changed to match the Pascal casing of the CLR object's
property names.
The bookName property should be returned as Name .

To satisfy the preceding requirements, make the following changes:

1. In Startup.ConfigureServices , chain the following highlighted code on to the AddMvc method call:
 public void ConfigureServices(IServiceCollection services)
{
services.Configure<BookstoreDatabaseSettings>(
Configuration.GetSection(nameof(BookstoreDatabaseSettings)));

services.AddSingleton<IBookstoreDatabaseSettings>(sp =>
sp.GetRequiredService<IOptions<BookstoreDatabaseSettings>>().Value);

services.AddSingleton<BookService>();

services.AddMvc()
.AddJsonOptions(options => options.UseMemberCasing())
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}

With the preceding change, property names in the web API's serialized JSON response match their
corresponding property names in the CLR object type. For example, the Book class's Author property
serializes as Author .
2. In Models/Book.cs, annotate the BookName property with the following [JsonProperty] attribute:

[BsonElement("Name")]
[JsonProperty("Name")]
public string BookName { get; set; }

The [JsonProperty] attribute's value of Name represents the property name in the web API's serialized
JSON response.
3. Add the following code to the top of Models/Book.cs to resolve the [JsonProperty] attribute reference:

using Newtonsoft.Json;

4. Repeat the steps defined in the Test the web API section. Notice the difference in JSON property names.

Next steps
For more information on building ASP.NET Core web APIs, see the following resources:
YouTube version of this article
Create web APIs with ASP.NET Core
Controller action return types in ASP.NET Core Web API
 ASP.NET Core web API help pages with Swagger /
OpenAPI
7/12/2019 • 2 minutes to read • Edit Online

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 Swashbuckle
Get started with NSwag
 Get started with Swashbuckle and ASP.NET Core
8/13/2019 • 12 minutes to read • Edit Online

By Shayne Boyer and Scott Addie

View or download sample code (how to download)
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.

Package installation
Swashbuckle can be added with the following approaches:
Visual Studio
Visual Studio for Mac
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 -Version 5.0.0-rc2

From the Manage NuGet Packages dialog:

Right-click the project in Solution Explorer > Manage NuGet Packages
Set the Package source to "nuget.org"
Ensure the "Include prerelease" option is enabled
Enter "Swashbuckle.AspNetCore" in the search box
Select the latest "Swashbuckle.AspNetCore" package from the Browse tab and click Install

Add and configure Swagger middleware

In the Startup class, import the following namespace to use the OpenApiInfo class:
 using Microsoft.OpenApi.Models;

Add the Swagger generator to the services collection in the Startup.ConfigureServices method:

public void ConfigureServices(IServiceCollection services)

{
services.AddDbContext<TodoContext>(opt =>
opt.UseInMemoryDatabase("TodoList"));
services.AddMvc();

// Register the Swagger generator, defining 1 or more Swagger documents

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

public void ConfigureServices(IServiceCollection services)

{
services.AddDbContext<TodoContext>(opt =>
opt.UseInMemoryDatabase("TodoList"));
services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

// Register the Swagger generator, defining 1 or more Swagger documents

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

In the Startup.Configure method, enable the middleware for serving the generated JSON document and the
Swagger UI:

public void Configure(IApplicationBuilder app)

{
// 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 File 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:

app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
c.RoutePrefix = string.Empty;
});

If using directories with IIS or a reverse proxy, set the Swagger endpoint to a relative path using the ./ prefix. For
example, ./swagger/v1/swagger.json . Using /swagger/v1/swagger.json instructs the app to look for the JSON file
at the true root of the URL (plus the route prefix, if used). For example, use
http://localhost:<port>/<route_prefix>/swagger/v1/swagger.json instead of
http://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json .

Customize and extend

Swagger provides options for documenting the object model and customizing the UI to match your theme.
In the Startup class, add the following namespaces:

using System;
using System.Reflection;
using System.IO;

API info and description

The configuration action passed to the AddSwaggerGen method adds information such as the author, license, and
description:

// Register the Swagger generator, defining 1 or more Swagger documents

services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "ToDo API",
Description = "A simple example ASP.NET Core Web API",
TermsOfService = new Uri("https://example.com/terms"),
Contact = new OpenApiContact
{
Name = "Shayne Boyer",
Email = string.Empty,
Url = new Uri("https://twitter.com/spboyer"),
},
License = new OpenApiLicense
{
Name = "Use under LICX",
Url = new Uri("https://example.com/license"),
}
});
});

The Swagger UI displays the version's information:

XML comments
XML comments can be enabled with the following approaches:
Visual Studio
Visual Studio for Mac
Visual Studio Code
.NET Core CLI
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.
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>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
 <PropertyGroup>
<DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</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 class Program
{
public static void Main(string[] args) =>
BuildWebHost(args).Run();

public static IWebHost BuildWebHost(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.Build();
}
#pragma warning restore CS1591
}

Configure Swagger to use the XML file that's generated with the preceding instructions. 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.
public void ConfigureServices(IServiceCollection services)
{
services.AddDbContext<TodoContext>(opt =>
opt.UseInMemoryDatabase("TodoList"));
services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

// Register the Swagger generator, defining 1 or more Swagger documents

services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "ToDo API",
Description = "A simple example ASP.NET Core Web API",
TermsOfService = new Uri("https://example.com/terms"),
Contact = new OpenApiContact
{
Name = "Shayne Boyer",
Email = string.Empty,
Url = new Uri("https://twitter.com/spboyer"),
},
License = new OpenApiLicense
{
Name = "Use under LICX",
Url = new Uri("https://example.com/license"),
}
});

// 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);
});
}
public void ConfigureServices(IServiceCollection services)
{
services.AddDbContext<TodoContext>(opt =>
opt.UseInMemoryDatabase("TodoList"));
services.AddMvc();

// Register the Swagger generator, defining 1 or more Swagger documents

services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "ToDo API",
Description = "A simple example ASP.NET Core Web API",
TermsOfService = new Uri("https://example.com/terms"),
Contact = new OpenApiContact
{
Name = "Shayne Boyer",
Email = string.Empty,
Url = new Uri("https://twitter.com/spboyer"),
},
License = new OpenApiLicense
{
Name = "Use under LICX",
Url = new Uri("https://example.com/license"),
}
});

// 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);
});
}
 public void ConfigureServices(IServiceCollection services)
{
services.AddDbContext<TodoContext>(opt =>
opt.UseInMemoryDatabase("TodoList"));
services.AddMvc();

// Register the Swagger generator, defining 1 or more Swagger documents

services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "ToDo API",
Description = "A simple example ASP.NET Core Web API",
TermsOfService = new Uri("https://example.com/terms"),
Contact = new OpenApiContact
{
Name = "Shayne Boyer",
Email = string.Empty,
Url = new Uri("https://twitter.com/spboyer"),
},
License = new OpenApiLicense
{
Name = "Use under LICX",
Url = new Uri("https://example.com/license"),
}
});

// Set the comments path for the Swagger JSON and UI.
var xmlFile = $"{Assembly.GetEntryAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
});
}

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. Some Swagger features (for
example, schemata of input parameters or HTTP methods and response codes from the respective attributes) work
without the use of an XML documentation file. For most features, namely method summaries and the descriptions
of parameters and response codes, the use of an XML file is mandatory.
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>
[HttpDelete("{id}")]
public IActionResult Delete(long id)
{
var todo = _context.TodoItems.Find(id);

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

_context.TodoItems.Remove(todo);
_context.SaveChanges();

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)]
[ProducesResponseType(400)]
public IActionResult Create([FromBody] TodoItem item)
{
if (item == null)
{
return BadRequest();
}

_context.TodoItems.Add(item);
_context.SaveChanges();

return CreatedAtRoute("GetTodo", new { id = item.Id }, item);

}

/// <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(201)]
[ProducesResponseType(400)]
public ActionResult<TodoItem> Create(TodoItem item)
{
_context.TodoItems.Add(item);
_context.SaveChanges();

return CreatedAtRoute("GetTodo", new { id = item.Id }, item);

}

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;
using System.ComponentModel.DataAnnotations;

namespace TodoApi.Models
{
public class TodoItem
{
public long Id { get; set; }

[Required]
public string Name { get; set; }

[DefaultValue(false)]
public bool IsComplete { get; set; }
}
}

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:
 [Produces("application/json")]
[Route("api/[controller]")]
public class TodoController : ControllerBase
{
private readonly TodoContext _context;

[Produces("application/json")]
[Route("api/[controller]")]
[ApiController]
public class TodoController : ControllerBase
{
private readonly TodoContext _context;

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
Developers consuming a web API 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>
/// 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)]
[ProducesResponseType(400)]
public IActionResult Create([FromBody] TodoItem item)
{
if (item == null)
{
return BadRequest();
}

_context.TodoItems.Add(item);
_context.SaveChanges();

return CreatedAtRoute("GetTodo", new { id = item.Id }, item);

}

/// <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(201)]
[ProducesResponseType(400)]
public ActionResult<TodoItem> Create(TodoItem item)
{
_context.TodoItems.Add(item);
_context.SaveChanges();

return CreatedAtRoute("GetTodo", new { id = item.Id }, item);

}

The Swagger UI now clearly documents the expected HTTP response codes:
In ASP.NET Core 2.2 or later, conventions can be used as an alternative to explicitly decorating individual actions
with [ProducesResponseType] . For more information, see Use web API conventions.
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 Static File Middleware:

public void Configure(IApplicationBuilder app)

{
app.UseStaticFiles();

// 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();
}

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 inside ui folder, 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

https://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 NSwag and ASP.NET Core
8/9/2019 • 6 minutes to read • Edit Online

By Christoph Nienaber, Rico Suter, and Dave Brock

View or download sample code (how to download)
View or download sample code (how to download)
NSwag offers the following capabilities:
The ability to utilize the Swagger UI and Swagger generator.
Flexible code generation capabilities.
With NSwag, you don't need an existing API—you can use third-party APIs that incorporate Swagger and generate
a client implementation. NSwag allows you to expedite the development cycle and easily adapt to API changes.

Register the NSwag middleware

Register the NSwag middleware 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 middleware, install the NSwag.AspNetCore NuGet package. This package
contains the middleware to generate and serve the Swagger specification, Swagger UI (v2 and v3), and ReDoc UI.
Use one of the following approaches to install the NSwag NuGet package:
Visual Studio
Visual Studio for Mac
.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

Add and configure Swagger in your ASP.NET Core app by performing the following steps:
 In the Startup.ConfigureServices method, register the required Swagger services:

public void ConfigureServices(IServiceCollection services)

{
services.AddDbContext<TodoContext>(opt =>
opt.UseInMemoryDatabase("TodoList"));
services.AddMvc();

// Register the Swagger services

services.AddSwaggerDocument();
}

In the Startup.Configure method, enable the middleware for serving the generated Swagger specification and
the Swagger UI:

public void Configure(IApplicationBuilder app)

{
app.UseStaticFiles();

// Register the Swagger generator and the Swagger UI middlewares

app.UseOpenApi();
app.UseSwaggerUi3();

app.UseMvc();
}

Launch the app. Navigate to:

http://localhost:<port>/swagger to view the Swagger UI.
http://localhost:<port>/swagger/v1/swagger.json to view the Swagger specification.

Code generation
You can take advantage of NSwag's code generation capabilities by choosing one of the following options:
NSwagStudio – a Windows desktop app for generating API client code in C# or TypeScript.
The NSwag.CodeGeneration.CSharp or NSwag.CodeGeneration.TypeScript NuGet packages for code
generation inside your project.
NSwag from the command line.
The NSwag.MSBuild NuGet package.
The Unchase OpenAPI (Swagger) Connected Service – a Visual Studio Connected Service for generating API
client code in C# or TypeScript. Also generates C# controllers for OpenAPI services with NSwag.
Generate code with NSwagStudio
Install NSwagStudio by following the instructions at the NSwagStudio GitHub repository.
Launch NSwagStudio and enter the swagger.json file URL in the Swagger Specification URL text box. For
example, http://localhost:44354/swagger/v1/swagger.json.
Click the Create local Copy button to generate a JSON representation of your Swagger specification.
In the Outputs area, click the CSharp Client check box. Depending on your project, you can also choose
TypeScript Client or CSharp Web API Controller. If you select CSharp Web API Controller, a service
specification rebuilds the service, serving as a reverse generation.
Click Generate Outputs to produce a complete C# client implementation of the TodoApi.NSwag project. To
see the generated client code, click the CSharp Client tab:
 //----------------------
// <auto-generated>
// Generated using the NSwag toolchain v12.0.9.0 (NJsonSchema v9.13.10.0 (Newtonsoft.Json v11.0.0.0))
(http://NSwag.org)
// </auto-generated>
//----------------------

namespace MyNamespace
{
#pragma warning disable

[System.CodeDom.Compiler.GeneratedCode("NSwag", "12.0.9.0 (NJsonSchema v9.13.10.0 (Newtonsoft.Json

v11.0.0.0))")]
public partial class TodoClient
{
private string _baseUrl = "https://localhost:44354";
private System.Net.Http.HttpClient _httpClient;
private System.Lazy<Newtonsoft.Json.JsonSerializerSettings> _settings;

public TodoClient(System.Net.Http.HttpClient httpClient)

{
_httpClient = httpClient;
_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 selections in the Settings 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 the client project that will consume the API.
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 via the API.

var createdTodo = await todoClient.CreateAsync(new TodoItem());

// Get a single to-do by ID

var foundTodo = await todoClient.GetByIdAsync(1);

Customize API documentation

Swagger provides options for documenting the object model to ease consumption of the web API.
API info and description
In the Startup.ConfigureServices method, a configuration action passed to the AddSwaggerDocument method adds
information such as the author, license, and description:

services.AddSwaggerDocument(config =>
{
config.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.OpenApiContact
{
Name = "Shayne Boyer",
Email = string.Empty,
Url = "https://twitter.com/spboyer"
};
document.Info.License = new NSwag.OpenApiLicense
{
Name = "Use under LICX",
Url = "https://example.com/license"
};
};
});

The Swagger UI displays the version's information:

XML comments
To enable XML comments, perform the following steps:
Visual Studio
Visual Studio for Mac
.NET Core CLI
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
Because NSwag uses Reflection, and the recommended return type for web API actions is IActionResult, it can't
infer what your action is doing and what it returns.
Consider the following example:

[HttpPost]
public IActionResult Create([FromBody] TodoItem item)
{
if (item == null)
{
return BadRequest();
}

_context.TodoItems.Add(item);
_context.SaveChanges();

return CreatedAtRoute("GetTodo", new { id = item.Id }, item);

}

The preceding action returns IActionResult , but inside the action it's returning either CreatedAtRoute or
BadRequest. Use data annotations 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

Because NSwag uses Reflection, and the recommended return type for web API actions is ActionResult<T>, it can
only infer the return type defined by T . You can't automatically infer other possible return types.
Consider the following example:

[HttpPost]
public ActionResult<TodoItem> Create(TodoItem item)
{
_context.TodoItems.Add(item);
_context.SaveChanges();

return CreatedAtRoute("GetTodo", new { id = item.Id }, item);

}

The preceding action returns ActionResult<T> . Inside the action, it's returning CreatedAtRoute. Since the controller
is decorated with the [ApiController] attribute, a BadRequest response is possible, too. For more information, see
Automatic HTTP 400 responses. Use data annotations 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
In ASP.NET Core 2.2 or later, you can use conventions instead of explicitly decorating individual actions with
[ProducesResponseType] . For more information, see Use web API conventions.

The Swagger generator can now accurately describe this action, and generated clients know what they receive
when calling the endpoint. As a recommendation, decorate all actions with these attributes.
For guidelines on what HTTP responses your API actions should return, see the RFC 7231 specification.
 Controller action return types in ASP.NET Core Web
API
6/3/2019 • 5 minutes to read • Edit Online

By Scott Addie
View or download sample code (how to download)
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(typeof(Product), StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
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(typeof(Product), StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> CreateAsync([FromBody] Product product)
{
if (product.Description.Contains("XYZ Widget"))
{
return BadRequest();
}

await _repository.AddProductAsync(product);

return CreatedAtAction(nameof(GetById), new { id = product.Id }, product);

}

In the preceding code:

A 400 status code (BadRequest) is returned by the ASP.NET Core runtime when the product description
contains "XYZ Widget".
A 201 status code is generated by the CreatedAtAction method when a product is created. In this code path,
the Product object is returned.

For example, the following model indicates that requests must include the Name and Description properties.
Therefore, failure to provide Name and Description in the request causes model validation to fail.

public class Product

{
public int Id { get; set; }

[Required]
public string Name { get; set; }

[Required]
public string Description { get; set; }
}

If the [ApiController] attribute in ASP.NET Core 2.1 or later is applied, model validation errors result in a 400
status code. For more information, see Automatic HTTP 400 responses.
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}")]
[ProducesResponseType(StatusCodes.Status404NotFound)]
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]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<ActionResult<Product>> CreateAsync(Product product)
{
if (product.Description.Contains("XYZ Widget"))
{
return BadRequest();
}

await _repository.AddProductAsync(product);

return CreatedAtAction(nameof(GetById), new { id = product.Id }, product);

}

In the preceding code:

A 400 status code (BadRequest) is returned by the ASP.NET Core runtime when:
The [ApiController] attribute has been applied and model validation fails.
The product description contains "XYZ Widget".
A 201 status code is generated by the CreatedAtAction method when a product is created. In this code path,
the Product object 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.

Additional resources
Handle requests with controllers in ASP.NET Core MVC
Model validation in ASP.NET Core MVC
ASP.NET Core Web API help pages with Swagger / OpenAPI
 Format response data in ASP.NET Core Web API
7/11/2019 • 9 minutes to read • Edit Online

By Steve Smith
ASP.NET Core MVC has built-in support for formatting response data, using fixed formats or in response to client
specifications.
View or download sample code (how to download)

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.

services.AddMvc(options =>
{
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.
Configure System.Text.Json-based formatters
Features for the System.Text.Json -based formatters can be configured using
Microsoft.AspNetCore.Mvc.MvcOptions.SerializerOptions .

services.AddMvc(options =>
{
options.SerializerOptions.WriterSettings.Indented = true;
});

Add Newtonsoft.Json-based JSON format support

Prior to ASP.NET Core 3.0, MVC defaulted to using JSON formatters implemented using the Newtonsoft.Json
package. In ASP.NET Core 3.0 or later, the default JSON formatters are based on System.Text.Json . Support for
Newtonsoft.Json -based formatters and features is available by installing the
Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet package and configuring it in Startup.ConfigureServices .

services.AddMvc()
.AddNewtonsoftJson();

Some features may not work well with System.Text.Json -based formatters and require a reference to the
Newtonsoft.Json -based formatters for the ASP.NET Core 3.0 release. Continue using the Newtonsoft.Json -based
formatters if your ASP.NET Core 3.0 or later app:
Uses Newtonsoft.Json attributes (for example, [JsonProperty] or [JsonIgnore] ), customizes the serialization
settings, or relies on features that Newtonsoft.Json provides.
Configures Microsoft.AspNetCore.Mvc.JsonResult.SerializerSettings . Prior to ASP.NET Core 3.0,
JsonResult.SerializerSettings accepts an instance of JsonSerializerSettings that is specific to
Newtonsoft.Json .
Generates OpenAPI documentation.
Add XML format support
To add XML formatting support in ASP.NET Core 2.2 or earlier, install the
Microsoft.AspNetCore.Mvc.Formatters.Xml NuGet package.
XML formatters implemented using System.Xml.Serialization.XmlSerializer can be configured by calling
AddXmlSerializerFormatters in Startup.ConfigureServices :

services.AddMvc()
.AddXmlSerializerFormatters();

Alternatively, XML formatters implemented using System.Runtime.Serialization.DataContractSerializer can be

configured by calling AddXmlDataContractSerializerFormatters in Startup.ConfigureServices :

services.AddMvc()
.AddXmlDataContractSerializerFormatters();

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.

[Produces("application/json")]
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 .

services.AddMvc(options =>
{
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)

 Custom formatters in ASP.NET Core Web API
7/11/2019 • 4 minutes to read • Edit Online

By Tom Dykstra
ASP.NET Core MVC has built-in support for data exchange in web APIs by using JSON or XML. This article
shows how to add support for additional formats by creating custom formatters.
View or download sample code (how to download)

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 and XML ).
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 an input formatter example, see the sample app.

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);
}

For an input formatter example, see the sample app.

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;
}

For an input formatter example, see the sample app.

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 async Task WriteResponseBodyAsync(OutputFormatterWriteContext context, Encoding
selectedEncoding)
{
IServiceProvider serviceProvider = context.HttpContext.RequestServices;
var logger = serviceProvider.GetService(typeof(ILogger<VcardOutputFormatter>)) as ILogger;

var response = context.HttpContext.Response;

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);
}
await 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}");
}

For an input formatter example, see the sample app.

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.

services.AddMvc(options =>
{
options.InputFormatters.Insert(0, new VcardInputFormatter());
options.OutputFormatters.Insert(0, new VcardOutputFormatter());
})
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

Formatters are evaluated in the order you insert them. The first one takes precedence.

Next steps
Plain text formatter sample code on GitHub.
Sample app for this doc, which implements simple vCard input and output formatters. The apps 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
http://localhost:63313/api/contacts/ (when running from Visual Studio) or 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.
 Use web API analyzers
7/3/2019 • 2 minutes to read • Edit Online

ASP.NET Core 2.2 and later includes the Microsoft.AspNetCore.Mvc.Api.Analyzers NuGet package containing
analyzers for web APIs. The analyzers work with controllers annotated with ApiControllerAttribute, while building
on API conventions.

Package installation
Microsoft.AspNetCore.Mvc.Api.Analyzers can be added with one of the following approaches:
Visual Studio
Visual Studio for Mac
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 ApiConventions.csproj file exists.
Execute the following command:

Install-Package Microsoft.AspNetCore.Mvc.Api.Analyzers

From the Manage NuGet Packages dialog:

Right-click the project in Solution Explorer > Manage NuGet Packages.
Set the Package source to "nuget.org".
Enter "Microsoft.AspNetCore.Mvc.Api.Analyzers" in the search box.
Select the "Microsoft.AspNetCore.Mvc.Api.Analyzers" package from the Browse tab and click Install.

Analyzers for API conventions

OpenAPI documents contain status codes and response types that an action may return. In ASP.NET Core MVC,
attributes such as ProducesResponseTypeAttribute and ProducesAttribute are used to document an action.
ASP.NET Core Web API help pages with Swagger / OpenAPI goes into further detail on documenting your API.
One of the analyzers in the package inspects controllers annotated with ApiControllerAttribute and identifies
actions that don't entirely document their responses. Consider the following example:
 // GET api/contacts/{guid}
[HttpGet("{id}", Name = "GetById")]
[ProducesResponseType(typeof(Contact), StatusCodes.Status200OK)]
public IActionResult Get(string id)
{
var contact = _contacts.Get(id);

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

return Ok(contact);
}

The preceding action documents the HTTP 200 success return type but doesn't document the HTTP 404 failure
status code. The analyzer reports the missing documentation for the HTTP 404 status code as a warning. An
option to fix the problem is provided.

Additional resources
Use web API conventions
ASP.NET Core Web API help pages with Swagger / OpenAPI
Create web APIs with ASP.NET Core
 Use web API conventions
6/28/2019 • 3 minutes to read • Edit Online

By Pranav Krishnamoorthy and Scott Addie

ASP.NET Core 2.2 and later includes a way to extract common API documentation and apply it to multiple
actions, controllers, or all controllers within an assembly. Web API conventions are a substitute for decorating
individual actions with [ProducesResponseType].
A convention allows you to:
Define the most common return types and status codes returned from a specific type of action.
Identify actions that deviate from the defined standard.
ASP.NET Core MVC 2.2 and later includes a set of default conventions in
Microsoft.AspNetCore.Mvc.DefaultApiConventions. The conventions are based on the controller
(ValuesController.cs) provided in the ASP.NET Core API project template. If your actions follow the patterns in
the template, you should be successful using the default conventions. If the default conventions don't meet your
needs, see Create web API conventions.
At runtime, Microsoft.AspNetCore.Mvc.ApiExplorer understands conventions. ApiExplorer is MVC's abstraction
to communicate with OpenAPI (also known as Swagger) document generators. Attributes from the applied
convention are associated with an action and are included in the action's OpenAPI documentation. API analyzers
also understand conventions. If your action is unconventional (for example, it returns a status code that isn't
documented by the applied convention), a warning encourages you to document the status code.
View or download sample code (how to download)

Apply web API conventions

Conventions don't compose; each action may be associated with exactly one convention. More specific
conventions take precedence over less specific conventions. The selection is non-deterministic when two or more
conventions of the same priority apply to an action. The following options exist to apply a convention to an action,
from the most specific to the least specific:
1. Microsoft.AspNetCore.Mvc.ApiConventionMethodAttribute — Applies to individual actions and specifies the
convention type and the convention method that applies.
In the following example, the default convention type's
Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put convention method is applied to the Update action:
 // PUT api/contactsconvention/{guid}
[HttpPut("{id}")]
[ApiConventionMethod(typeof(DefaultApiConventions),
nameof(DefaultApiConventions.Put))]
public IActionResult Update(string id, Contact contact)
{
var contactToUpdate = _contacts.Get(id);

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

_contacts.Update(contact);

return NoContent();
}

The Microsoft.AspNetCore.Mvc.DefaultApiConventions.Put convention method applies the following

attributes to the action:

[ProducesDefaultResponseType]
[ProducesResponseType(StatusCodes.Status204NoContent)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]

For more information on [ProducesDefaultResponseType] , see Default Response.

2. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute applied to a controller — Applies the specified
convention type to all actions on the controller. A convention method is decorated with hints that
determine the actions to which the convention method applies. For more information on hints, see Create
web API conventions).
In the following example, the default set of conventions is applied to all actions in
ContactsConventionController:

[ApiController]
[ApiConventionType(typeof(DefaultApiConventions))]
[Route("api/[controller]")]
public class ContactsConventionController : ControllerBase
{

3. Microsoft.AspNetCore.Mvc.ApiConventionTypeAttribute applied to an assembly — Applies the specified

convention type to all controllers in the current assembly. As a recommendation, apply assembly-level
attributes in the Startup.cs file.
In the following example, the default set of conventions is applied to all controllers in the assembly:

[assembly: ApiConventionType(typeof(DefaultApiConventions))]
namespace ApiConventions
{
public class Startup
{

Create web API conventions

If the default API conventions don't meet your needs, create your own conventions. A convention is:
 A static type with methods.
Capable of defining response types and naming requirements on actions.
Response types
These methods are annotated with [ProducesResponseType] or [ProducesDefaultResponseType] attributes. For
example:

public static class MyAppConventions

{
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public static void Find(int id)
{
}
}

If more specific metadata attributes are absent, applying this convention to an assembly enforces that:
The convention method applies to any action named Find .
A parameter named id is present on the Find action.
Naming requirements
The [ApiConventionNameMatch] and [ApiConventionTypeMatch] attributes can be applied to the convention method
that determines the actions to which they apply. For example:

[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[ApiConventionNameMatch(ApiConventionNameMatchBehavior.Prefix)]
public static void Find(
[ApiConventionNameMatch(ApiConventionNameMatchBehavior.Suffix)]
int id)
{ }

In the preceding example:

The Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Prefix option applied to the method
indicates that the convention matches any action prefixed with "Find". Examples of matching actions include
Find , FindPet , and FindById .
The Microsoft.AspNetCore.Mvc.ApiExplorer.ApiConventionNameMatchBehavior.Suffix applied to the parameter
indicates that the convention matches methods with exactly one parameter ending in the suffix identifier.
Examples include parameters such as id or petId . ApiConventionTypeMatch can be similarly applied to types
to constrain the parameter type. A params[] argument indicates remaining parameters that don't need to be
explicitly matched.

Additional resources
Use web API analyzers
ASP.NET Core Web API help pages with Swagger / OpenAPI
 Test web APIs with the HTTP REPL
8/7/2019 • 17 minutes to read • Edit Online

By Scott Addie
The HTTP Read-Eval-Print Loop (REPL ) is:
A lightweight, cross-platform command-line tool that's supported everywhere .NET Core is supported.
Used for making HTTP requests to test ASP.NET Core web APIs (and non-ASP.NET Core web APIs) and view
their results.
Capable of testing web APIs hosted in any environment, including localhost and Azure App Service.
The following HTTP verbs are supported:
DELETE
GET
HEAD
OPTIONS
PATCH
POST
PUT
To follow along, view or download the sample ASP.NET Core web API (how to download).

Prerequisites
.NET Core 2.1 SDK or later

Installation
To install the HTTP REPL, run the following command:

dotnet tool install -g Microsoft.dotnet-httprepl --version "3.0.0-*"

A .NET Core Global Tool is installed from the Microsoft.dotnet-httprepl NuGet package.

Usage
After successful installation of the tool, run the following command to start the HTTP REPL:

dotnet httprepl

To view the available HTTP REPL commands, run one of the following commands:

dotnet httprepl -h

dotnet httprepl --help

The following output is displayed:

Usage:
dotnet httprepl [<BASE_ADDRESS>] [options]

Arguments:
<BASE_ADDRESS> - The initial base address for the REPL.

Options:
-h|--help - Show help information.

Once the REPL starts, these commands are valid:

HTTP Commands:
Use these commands to execute requests against your application.

GET get - Issues a GET request

POST post - Issues a POST request
PUT put - Issues a PUT request
DELETE delete - Issues a DELETE request
PATCH patch - Issues a PATCH request
HEAD head - Issues a HEAD request
OPTIONS options - Issues a OPTIONS request

set header Sets or clears a header for all requests. e.g. `set header content-type application/json`

Navigation Commands:
The REPL allows you to navigate your URL space and focus on specific APIs that you are working on.

set base Set the base URI. e.g. `set base http://locahost:5000`
set swagger Sets the swagger document to use for information about the current server
ls Show all endpoints for the current path
cd Append the given directory to the currently selected path, or move up a path when using `cd ..`

Shell Commands:
Use these commands to interact with the REPL shell.

clear Removes all text from the shell

echo [on/off] Turns request echoing on or off, show the request that was made when using request commands
exit Exit the shell

REPL Customization Commands:

Use these commands to customize the REPL behavior.

pref [get/set] Allows viewing or changing preferences, e.g. 'pref set editor.command.default 'C:\\Program
Files\\Microsoft VS Code\\Code.exe'`
run Runs the script at the given path. A script is a set of commands that can be typed with one
command per line
ui Displays the Swagger UI page, if available, in the default browser

Use `help <COMMAND>` for more detail on an individual command. e.g. `help get`.
For detailed tool info, see https://aka.ms/http-repl-doc.

The HTTP REPL offers command completion. Pressing the Tab key iterates through the list of commands that
complete the characters or API endpoint that you typed. The following sections outline the available CLI
commands.

Connect to the web API

Connect to a web API by running the following command:

dotnet httprepl <BASE URI>

<BASE URI> is the base URI for the web API. For example:

dotnet httprepl https://localhost:5001

Alternatively, run the following command at any time while the HTTP REPL is running:

set base <BASE URI>

For example:

(Disconnected)~ set base https://localhost:5001

Point to the Swagger document for the web API

To properly inspect the web API, set the relative URI to the Swagger document for the web API. Run the following
command:

set swagger <RELATIVE URI>

For example:

https://localhost:5001/~ set swagger /swagger/v1/swagger.json

Navigate the web API

View available endpoints
To list the different endpoints (controllers) at the current path of the web API address, run the ls or dir
command:

https://localhot:5001/~ ls

The following output format is displayed:

. []
Fruits [get|post]
People [get|post]

https://localhost:5001/~

The preceding output indicates that there are two controllers available: Fruits and People . Both controllers
support parameterless HTTP GET and POST operations.
Navigating into a specific controller reveals more detail. For example, the following command's output shows the
Fruits controller also supports HTTP GET, PUT, and DELETE operations. Each of these operations expects an id
parameter in the route:
 https://localhost:5001/fruits~ ls
. [get|post]
.. []
{id} [get|put|delete]

https://localhost:5001/fruits~

Alternatively, run the ui command to open the web API's Swagger UI page in a browser. For example:

https://localhost:5001/~ ui

Navigate to an endpoint
To navigate to a different endpoint on the web API, run the cd command:

https://localhost:5001/~ cd people

The path following the cd command is case insensitive. The following output format is displayed:

/people [get|post]

https://localhost:5001/people~

Customize the HTTP REPL

The HTTP REPL's default colors can be customized. Additionally, a default text editor can be defined. The HTTP
REPL preferences are persisted across the current session and are honored in future sessions. Once modified, the
preferences are stored in the following file:
Linux
macOS
Windows
%HOME%/.httpreplprefs
The .httpreplprefs file is loaded on startup and not monitored for changes at runtime. Manual modifications to the
file take effect only after restarting the tool.
View the settings
To view the available settings, run the pref get command. For example:

https://localhost:5001/~ pref get

The preceding command displays the available key-value pairs:

colors.json=Green
colors.json.arrayBrace=BoldCyan
colors.json.comma=BoldYellow
colors.json.name=BoldMagenta
colors.json.nameSeparator=BoldWhite
colors.json.objectBrace=Cyan
colors.protocol=BoldGreen
colors.status=BoldYellow
Set color preferences
Response colorization is currently supported for JSON only. To customize the default HTTP REPL tool coloring,
locate the key corresponding to the color to be changed. For instructions on how to find the keys, see the View the
settings section. For example, change the colors.json key value from Green to White as follows:

https://localhost:5001/people~ pref set colors.json White

Only the allowed colors may be used. Subsequent HTTP requests display output with the new coloring.
When specific color keys aren't set, more generic keys are considered. To demonstrate this fallback behavior,
consider the following example:
If colors.json.name doesn't have a value, colors.json.string is used.
If colors.json.string doesn't have a value, colors.json.literal is used.
If colors.json.literal doesn't have a value, colors.json is used.
If colors.json doesn't have a value, the command shell's default text color ( AllowedColors.None ) is used.

Set indentation size

Response indentation size customization is currently supported for JSON only. The default size is two spaces. For
example:

[
{
"id": 1,
"name": "Apple"
},
{
"id": 2,
"name": "Orange"
},
{
"id": 3,
"name": "Strawberry"
}
]

To change the default size, set the formatting.json.indentSize key. For example, to always use four spaces:

pref set formatting.json.indentSize 4

Subsequent responses honor the setting of four spaces:

[
{
"id": 1,
"name": "Apple"
},
{
"id": 2,
"name": "Orange"
},
{
"id": 3,
"name": "Strawberry"
}
]
Set indentation size
Response indentation size customization is currently supported for JSON only. The default size is two spaces. For
example:

[
{
"id": 1,
"name": "Apple"
},
{
"id": 2,
"name": "Orange"
},
{
"id": 3,
"name": "Strawberry"
}
]

To change the default size, set the formatting.json.indentSize key. For example, to always use four spaces:

pref set formatting.json.indentSize 4

Subsequent responses honor the setting of four spaces:

[
{
"id": 1,
"name": "Apple"
},
{
"id": 2,
"name": "Orange"
},
{
"id": 3,
"name": "Strawberry"
}
]

Set the default text editor

By default, the HTTP REPL has no text editor configured for use. To test web API methods requiring an HTTP
request body, a default text editor must be set. The HTTP REPL tool launches the configured text editor for the sole
purpose of composing the request body. Run the following command to set your preferred text editor as the
default:

pref set editor.command.default "<EXECUTABLE>"

In the preceding command, <EXECUTABLE> is the full path to the text editor's executable file. For example, run the
following command to set Visual Studio Code as the default text editor:
Linux
macOS
Windows
 pref set editor.command.default "/usr/bin/code"

To launch the default text editor with specific CLI arguments, set the editor.command.default.arguments key. For
example, assume Visual Studio Code is the default text editor and that you always want the HTTP REPL to open
Visual Studio Code in a new session with extensions disabled. Run the following command:

pref set editor.command.default.arguments "--disable-extensions --new-window"

Test HTTP GET requests

Synopsis

get <PARAMETER> [-F|--no-formatting] [-h|--header] [--response] [--response:body] [--response:headers] [-s|--

streaming]

Arguments
PARAMETER

The route parameter, if any, expected by the associated controller action method.
Options
The following options are available for the get command:
-F|--no-formatting

A flag whose presence suppresses HTTP response formatting.

-h|--header

Sets an HTTP request header. The following two value formats are supported:
{header}={value}
{header}:{value}

--response

Specifies a file to which the entire HTTP response (including headers and body) should be written. For
example, --response "C:\response.txt" . The file is created if it doesn't exist.
--response:body

Specifies a file to which the HTTP response body should be written. For example,
--response:body "C:\response.json" . The file is created if it doesn't exist.

--response:headers

Specifies a file to which the HTTP response headers should be written. For example,
--response:headers "C:\response.txt" . The file is created if it doesn't exist.

-s|--streaming

A flag whose presence enables streaming of the HTTP response.

Example
To issue an HTTP GET request:
1. Run the get command on an endpoint that supports it:
 https://localhost:5001/people~ get

The preceding command displays the following output format:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 21 Jun 2019 03:38:45 GMT
Server: Kestrel
Transfer-Encoding: chunked

[
{
"id": 1,
"name": "Scott Hunter"
},
{
"id": 2,
"name": "Scott Hanselman"
},
{
"id": 3,
"name": "Scott Guthrie"
}
]

https://localhost:5001/people~

2. Retrieve a specific record by passing a parameter to the get command:

https://localhost:5001/people~ get 2

The preceding command displays the following output format:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 21 Jun 2019 06:17:57 GMT
Server: Kestrel
Transfer-Encoding: chunked

[
{
"id": 2,
"name": "Scott Hanselman"
}
]

https://localhost:5001/people~

Test HTTP POST requests

Synopsis

post <PARAMETER> [-c|--content] [-f|--file] [-h|--header] [--no-body] [-F|--no-formatting] [--response] [--

response:body] [--response:headers] [-s|--streaming]

Arguments
PARAMETER

The route parameter, if any, expected by the associated controller action method.
Options
-F|--no-formatting

A flag whose presence suppresses HTTP response formatting.

-h|--header

Sets an HTTP request header. The following two value formats are supported:
{header}={value}
{header}:{value}
--response

Specifies a file to which the entire HTTP response (including headers and body) should be written. For
example, --response "C:\response.txt" . The file is created if it doesn't exist.
--response:body

Specifies a file to which the HTTP response body should be written. For example,
--response:body "C:\response.json" . The file is created if it doesn't exist.

--response:headers

Specifies a file to which the HTTP response headers should be written. For example,
--response:headers "C:\response.txt" . The file is created if it doesn't exist.

-s|--streaming

A flag whose presence enables streaming of the HTTP response.

-c|--content

Provides an inline HTTP request body. For example, -c "{ 'id': 2, 'name': 'Cherry' }" .
-f|--file

Provides a path to a file containing the HTTP request body. For example, -f "C:\request.json" .
--no-body

Indicates that no HTTP request body is needed.

Example
To issue an HTTP POST request:
1. Run the post command on an endpoint that supports it:

https://localhost:5001/people~ post -h Content-Type=application/json

In the preceding command, the Content-Type HTTP request header is set to indicate a request body media
type of JSON. The default text editor opens a .tmp file with a JSON template representing the HTTP request
body. For example:
 {
"id": 0,
"name": ""
}

TIP
To set the default text editor, see the Set the default text editor section.

2. Modify the JSON template to satisfy model validation requirements:

{
"id": 0,
"name": "Scott Addie"
}

3. Save the .tmp file, and close the text editor. The following output appears in the command shell:

HTTP/1.1 201 Created

Content-Type: application/json; charset=utf-8
Date: Thu, 27 Jun 2019 21:24:18 GMT
Location: https://localhost:5001/people/4
Server: Kestrel
Transfer-Encoding: chunked

{
"id": 4,
"name": "Scott Addie"
}

https://localhost:5001/people~

Test HTTP PUT requests

Synopsis

put <PARAMETER> [-c|--content] [-f|--file] [-h|--header] [--no-body] [-F|--no-formatting] [--response] [--

response:body] [--response:headers] [-s|--streaming]

Arguments
PARAMETER

The route parameter, if any, expected by the associated controller action method.
Options
-F|--no-formatting

A flag whose presence suppresses HTTP response formatting.

-h|--header

Sets an HTTP request header. The following two value formats are supported:
{header}={value}
{header}:{value}
 --response

Specifies a file to which the entire HTTP response (including headers and body) should be written. For
example, --response "C:\response.txt" . The file is created if it doesn't exist.
--response:body

Specifies a file to which the HTTP response body should be written. For example,
--response:body "C:\response.json" . The file is created if it doesn't exist.

--response:headers

Specifies a file to which the HTTP response headers should be written. For example,
--response:headers "C:\response.txt" . The file is created if it doesn't exist.

-s|--streaming

A flag whose presence enables streaming of the HTTP response.

-c|--content

Provides an inline HTTP request body. For example, -c "{ 'id': 2, 'name': 'Cherry' }" .
-f|--file

Provides a path to a file containing the HTTP request body. For example, -f "C:\request.json" .
--no-body

Indicates that no HTTP request body is needed.

Example
To issue an HTTP PUT request:
1. Optional: Run the get command to view the data before modifying it:

https://localhost:5001/fruits~ get
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Sat, 22 Jun 2019 00:07:32 GMT
Server: Kestrel
Transfer-Encoding: chunked

[
{
"id": 1,
"data": "Apple"
},
{
"id": 2,
"data": "Orange"
},
{
"id": 3,
"data": "Strawberry"
}
]

2. Run the put command on an endpoint that supports it:

 https://localhost:5001/fruits~ put 2 -h Content-Type=application/json

In the preceding command, the Content-Type HTTP request header is set to indicate a request body media
type of JSON. The default text editor opens a .tmp file with a JSON template representing the HTTP request
body. For example:

{
"id": 0,
"name": ""
}

TIP
To set the default text editor, see the Set the default text editor section.

3. Modify the JSON template to satisfy model validation requirements:

{
"id": 2,
"name": "Cherry"
}

4. Save the .tmp file, and close the text editor. The following output appears in the command shell:

[main 2019-06-28T17:27:01.805Z] update#setState idle

HTTP/1.1 204 No Content
Date: Fri, 28 Jun 2019 17:28:21 GMT
Server: Kestrel

5. Optional: Issue a get command to see the modifications. For example, if you typed "Cherry" in the text
editor, a get returns the following:

https://localhost:5001/fruits~ get
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Sat, 22 Jun 2019 00:08:20 GMT
Server: Kestrel
Transfer-Encoding: chunked

[
{
"id": 1,
"data": "Apple"
},
{
"id": 2,
"data": "Cherry"
},
{
"id": 3,
"data": "Strawberry"
}
]

https://localhost:5001/fruits~
Test HTTP DELETE requests
Synopsis

delete <PARAMETER> [-F|--no-formatting] [-h|--header] [--response] [--response:body] [--response:headers] [-s|-

-streaming]

Arguments
PARAMETER

The route parameter, if any, expected by the associated controller action method.
Options
-F|--no-formatting

A flag whose presence suppresses HTTP response formatting.

-h|--header

Sets an HTTP request header. The following two value formats are supported:
{header}={value}
{header}:{value}
--response

Specifies a file to which the entire HTTP response (including headers and body) should be written. For
example, --response "C:\response.txt" . The file is created if it doesn't exist.
--response:body

Specifies a file to which the HTTP response body should be written. For example,
--response:body "C:\response.json" . The file is created if it doesn't exist.

--response:headers

Specifies a file to which the HTTP response headers should be written. For example,
--response:headers "C:\response.txt" . The file is created if it doesn't exist.

-s|--streaming

A flag whose presence enables streaming of the HTTP response.

Example
To issue an HTTP DELETE request:
1. Optional: Run the get command to view the data before modifying it:
 https://localhost:5001/fruits~ get
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Sat, 22 Jun 2019 00:07:32 GMT
Server: Kestrel
Transfer-Encoding: chunked

[
{
"id": 1,
"data": "Apple"
},
{
"id": 2,
"data": "Orange"
},
{
"id": 3,
"data": "Strawberry"
}
]

2. Run the delete command on an endpoint that supports it:

https://localhost:5001/fruits~ delete 2

The preceding command displays the following output format:

HTTP/1.1 204 No Content

Date: Fri, 28 Jun 2019 17:36:42 GMT
Server: Kestrel

3. Optional: Issue a get command to see the modifications. In this example, a get returns the following:

https://localhost:5001/fruits~ get
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Sat, 22 Jun 2019 00:16:30 GMT
Server: Kestrel
Transfer-Encoding: chunked

[
{
"id": 1,
"data": "Apple"
},
{
"id": 3,
"data": "Strawberry"
}
]

https://localhost:5001/fruits~

Test HTTP PATCH requests

Synopsis
 patch <PARAMETER> [-c|--content] [-f|--file] [-h|--header] [--no-body] [-F|--no-formatting] [--response] [--
response:body] [--response:headers] [-s|--streaming]

Arguments
PARAMETER

The route parameter, if any, expected by the associated controller action method.
Options
-F|--no-formatting

A flag whose presence suppresses HTTP response formatting.

-h|--header

Sets an HTTP request header. The following two value formats are supported:
{header}={value}
{header}:{value}
--response

Specifies a file to which the entire HTTP response (including headers and body) should be written. For
example, --response "C:\response.txt" . The file is created if it doesn't exist.
--response:body

Specifies a file to which the HTTP response body should be written. For example,
--response:body "C:\response.json" . The file is created if it doesn't exist.

--response:headers

Specifies a file to which the HTTP response headers should be written. For example,
--response:headers "C:\response.txt" . The file is created if it doesn't exist.

-s|--streaming

A flag whose presence enables streaming of the HTTP response.

-c|--content

Provides an inline HTTP request body. For example, -c "{ 'id': 2, 'name': 'Cherry' }" .
-f|--file

Provides a path to a file containing the HTTP request body. For example, -f "C:\request.json" .
--no-body

Indicates that no HTTP request body is needed.

Test HTTP HEAD requests

Synopsis

head <PARAMETER> [-F|--no-formatting] [-h|--header] [--response] [--response:body] [--response:headers] [-s|--

streaming]

Arguments
PARAMETER

The route parameter, if any, expected by the associated controller action method.
Options
-F|--no-formatting

A flag whose presence suppresses HTTP response formatting.

-h|--header

Sets an HTTP request header. The following two value formats are supported:
{header}={value}
{header}:{value}
--response

Specifies a file to which the entire HTTP response (including headers and body) should be written. For
example, --response "C:\response.txt" . The file is created if it doesn't exist.
--response:body

Specifies a file to which the HTTP response body should be written. For example,
--response:body "C:\response.json" . The file is created if it doesn't exist.

--response:headers

Specifies a file to which the HTTP response headers should be written. For example,
--response:headers "C:\response.txt" . The file is created if it doesn't exist.

-s|--streaming

A flag whose presence enables streaming of the HTTP response.

Test HTTP OPTIONS requests

Synopsis

options <PARAMETER> [-F|--no-formatting] [-h|--header] [--response] [--response:body] [--response:headers] [-

s|--streaming]

Arguments
PARAMETER

The route parameter, if any, expected by the associated controller action method.
Options
-F|--no-formatting

A flag whose presence suppresses HTTP response formatting.

-h|--header

Sets an HTTP request header. The following two value formats are supported:
{header}={value}
{header}:{value}
--response
 Specifies a file to which the entire HTTP response (including headers and body) should be written. For
example, --response "C:\response.txt" . The file is created if it doesn't exist.
--response:body

Specifies a file to which the HTTP response body should be written. For example,
--response:body "C:\response.json" . The file is created if it doesn't exist.

--response:headers

Specifies a file to which the HTTP response headers should be written. For example,
--response:headers "C:\response.txt" . The file is created if it doesn't exist.

-s|--streaming

A flag whose presence enables streaming of the HTTP response.

Set HTTP request headers

To set an HTTP request header, use one of the following approaches:
1. Set inline with the HTTP request. For example:

https://localhost:5001/people~ post -h Content-Type=application/json

With the preceding approach, each distinct HTTP request header requires its own -h option.
1. Set before sending the HTTP request. For example:

https://localhost:5001/people~ set header Content-Type application/json

When setting the header before sending a request, the header remains set for the duration of the command shell
session. To clear the header, provide an empty value. For example:

https://localhost:5001/people~ set header Content-Type

Toggle HTTP request display

By default, display of the HTTP request being sent is suppressed. It's possible to change the corresponding setting
for the duration of the command shell session.
Enable request display
View the HTTP request being sent by running the echo on command. For example:

https://localhost:5001/people~ echo on
Request echoing is on

Subsequent HTTP requests in the current session display the request headers. For example:
 https://localhost:5001/people~ post

[main 2019-06-28T18:50:11.930Z] update#setState idle

Request to https://localhost:5001...

POST /people HTTP/1.1

Content-Length: 41
Content-Type: application/json
User-Agent: HTTP-REPL

{
"id": 0,
"name": "Scott Addie"
}

Response from https://localhost:5001...

HTTP/1.1 201 Created

Content-Type: application/json; charset=utf-8
Date: Fri, 28 Jun 2019 18:50:21 GMT
Location: https://localhost:5001/people/4
Server: Kestrel
Transfer-Encoding: chunked

{
"id": 4,
"name": "Scott Addie"
}

https://localhost:5001/people~

Disable request display

Suppress display of the HTTP request being sent by running the echo off command. For example:

https://localhost:5001/people~ echo off

Request echoing is off

Run a script
If you frequently execute the same set of HTTP REPL commands, consider storing them in a text file. Commands in
the file take the same form as those executed manually on the command line. The commands can be executed in a
batched fashion using the run command. For example:
1. Create a text file containing a set of newline-delimited commands. To illustrate, consider a people-script.txt
file containing the following commands:

set base https://localhost:5001

ls
cd People
ls
get 1

2. Execute the run command, passing in the text file's path. For example:

https://localhost:5001/~ run C:\http-repl-scripts\people-script.txt

The following output appears:

 https://localhost:5001/~ set base https://localhost:5001
Using swagger metadata from https://localhost:5001/swagger/v1/swagger.json

https://localhost:5001/~ ls
. []
Fruits [get|post]
People [get|post]

https://localhost:5001/~ cd People
/People [get|post]

https://localhost:5001/People~ ls
. [get|post]
.. []
{id} [get|put|delete]

https://localhost:5001/People~ get 1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 12 Jul 2019 19:20:10 GMT
Server: Kestrel
Transfer-Encoding: chunked

{
"id": 1,
"name": "Scott Hunter"
}

https://localhost:5001/People~

Clear the output

To remove all output written to the command shell by the HTTP REPL tool, run the clear or cls command. To
illustrate, imagine the command shell contains the following output:

dotnet httprepl https://localhost:5001

(Disconnected)~ set base "https://localhost:5001"
Using swagger metadata from https://localhost:5001/swagger/v1/swagger.json

https://localhost:5001/~ ls
. []
Fruits [get|post]
People [get|post]

https://localhost:5001/~

Run the following command to clear the output:

https://localhost:5001/~ clear

After running the preceding command, the command shell contains only the following output:

https://localhost:5001/~

Additional resources
REST API requests
HTTP REPL GitHub repository
 Introduction to ASP.NET Core SignalR
4/26/2019 • 2 minutes to read • Edit Online

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.

Additional resources
Get started with SignalR for ASP.NET Core
Supported Platforms
Hubs
JavaScript client
 ASP.NET Core SignalR supported platforms
4/26/2019 • 2 minutes to read • Edit Online

Server system requirements

SignalR for ASP.NET Core supports any server platform that ASP.NET Core supports.

JavaScript client
The JavaScript client runs on NodeJS 8 and later versions and the following browsers:

BROWSER VERSION

Microsoft Edge current

Mozilla Firefox current

Google Chrome; includes Android current

Safari; includes iOS current

Microsoft Internet Explorer 11

.NET client
The .NET client runs on any platform supported by ASP.NET Core. For example, Xamarin developers can use
SignalR for building Android apps using Xamarin.Android 8.4.0.1 and later and iOS apps using Xamarin.iOS
11.14.0.4 and later.
If the server runs IIS, the WebSockets transport requires IIS 8.0 or later on Windows Server 2012 or later. Other
transports are supported on all platforms.

Java client
The Java client supports Java 8 and later versions.

Unsupported clients
The following clients are available but are experimental or unofficial. They aren't currently supported and may
never be.
C++ client
Swift client
 Tutorial: Get started with ASP.NET Core SignalR
7/15/2019 • 13 minutes to read • Edit Online

This tutorial teaches the basics of building a real-time app using SignalR. You learn how to:
Create a web project.
Add the SignalR client library.
Create a SignalR hub.
Configure the project to use SignalR.
Add code that sends messages from any client to all connected clients.
At the end, you'll have a working chat app:

Prerequisites
Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 3.0 Preview

Create a web app project

Visual Studio
Visual Studio Code
Visual Studio for Mac
From the menu, select File > New Project.
In the Create a new project dialog, select ASP.NET Core Web Application, and then select Next.
In the Configure your new project dialog, name the project SignalRChat, and then select Create.
In the Create a new ASP.NET Core Web Application dialog, select .NET Core and ASP.NET Core 3.0.
 Select Web Application to create a project that uses Razor Pages, and then select Create.

Add the SignalR client library

The SignalR server library is included in the ASP.NET Core 3.0 shared framework. 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 (CDN )) that can deliver anything found in npm, the
Node.js package manager.
Visual Studio
Visual Studio Code
Visual Studio for Mac
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@next .
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 a 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;
using System.Threading.Tasks;

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 a connected client to send a message to all clients. JavaScript
client code that calls the method is shown later in the tutorial. SignalR code is asynchronous to provide
maximum scalability.

Configure 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.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using SignalRChat.Hubs;

namespace SignalRChat
{
public class Startup
{
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.
public void ConfigureServices(IServiceCollection services)
{
services.Configure<CookiePolicyOptions>(options =>
{
// This lambda determines whether user consent for non-essential cookies is needed for
a given request.
options.CheckConsentNeeded = context => true;
});

services.AddRazorPages();
services.AddSignalR();
}

// This method gets called by the runtime. Use this method to configure the HTTP request
pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
// The default HSTS value is 30 days. You may want to change this for production
scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}

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

app.UseCookiePolicy();
app.UseRouting();

app.UseAuthorization();

app.UseEndpoints(endpoints =>
{
endpoints.MapRazorPages();
endpoints.MapHub<ChatHub>("/chatHub");
});
}
}
}
 These changes add SignalR to the ASP.NET Core dependency injection and routing systems.

Add SignalR client code

Replace the content in Pages\Index.cshtml with the following code:

@page
<div class="container">
<div class="row">&nbsp;</div>
<div class="row">
<div class="col-2">User</div>
<div class="col-4"><input type="text" id="userInput" /></div>
</div>
<div class="row">
<div class="col-2">Message</div>
<div class="col-4"><input type="text" id="messageInput" /></div>
</div>
<div class="row">&nbsp;</div>
<div class="row">
<div class="col-6">
<input type="button" id="sendButton" value="Send Message" />
</div>
</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();

//Disable send button until connection is established

document.getElementById("sendButton").disabled = true;

connection.on("ReceiveMessage", function (user, message) {

var msg = message.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
var encodedMsg = user + " says " + msg;
var li = document.createElement("li");
li.textContent = encodedMsg;
document.getElementById("messagesList").appendChild(li);
});

connection.start().then(function () {
document.getElementById("sendButton").disabled = false;
}).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) {
return console.error(err.toString());
});
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
Visual Studio for Mac
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 Message 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.

If you get the error ERR_SPDY_INADEQUATE_TRANSPORT_SECURITY in Chrome or

NS_ERROR_NET_INADEQUATE_SECURITY in Firefox, run these commands to update your development certificate:

dotnet dev-certs https --clean

dotnet dev-certs https --trust

Next steps
To learn more about SignalR, see the introduction:
Introduction to ASP.NET Core SignalR
This tutorial teaches the basics of building a real-time app using SignalR. You learn how to:
Create a web project.
Add the SignalR client library.
Create a SignalR hub.
Configure the project to use SignalR.
Add code that sends messages from any client to all connected clients.
At the end, you'll have a working chat app:
Prerequisites
Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio 2017 version 15.9 or later with the ASP.NET and web development workload. You can use
Visual Studio 2019, but some project creation steps differ from what's shown in the tutorial.
.NET Core SDK 2.2 or later

WARNING
If you use Visual Studio 2017, see dotnet/sdk issue #3124 for information about .NET Core SDK versions that don't work
with Visual Studio.

Create a web project

Visual Studio
Visual Studio Code
Visual Studio for Mac
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.2, 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 (CDN )) that can deliver anything found in npm, the
Node.js package manager.
 Visual Studio
Visual Studio Code
Visual Studio for Mac
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 a 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;
using System.Threading.Tasks;

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 a connected client to send a message to all clients. JavaScript
client code that calls the method is shown later in the tutorial. SignalR code is asynchronous to provide
maximum scalability.

Configure 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.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using SignalRChat.Hubs;

namespace SignalRChat
{
public class Startup
{
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.
public void ConfigureServices(IServiceCollection services)
{
services.Configure<CookiePolicyOptions>(options =>
{
// This lambda determines whether user consent for non-essential cookies is needed for
a given request.
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

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.UseStaticFiles();
app.UseCookiePolicy();
app.UseSignalR(routes =>
{
routes.MapHub<ChatHub>("/chatHub");
});
app.UseMvc();
}
}
}

These changes add SignalR to the ASP.NET Core dependency injection system and the middleware
pipeline.
Add SignalR client code
Replace the content in Pages\Index.cshtml with the following code:

@page
<div class="container">
<div class="row">&nbsp;</div>
<div class="row">
<div class="col-6">&nbsp;</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">&nbsp;</div>
<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();

//Disable send button until connection is established

document.getElementById("sendButton").disabled = true;

connection.on("ReceiveMessage", function (user, message) {

var msg = message.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
var encodedMsg = user + " says " + msg;
var li = document.createElement("li");
li.textContent = encodedMsg;
document.getElementById("messagesList").appendChild(li);
});

connection.start().then(function(){
document.getElementById("sendButton").disabled = false;
}).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) {
return console.error(err.toString());
});
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
Visual Studio for Mac
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 Message 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
In this tutorial, you learned how to:
Create a web app project.
Add the SignalR client library.
Create a SignalR hub.
Configure the project to use SignalR.
Add code that uses the hub to send messages from any client to all connected clients.
To learn more about SignalR, see the introduction:
Introduction to ASP.NET Core SignalR
 Use ASP.NET Core SignalR with TypeScript and
Webpack
5/14/2019 • 10 minutes to read • Edit Online

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
View or download sample code (how to download)

Prerequisites
Visual Studio
Visual Studio Code
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 2.2 or later
Node.js with npm

Create the ASP.NET Core web app

Visual Studio
Visual Studio Code
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.
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 select OK.
3. Select .NET Core from the target framework drop-down, and select ASP.NET Core 2.2 from the framework
selector drop-down. Select the Empty template, and select OK.

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.29.3" is used instead of "webpack": "^4.29.3" . 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>
<meta charset="utf-8" />
<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.

app.UseDefaultFiles();
app.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.

services.AddSignalR();

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:
 using Microsoft.AspNetCore.SignalR;
using System.Threading.Tasks;

namespace SignalRWebPack.Hubs
{
public class ChatHub : Hub
{
}
}

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 "./css/main.css";
import * as signalR from "@aspnet/signalr";

const divMessages: HTMLDivElement = document.querySelector("#divMessages");

const tbMessage: HTMLInputElement = document.querySelector("#tbMessage");
const btnSend: HTMLButtonElement = document.querySelector("#btnSend");
const username = new Date().getTime();

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;
});

tbMessage.addEventListener("keyup", (e: KeyboardEvent) => {

if (e.keyCode === 13) {
send();
}
});

btnSend.addEventListener("click", 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:
 import "./css/main.css";
import * as signalR from "@aspnet/signalr";

const divMessages: HTMLDivElement = document.querySelector("#divMessages");

const tbMessage: HTMLInputElement = document.querySelector("#tbMessage");
const btnSend: HTMLButtonElement = document.querySelector("#btnSend");
const username = new Date().getTime();

const connection = new signalR.HubConnectionBuilder()

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

connection.start().catch(err => document.write(err));

connection.on("messageReceived", (username: string, message: string) => {

let messageContainer = document.createElement("div");

messageContainer.innerHTML =
`<div class="message-author">${username}</div><div>${message}</div>`;

divMessages.appendChild(messageContainer);
divMessages.scrollTop = divMessages.scrollHeight;
});

tbMessage.addEventListener("keyup", (e: KeyboardEvent) => {

if (e.keyCode === 13) {
send();
}
});

btnSend.addEventListener("click", 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:

using Microsoft.AspNetCore.SignalR;
using System.Threading.Tasks;

namespace SignalRWebPack.Hubs
{
public class ChatHub : Hub
{
public async Task NewMessage(long 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
Visual Studio Code
1. Run Webpack in release mode. Using the Package Manager Console window, execute the following
command in the project root. If you are not in the project root, enter cd SignalRWebPack before entering the
command.

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.
Additional resources
ASP.NET Core SignalR JavaScript client
Use hubs in ASP.NET Core SignalR
 Use hubs in SignalR for ASP.NET Core
4/26/2019 • 6 minutes to read • Edit Online

By Rachel Appel and Kevin Griffin

View or download sample code (how to download)

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 .

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 .

public class ChatHub : Hub

{
public Task SendMessage(string user, string message)
{
return Clients.All.SendAsync("ReceiveMessage", user, message);
}
}

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.
 NOTE
Hubs are transient:
Don't store state in a property on the hub class. Every hub method call is executed on a new hub instance.
Use await when calling asynchronous methods that depend on the hub staying alive. For example, a method such as
Clients.All.SendAsync(...) can fail if it's called without await and the hub method completes before SendAsync
finishes.

The Context object

The Hub class has a Context property that contains the following properties with information about the
connection:

PROPERTY DESCRIPTION

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:
 PROPERTY DESCRIPTION

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 on all connections in the specified group

GroupExcept Calls a method on all connections in the specified group,

except the specified connections

Groups Calls a method on multiple groups of connections

OthersInGroup Calls a method on a group of connections, excluding the

client that invoked the hub method

User Calls a method on all connections associated with a specific

user

Users Calls a method on 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, there are
three Hub methods:
SendMessage sends a message to all connected clients, using Clients.All .
SendMessageToCaller sends a message back to the caller, using Clients.Caller .
SendMessageToGroups sends a message to all clients in the SignalR Users group.
 public Task SendMessage(string user, string message)
{
return Clients.All.SendAsync("ReceiveMessage", user, message);
}

public Task SendMessageToCaller(string message)

{
return Clients.Caller.SendAsync("ReceiveMessage", message);
}

public Task SendMessageToGroup(string message)

{
return Clients.Group("SignalR Users").SendAsync("ReceiveMessage", message);
}

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>

{
public async Task SendMessage(string user, string message)
{
await Clients.All.ReceiveMessage(user, message);
}

public Task SendMessageToCaller(string 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 . Any methods defined on the interface can
still be defined as asynchronous. In fact, each of these methods should return a Task . Since it's an interface,
don't use the async keyword. For example:

public interface IClient

{
Task ClientMethod();
}
 NOTE
The Async suffix isn't stripped from the method name. Unless your client method is defined with
.on('MyMethodAsync') , you shouldn't use MyMethodAsync as a name.

Change the name of a hub method

By default, a server hub method name is the name of the .NET method. However, you can use the
HubMethodName attribute to change this default and manually specify a name for the method. The client
should use this name, instead of the .NET method name, when invoking the method.

[HubMethodName("SendMessageToUser")]
public Task DirectMessage(string user, string message)
{
return Clients.User(user).SendAsync("ReceiveMessage", message);
}

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.

public override async Task OnConnectedAsync()

{
await Groups.AddToGroupAsync(Context.ConnectionId, "SignalR Users");
await base.OnConnectedAsync();
}

Override the OnDisconnectedAsync virtual method to perform actions when a client disconnects. If the client
disconnects intentionally (by calling connection.stop() , for example), the exception parameter will be null .
However, if the client is disconnected due to an error (such as a network failure), the exception parameter will
contain an exception describing the failure.

public override async Task OnDisconnectedAsync(Exception exception)

{
await Groups.RemoveFromGroupAsync(Context.ConnectionId, "SignalR Users");
await base.OnDisconnectedAsync(exception);
}

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));

If your Hub throws an exception, connections aren't closed. By default, SignalR returns a generic error message
to the client. For example:
 Microsoft.AspNetCore.SignalR.HubException: An unexpected error occurred invoking 'MethodName' on the server.

Unexpected exceptions often contain sensitive information, such as the name of a database server in an
exception triggered when the database connection fails. SignalR doesn't expose these detailed error messages by
default as a security measure. See the Security considerations article for more information on why exception
details are suppressed.
If you have an exceptional condition you do want to propagate to the client, you can use the HubException class.
If you throw a HubException from your hub method, SignalR will send the entire message to the client,
unmodified.

public Task ThrowException()

{
throw new HubException("This error will be sent to the client!");
}

NOTE
SignalR only sends the Message property of the exception to the client. The stack trace and other properties on the
exception aren't available to the client.

Related resources
Intro to ASP.NET Core SignalR
JavaScript client
Publish to Azure
 Send messages from outside a hub
4/26/2019 • 2 minutes to read • Edit Online

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.
View or download sample code (how to download)

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:

public class HomeController : Controller

{
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.

public async Task<IActionResult> Index()

{
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(async (context, next) =>
{
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.

Inject a strongly-typed HubContext

To inject a strongly-typed HubContext, ensure your Hub inherits from Hub<T> . Inject it using the
IHubContext<THub, T> interface rather than IHubContext<THub> .

public class ChatController : Controller

{
public IHubContext<ChatHub, IChatClient> _strongChatHubContext { get; }

public ChatController(IHubContext<ChatHub, IChatClient> chatHubContext)

{
_strongChatHubContext = chatHubContext;
}

public async Task SendMessage(string message)

{
await _strongChatHubContext.Clients.All.ReceiveMessage(message);
}
}

Related resources
Get started
Hubs
Publish to Azure
 Manage users and groups in SignalR
4/26/2019 • 2 minutes to read • Edit Online

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.
View or download sample code (how to download)

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);
}

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.
To protect access to resources while using groups, use authentication and authorization functionality in ASP.NET
Core. If you only add users to a group when the credentials are valid for that group, messages sent to that group
will only go to authorized users. However, groups are not a security feature. Authentication claims have features
that groups do not, such as expiry and revocation. If a user's permission to access the group is revoked, you have
to manually detect that and remove them from the group.

NOTE
Group names are case-sensitive.

Related resources
Get started
Hubs
Publish to Azure
 SignalR API design considerations
4/26/2019 • 2 minutes to read • Edit Online

By Andrew Stanton-Nurse
This article provides guidance for building SignalR -based APIs.

Use custom object parameters to ensure backwards-compatibility

Adding parameters to a SignalR hub method (on either the client or the server) is a breaking change. This means
older clients/servers will get errors when they try to invoke the method without the appropriate number of
parameters. However, adding properties to a custom object parameter is not a breaking change. This can be used
to design compatible APIs that are resilient to changes on the client or the server.
For example, consider a server-side API like the following:

public async Task<string> GetTotalLength(string param1)

{
return param1.Length;
}

The JavaScript client calls this method using invoke as follows:

connection.invoke("GetTotalLength", "value1");

If you later add a second parameter to the server method, older clients won't provide this parameter value. For
example:

public async Task<string> GetTotalLength(string param1, string param2)

{
return param1.Length + param2.Length;
}

When the old client tries to invoke this method, it will get an error like this:

Microsoft.AspNetCore.SignalR.HubException: Failed to invoke 'GetTotalLength' due to an error on the server.

On the server, you'll see a log message like this:

System.IO.InvalidDataException: Invocation provides 1 argument(s) but target expects 2.

The old client only sent one parameter, but the newer server API required two parameters. Using custom objects as
parameters gives you more flexibility. Let's redesign the original API to use a custom object:
 public class TotalLengthRequest
{
public string Param1 { get; set; }
}

public async Task GetTotalLength(TotalLengthRequest req)

{
return req.Param1.Length;
}

Now, the client uses an object to call the method:

connection.invoke("GetTotalLength", { param1: "value1" });

Instead of adding a parameter, add a property to the TotalLengthRequest object:

public class TotalLengthRequest

{
public string Param1 { get; set; }
public string Param2 { get; set; }
}

public async Task GetTotalLength(TotalLengthRequest req)

{
var length = req.Param1.Length;
if (req.Param2 != null)
{
length += req.Param2.Length;
}
return length;
}

When the old client sends a single parameter, the extra Param2 property will be left null . You can detect a
message sent by an older client by checking the Param2 for null and apply a default value. A new client can send
both parameters.

connection.invoke("GetTotalLength", { param1: "value1", param2: "value2" });

The same technique works for methods defined on the client. You can send a custom object from the server side:

public async Task Broadcast(string message)

{
await Clients.All.SendAsync("ReceiveMessage", new
{
Message = message
});
}

On the client side, you access the Message property rather than using a parameter:

connection.on("ReceiveMessage", (req) => {

appendMessageToChatWindow(req.message);
});

If you later decide to add the sender of the message to the payload, add a property to the object:
 public async Task Broadcast(string message)
{
await Clients.All.SendAsync("ReceiveMessage", new
{
Sender = Context.User.Identity.Name,
Message = message
});
}

The older clients won't be expecting the Sender value, so they'll ignore it. A new client can accept it by updating to
read the new property:

connection.on("ReceiveMessage", (req) => {

let message = req.message;
if (req.sender) {
message = req.sender + ": " + message;
}
appendMessageToChatWindow(message);
});

In this case, the new client is also tolerant of an old server that doesn't provide the Sender value. Since the old
server won't provide the Sender value, the client checks to see if it exists before accessing it.
 ASP.NET Core SignalR .NET Client
6/17/2019 • 7 minutes to read • Edit Online

The ASP.NET Core SignalR .NET client library lets you communicate with SignalR hubs from .NET apps.
View or download sample code (how to download)
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.Threading.Tasks;
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
{
await connection.StartAsync();
messagesList.Items.Add("Connection started");
connectButton.IsEnabled = false;
sendButton.IsEnabled = true;
}
catch (Exception ex)
{
messagesList.Items.Add(ex.Message);
}
}

private async void sendButton_Click(object sender, RoutedEventArgs e)

{
try
{
await connection.InvokeAsync("SendMessage",
userTextBox.Text, messageTextBox.Text);
}
catch (Exception ex)
{
messagesList.Items.Add(ex.Message);
}
}
}
}

Handle lost connection

Automatically reconnect
The HubConnection can be configured to automatically reconnect using the WithAutomaticReconnect method on
the HubConnectionBuilder. It won't automatically reconnect by default.

HubConnection connection= new HubConnectionBuilder()

.WithUrl(new Uri("http://127.0.0.1:5000/chatHub"))
.WithAutomaticReconnect()
.Build();

Without any parameters, WithAutomaticReconnect() configures the client to wait 0, 2, 10, and 30 seconds
respectively before trying each reconnect attempt, stopping after four failed attempts.
Before starting any reconnect attempts, the HubConnection will transition to the HubConnectionState.Reconnecting
state and fire the Reconnecting event. This provides an opportunity to warn users that the connection has been
lost and to disable UI elements. Non-interactive apps can start queuing or dropping messages.

connection.Reconnecting += error =>

{
Debug.Assert(connection.State == HubConnectionState.Reconnecting);

// Notify users the connection was lost and the client is reconnecting.
// Start queuing or dropping messages.

return Task.CompletedTask;
};

If the client successfully reconnects within its first four attempts, the HubConnection will transition back to the
Connected state and fire the Reconnected event. This provides an opportunity to inform users the connection has
been reestablished and dequeue any queued messages.
Since the connection looks entirely new to the server, a new ConnectionId will be provided to the Reconnected
event handlers.

WARNING
The Reconnected event handler's connectionId parameter will be null if the HubConnection was configured to skip
negotiation.

connection.Reconnected += connectionId =>

{
Debug.Assert(connection.State == HubConnectionState.Connected);

// Notify users the connection was reestablished.

// Start dequeuing messages queued while reconnecting if any.

return Task.CompletedTask;
};

WithAutomaticReconnect() won't configure the HubConnection to retry initial start failures, so start failures need to
be handled manually:
 public static async Task<bool> ConnectWithRetryAsync(HubConnection connection, CancellationToken token)
{
// Keep trying to until we can start or the token is canceled.
while (true)
{
try
{
await connection.StartAsync(token);
Debug.Assert(connection.State == HubConnectionState.Connected);
return true;
}
catch when (token.IsCancellationRequested)
{
return false;
}
catch
{
// Failed to connect, trying again in 5000 ms.
Debug.Assert(connection.State == HubConnectionState.Disconnected);
await Task.Delay(5000);
}
}
}

If the client doesn't successfully reconnect within its first four attempts, the HubConnection will transition to the
Disconnected state and fire the Closed event. This provides an opportunity to attempt to restart the connection
manually or inform users the connection has been permanently lost.

connection.Closed += error =>

{
Debug.Assert(connection.State == HubConnectionState.Disconnected);

// Notify users the connection has been closed or manually try to restart the connection.

return Task.CompletedTask;
};

In order to configure a custom number of reconnect attempts before disconnecting or change the reconnect
timing, WithAutomaticReconnect accepts an array of numbers representing the delay in milliseconds to wait before
starting each reconnect attempt.

HubConnection connection= new HubConnectionBuilder()

.WithUrl(new Uri("http://127.0.0.1:5000/chatHub"))
.WithAutomaticReconnect(new[] { TimeSpan.Zero, TimeSpan.Zero, TimeSpan.FromSeconds(10) })
.Build();

// .WithAutomaticReconnect(new[] { TimeSpan.Zero, TimeSpan.FromSeconds(2), TimeSpan.FromSeconds(10),

TimeSpan.FromSeconds(30) }) yields the default behavior.

The preceding example configures the HubConnection to start attempting reconnects immediately after the
connection is lost. This is also true for the default configuration.
If the first reconnect attempt fails, the second reconnect attempt will also start immediately instead of waiting 2
seconds like it would in the default configuration.
If the second reconnect attempt fails, the third reconnect attempt will start in 10 seconds which is again like the
default configuration.
The custom behavior then diverges again from the default behavior by stopping after the third reconnect attempt
failure. In the default configuration there would be one more reconnect attempt in another 30 seconds.
If you want even more control over the timing and number of automatic reconnect attempts,
WithAutomaticReconnect accepts an object implementing the IRetryPolicy interface, which has a single method
named NextRetryDelay .
NextRetryDelay takes a single argument with the type RetryContext . The RetryContext has three properties:
PreviousRetryCount , ElapsedTime and RetryReason which are a long , a TimeSpan and an Exception respectively.
Before the first reconnect attempt, both PreviousRetryCount and ElapsedTime will be zero, and the RetryReason
will be the Exception that caused the connection to be lost. After each failed retry attempt, PreviousRetryCount will
be incremented by one, ElapsedTime will be updated to reflect the amount of time spent reconnecting so far, and
the RetryReason will be the Exception that caused the last reconnect attempt to fail.
NextRetryDelay must return either a TimeSpan representing the time to wait before the next reconnect attempt or
null if the HubConnection should stop reconnecting.

public class RandomRetryPolicy : IRetryPolicy

{
private readonly Random _random = new Random();

public TimeSpan? NextRetryDelay(RetryContext retryContext)

{
// If we've been reconnecting for less than 60 seconds so far,
// wait between 0 and 10 seconds before the next reconnect attempt.
if (retryContext.ElapsedTime < TimeSpan.FromSeconds(60))
{
return TimeSpan.FromSeconds(_random.Next() * 10);
}
else
{
// If we've been reconnecting for more than 60 seconds so far, stop reconnecting.
return null;
}
}
}

HubConnection connection = new HubConnectionBuilder()

.WithUrl(new Uri("http://127.0.0.1:5000/chatHub"))
.WithAutomaticReconnect(new RandomRetryPolicy())
.Build();

Alternatively, you can write code that will reconnect your client manually as demonstrated in Manually reconnect.
Manually reconnect

WARNING
Prior to 3.0, the .NET client for SignalR doesn't automatically reconnect. You must write code that will reconnect your client
manually.

Use the Closed event to respond to a lost connection. For example, you might want to automate reconnection.
The Closedevent 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.
return Task.CompletedTask;
};

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);
await connection.StartAsync();
};

Call hub methods from client

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.

await connection.InvokeAsync("SendMessage",
userTextBox.Text, messageTextBox.Text);

The InvokeAsync method returns a Task which completes when the server method returns. The return value, if
any, is provided as the result of the Task . Any exceptions thrown by the method on the server produce a faulted
Task . Use await syntax to wait for the server method to complete and try...catch syntax to handle errors.

The SendAsync method returns a Task which completes when the message has been sent to the server. No
return value is provided since this Task doesn't wait until the server method completes. Any exceptions thrown
on the client while sending the message produce a faulted Task . Use await and try...catch syntax to handle
send errors.

NOTE
If you're using Azure SignalR Service in Serverless mode, you cannot call hub methods from a client. For more information,
see the SignalR Service documentation.

Call client methods from hub

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.
 public async Task SendMessage(string user, string message)
{
await Clients.All.SendAsync("ReceiveMessage", user,message);
}

Error handling and logging

Handle errors with a try-catch statement. Inspect the Exception object to determine the proper action to take
after an error occurs.

try
{
await connection.InvokeAsync("SendMessage",
userTextBox.Text, messageTextBox.Text);
}
catch (Exception ex)
{
messagesList.Items.Add(ex.Message);
}

Additional resources
Hubs
JavaScript client
Publish to Azure
Azure SignalR Service serverless documentation
 ASP.NET Core SignalR Java client
7/11/2019 • 2 minutes to read • Edit Online

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.
View or download sample code (how to download)

Install the SignalR Java client package

The signalr-1.0.0 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.signalr:signalr:1.0.0'

If using Maven, add the following lines inside the <dependencies> element of your pom.xml file:

<dependency>
<groupId>com.microsoft.signalr</groupId>
<artifactId>signalr</artifactId>
<version>1.0.0</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 = HubConnectionBuilder.create(input)

.build();

Call hub methods from client

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);
 NOTE
If you're using Azure SignalR Service in Serverless mode, you cannot call hub methods from a client. For more information,
see the SignalR Service documentation.

Call client methods from hub

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);

Add logging
The SignalR Java client uses the SLF4J library for logging. It's a high-level logging API that allows users of the
library to chose their own specific logging implementation by bringing in a specific logging dependency. The
following code snippet shows how to use java.util.logging with the SignalR Java client.

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

If you don't configure logging in your dependencies, SLF4J loads a default no-operation logger with the following
warning message:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".

SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

This can safely be ignored.

Android development notes

With regards to Android SDK compatibility for the SignalR client features, consider the following items when
specifying your target Android SDK version:
The SignalR Java Client will run on Android API Level 16 and later.
Connecting through the Azure SignalR Service will require Android API Level 20 and later because the Azure
SignalR Service requires TLS 1.2 and doesn't support SHA-1-based cipher suites. Android added support for
SHA-256 (and above) cipher suites in API Level 20.

Configure bearer token authentication

In the SignalR Java client, you can configure a bearer token to use for authentication by providing an "access token
factory" to the HttpHubConnectionBuilder. Use withAccessTokenFactory to provide an RxJava Single<String>.
With a call to Single.defer, you can write logic to produce access tokens for your client.
 HubConnection hubConnection = HubConnectionBuilder.create("YOUR HUB URL HERE")
.withAccessTokenProvider(Single.defer(() -> {
// Your logic here.
return Single.just("An Access Token");
})).build();

Known limitations
Only the JSON protocol is supported.
Transport fallback and the Server Sent Events transport aren't supported.
Only the JSON protocol is supported.
Only the WebSockets transport is supported.
Streaming isn't supported yet.

Additional resources
Java API reference
Use hubs in ASP.NET Core SignalR
ASP.NET Core SignalR JavaScript client
Publish an ASP.NET Core SignalR app to Azure App Service
Azure SignalR Service serverless documentation
 ASP.NET Core SignalR JavaScript client
7/23/2019 • 8 minutes to read • Edit Online

By Rachel Appel
The ASP.NET Core SignalR JavaScript client library enables developers to call server-side hub code.
View or download sample code (how to download)

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 install @microsoft/signalr

npm installs the package contents in the node_modules\@microsoft\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.

npm init -y
npm install @aspnet/signalr

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.

const connection = new signalR.HubConnectionBuilder()

.withUrl("/chatHub")
.configureLogging(signalR.LogLevel.Information)
.build();

connection.start().then(function () {
console.log("connected");
});

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.
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using SignalRChat.Hubs;

namespace SignalRChat
{
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}

public IConfiguration Configuration { get; }

public void ConfigureServices(IServiceCollection services)

{
services.Configure<CookiePolicyOptions>(options =>
{
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddMvc();

services.AddCors(options => options.AddPolicy("CorsPolicy",

builder =>
{
builder.AllowAnyMethod().AllowAnyHeader()
.WithOrigins("http://localhost:55830")
.AllowCredentials();
}));

services.AddSignalR();
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
if (env.IsDevelopment())
{
app.UseBrowserLink();
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseCookiePolicy();
app.UseCors("CorsPolicy");
app.UseSignalR(routes =>
{
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 . The
example code uses arrow function syntax that is supported in current versions of all major browsers
except Internet Explorer.

connection.invoke("SendMessage", user, message).catch(err => console.error(err.toString()));

NOTE
If you're using Azure SignalR Service in Serverless mode, you cannot call hub methods from a client. For more information,
see the SignalR Service documentation.

The invoke method returns a JavaScript Promise. The Promise is resolved with the return value (if any) when
the method on the server returns. If the method on the server throws an error, the Promise is rejected with the
error message. Use the then and catch methods on the Promise itself to handle these cases (or await
syntax).
The send method returns a JavaScript Promise . The Promise is resolved when the message has been sent to
the server. If there is an error sending the message, the Promise is rejected with the error message. Use the
then and catch methods on the Promise itself to handle these cases (or await syntax).

NOTE
Using send doesn't wait until the server has received the message. Consequently, it's not possible to return data or
errors from the server.

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");
li.textContent = encodedMsg;
document.getElementById("messagesList").appendChild(li);
});

The preceding code in connection.on runs when server-side code calls it using the SendAsync method.

public async Task SendMessage(string user, string message)

{
await Clients.All.SendAsync("ReceiveMessage", user, message);
}
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.

connection.start().catch(function (err) {
return console.error(err.toString());
});

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.

const connection = new signalR.HubConnectionBuilder()

.withUrl("/chatHub")
.configureLogging(signalR.LogLevel.Information)
.build();

Reconnect clients
Automatically reconnect
The JavaScript client for SignalR can be configured to automatically reconnect using the withAutomaticReconnect
method on HubConnectionBuilder. It won't automatically reconnect by default.

const connection = new signalR.HubConnectionBuilder()

.withUrl("/chatHub")
.withAutomaticReconnect()
.build();

Without any parameters, withAutomaticReconnect() configures the client to wait 0, 2, 10, and 30 seconds
respectively before trying each reconnect attempt, stopping after four failed attempts.
Before starting any reconnect attempts, the HubConnection will transition to the
HubConnectionState.Reconnecting state and fire its onreconnecting callbacks instead of transitioning to the
Disconnected state and triggering its onclose callbacks like a HubConnection without automatic reconnect
configured. This provides an opportunity to warn users that the connection has been lost and to disable UI
elements.

connection.onreconnecting((error) => {
console.assert(connection.state === signalR.HubConnectionState.Reconnecting);

document.getElementById("messageInput").disabled = true;

const li = document.createElement("li");
li.textContent = `Connection lost due to error "${error}". Reconnecting.`;
document.getElementById("messagesList").appendChild(li);
});

If the client successfully reconnects within its first four attempts, the HubConnection will transition back to the
Connected state and fire its onreconnected callbacks. This provides an opportunity to inform users the
connection has been reestablished.
Since the connection looks entirely new to the server, a new connectionId will be provided to the onreconnected
callback.

WARNING
The onreconnected callback's connectionId parameter will be undefined if the HubConnection was configured to skip
negotiation.

connection.onreconnected((connectionId) => {
console.assert(connection.state === signalR.HubConnectionState.Connected);

document.getElementById("messageInput").disabled = false;

const li = document.createElement("li");
li.textContent = `Connection reestablished. Connected with connectionId "${connectionId}".`;
document.getElementById("messagesList").appendChild(li);
});

withAutomaticReconnect() won't configure the HubConnection to retry initial start failures, so start failures need
to be handled manually:

async function start() {

try {
await connection.start();
console.assert(connection.state === signalR.HubConnectionState.Connected);
console.log("connected");
} catch (err) {
console.assert(connection.state === signalR.HubConnectionState.Disconnected);
console.log(err);
setTimeout(() => start(), 5000);
}
};

If the client doesn't successfully reconnect within its first four attempts, the HubConnection will transition to the
Disconnected state and fire its onclose callbacks. This provides an opportunity to inform users the connection
has been permanently lost and recommend refreshing the page:
 connection.onclose((error) => {
console.assert(connection.state === signalR.HubConnectionState.Disconnected);

document.getElementById("messageInput").disabled = true;

const li = document.createElement("li");
li.textContent = `Connection closed due to error "${error}". Try refreshing this page to restart the
connection.`;
document.getElementById("messagesList").appendChild(li);
});

In order to configure a custom number of reconnect attempts before disconnecting or change the reconnect
timing, withAutomaticReconnect accepts an array of numbers representing the delay in milliseconds to wait
before starting each reconnect attempt.

const connection = new signalR.HubConnectionBuilder()

.withUrl("/chatHub")
.withAutomaticReconnect([0, 0, 10000])
.build();

// .withAutomaticReconnect([0, 2000, 10000, 30000]) yields the default behavior

The preceding example configures the HubConnection to start attempting reconnects immediately after the
connection is lost. This is also true for the default configuration.
If the first reconnect attempt fails, the second reconnect attempt will also start immediately instead of waiting 2
seconds like it would in the default configuration.
If the second reconnect attempt fails, the third reconnect attempt will start in 10 seconds which is again like the
default configuration.
The custom behavior then diverges again from the default behavior by stopping after the third reconnect
attempt failure instead of trying one more reconnect attempt in another 30 seconds like it would in the default
configuration.
If you want even more control over the timing and number of automatic reconnect attempts,
withAutomaticReconnect accepts an object implementing the IRetryPolicy interface, which has a single method
named nextRetryDelayInMilliseconds .
nextRetryDelayInMilliseconds takes a single argument with the type RetryContext . The RetryContext has three
properties: previousRetryCount , elapsedMilliseconds and retryReason which are a number , a number and an
Error respectively. Before the first reconnect attempt, both previousRetryCount and elapsedMilliseconds will
be zero, and the retryReason will be the Error that caused the connection to be lost. After each failed retry
attempt, previousRetryCount will be incremented by one, elapsedMilliseconds will be updated to reflect the
amount of time spent reconnecting so far in milliseconds, and the retryReason will be the Error that caused the
last reconnect attempt to fail.
nextRetryDelayInMilliseconds must return either a number representing the number of milliseconds to wait
before the next reconnect attempt or null if the HubConnection should stop reconnecting.
 const connection = new signalR.HubConnectionBuilder()
.withUrl("/chatHub")
.withAutomaticReconnect({
nextRetryDelayInMilliseconds: retryContext => {
if (retryContext.elapsedMilliseconds < 60000) {
// If we've been reconnecting for less than 60 seconds so far,
// wait between 0 and 10 seconds before the next reconnect attempt.
return Math.random() * 10000;
} else {
// If we've been reconnecting for more than 60 seconds so far, stop reconnecting.
return null;
}
})
.build();

Alternatively, you can write code that will reconnect your client manually as demonstrated in Manually
reconnect.
Manually reconnect

WARNING
Prior to 3.0, the JavaScript client for SignalR doesn't automatically reconnect. You must write code that will reconnect your
client manually.

The following code demonstrates a typical manual reconnection approach:

1. A function (in this case, the start function) is created to start the connection.
2. Call the start function in the connection's onclose event handler.

async function start() {

try {
await connection.start();
console.log("connected");
} catch (err) {
console.log(err);
setTimeout(() => start(), 5000);
}
};

connection.onclose(async () => {
await start();
});

A real-world implementation would use an exponential back-off or retry a specified number of times before
giving up.

Additional resources
JavaScript API reference
JavaScript tutorial
WebPack and TypeScript tutorial
Hubs
.NET client
Publish to Azure
Cross-Origin Requests (CORS )
Azure SignalR Service serverless documentation
 ASP.NET Core SignalR hosting and scaling
4/26/2019 • 3 minutes to read • Edit Online

By Andrew Stanton-Nurse, Brady Gaster, and Tom Dykstra,

This article explains hosting and scaling considerations for high-traffic apps that use ASP.NET Core SignalR.

TCP connection resources

The number of concurrent TCP connections that a web server can support is limited. Standard HTTP clients use
ephemeral connections. These connections can be closed when the client goes idle and reopened later. On the
other hand, a SignalR connection is persistent. SignalR connections stay open even when the client goes idle. In a
high-traffic app that serves many clients, these persistent connections can cause servers to hit their maximum
number of connections.
Persistent connections also consume some additional memory, to track each connection.
The heavy use of connection-related resources by SignalR can affect other web apps that are hosted on the same
server. When SignalR opens and holds the last available TCP connections, other web apps on the same server also
have no more connections available to them.
If a server runs out of connections, you'll see random socket errors and connection reset errors. For example:

An attempt was made to access a socket in a way forbidden by its access permissions...

To keep SignalR resource usage from causing errors in other web apps, run SignalR on different servers than your
other web apps.
To keep SignalR resource usage from causing errors in a SignalR app, scale out to limit the number of connections
a server has to handle.

Scale out
An app that uses SignalR needs to keep track of all its connections, which creates problems for a server farm. Add
a server, and it gets new connections that the other servers don't know about. For example, SignalR on each server
in the following diagram is unaware of the connections on the other servers. When SignalR on one of the servers
wants to send a message to all clients, the message only goes to the clients connected to that server.
The options for solving this problem are the Azure SignalR Service and Redis backplane.

Azure SignalR Service

The Azure SignalR Service is a proxy rather than a backplane. Each time a client initiates a connection to the server,
the client is redirected to connect to the service. That process is illustrated in the following diagram:

The result is that the service manages all of the client connections, while each server needs only a small constant
number of connections to the service, as shown in the following diagram:

This approach to scale-out has several advantages over the Redis backplane alternative:
Sticky sessions, also known as client affinity, is not required, because clients are immediately redirected to the
Azure SignalR Service when they connect.
A SignalR app can scale out based on the number of messages sent, while the Azure SignalR Service
automatically scales to handle any number of connections. For example, there could be thousands of clients, but
if only a few messages per second are sent, the SignalR app won't need to scale out to multiple servers just to
handle the connections themselves.
A SignalR app won't use significantly more connection resources than a web app without SignalR.
For these reasons, we recommend the Azure SignalR Service for all ASP.NET Core SignalR apps hosted on Azure,
including App Service, VMs, and containers.
For more information see the Azure SignalR Service documentation.

Redis backplane
Redis is an in-memory key-value store that supports a messaging system with a publish/subscribe model. The
SignalR Redis backplane uses the pub/sub feature to forward messages to other servers. When a client makes a
connection, the connection information is passed to the backplane. When a server wants to send a message to all
clients, it sends to the backplane. The backplane knows all connected clients and which servers they're on. It sends
the message to all clients via their respective servers. This process is illustrated in the following diagram:

The Redis backplane is the recommended scale-out approach for apps hosted on your own infrastructure. Azure
SignalR Service isn't a practical option for production use with on-premises apps due to connection latency
between your data center and an Azure data center.
The Azure SignalR Service advantages noted earlier are disadvantages for the Redis backplane:
Sticky sessions, also known as client affinity, is required. Once a connection is initiated on a server, the
connection has to stay on that server.
A SignalR app must scale out based on number of clients even if few messages are being sent.
A SignalR app uses significantly more connection resources than a web app without SignalR.

Next steps
For more information, see the following resources:
Azure SignalR Service documentation
Set up a Redis backplane
 Publish an ASP.NET Core SignalR app to Azure App
Service
6/26/2019 • 2 minutes to read • Edit Online

By Brady Gaster
Azure App Service 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. For more information, see SignalR service
for Azure.

Publish the app

This article covers publishing using the tools in Visual Studio. Visual Studio Code users can use Azure CLI
commands to publish apps to Azure. For more information, see Publish an ASP.NET Core app to Azure with
command line tools.
1. Right-click on the project in Solution Explorer and select Publish.
2. Confirm that App Service and Create new are selected in the Pick a publish target dialog.
3. Select Create Profile from the Publish button drop down.
Enter the information described in the following table in the Create App Service dialog and select
Create.

ITEM DESCRIPTION

Name Unique name of the app.

Subscription Azure subscription that the app uses.

Resource Group Group of related resources to which the app belongs.

Hosting Plan Pricing plan for the web app.

4. Select the Azure SignalR Service in the Dependencies > Add drop-down list:

5. In the Azure SignalR Service dialog, select Create a new Azure SignalR Service instance.
6. Provide a Name, Resource Group, and Location. Return to the Azure SignalR Service dialog and
select Add.
Visual Studio completes the following tasks:
Creates a Publish Profile containing publish settings.
Creates an Azure Web App with the provided details.
Publishes the app.
Launches a browser, which loads the web app.
The format of the app's URL is {APP SERVICE NAME}.azurewebsites.net . For example, an app named
SignalRChatApp has a URL of https://signalrchatapp.azurewebsites.net .

If an HTTP 502.2 - Bad Gateway error occurs when deploying an app that targets a preview .NET Core release,
see Deploy ASP.NET Core preview release to Azure App Service to resolve it.

Configure the app in Azure App Service

NOTE
This section only applies to apps not using the Azure SignalR Service.
If the app uses the Azure SignalR Service, the App Service doesn't require the configuration of Application Request Routing
(ARR) Affinity and Web Sockets described in this section. Clients connect their Web Sockets to the Azure SignalR Service,
not directly to the app.

For apps hosted without the Azure SignalR Service, enable:

ARR Affinity to route requests from a user back to the same App Service instance. The default setting is On.
Web Sockets to allow the Web Sockets transport to function. The default setting is Off.
1. In the Azure portal, navigate to the web app in App Services.
2. Open Configuration > General settings.
3. Set Web sockets to On.
4. Verify that ARR affinity is set to On.

App Service Plan limits

Web Sockets and other transports are limited based on the App Service Plan selected. For more information, see
the Azure Cloud Services limits and App Service limits sections of the Azure subscription and service limits,
quotas, and constraints article.

Additional resources
What is Azure SignalR Service?
Introduction to ASP.NET Core SignalR
Host and deploy ASP.NET Core
Publish an ASP.NET Core app to Azure with Visual Studio
Publish an ASP.NET Core app to Azure with command line tools
Host and deploy ASP.NET Core Preview apps on Azure
 Set up a Redis backplane for ASP.NET Core SignalR
scale-out
6/17/2019 • 3 minutes to read • Edit Online

By Andrew Stanton-Nurse, Brady Gaster, and Tom Dykstra,

This article explains SignalR -specific aspects of setting up a Redis server to use for scaling out an ASP.NET Core
SignalR app.

Set up a Redis backplane

Deploy a Redis server.

IMPORTANT
For production use, a Redis backplane is recommended only when it runs in the same data center as the SignalR app.
Otherwise, network latency degrades performance. If your SignalR app is running in the Azure cloud, we recommend
Azure SignalR Service instead of a Redis backplane. You can use the Azure Redis Cache Service for development and
test environments.

For more information, see the following resources:

ASP.NET Core SignalR production hosting and scaling
Redis documentation
Azure Redis Cache documentation
In the SignalR app, install the Microsoft.AspNetCore.SignalR.Redis NuGet package. (There is also a
Microsoft.AspNetCore.SignalR.StackExchangeRedis package, but that one is for ASP.NET Core 2.2 and later.)
In the Startup.ConfigureServices method, call AddRedis after AddSignalR :

services.AddSignalR().AddRedis("<your_Redis_connection_string>");

Configure options as needed:

Most options can be set in the connection string or in the ConfigurationOptions object. Options specified in
ConfigurationOptions override the ones set in the connection string.

The following example shows how to set options in the ConfigurationOptions object. This example adds a
channel prefix so that multiple apps can share the same Redis instance, as explained in the following step.

services.AddSignalR()
.AddRedis(connectionString, options => {
options.Configuration.ChannelPrefix = "MyApp";
});

In the preceding code, options.Configuration is initialized with whatever was specified in the connection
string.
In the SignalR app, install one of the following NuGet packages:
 Microsoft.AspNetCore.SignalR.StackExchangeRedis - Depends on StackExchange.Redis 2.X.X. This is the
recommended package for ASP.NET Core 2.2 and later.
Microsoft.AspNetCore.SignalR.Redis - Depends on StackExchange.Redis 1.X.X. This package will not be
shipping in ASP.NET Core 3.0.
In the Startup.ConfigureServices method, call AddStackExchangeRedis after AddSignalR :

services.AddSignalR().AddStackExchangeRedis("<your_Redis_connection_string>");

Configure options as needed:

Most options can be set in the connection string or in the ConfigurationOptions object. Options specified in
ConfigurationOptions override the ones set in the connection string.

The following example shows how to set options in the ConfigurationOptions object. This example adds a
channel prefix so that multiple apps can share the same Redis instance, as explained in the following step.

services.AddSignalR()
.AddStackExchangeRedis(connectionString, options => {
options.Configuration.ChannelPrefix = "MyApp";
});

In the preceding code, options.Configuration is initialized with whatever was specified in the connection
string.
For information about Redis options, see the StackExchange Redis documentation.
If you're using one Redis server for multiple SignalR apps, use a different channel prefix for each SignalR
app.
Setting a channel prefix isolates one SignalR app from others that use different channel prefixes. If you
don't assign different prefixes, a message sent from one app to all of its own clients will go to all clients of all
apps that use the Redis server as a backplane.
Configure your server farm load balancing software for sticky sessions. Here are some examples of
documentation on how to do that:
IIS
HAProxy
Nginx
pfSense

Redis server errors

When a Redis server goes down, SignalR throws exceptions that indicate messages won't be delivered. Some
typical exception messages:
Failed writing message
Failed to invoke hub method 'MethodName'
Connection to Redis failed
SignalR doesn't buffer messages to send them when the server comes back up. Any messages sent while the Redis
server is down are lost.
SignalR automatically reconnects when the Redis server is available again.
Custom behavior for connection failures
Here's an example that shows how to handle Redis connection failure events.

services.AddSignalR()
.AddRedis(o =>
{
o.ConnectionFactory = async writer =>
{
var config = new ConfigurationOptions
{
AbortOnConnectFail = false
};
config.EndPoints.Add(IPAddress.Loopback, 0);
config.SetDefaultPorts();
var connection = await ConnectionMultiplexer.ConnectAsync(config, writer);
connection.ConnectionFailed += (_, e) =>
{
Console.WriteLine("Connection to Redis failed.");
};

if (!connection.IsConnected)
{
Console.WriteLine("Did not connect to Redis.");
}

return connection;
};
});

services.AddSignalR()
.AddMessagePackProtocol()
.AddStackExchangeRedis(o =>
{
o.ConnectionFactory = async writer =>
{
var config = new ConfigurationOptions
{
AbortOnConnectFail = false
};
config.EndPoints.Add(IPAddress.Loopback, 0);
config.SetDefaultPorts();
var connection = await ConnectionMultiplexer.ConnectAsync(config, writer);
connection.ConnectionFailed += (_, e) =>
{
Console.WriteLine("Connection to Redis failed.");
};

if (!connection.IsConnected)
{
Console.WriteLine("Did not connect to Redis.");
}

return connection;
};
});

Redis Clustering
Redis Clustering is a method for achieving high availability by using multiple Redis servers. Clustering isn't
officially supported, but it might work.

Next steps
For more information, see the following resources:
ASP.NET Core SignalR production hosting and scaling
Redis documentation
StackExchange Redis documentation
Azure Redis Cache documentation
 Host ASP.NET Core SignalR in background services
4/26/2019 • 3 minutes to read • Edit Online

By Brady Gaster
This article provides guidance for:
Hosting SignalR Hubs using a background worker process hosted with ASP.NET Core.
Sending messages to connected clients from within a .NET Core BackgroundService.
View or download sample code (how to download)

Wire up SignalR during startup

Hosting ASP.NET Core SignalR Hubs in the context of a background worker process is identical to hosting a Hub
in an ASP.NET Core web app. In the Startup.ConfigureServices method, calling services.AddSignalR adds the
required services to the ASP.NET Core Dependency Injection (DI) layer to support SignalR. In Startup.Configure ,
the UseSignalR method is called to wire up the Hub endpoint(s) in the ASP.NET Core request pipeline.

public class Startup

{
public void ConfigureServices(IServiceCollection services)
{
services.AddSignalR();
services.AddHostedService<Worker>();
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}

app.UseSignalR((routes) =>
{
routes.MapHub<ClockHub>("/hubs/clock");
});
}
}

In the preceding example, the ClockHub class implements the Hub<T> class to create a strongly typed Hub. The
ClockHub has been configured in the Startup class to respond to requests at the endpoint /hubs/clock .

For more information on strongly typed Hubs, see Use hubs in SignalR for ASP.NET Core.

NOTE
This functionality isn't limited to the Hub<T> class. Any class that inherits from Hub, such as DynamicHub, will also work.
 public class ClockHub : Hub<IClock>
{
public async Task SendTimeToClients(DateTime dateTime)
{
await Clients.All.ShowTime(dateTime);
}
}

The interface used by the strongly typed ClockHub is the IClock interface.

public interface IClock

{
Task ShowTime(DateTime currentTime);
}

Call a SignalR Hub from a background service

During startup, the Worker class, a BackgroundService , is wired up using AddHostedService .

services.AddHostedService<Worker>();

Since SignalR is also wired up during the Startup phase, in which each Hub is attached to an individual endpoint
in ASP.NET Core's HTTP request pipeline, each Hub is represented by an IHubContext<T> on the server. Using
ASP.NET Core's DI features, other classes instantiated by the hosting layer, like BackgroundService classes, MVC
Controller classes, or Razor page models, can get references to server-side Hubs by accepting instances of
IHubContext<ClockHub, IClock> during construction.

public class Worker : BackgroundService

{
private readonly ILogger<Worker> _logger;
private readonly IHubContext<ClockHub, IClock> _clockHub;

public Worker(ILogger<Worker> logger, IHubContext<ClockHub, IClock> clockHub)

{
_logger = logger;
_clockHub = clockHub;
}

protected override async Task ExecuteAsync(CancellationToken stoppingToken)

{
while (!stoppingToken.IsCancellationRequested)
{
_logger.LogInformation($"Worker running at: {DateTime.Now}");
await _clockHub.Clients.All.ShowTime(DateTime.Now);
await Task.Delay(1000);
}
}
}

As the ExecuteAsync method is called iteratively in the background service, the server's current date and time are
sent to the connected clients using the ClockHub .

React to SignalR events with background services

Like a Single Page App using the JavaScript client for SignalR or a .NET desktop app can do using the using the
ASP.NET Core SignalR .NET Client, a BackgroundService or IHostedService implementation can also be used to
connect to SignalR Hubs and respond to events.
The ClockHubClient class implements both the IClock interface and the IHostedService interface. This way it can
be wired up during Startup to run continuously and respond to Hub events from the server.

public partial class ClockHubClient : IClock, IHostedService

{
}

During initialization, the ClockHubClient creates an instance of a HubConnection and wires up the IClock.ShowTime
method as the handler for the Hub's ShowTime event.

private readonly ILogger<ClockHubClient> _logger;

private HubConnection _connection;

public ClockHubClient(ILogger<ClockHubClient> logger)

{
_logger = logger;

_connection = new HubConnectionBuilder()

.WithUrl(Strings.HubUrl)
.Build();

_connection.On<DateTime>(Strings.Events.TimeSent,
dateTime => _ = ShowTime(dateTime));
}

public Task ShowTime(DateTime currentTime)

{
_logger.LogInformation($"{currentTime.ToShortTimeString()}");

return Task.CompletedTask;
}

In the IHostedService.StartAsync implementation, the HubConnection is started asynchronously.

public async Task StartAsync(CancellationToken cancellationToken)

{
// Loop is here to wait until the server is running
while (true)
{
try
{
await _connection.StartAsync(cancellationToken);

break;
}
catch
{
await Task.Delay(1000);
}
}
}

During the IHostedService.StopAsync method, the HubConnection is disposed of asynchronously.

 public Task StopAsync(CancellationToken cancellationToken)
{
return _connection.DisposeAsync();
}
}

Additional resources
Get started
Hubs
Publish to Azure
Strongly typed Hubs
 ASP.NET Core SignalR configuration
8/9/2019 • 18 minutes to read • Edit Online

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:

using Microsoft.Extensions.DependencyInjection;

// 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

ClientTimeoutInterval 30 seconds The server will consider the client

disconnected if it hasn't received a
message (including keep-alive) in this
interval. It could take longer than this
timeout interval for the client to actually
be marked disconnected, due to how
this is implemented. The recommended
value is double the
KeepAliveInterval value.

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.

StreamBufferCapacity 10 The maximum number of items that can

be buffered for client upload streams. If
this limit is reached, the processing of
invocations is blocked until the server
processes stream items.

MaximumReceiveMessageSize 32 KB Maximum size of a single incoming hub

message.
OPTION DEFAULT VALUE DESCRIPTION

ClientTimeoutInterval 30 seconds The server will consider the client

disconnected if it hasn't received a
message (including keep-alive) in this
interval. It could take longer than this
timeout interval for the client to actually
be marked disconnected, due to how
this is implemented. The recommended
value is double the
KeepAliveInterval value.

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.

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.
 OPTION DEFAULT VALUE DESCRIPTION

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
Startup.ConfigureServices .

public void ConfigureServices(IServiceCollection services)

{
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:

services.AddSignalR().AddHubOptions<MyHub>(options =>
{
options.EnableDetailedErrors = true;
});

Advanced HTTP configuration options

Use HttpConnectionDispatcherOptions to configure advanced settings related to transports and memory buffer
management. These options are configured by passing a delegate to MapHub<T> in Startup.Configure .
 public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseSignalR((configure) =>
{
var desiredTransports =
HttpTransportType.WebSockets |
HttpTransportType.LongPolling;

configure.MapHub<MyHub>("/myhub", (options) =>

{
options.Transports = desiredTransports;
});
});
}

The following table describes options for configuring ASP.NET Core SignalR's advanced HTTP options:

OPTION DEFAULT VALUE DESCRIPTION

ApplicationMaxBufferSize 32 KB The maximum number of bytes received

from the client that the server buffers
before applying backpressure.
Increasing this value allows the server
to receive larger messages more quickly
without applying backpressure, but can
increase 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 before
observing backpressure. Increasing this
value allows the server to buffer larger
messages more quickly without
awaiting backpressure, but can increase
memory consumption.

Transports All Transports are enabled. A bit flags enum 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.

OPTION DEFAULT VALUE DESCRIPTION

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.
 OPTION DEFAULT VALUE DESCRIPTION

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 bit flags enum 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:

OPTION DEFAULT VALUE DESCRIPTION

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:

OPTION DEFAULT VALUE DESCRIPTION

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 the .NET and JavaScript clients).
It's also available in the Java client, but the HttpHubConnectionBuilder subclass is what contains the builder
configuration options, 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:

var connection = new HubConnectionBuilder()

.WithUrl("https://example.com/myhub")
.ConfigureLogging(logging => {
logging.SetMinimumLevel(LogLevel.Information);
logging.AddConsole();
})
.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")
.configureLogging(signalR.LogLevel.Information)
.build();

Instead of a LogLevel value, you can also provide a string value representing a log level name. This is useful
when configuring SignalR logging in environments where you don't have access to the LogLevel constants.

let connection = new signalR.HubConnectionBuilder()

.withUrl("/myhub")
.configureLogging("warn")
.build();

The following table lists the available log levels. The value you provide to configureLogging sets the minimum log
level that will be logged. Messages logged at this level, or the levels listed after it in the table, will be logged.

STRING LOGLEVEL

trace LogLevel.Trace

debug LogLevel.Debug

info or information LogLevel.Information

warn or warning LogLevel.Warning

error LogLevel.Error

critical LogLevel.Critical
 STRING LOGLEVEL

none LogLevel.None

NOTE
To disable logging entirely, specify signalR.LogLevel.None in the configureLogging method.

For more information on logging, see the SignalR Diagnostics documentation.

The SignalR Java client uses the SLF4J library for logging. It's a high-level logging API that allows users of the
library to chose their own specific logging implementation by bringing in a specific logging dependency. The
following code snippet shows how to use java.util.logging with the SignalR Java client.

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

If you don't configure logging in your dependencies, SLF4J loads a default no-operation logger with the following
warning message:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".

SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

This can safely be ignored.

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:

var connection = new HubConnectionBuilder()

.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 :

let connection = new signalR.HubConnectionBuilder()

.withUrl("/myhub", { transport: signalR.HttpTransportType.WebSockets |
signalR.HttpTransportType.LongPolling })
.build();

In this version of the Java client websockets is the only available transport.
In the Java client, the transport is selected with the withTransport method on the HttpHubConnectionBuilder . The
Java client defaults to using the WebSockets transport.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/myhub")

.withTransport(TransportEnum.WEBSOCKETS)
.build();
 NOTE
The SignalR Java client doesn't support transport fallback yet.

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 :

var connection = new HubConnectionBuilder()

.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 :

let connection = new signalR.HubConnectionBuilder()

.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();

In the SignalR Java client, you can configure a bearer token to use for authentication by providing an access token
factory to the HttpHubConnectionBuilder. Use withAccessTokenFactory to provide an RxJava Single<String>.
With a call to Single.defer, you can write logic to produce access tokens for your client.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/myhub")

.withAccessTokenProvider(Single.defer(() -> {
// Your logic here.
return Single.just("An 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
JavaScript
Java
 OPTION DEFAULT VALUE DESCRIPTION

ServerTimeout 30 seconds (30,000 milliseconds) Timeout for server activity. If 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 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.

KeepAliveInterval 15 seconds Determines the interval at which the

client sends ping messages. Sending
any message from the client resets the
timer to the start of the interval. If the
client hasn't sent a message in the
ClientTimeoutInterval set on the
server, the server considers the client
disconnected.

In the .NET Client, timeout values are specified as TimeSpan values.

.NET
JavaScript
Java

OPTION DEFAULT VALUE DESCRIPTION

ServerTimeout 30 seconds (30,000 milliseconds) Timeout for server activity. If 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.
 OPTION DEFAULT VALUE DESCRIPTION

HandshakeTimeout 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.

Configure additional options

Additional options can be configured in the WithUrl ( withUrl in JavaScript) method on HubConnectionBuilder or
on the various configuration APIs on the HttpHubConnectionBuilder in the Java client:
.NET
JavaScript
Java

.NET OPTION DEFAULT VALUE DESCRIPTION

AccessTokenProvider null A function returning a string that is

provided as a Bearer authentication
token in HTTP requests.

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 Empty A collection of TLS certificates to send

to authenticate requests.

Cookies Empty A collection of HTTP cookies to send

with every HTTP request.

Credentials Empty Credentials to send with every HTTP

request.

CloseTimeout 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 Empty A Map of additional HTTP headers to

send with every HTTP request.
 .NET OPTION DEFAULT VALUE DESCRIPTION

HttpMessageHandlerFactory 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 null An HTTP proxy to use when sending

HTTP requests.

UseDefaultCredentials false Set this boolean to send the default

credentials for HTTP and WebSockets
requests. This enables the use of
Windows authentication.

WebSocketConfiguration 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.

In the .NET Client, these options can be modified by the options delegate provided to WithUrl :

var connection = new HubConnectionBuilder()

.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 :

let connection = new signalR.HubConnectionBuilder()

.withUrl("/myhub", {
skipNegotiation: true,
transport: signalR.HttpTransportType.WebSockets
})
.build();

In the Java client, these options can be configured with the methods on the HttpHubConnectionBuilder returned
from the HubConnectionBuilder.create("HUB URL")
 HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/myhub")
.withHeader("Foo", "Bar")
.shouldSkipNegotiate(true)
.withHandshakeResponseTimeout(30*1000)
.build();

Additional resources
Get started with ASP.NET Core SignalR
Use hubs in ASP.NET Core SignalR
ASP.NET Core SignalR JavaScript client
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
7/23/2019 • 8 minutes to read • Edit Online

By Andrew Stanton-Nurse
View or download sample code (how to download)

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.
The following is an example of Startup.Configure which uses SignalR and ASP.NET Core authentication:

public void Configure(IApplicationBuilder app)

{
...

app.UseStaticFiles();

app.UseAuthentication();

app.UseSignalR(hubs =>
{
hubs.MapHub<ChatHub>("/chat");
});

app.UseMvc(routes =>
{
routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");
});
}

NOTE
The order in which you register the SignalR and ASP.NET Core authentication middleware matters. Always call
UseAuthentication before UseSignalR so that SignalR has a user on the HttpContext .

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.
Cookies are a browser-specific way to send access tokens, but non-browser clients can send them. 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
The client can provide an access token instead of using a cookie. The server validates the token and uses it to
identify the user. This validation is done only when the connection is established. During the life of the connection,
the server doesn't automatically revalidate to check for token revocation.
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:

var connection = new HubConnectionBuilder()

.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:

public void ConfigureServices(IServiceCollection services)

{
services.AddDbContext<ApplicationDbContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")));

services.AddIdentity<ApplicationUser, IdentityRole>()
.AddEntityFrameworkStores<ApplicationDbContext>()
.AddDefaultTokenProviders();

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,
 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;
}
return Task.CompletedTask;
}
};
});

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

services.AddSignalR();

// 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>();

// Change to use email as the user identifier for SignalR

// services.AddSingleton<IUserIdProvider, EmailBasedUserIdProvider>();

// WARNING: use *either* the NameUserIdProvider *or* the

// EmailBasedUserIdProvider, but do not use both.
}

Cookies vs. bearer tokens

Because cookies are specific to browsers, sending them from other kinds of clients adds complexity compared to
sending bearer tokens. For this reason, cookie authentication isn't recommended unless the app only needs to
authenticate users from the browser client. Bearer token authentication is the recommended approach when using
clients other than the browser client.
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?.Identity?.Name;
}
}

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.

public void ConfigureServices(IServiceCollection services)

{
// ... other services ...

services.AddSignalR();
services.AddSingleton<IUserIdProvider, NameUserIdProvider>();
}

In the .NET Client, Windows Authentication must be enabled by setting the UseDefaultCredentials property:

var connection = new HubConnectionBuilder()

.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.
Use claims to customize identity handling
An app that authenticates users can derive SignalR user IDs from user claims. To specify how SignalR creates user
IDs, implement IUserIdProvider and register the implementation.
The sample code demonstrates how you would use claims to select the user's email address as the identifying
property.

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.
 public class EmailBasedUserIdProvider : IUserIdProvider
{
public virtual string GetUserId(HubConnectionContext connection)
{
return connection.User?.FindFirst(ClaimTypes.Email)?.Value;
}
}

The account registration adds a claim with type ClaimsTypes.Email to the ASP.NET identity database.

// create a new user

var user = new ApplicationUser { UserName = Input.Email, Email = Input.Email };
var result = await _userManager.CreateAsync(user, Input.Password);

// add the email claim and value for this user

await _userManager.AddClaimAsync(user, new Claim(ClaimTypes.Email, Input.Email));

Register this component in your Startup.ConfigureServices .

services.AddSingleton<IUserIdProvider, EmailBasedUserIdProvider>();

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")]
public class ChatHub : Hub
{
}

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 class ChatHub : Hub
{
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) ...
}
}

Use authorization handlers to customize hub method authorization

SignalR provides a custom resource to authorization handlers when a hub method requires authorization. The
resource is an instance of HubInvocationContext . The HubInvocationContext includes the HubCallerContext , the
name of the hub method being invoked, and the arguments to the hub method.
Consider the example of a chat room allowing multiple organization sign-in via Azure Active Directory. Anyone
with a Microsoft account can sign in to chat, but only members of the owning organization should be able to ban
users or view users' chat histories. Furthermore, we might want to restrict certain functionality from certain users.
Using the updated features in ASP.NET Core 3.0, this is entirely possible. Note how the
DomainRestrictedRequirement serves as a custom IAuthorizationRequirement . Now that the HubInvocationContext
resource parameter is being passed in, the internal logic can inspect the context in which the Hub is being called
and make decisions on allowing the user to execute individual Hub methods.
 [Authorize]
public class ChatHub : Hub
{
public void SendMessage(string message)
{
}

[Authorize("DomainRestricted")]
public void BanUser(string username)
{
}

[Authorize("DomainRestricted")]
public void ViewUserHistory(string username)
{
}
}

public class DomainRestrictedRequirement :

AuthorizationHandler<DomainRestrictedRequirement, HubInvocationContext>,
IAuthorizationRequirement
{
protected override Task HandleRequirementAsync(AuthorizationHandlerContext context,
DomainRestrictedRequirement requirement,
HubInvocationContext resource)
{
if (IsUserAllowedToDoThis(resource.HubMethodName, context.User.Identity.Name) &&
context.User.Identity.Name.EndsWith("@microsoft.com"))
{
context.Succeed(requirement);
}
return Task.CompletedTask;
}

private bool IsUserAllowedToDoThis(string hubMethodName,

string currentUsername)
{
return !(currentUsername.Equals("[email protected]") &&
hubMethodName.Equals("banUser", StringComparison.OrdinalIgnoreCase));
}
}

In Startup.ConfigureServices , add the new policy, providing the custom DomainRestrictedRequirement requirement
as a parameter to create the DomainRestricted policy.

public void ConfigureServices(IServiceCollection services)

{
// ... other services ...

services
.AddAuthorization(options =>
{
options.AddPolicy("DomainRestricted", policy =>
{
policy.Requirements.Add(new DomainRestrictedRequirement());
});
});
}

In the preceding example, the DomainRestrictedRequirement class is both an IAuthorizationRequirement and its
own AuthorizationHandler for that requirement. It's acceptable to split these two components into separate
classes to separate concerns. A benefit of the example's approach is there's no need to inject the
AuthorizationHandler during startup, as the requirement and the handler are the same thing.
Additional resources
Bearer Token Authentication in ASP.NET Core
Resource-based Authorization
 Security considerations in ASP.NET Core SignalR
4/26/2019 • 4 minutes to read • Edit Online

By Andrew Stanton-Nurse
This article provides information on securing SignalR.

Cross-origin resource sharing

Cross-origin resource sharing (CORS ) can be used to allow cross-origin SignalR connections in the browser. If
JavaScript code is hosted on a different domain from the SignalR app, CORS middleware must be enabled to allow
the JavaScript to connect to the SignalR app. Allow cross-origin requests only from domains you trust or control.
For example:
Your site is hosted on http://www.example.com
Your SignalR app is hosted on http://signalr.example.com
CORS should be configured in the SignalR app to only allow the origin www.example.com .
For more information on configuring CORS, see Enable Cross-Origin Requests (CORS ). SignalR requires the
following CORS policies:
Allow the specific expected origins. Allowing any origin is possible but is not secure or recommended.
HTTP methods GET and POST must be allowed.
Credentials must be enabled, even when authentication is not used.
For example, the following CORS policy allows a SignalR browser client hosted on https://example.com to access
the SignalR app hosted on https://signalr.example.com :

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
// ... other middleware ...

// Make sure the CORS middleware is ahead of SignalR.

app.UseCors(builder =>
{
builder.WithOrigins("https://example.com")
.AllowAnyHeader()
.WithMethods("GET", "POST")
.AllowCredentials();
});

// ... other middleware ...

app.UseSignalR(routes =>
{
routes.MapHub<ChatHub>("/chatHub");
});

// ... other middleware ...

}
 NOTE
SignalR is not compatible with the built-in CORS feature in Azure App Service.

WebSocket Origin Restriction

The protections provided by CORS don't apply to WebSockets. For origin restriction on WebSockets, read
WebSockets origin restriction.
The protections provided by CORS don't apply to WebSockets. Browsers do not:
Perform CORS pre-flight requests.
Respect the restrictions specified in Access-Control headers when making WebSocket requests.
However, browsers do send the Origin header when issuing WebSocket requests. Applications should be
configured to validate these headers to ensure that only WebSockets coming from the expected origins are
allowed.
In ASP.NET Core 2.1 and later, header validation can be achieved using a custom middleware placed before
UseSignalR , and authentication middleware in Configure :
 // In Startup, add a static field listing the allowed Origin values:
private static readonly HashSet<string> _allowedOrigins = new HashSet<string>()
{
// Add allowed origins here. For example:
"https://www.mysite.com",
"https://mysite.com",
};

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
// ... other middleware ...

// Validate Origin header on WebSocket requests to prevent unexpected cross-site

// WebSocket requests.
app.Use((context, next) =>
{
// Check for a WebSocket request.
if (string.Equals(context.Request.Headers["Upgrade"], "websocket"))
{
var origin = context.Request.Headers["Origin"];

// If there is an origin header, and the origin header doesn't match

// an allowed value:
if (!string.IsNullOrEmpty(origin) && !_allowedOrigins.Contains(origin))
{
// The origin is not allowed, reject the request
context.Response.StatusCode = StatusCodes.Status403Forbidden;
return Task.CompletedTask;
}
}

// The request is a valid Origin or not a WebSocket request, so continue.

return next();
});

// ... other middleware ...

app.UseSignalR(routes =>
{
routes.MapHub<ChatHub>("/chatHub");
});

// ... other middleware ...

}

NOTE
The Origin header is controlled by the client and, like the Referer header, can be faked. These headers should not be
used as an authentication mechanism.

Access token logging

When using WebSockets or Server-Sent Events, the browser client sends the access token in the query string.
Receiving the access token via query string is generally as secure as using the standard Authorization header. You
should always use HTTPS to ensure a secure end-to-end connection between the client and the server. Many web
servers log the URL for each request, including the query string. Logging the URLs may log the access token.
ASP.NET Core logs the URL for each request by default, which will include the query string. For example:
 info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
Request starting HTTP/1.1 GET http://localhost:5000/myhub?access_token=1234

If you have concerns about logging this data with your server logs, you can disable this logging entirely by
configuring the Microsoft.AspNetCore.Hosting logger to the Warning level or above (these messages are written at
Info level). See the documentation on Log Filtering for more information. If you still want to log certain request
information, you can write a middleware to log the data you require and filter out the access_token query string
value (if present).

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. Exception message delivery to the client can be overridden (for
example in development or test) with EnableDetailedErrors . Exception messages should not be exposed to the
client in production apps.

Buffer management
SignalR uses per-connection buffers to manage incoming and outgoing messages. By default, SignalR limits these
buffers to 32 KB. The largest message a client or server can send is 32 KB. The maximum memory consumed by a
connection for messages is 32 KB. If your messages are always smaller than 32 KB, you can reduce the limit, which:
Prevents a client from being able to send a larger message.
The server will never need to allocate large buffers to accept messages.
If your messages are larger than 32 KB, you can increase the limit. Increasing this limit means:
The client can cause the server to allocate large memory buffers.
Server allocation of large buffers may reduce the number of concurrent connections.
There are 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 (including return values from hub methods) larger than this limit, an exception will be thrown.
Setting the limit to 0 disables the limit. Removing the limit allows a client to send a message of any size. Malicious
clients sending large messages can cause excess memory to be allocated. Excess memory usage can significantly
reduce the number of concurrent connections.
 Use MessagePack Hub Protocol in SignalR for
ASP.NET Core
4/26/2019 • 4 minutes to read • Edit Online

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.

services.AddSignalR()
.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.

services.AddSignalR()
.AddMessagePackProtocol(options =>
{
options.FormatterResolvers = new List<MessagePack.IFormatterResolver>()
{
MessagePack.Resolvers.StandardResolver.Instance
};
});

Configure MessagePack on the client

 NOTE
JSON is enabled by default for the supported clients. Clients can only support a single protocol. Adding MessagePack
support will replace any previously configured protocols.

.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/signalr/signalr.js"></script>
<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.

const connection = new signalR.HubConnectionBuilder()

.withUrl("/chatHub")
.withHubProtocol(new signalR.protocols.msgpack.MessagePackHubProtocol())
.build();

NOTE
At this time, there are no configuration options for the MessagePack protocol on the JavaScript client.
MessagePack quirks
There are a few issues to be aware of when using the MessagePack Hub Protocol.
MessagePack is case -sensitive
The MessagePack protocol is case-sensitive. For example, consider the following C# class:

public class ChatMessage

{
public string Sender { get; }
public string Message { get; }
}

When sending from the JavaScript client, you must use PascalCased property names, since the casing must match
the C# class exactly. For example:

connection.invoke("SomeMethod", { Sender: "Sally", Message: "Hello!" });

Using camelCased names won't properly bind to the C# class. You can work around this by using the Key
attribute to specify a different name for the MessagePack property. For more information, see the MessagePack-
CSharp documentation.
DateTime.Kind is not preserved when serializing/deserializing
The MessagePack protocol doesn't provide a way to encode the Kind value of a DateTime . As a result, when
deserializing a date, the MessagePack Hub Protocol assumes the incoming date is in UTC format. If you're working
with DateTime values in local time, we recommend converting to UTC before sending them. Convert them from
UTC to local time when you receive them.
For more information on this limitation, see GitHub issue aspnet/SignalR#2632.
DateTime.MinValue is not supported by MessagePack in JavaScript
The msgpack5 library used by the SignalR JavaScript client doesn't support the timestamp96 type in
MessagePack. This type is used to encode very large date values (either very early in the past or very far in the
future). The value of DateTime.MinValue is January 1, 0001 which must be encoded in a timestamp96 value.
Because of this, sending DateTime.MinValue to a JavaScript client isn't supported. When DateTime.MinValue is
received by the JavaScript client, the following error is thrown:

Uncaught Error: unable to find ext type 255 at decoder.js:427

Usually, DateTime.MinValue is used to encode a "missing" or null value. If you need to encode that value in
MessagePack, use a nullable DateTime value ( DateTime? ) or encode a separate bool value indicating if the date is
present.
For more information on this limitation, see GitHub issue aspnet/SignalR#2228.
MessagePack support in "ahead-of-time" compilation environment
The MessagePack-CSharp library used by the .NET client and server uses code generation to optimize
serialization. As a result, it isn't supported by default on environments that use "ahead-of-time" compilation (such
as Xamarin iOS or Unity). It's possible to use MessagePack in these environments by "pre-generating" the
serializer/deserializer code. For more information, see the MessagePack-CSharp documentation. Once you have
pre-generated the serializers, you can register them using the configuration delegate passed to
AddMessagePackProtocol :
 services.AddSignalR()
.AddMessagePackProtocol(options =>
{
options.FormatterResolvers = new List<MessagePack.IFormatterResolver>()
{
MessagePack.Resolvers.GeneratedResolver.Instance,
MessagePack.Resolvers.StandardResolver.Instance
};
});

Type checks are more strict in MessagePack

The JSON Hub Protocol will perform type conversions during deserialization. For example, if the incoming object
has a property value that is a number ( { foo: 42 } ) but the property on the .NET class is of type string , the
value will be converted. However, MessagePack doesn't perform this conversion and will throw an exception that
can be seen in server-side logs (and in the console):

InvalidDataException: Error binding arguments. Make sure that the types of the provided values match the types
of the hub method being invoked.

For more information on this limitation, see GitHub issue aspnet/SignalR#2937.

Related resources
Get Started
.NET client
JavaScript client
 Use streaming in ASP.NET Core SignalR
6/6/2019 • 9 minutes to read • Edit Online

By Brennan Conroy
ASP.NET Core SignalR supports streaming from client to server and from server to client. This is useful for
scenarios where fragments of data arrive over time. When streaming, each fragment is sent to the client or server
as soon as it becomes available, rather than waiting for all of the data to become available.
ASP.NET Core SignalR supports streaming return values of server methods. This is useful for scenarios where
fragments of data arrive 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.
View or download sample code (how to download)

Set up a hub for streaming

A hub method automatically becomes a streaming hub method when it returns IAsyncEnumerable<T>,
ChannelReader<T>, Task<IAsyncEnumerable<T>> , or Task<ChannelReader<T>> .
A hub method automatically becomes a streaming hub method when it returns a ChannelReader<T> or a
Task<ChannelReader<T>> .

Server-to -client streaming

Streaming hub methods can return IAsyncEnumerable<T> in addition to ChannelReader<T> . The simplest way to
return IAsyncEnumerable<T> is by making the hub method an async iterator method as the following sample
demonstrates. Hub async iterator methods can accept a CancellationToken parameter that's triggered when the
client unsubscribes from the stream. Async iterator methods avoid problems common with Channels, such as not
returning the ChannelReader early enough or exiting the method without completing the ChannelWriter<T>.

NOTE
The following sample requires C# 8.0 or later.
 public class AsyncEnumerableHub : Hub
{
public async IAsyncEnumerable<int> Counter(
int count,
int delay,
CancellationToken cancellationToken)
{
for (var i = 0; i < count; i++)
{
// Check the cancellation token regularly so that the server will stop
// producing items if the client disconnects.
cancellationToken.ThrowIfCancellationRequested();

yield return i;

// Use the cancellationToken in other APIs that accept cancellation

// tokens so the cancellation can flow down to them.
await Task.Delay(delay, cancellationToken);
}
}
}

The following sample shows the basics of streaming data to the client using Channels. Whenever an object is
written to the ChannelWriter<T>, the object is immediately sent to the client. At the end, the ChannelWriter is
completed to tell the client the stream is closed.

NOTE
Write to the ChannelWriter<T> on a background thread and return the ChannelReader as soon as possible. Other hub
invocations are blocked until a ChannelReader is returned.
Wrap logic in a try ... catch . Complete the Channel in the catch and outside the catch to make sure the hub
method invocation is completed properly.
public ChannelReader<int> Counter(
int count,
int delay,
CancellationToken cancellationToken)
{
var channel = Channel.CreateUnbounded<int>();

// We don't want to await WriteItemsAsync, otherwise we'd end up waiting

// for all the items to be written before returning the channel back to
// the client.
_ = WriteItemsAsync(channel.Writer, count, delay, cancellationToken);

return channel.Reader;
}

private async Task WriteItemsAsync(

ChannelWriter<int> writer,
int count,
int delay,
CancellationToken cancellationToken)
{
Exception localException = null;
try
{
for (var i = 0; i < count; i++)
{
await writer.WriteAsync(i, cancellationToken);

// Use the cancellationToken in other APIs that accept cancellation

// tokens so the cancellation can flow down to them.
await Task.Delay(delay, cancellationToken);
}
}
catch (Exception ex)
{
localException = ex;
}

writer.Complete(localException);
}
public class StreamHub : Hub
{
public ChannelReader<int> Counter(
int count,
int delay,
CancellationToken cancellationToken)
{
var channel = Channel.CreateUnbounded<int>();

// We don't want to await WriteItemsAsync, otherwise we'd end up waiting

// for all the items to be written before returning the channel back to
// the client.
_ = WriteItemsAsync(channel.Writer, count, delay, cancellationToken);

return channel.Reader;
}

private async Task WriteItemsAsync(

ChannelWriter<int> writer,
int count,
int delay,
CancellationToken cancellationToken)
{
try
{
for (var i = 0; i < count; i++)
{
// Check the cancellation token regularly so that the server will stop
// producing items if the client disconnects.
cancellationToken.ThrowIfCancellationRequested();
await writer.WriteAsync(i);

// Use the cancellationToken in other APIs that accept cancellation

// tokens so the cancellation can flow down to them.
await Task.Delay(delay, cancellationToken);
}
}
catch (Exception ex)
{
writer.TryComplete(ex);
}

writer.TryComplete();
}
}
 public class StreamHub : Hub
{
public ChannelReader<int> Counter(int count, int delay)
{
var channel = Channel.CreateUnbounded<int>();

// We don't want to await WriteItemsAsync, otherwise we'd end up waiting

// for all the items to be written before returning the channel back to
// the client.
_ = WriteItemsAsync(channel.Writer, count, delay);

return channel.Reader;
}

private async Task WriteItemsAsync(

ChannelWriter<int> writer,
int count,
int delay)
{
try
{
for (var i = 0; i < count; i++)
{
await writer.WriteAsync(i);
await Task.Delay(delay);
}
}
catch (Exception ex)
{
writer.TryComplete(ex);
}

writer.TryComplete();
}
}

Server-to-client streaming hub methods can accept a CancellationToken parameter that's triggered when the client
unsubscribes from the stream. Use this token to stop the server operation and release any resources if the client
disconnects before the end of the stream.
Client-to -server streaming
A hub method automatically becomes a client-to-server streaming hub method when it accepts one or more
objects of type ChannelReader<T> or IAsyncEnumerable<T>. The following sample shows the basics of reading
streaming data sent from the client. Whenever the client writes to the ChannelWriter<T>, the data is written into
the ChannelReader on the server from which the hub method is reading.

public async Task UploadStream(ChannelReader<string> stream)

{
while (await stream.WaitToReadAsync())
{
while (stream.TryRead(out var item))
{
// do something with the stream item
Console.WriteLine(item);
}
}
}

An IAsyncEnumerable<T> version of the method follows.

 NOTE
The following sample requires C# 8.0 or later.

public async Task UploadStream(IAsyncEnumerable<Stream> stream)

{
await foreach (var item in stream)
{
Console.WriteLine(item);
}
}

.NET client
Server-to -client streaming
The StreamAsync and StreamAsChannelAsync methods on HubConnection are used to invoke server-to-client
streaming methods. Pass the hub method name and arguments defined in the hub method to StreamAsync or
StreamAsChannelAsync . The generic parameter on StreamAsync<T> and StreamAsChannelAsync<T> specifies the type
of objects returned by the streaming method. An object of type IAsyncEnumerable<T> or ChannelReader<T> is
returned from the stream invocation and represents the stream on the client.
A StreamAsync example that returns IAsyncEnumerable<int> :

// Call "Cancel" on this CancellationTokenSource to send a cancellation message to

// the server, which will trigger the corresponding token in the hub method.
var cancellationTokenSource = new CancellationTokenSource();
var stream = await hubConnection.StreamAsync<int>(
"Counter", 10, 500, cancellationTokenSource.Token);

await foreach (var count in stream)

{
Console.WriteLine($"{count}");
}

Console.WriteLine("Streaming completed");

A corresponding StreamAsChannelAsync example that returns ChannelReader<int> :

// Call "Cancel" on this CancellationTokenSource to send a cancellation message to

// the server, which will trigger the corresponding token in the hub method.
var cancellationTokenSource = new CancellationTokenSource();
var channel = await hubConnection.StreamAsChannelAsync<int>(
"Counter", 10, 500, cancellationTokenSource.Token);

// 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");

The StreamAsChannelAsync method on HubConnection is used to invoke a server-to-client 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.

// Call "Cancel" on this CancellationTokenSource to send a cancellation message to

// the server, which will trigger the corresponding token in the hub method.
var cancellationTokenSource = new CancellationTokenSource();
var channel = await hubConnection.StreamAsChannelAsync<int>(
"Counter", 10, 500, cancellationTokenSource.Token);

// 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");

The StreamAsChannelAsync method on HubConnection is used to invoke a server-to-client 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.

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");

Client-to -server streaming

There are two ways to invoke a client-to-server streaming hub method from the .NET client. You can either pass in
an IAsyncEnumerable<T> or a ChannelReader as an argument to SendAsync , InvokeAsync , or StreamAsChannelAsync ,
depending on the hub method invoked.
Whenever data is written to the IAsyncEnumerable or ChannelWriter object, the hub method on the server receives
a new item with the data from the client.
If using an IAsyncEnumerable object, the stream ends after the method returning stream items exits.

NOTE
The following sample requires C# 8.0 or later.
 async IAsyncEnumerable<string> clientStreamData()
{
for (var i = 0; i < 5; i++)
{
var data = await FetchSomeData();
yield return data;
}
//After the for loop has completed and the local function exits the stream completion will be sent.
}

await connection.SendAsync("UploadStream", clientStreamData());

Or if you're using a ChannelWriter , you complete the channel with channel.Writer.Complete() :

var channel = Channel.CreateBounded<string>(10);

await connection.SendAsync("UploadStream", channel.Reader);
await channel.Writer.WriteAsync("some data");
await channel.Writer.WriteAsync("some more data");
channel.Writer.Complete();

JavaScript client
Server-to -client streaming
JavaScript clients call server-to-client streaming methods on hubs with 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 receive notifications from the stream invocation.

connection.stream("Counter", 10, 500)

.subscribe({
next: (item) => {
var li = document.createElement("li");
li.textContent = item;
document.getElementById("messagesList").appendChild(li);
},
complete: () => {
var li = document.createElement("li");
li.textContent = "Stream completed";
document.getElementById("messagesList").appendChild(li);
},
error: (err) => {
var li = document.createElement("li");
li.textContent = err;
document.getElementById("messagesList").appendChild(li);
},
});

To end the stream from the client, call the dispose method on the ISubscription that's returned from the
subscribe method. Calling this method causes cancellation of the CancellationToken parameter of the Hub
method, if you provided one.
 connection.stream("Counter", 10, 500)
.subscribe({
next: (item) => {
var li = document.createElement("li");
li.textContent = item;
document.getElementById("messagesList").appendChild(li);
},
complete: () => {
var li = document.createElement("li");
li.textContent = "Stream completed";
document.getElementById("messagesList").appendChild(li);
},
error: (err) => {
var li = document.createElement("li");
li.textContent = err;
document.getElementById("messagesList").appendChild(li);
},
});

To end the stream from the client, call the dispose method on the ISubscription that's returned from the
subscribe method.

Client-to -server streaming

JavaScript clients call client-to-server streaming methods on hubs by passing in a Subject as an argument to
send , invoke , or stream , depending on the hub method invoked. The Subject is a class that looks like a
Subject . For example in RxJS, you can use the Subject class from that library.

const subject = new signalR.Subject();

yield connection.send("UploadStream", subject);
var iteration = 0;
const intervalHandle = setInterval(() => {
iteration++;
subject.next(iteration.toString());
if (iteration === 10) {
clearInterval(intervalHandle);
subject.complete();
}
}, 500);

Calling subject.next(item) with an item writes the item to the stream, and the hub method receives the item on
the server.
To end the stream, call subject.complete() .

Java client
Server-to -client streaming
The SignalR Java client uses the stream method to invoke streaming methods. stream accepts three or more
arguments:
The expected type of the stream items.
The name of the hub method.
Arguments defined in the hub method.
 hubConnection.stream(String.class, "ExampleStreamingHubMethod", "Arg1")
.subscribe(
(item) -> {/* Define your onNext handler here. */ },
(error) -> {/* Define your onError handler here. */},
() -> {/* Define your onCompleted handler here. */});

The stream method on HubConnection returns an Observable of the stream item type. The Observable type's
subscribe method is where onNext , onError and onCompleted handlers are defined.

Additional resources
Hubs
.NET client
JavaScript client
Publish to Azure
 Differences between ASP.NET SignalR and ASP.NET
Core SignalR
6/23/2019 • 3 minutes to read • Edit Online

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

Java Client GitHub Repository (deprecated) Maven package com.microsoft.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 aren't supported in ASP.NET Core SignalR. If the client is disconnected, the user must
explicitly start a new connection if they want to reconnect. In ASP.NET SignalR, SignalR attempts to reconnect to
the server if the connection is dropped.
Protocol support
ASP.NET Core SignalR supports JSON, as well as a new binary protocol based on MessagePack. Additionally,
custom protocols can be created.
Transports
The Forever Frame transport is not supported in ASP.NET Core SignalR.

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
Startup.ConfigureServices .
 services.AddSignalR()

To configure routing, map routes to hubs inside the UseSignalR method call in the Startup.Configure method.

app.UseSignalR(routes =>
{
routes.MapHub<ChatHub>("/hub");
});

Sticky sessions
The scaleout model for ASP.NET SignalR allows clients to reconnect and send messages to any server in the farm.
In ASP.NET Core SignalR, the client must interact with the same server for the duration of the connection. For
scaleout using Redis, that means sticky sessions are required. For scaleout using Azure SignalR Service, sticky
sessions are not required because the service handles connections to clients.
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.
PersistentConnection removal
In ASP.NET Core SignalR, the PersistentConnection class has been removed.
GlobalHost
ASP.NET Core has dependency injection (DI) built into the framework. Services can use DI to access the
HubContext. The GlobalHost object that is used in ASP.NET SignalR to get a HubContext doesn't exist in ASP.NET
Core SignalR.
HubPipeline
ASP.NET Core SignalR doesn't have support for HubPipeline modules.

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
npm install @aspnet/signalr

jQuery
The dependency on jQuery has been removed, however projects can still use jQuery.
Internet Explorer support
ASP.NET Core SignalR requires Microsoft Internet Explorer 11 or later (ASP.NET SignalR supported Microsoft
Internet Explorer 8 and later).
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.

const connection = new signalR.HubConnectionBuilder()

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

Use the on method to specify client methods that the hub can call.

connection.on("ReceiveMessage", (user, message) => {

const msg = message.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
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.

connection.start().catch(err => console.error(err.toString()));

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 SQL Server and Redis. ASP.NET Core SignalR supports 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
Redis Backplane
Additional resources
Hubs
JavaScript client
.NET client
Supported platforms
 WebSockets support in ASP.NET Core
6/2/2019 • 7 minutes to read • Edit Online

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). How to run.

SignalR
ASP.NET Core SignalR is a library that simplifies adding real-time web functionality to apps. It uses WebSockets
whenever possible.
For most applications, we recommend SignalR over raw WebSockets. SignalR provides transport fallback for
environments where WebSockets is not available. It also provides a simple remote procedure call app model. And
in most scenarios, SignalR has no significant performance disadvantage compared to using raw WebSockets.

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:
Windows 8 / Windows Server 2012 or later
IIS 8 / IIS 8 Express
WebSockets must be enabled (See the IIS/IIS Express support section.).
If the app runs on HTTP.sys:
Windows 8 / Windows Server 2012 or later
For supported browsers, see https://caniuse.com/#feat=websockets.

NuGet package
Install the Microsoft.AspNetCore.WebSockets package.

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. The default is two minutes.
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. The default is 4 KB.
The following settings can be configured:
KeepAliveInterval - How frequently to send "ping" frames to the client to ensure proxies keep the connection
open. The default is two minutes.
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. The default is 4 KB.
AllowedOrigins - A list of allowed Origin header values for WebSocket requests. By default, all origins are
allowed. See "WebSocket origin restriction" below for details.

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 action method, for example)
check if it's a WebSocket request and accept the WebSocket request.
The following example is from later in the Configure method:

app.Use(async (context, next) =>

{
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 .
When using a WebSocket, you must keep the middleware pipeline running for the duration of the connection. If
you attempt to send or receive a WebSocket message after the middleware pipeline ends, you may get an
exception like the following:
 System.Net.WebSockets.WebSocketException (0x80004005): The remote party closed the WebSocket connection
without completing the close handshake. ---> System.ObjectDisposedException: Cannot write to the response
body, the response has completed.
Object name: 'HttpResponseStream'.

If you're using a background service to write data to a WebSocket, make sure you keep the middleware pipeline
running. Do this by using a TaskCompletionSource<TResult>. Pass the TaskCompletionSource to your background
service and have it call TrySetResult when you finish with the WebSocket. Then await the Task property during
the request, as shown in the following example:

app.Use(async (context, next) => {

var socket = await context.WebSockets.AcceptWebSocketAsync();
var socketFinishedTcs = new TaskCompletionSource<object>();

BackgroundSocketProcessor.AddSocket(socket, socketFinishedTcs);

await socketFinishedTcs.Task;
});

The WebSocket closed exception can also happen if you return too soon from an action method. If you accept a
socket in an action method, wait for the code that uses the socket to complete before returning from the action
method.
Never use Task.Wait() , Task.Result , or similar blocking calls to wait for the socket to complete, as that can cause
serious threading issues. Always use await .

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),
CancellationToken.None);
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,
CancellationToken.None);
}

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.
Handle client disconnects
The server is not automatically informed when the client disconnects due to loss of connectivity. The server
receives a disconnect message only if the client sends it, which can't be done if the internet connection is lost. If
you want to take some action when that happens, set a timeout after nothing is received from the client within a
certain time window.
If the client isn't always sending messages and you don't want to timeout just because the connection goes idle,
have the client use a timer to send a ping message every X seconds. On the server, if a message hasn't arrived
within 2*X seconds after the previous one, terminate the connection and report that the client disconnected. Wait
for twice the expected time interval to leave extra time for network delays that might hold up the ping message.

WebSocket origin restriction

The protections provided by CORS don't apply to WebSockets. Browsers do not:
Perform CORS pre-flight requests.
Respect the restrictions specified in Access-Control headers when making WebSocket requests.

However, browsers do send the Origin header when issuing WebSocket requests. Applications should be
configured to validate these headers to ensure that only WebSockets coming from the expected origins are
allowed.
If you're hosting your server on "https://server.com" and hosting your client on "https://client.com", add
"https://client.com" to the AllowedOrigins list for WebSockets to verify.

var webSocketOptions = new WebSocketOptions()

{
KeepAliveInterval = TimeSpan.FromSeconds(120),
ReceiveBufferSize = 4 * 1024
};
webSocketOptions.AllowedOrigins.Add("https://client.com");
webSocketOptions.AllowedOrigins.Add("https://www.client.com");

app.UseWebSockets(webSocketOptions);

NOTE
The Origin header is controlled by the client and, like the Referer header, can be faked. Do not use these headers as an
authentication mechanism.

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.

NOTE
WebSockets are always enabled when using IIS Express.

Enabling WebSockets on IIS

To enable support for the WebSocket protocol on Windows Server 2012 or later:
 NOTE
These steps are not required when using IIS Express

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:

NOTE
These steps are not required when using IIS Express

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>

Sample app
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.
 Logging and diagnostics in ASP.NET Core SignalR
6/21/2019 • 7 minutes to read • Edit Online

By Andrew Stanton-Nurse
This article provides guidance for gathering diagnostics from your ASP.NET Core SignalR app to help
troubleshoot issues.

Server-side logging
WARNING
Server-side logs may contain sensitive information from your app. Never post raw logs from production apps to public
forums like GitHub.

Since SignalR is part of ASP.NET Core, it uses the ASP.NET Core logging system. In the default configuration,
SignalR logs very little information, but this can configured. See the documentation on ASP.NET Core logging for
details on configuring ASP.NET Core logging.
SignalR uses two logger categories:
Microsoft.AspNetCore.SignalR – for logs related to Hub Protocols, activating Hubs, invoking methods, and other
Hub-related activities.
Microsoft.AspNetCore.Http.Connections – for logs related to transports such as WebSockets, Long Polling and
Server-Sent Events and low -level SignalR infrastructure.
To enable detailed logs from SignalR, configure both of the preceding prefixes to the Debug level in your
appsettings.json file by adding the following items to the LogLevel sub-section in Logging :

{
"Logging": {
"LogLevel": {
"Default": "Debug",
"System": "Information",
"Microsoft": "Information",
"Microsoft.AspNetCore.SignalR": "Debug",
"Microsoft.AspNetCore.Http.Connections": "Debug"
}
}
}

You can also configure this in code in your CreateWebHostBuilder method:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.ConfigureLogging(logging =>
{
logging.AddFilter("Microsoft.AspNetCore.SignalR", LogLevel.Debug);
logging.AddFilter("Microsoft.AspNetCore.Http.Connections", LogLevel.Debug);
})
.UseStartup<Startup>();

If you aren't using JSON -based configuration, set the following configuration values in your configuration system:
 Logging:LogLevel:Microsoft.AspNetCore.SignalR = Debug
Logging:LogLevel:Microsoft.AspNetCore.Http.Connections = Debug

Check the documentation for your configuration system to determine how to specify nested configuration values.
For example, when using environment variables, two _ characters are used instead of the : (for example,
Logging__LogLevel__Microsoft.AspNetCore.SignalR ).

We recommend using the Debug level when gathering more detailed diagnostics for your app. The Trace level
produces very low -level diagnostics and is rarely needed to diagnose issues in your app.

Access server-side logs

How you access server-side logs depends on the environment in which you're running.
As a console app outside IIS
If you're running in a console app, the Console logger should be enabled by default. SignalR logs will appear in the
console.
Within IIS Express from Visual Studio
Visual Studio displays the log output in the Output window. Select the ASP.NET Core Web Server drop down
option.
Azure App Service
Enable the Application Logging (Filesystem ) option in the Diagnostics logs section of the Azure App Service
portal and configure the Level to Verbose . Logs should be available from the Log streaming service and in logs
on the file system of the App Service. For more information, see Azure log streaming.
Other environments
If the app is deployed to another environment (for example, Docker, Kubernetes, or Windows Service), see
Logging in .NET Core and ASP.NET Core for more information on how to configure logging providers suitable for
the environment.

JavaScript client logging

WARNING
Client-side logs may contain sensitive information from your app. Never post raw logs from production apps to public
forums like GitHub.

When using the JavaScript client, you can configure logging options using the configureLogging method on
HubConnectionBuilder :

let connection = new signalR.HubConnectionBuilder()

.withUrl("/my/hub/url")
.configureLogging(signalR.LogLevel.Debug)
.build();

To disable logging entirely, specify signalR.LogLevel.None in the configureLogging method.

The following table shows log levels available to the JavaScript client. Setting the log level to one of these values
enables logging at that level and all levels above it in the table.
 LEVEL DESCRIPTION

None No messages are logged.

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.

Once you've configured the verbosity, the logs will be written to the Browser Console (or Standard Output in a
NodeJS app).
If you want to send logs to a custom logging system, you can provide a JavaScript object implementing the
ILogger interface. The only method that needs to be implemented is log , which takes the level of the event and
the message associated with the event. For example:

import { ILogger, LogLevel, HubConnectionBuilder } from "@aspnet/signalr";

export class MyLogger implements ILogger {

log(logLevel: LogLevel, message: string) {
// Use `message` and `logLevel` to record the log message to your own system
}
}

// later on, when configuring your connection...

let connection = new HubConnectionBuilder()

.withUrl("/my/hub/url")
.configureLogging(new MyLogger())
.build();

.NET client logging

WARNING
Client-side logs may contain sensitive information from your app. Never post raw logs from production apps to public
forums like GitHub.

To get logs from the .NET client, you can use the ConfigureLogging method on HubConnectionBuilder . This works
the same way as the ConfigureLogging method on WebHostBuilder and HostBuilder . You can configure the same
logging providers you use in ASP.NET Core. However, you have to manually install and enable the NuGet
packages for the individual logging providers.
Console logging
In order to enable Console logging, add the Microsoft.Extensions.Logging.Console package. Then, use the
AddConsole method to configure the console logger:
 var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/my/hub/url")
.ConfigureLogging(logging =>
{
// Log to the Console
logging.AddConsole();

// This will set ALL logging to Debug level

logging.SetMinimumLevel(LogLevel.Debug);
})
.Build();

Debug output window logging

You can also configure logs to go to the Output window in Visual Studio. Install the
Microsoft.Extensions.Logging.Debug package and use the AddDebug method:

var connection = new HubConnectionBuilder()

.WithUrl("https://example.com/my/hub/url")
.ConfigureLogging(logging =>
{
// Log to the Output Window
logging.AddDebug();

// This will set ALL logging to Debug level

logging.SetMinimumLevel(LogLevel.Debug)
})
.Build();

Other logging providers

SignalR supports other logging providers such as Serilog, Seq, NLog, or any other logging system that integrates
with Microsoft.Extensions.Logging . If your logging system provides an ILoggerProvider , you can register it with
AddProvider :

var connection = new HubConnectionBuilder()

.WithUrl("https://example.com/my/hub/url")
.ConfigureLogging(logging =>
{
// Log to your custom provider
logging.AddProvider(new MyCustomLoggingProvider());

// This will set ALL logging to Debug level

logging.SetMinimumLevel(LogLevel.Debug)
})
.Build();

Control verbosity
If you are logging from other places in your app, changing the default level to Debug may be too verbose. You can
use a Filter to configure the logging level for SignalR logs. This can be done in code, in much the same way as on
the server:
 var connection = new HubConnectionBuilder()
.WithUrl("https://example.com/my/hub/url")
.ConfigureLogging(logging =>
{
// Register your providers

// Set the default log level to Information, but to Debug for SignalR-related loggers.
logging.SetMinimumLevel(LogLevel.Information);
logging.AddFilter("Microsoft.AspNetCore.SignalR", LogLevel.Debug);
logging.AddFilter("Microsoft.AspNetCore.Http.Connections", LogLevel.Debug);
})
.Build();

Network traces
WARNING
A network trace contains the full contents of every message sent by your app. Never post raw network traces from
production apps to public forums like GitHub.

If you encounter an issue, a network trace can sometimes provide a lot of helpful information. This is particularly
useful if you're going to file an issue on our issue tracker.

Collect a network trace with Fiddler (preferred option)

This method works for all apps.
Fiddler is a very powerful tool for collecting HTTP traces. Install it from telerik.com/fiddler, launch it, and then run
your app and reproduce the issue. Fiddler is available for Windows, and there are beta versions for macOS and
Linux.
If you connect using HTTPS, there are some extra steps to ensure Fiddler can decrypt the HTTPS traffic. For more
details, see the Fiddler documentation.
Once you've collected the trace, you can export the trace by choosing File > Save > All Sessions from the menu
bar.
Collect a network trace with tcpdump (macOS and Linux only)
This method works for all apps.
You can collect raw TCP traces using tcpdump by running the following command from a command shell. You may
need to be root or prefix the command with sudo if you get a permissions error:

tcpdump -i [interface] -w trace.pcap

Replace [interface] with the network interface you wish to capture on. Usually, this is something like /dev/eth0
(for your standard Ethernet interface) or /dev/lo0 (for localhost traffic). For more information, see the tcpdump
man page on your host system.

Collect a network trace in the browser

This method only works for browser-based apps.
Most browser Developer Tools have a "Network" tab that allows you to capture network activity between the
browser and the server. However, these traces don't include WebSocket and Server-Sent Event messages. If you
are using those transports, using a tool like Fiddler or TcpDump (described below ) is a better approach.
Microsoft Edge and Internet Explorer
(The instructions are the same for both Edge and Internet Explorer)
1. Press F12 to open the Dev Tools
2. Click the Network Tab
3. Refresh the page (if needed) and reproduce the problem
4. Click the Save icon in the toolbar to export the trace as a "HAR" file:
Google Chrome
1. Press F12 to open the Dev Tools
2. Click the Network Tab
3. Refresh the page (if needed) and reproduce the problem
4. Right click anywhere in the list of requests and choose "Save as HAR with content":

Mozilla Firefox
1. Press F12 to open the Dev Tools
2. Click the Network Tab
3. Refresh the page (if needed) and reproduce the problem
4. Right click anywhere in the list of requests and choose "Save All As HAR"
Attach diagnostics files to GitHub issues
You can attach Diagnostics files to GitHub issues by renaming them so they have a .txt extension and then
dragging and dropping them on to the issue.

NOTE
Please don't paste the content of log files or network traces into a GitHub issue. These logs and traces can be quite large, and
GitHub usually truncates them.

Additional resources
ASP.NET Core SignalR configuration
ASP.NET Core SignalR JavaScript client
ASP.NET Core SignalR .NET Client
 Introduction to gRPC on ASP.NET Core
4/26/2019 • 2 minutes to read • Edit Online

By John Luo
gRPC is a language agnostic, high-performance Remote Procedure Call (RPC ) framework. For more on gRPC
fundamentals, see the gRPC documentation page.
The main benefits of gRPC are:
Modern high-performance lightweight RPC framework.
Contract-first API development, using Protocol Buffers by default, allowing for language agnostic
implementations.
Tooling available for many languages to generate strongly-typed servers and clients.
Supports client, server, and bi-directional streaming calls.
Reduced network usage with Protobuf binary serialization.
These benefits make gRPC ideal for:
Lightweight microservices where efficiency is critical.
Polyglot systems where multiple languages are required for development.
Point-to-point real-time services that need to handle streaming requests or responses.
While a C# implementation is currently available on the official gRPC page, the current implementation relies on
the native library written in C (gRPC C -core). Work is currently in progress to provide a new implementation
based on the Kestrel HTTP server and the ASP.NET Core stack that is fully managed. The following documents
provide an introduction to building gRPC services with this new implementation.

Additional resources
gRPC services with C#
Create a .NET Core gRPC client and server in ASP.NET Core
gRPC services with ASP.NET Core
Migrating gRPC services from C -core to ASP.NET Core
 gRPC services with C#
8/7/2019 • 3 minutes to read • Edit Online

This document outlines the concepts needed to write gRPC apps in C#. The topics covered here apply to both C -
core-based and ASP.NET Core-based gRPC apps.

proto file
gRPC uses a contract-first approach to API development. Protocol buffers (protobuf) are used as the Interface
Design Language (IDL ) by default. The .proto file contains:
The definition of the gRPC service.
The messages sent between clients and servers.
For more information on the syntax of protobuf files, see the official documentation (protobuf).
For example, consider the greet.proto file used in Get started with gRPC service:
Defines a Greeter service.
The Greeter service defines a SayHello call.
SayHello sends a HelloRequest message and receives a HelloReply message:

syntax = "proto3";

option csharp_namespace = "GrpcGreeter";

package Greet;

// The greeting service definition.

service Greeter {
// Sends a greeting
rpc SayHello (HelloRequest) returns (HelloReply);
}

// The request message containing the user's name.

message HelloRequest {
string name = 1;
}

// The response message containing the greetings.

message HelloReply {
string message = 1;
}

Add a .proto file to a C# app

The .proto file is included in a project by adding it to the <Protobuf> item group:

<ItemGroup>
<Protobuf Include="Protos\greet.proto" GrpcServices="Server"/>
</ItemGroup>

C# Tooling support for .proto files

The tooling package Grpc.Tools is required to generate the C# assets from .proto files. The generated assets (files):
Are generated on an as-needed basis each time the project is built.
Aren't added to the project or checked into source control.
Are a build artifact contained in the obj directory.
This package is required by both the server and client projects. The Grpc.AspNetCore metapackage includes a
reference to Grpc.Tools . Server projects can add Grpc.AspNetCore using the Package Manager in Visual Studio or
by adding a <PackageReference> to the project file:

<PackageReference Include="Grpc.AspNetCore" Version="0.1.22-pre2" />

Client projects should directly reference Grpc.Tools alongside the other packages required to use the gRPC
client. The tooling package isn't required at runtime, so the dependency is marked with PrivateAssets="All" :

<PackageReference Include="Google.Protobuf" Version="3.8.0" />

<PackageReference Include="Grpc.Net.Client" Version="0.1.22-pre2" />
<PackageReference Include="Grpc.Tools" Version="1.22.0-pre1" PrivateAssets="All" />

Generated C# assets
The tooling package generates the C# types representing the messages defined in the included .proto files.
For server-side assets, an abstract service base type is generated. The base type contains the definitions of all the
gRPC calls contained in the .proto file. Create a concrete service implementation that derives from this base type
and implements the logic for the gRPC calls. For the greet.proto , the example described previously, an abstract
GreeterBase type that contains a virtual SayHello method is generated. A concrete implementation
GreeterService overrides the method and implements the logic handling the gRPC call.

public class GreeterService : Greeter.GreeterBase

{
public override Task<HelloReply> SayHello(
HelloRequest request, ServerCallContext context)
{
return Task.FromResult(new HelloReply
{
Message = "Hello " + request.Name
});
}
}

For client-side assets, a concrete client type is generated. The gRPC calls in the .proto file are translated into
methods on the concrete type, which can be called. For the greet.proto , the example described previously, a
concrete GreeterClient type is generated. Call GreeterClient.SayHelloAsync to initiate a gRPC call to the server.
 static async Task Main(string[] args)
{
var httpClient = new HttpClient();
// The port number(5001) must match the port of the gRPC server.
httpClient.BaseAddress = new Uri("https://localhost:5001");
var client = GrpcClient.Create<Greeter.GreeterClient>(httpClient);
var reply = await client.SayHelloAsync(
new HelloRequest { Name = "GreeterClient" });
Console.WriteLine("Greeting: " + reply.Message);
Console.WriteLine("Press any key to exit...");
Console.ReadKey();
}

By default, server and client assets are generated for each .proto file included in the <Protobuf> item group. To
ensure only the server assets are generated in a server project, the GrpcServices attribute is set to Server .

<ItemGroup>
<Protobuf Include="Protos\greet.proto" GrpcServices="Server"/>
</ItemGroup>

Similarly, the attribute is set to Client in client projects.

Additional resources
Introduction to gRPC on ASP.NET Core
Create a .NET Core gRPC client and server in ASP.NET Core
gRPC services with ASP.NET Core
Migrating gRPC services from C -core to ASP.NET Core
 gRPC services with ASP.NET Core
8/7/2019 • 4 minutes to read • Edit Online

This document shows how to get started with gRPC services using ASP.NET Core.

Prerequisites
Visual Studio
Visual Studio Code
Visual Studio for Mac
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 3.0 Preview

Get started with gRPC service in ASP.NET Core

View or download sample code (how to download).
Visual Studio
Visual Studio Code / Visual Studio for Mac
See Get started with gRPC services for detailed instructions on how to create a gRPC project.

Add gRPC services to an ASP.NET Core app

gRPC requires the Grpc.AspNetCore package.
Configure gRPC
gRPC is enabled with the AddGrpc method:
 public class Startup
{
// This method gets called by the runtime. Use this method to add services to the container.
// For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?
LinkID=398940
public void ConfigureServices(IServiceCollection services)
{
services.AddGrpc();
}

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}

app.UseRouting();

app.UseEndpoints(endpoints =>
{
// Communication with gRPC endpoints must be made through a gRPC client.
// To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909
endpoints.MapGrpcService<GreeterService>();
});
}
}

Each gRPC service is added to the routing pipeline through the MapGrpcService method:

public class Startup

{
// This method gets called by the runtime. Use this method to add services to the container.
// For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?
LinkID=398940
public void ConfigureServices(IServiceCollection services)
{
services.AddGrpc();
}

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}

app.UseRouting();

app.UseEndpoints(endpoints =>
{
// Communication with gRPC endpoints must be made through a gRPC client.
// To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909
endpoints.MapGrpcService<GreeterService>();
});
}
}

ASP.NET Core middlewares and features share the routing pipeline, therefore an app can be configured to serve
additional request handlers. The additional request handlers, such as MVC controllers, work in parallel with the
configured gRPC services.
Integration with ASP.NET Core APIs
gRPC services have full access to the ASP.NET Core features such as Dependency Injection (DI) and Logging. For
example, the service implementation can resolve a logger service from the DI container via the constructor:

public class GreeterService : Greeter.GreeterBase

{
public GreeterService(ILogger<GreeterService> logger)
{
}
}

By default, the gRPC service implementation can resolve other DI services with any lifetime (Singleton, Scoped, or
Transient).
Resolve HttpContext in gRPC methods
The gRPC API provides access to some HTTP/2 message data, such as the method, host, header, and trailers.
Access is through the ServerCallContext argument passed to each gRPC method:

public class GreeterService : Greeter.GreeterBase

{
public override Task<HelloReply> SayHello(
HelloRequest request, ServerCallContext context)
{
return Task.FromResult(new HelloReply
{
Message = "Hello " + request.Name
});
}
}

ServerCallContext does not provide full access to HttpContext in all ASP.NET APIs. The GetHttpContext
extension method provides full access to the HttpContext representing the underlying HTTP/2 message in
ASP.NET APIs:

public class GreeterService : Greeter.GreeterBase

{
public override Task<HelloReply> SayHello(
HelloRequest request, ServerCallContext context)
{
var httpContext = context.GetHttpContext();
var clientCertificate = httpContext.Connection.ClientCertificate;

return Task.FromResult(new HelloReply

{
Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
});
}
}

gRPC and ASP.NET Core on macOS

Kestrel doesn't support HTTP/2 with Transport Layer Security (TLS ) on macOS. The ASP.NET Core gRPC
template and samples use TLS by default. You'll see the following error message when you attempt to start the
gRPC server:

Unable to bind to https://localhost:5001 on the IPv4 loopback interface: 'HTTP/2 over TLS is not supported on
macOS due to missing ALPN support.'.
To work around this issue, configure Kestrel and the gRPC client to use HTTP/2 without TLS. You should only do
this during development. Not using TLS will result in gRPC messages being sent without encryption.
Kestrel must configure a HTTP/2 endpoint without TLS in Program.cs :

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.ConfigureKestrel(options =>
{
// Setup a HTTP/2 endpoint without TLS.
options.ListenLocalhost(5000, o => o.Protocols = HttpProtocols.Http2);
});
webBuilder.UseStartup<Startup>();
});

The gRPC client must set the System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport switch to true and use
http in the server address:

// This switch must be set before creating the HttpClient.

AppContext.SetSwitch("System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport", true);

var httpClient = new HttpClient();

// The port number(5000) must match the port of the gRPC server.
httpClient.BaseAddress = new Uri("http://localhost:5000");
var client = GrpcClient.Create<Greeter.GreeterClient>(httpClient);

WARNING
HTTP/2 without TLS should only be used during app development. Production applications should always use transport
security. For more information, see Security considerations in gRPC for ASP.NET Core.

Additional resources
Create a .NET Core gRPC client and server in ASP.NET Core
Introduction to gRPC on ASP.NET Core
gRPC services with C#
Migrating gRPC services from C -core to ASP.NET Core
 gRPC for ASP.NET Core configuration
7/11/2019 • 2 minutes to read • Edit Online

Configure services options

The following table describes options for configuring gRPC services:

OPTION DEFAULT VALUE DESCRIPTION

SendMaxMessageSize null The maximum message size in bytes

that can be sent from the server.
Attempting to send a message that
exceeds the configured maximum
message size results in an exception.

ReceiveMaxMessageSize 4 MB The maximum message size in bytes

that can be received by the server. If the
server receives a message that exceeds
this limit, it throws an exception.
Increasing this value allows the server
to receive larger messages, but can
negatively impact memory
consumption.

EnableDetailedErrors false If true , detailed exception messages

are returned to clients when an
exception is thrown in a service method.
The default is false . Setting
EnableDetailedErrors to true can
leak sensitive information.

CompressionProviders gzip A collection of compression providers

used to compress and decompress
messages. Custom compression
providers can be created and added to
the collection. The default configured
provider supports gzip compression.

ResponseCompressionAlgorithm null The compression algorithm used to

compress messages sent from the
server. The algorithm must match a
compression provider in
CompressionProviders . For the
algorithm to compress a response, the
client must indicate it supports the
algorithm by sending it in the grpc-
accept-encoding header.

ResponseCompressionLevel null The compress level used to compress

messages sent from the server.

Options can be configured for all services by providing an options delegate to the AddGrpc call in
Startup.ConfigureServices :
 public void ConfigureServices(IServiceCollection services)
{
services.AddGrpc(options =>
{
options.EnableDetailedErrors = true;
options.ReceiveMaxMessageSize = 2 * 1024 * 1024; // 2 megabytes
options.SendMaxMessageSize = 5 * 1024 * 1024; // 5 megabytes
});
}

Options for a single service override the global options provided in AddGrpc and can be configured using
AddServiceOptions<TService> :

public void ConfigureServices(IServiceCollection services)

{
services.AddGrpc().AddServiceOptions<MyService>(options =>
{
options.ReceiveMaxMessageSize = 2 * 1024 * 1024;
options.SendMaxMessageSize = 5 * 1024 * 1024;
});
}

Configure client options

The following code sets the client maximum send and receive message size:

static async Task Main(string[] args)

{
var channel = new Channel("localhost:5001", ChannelCredentials.Insecure, new[]{
new ChannelOption(ChannelOptions.MaxSendMessageLength , 2*1024*1024),
new ChannelOption(ChannelOptions.MaxReceiveMessageLength , 5 *1024*1024)
});
var client = new Greeter.GreeterClient(channel);
var reply = await client.SayHelloAsync(
new HelloRequest { Name = "GreeterClient" });
Console.WriteLine("Greeting: " + reply.Message);
await channel.ShutdownAsync();
Console.WriteLine("Press any key to exit...");
Console.ReadKey();
}

Additional resources
Create a .NET Core gRPC client and server in ASP.NET Core
Introduction to gRPC on ASP.NET Core
gRPC services with C#
Migrating gRPC services from C -core to ASP.NET Core
 Authentication and authorization in gRPC for
ASP.NET Core
8/13/2019 • 3 minutes to read • Edit Online

By James Newton-King
View or download sample code (how to download)

Authenticate users calling a gRPC service

gRPC can be used with ASP.NET Core authentication to associate a user with each call.
The following is an example of Startup.Configure which uses gRPC and ASP.NET Core authentication:

public void Configure(IApplicationBuilder app)

{
app.UseRouting();

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

app.UseEndpoints(endpoints =>
{
routes.MapGrpcService<GreeterService>();
});
}

NOTE
The order in which you register the ASP.NET Core authentication middleware matters. Always call UseAuthentication and
UseAuthorization after UseRouting and before UseEndpoints .

The authentication mechanism your app uses during a call needs to be configured. Authentication configuration is
added in Startup.ConfigureServices and will be different depending upon the authentication mechanism your app
uses. For examples of how to secure ASP.NET Core apps, see Authentication samples.
Once authentication has been setup, the user can be accessed in a gRPC service methods via the
ServerCallContext .

public override Task<BuyTicketsResponse> BuyTickets(

BuyTicketsRequest request, ServerCallContext context)
{
var user = context.GetHttpContext().User;

// ... access data from ClaimsPrincipal ...

}

Bearer token authentication

The client can provide an access token for authentication. The server validates the token and uses it to identify the
user.
On the server, bearer token authentication is configured using the JWT Bearer middleware.
In the .NET gRPC client, the token can be sent with calls as a header:

public bool DoAuthenticatedCall(

Ticketer.TicketerClient client, string token)
{
var headers = new Metadata();
headers.Add("Authorization", $"Bearer {token}");

var request = new BuyTicketsRequest { Count = 1 };

var response = await client.BuyTicketsAsync(request, headers);

return response.Success;
}

Client certificate authentication

A client could alternatively provide a client certificate for authentication. Certificate authentication happens at the
TLS level, long before it ever gets to ASP.NET Core. When the request enters ASP.NET Core, the client certificate
authentication package allows you to resolve the certificate to a ClaimsPrincipal .

NOTE
The host needs to be configured to accept client certificates. See configure your host to require certificates for information on
accepting client certificates in Kestrel, IIS and Azure.

In the .NET gRPC client, the client certificate is added to HttpClientHandler that is then used to create the gRPC
client:

public Ticketer.TicketerClient CreateClientWithCert(

string baseAddress,
X509Certificate2 certificate)
{
// Add client cert to the handler
var handler = new HttpClientHandler();
handler.ClientCertificates.Add(certificate);

// Create the gRPC client

var httpClient = new HttpClient(handler);
httpClient.BaseAddress = new Uri(baseAddress);

return GrpcClient.Create<Ticketer.TicketerClient>(httpClient);
}

Other authentication mechanisms

Many ASP.NET Core supported authentication mechanisms work with gRPC:
Azure Active Directory
Client Certificate
IdentityServer
JWT Token
OAuth 2.0
OpenID Connect
WS -Federation
For more information on configuring authentication on the server, see ASP.NET Core authentication.
Configuring the gRPC client to use authentication will depend on the authentication mechanism you are using. The
previous bearer token and client certificate examples show a couple of ways the gRPC client can be configured to
send authentication metadata with gRPC calls:
Strongly typed gRPC clients use HttpClient internally. Authentication can be configured on HttpClientHandler ,
or by adding custom HttpMessageHandler instances to the HttpClient .
Each gRPC call has an optional CallOptions argument. Custom headers can be sent using the option's headers
collection.

NOTE
Windows Authentication (NTLM/Kerberos/Negotiate) can't be used with gRPC. gRPC requires HTTP/2, and HTTP/2 doesn't
support Windows Authentication.

Authorize users to access services and service methods

By default, all methods in a service can be called by unauthenticated users. To require authentication, apply the
[Authorize] attribute to the service:

[Authorize]
public class TicketerService : Ticketer.TicketerBase
{
}

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 , ensure that only users matching that policy can access the service using the following code:

[Authorize("MyAuthorizationPolicy")]
public class TicketerService : Ticketer.TicketerBase
{
}

Individual service methods can have the [Authorize] attribute applied as well. If the current user doesn't match
the policies applied to both the method and the class, an error is returned to the caller:

[Authorize]
public class TicketerService : Ticketer.TicketerBase
{
public override Task<AvailableTicketsResponse> GetAvailableTickets(
Empty request, ServerCallContext context)
{
// ... buy tickets for the current user ...
}

[Authorize("Administrators")]
public override Task<BuyTicketsResponse> RefundTickets(
BuyTicketsRequest request, ServerCallContext context)
{
// ... refund tickets (something only Administrators can do) ..
}
}

Additional resources
Bearer Token authentication in ASP.NET Core
Configure Client Certificate authentication in ASP.NET Core
 Security considerations in gRPC for ASP.NET Core
7/18/2019 • 2 minutes to read • Edit Online

By James Newton-King
This article provides information on securing gRPC with .NET Core.

Transport security
gRPC messages are sent and received using HTTP/2. We recommend:
Transport Layer Security (TLS ) be used to secure messages in production gRPC apps.
gRPC services should only listen and respond over secured ports.
TLS is configured in Kestrel. For more information on configuring Kestrel endpoints, see Kestrel endpoint
configuration.

Exceptions
Exception messages are generally considered sensitive data that shouldn't be revealed to a client. By default, gRPC
doesn't send the details of an exception thrown by a gRPC service to the client. Instead, the client receives a generic
message indicating an error occurred. Exception message delivery to the client can be overridden (for example, in
development or test) with EnableDetailedErrors. Exception messages shouldn't be exposed to the client in
production apps.

Message size limits

Incoming messages to gRPC clients and services are loaded into memory. Message size limits are a mechanism to
help prevent gRPC from consuming excessive resources.
gRPC uses per-message size limits to manage incoming and outgoing messages. By default, gRPC limits incoming
messages to 4 MB. There is no limit on outgoing messages.
On the server, gRPC message limits can be configured for all services in an app with AddGrpc :

public void ConfigureServices(IServiceCollection services)

{
services.AddGrpc(options =>
{
options.ReceiveMaxMessageSize = 1 * 1024 * 1024; // 1 megabyte
options.SendMaxMessageSize = 1 * 1024 * 1024; // 1 megabyte
});
}

Limits can also be configured for an individual service using AddServiceOptions<TService> . For more information
on configuring message size limits, see gRPC configuration.

Client certificate validation

Client certificates are initially validated when the connection is established. By default, Kestrel doesn't perform
additional validation of a connection's client certificate.
We recommend that gRPC services secured by client certificates use the
Microsoft.AspNetCore.Authentication.Certificate package. ASP.NET Core certification authentication will perform
additional validation on a client certificate, including:
Certificate has a valid extended key use (EKU )
Is within its validity period
Check certificate revocation
 Migrating gRPC services from C-core to ASP.NET
Core
4/26/2019 • 2 minutes to read • Edit Online

By John Luo
Due to the implementation of the underlying stack, not all features work in the same way between C -core-based
gRPC apps and ASP.NET Core-based apps. This document highlights the key differences for migrating between
the two stacks.

gRPC service implementation lifetime

In the ASP.NET Core stack, gRPC services, by default, are created with a scoped lifetime. In contrast, gRPC C -
core by default binds to a service with a singleton lifetime.
A scoped lifetime allows the service implementation to resolve other services with scoped lifetimes. For example,
a scoped lifetime can also resolve DBContext from the DI container through constructor injection. Using scoped
lifetime:
A new instance of the service implementation is constructed for each request.
It isn't possible to share state between requests via instance members on the implementation type.
The expectation is to store shared states in a singleton service in the DI container. The stored shared states are
resolved in the constructor of the gRPC service implementation.
For more information on service lifetimes, see Dependency injection in ASP.NET Core.
Add a singleton service
To facilitate the transition from a gRPC C -core implementation to ASP.NET Core, it's possible to change the
service lifetime of the service implementation from scoped to singleton. This involves adding an instance of the
service implementation to the DI container:

public void ConfigureServices(IServiceCollection services)

{
services.AddGrpc();
services.AddSingleton(new GreeterService());
}

However, a service implementation with a singleton lifetime is no longer able to resolve scoped services through
constructor injection.

Configure gRPC services options

In C -core-based apps, settings such as grpc.max_receive_message_length and grpc.max_send_message_length are
configured with ChannelOption when constructing the Server instance.
In ASP.NET Core, gRPC provides configuration through the GrpcServiceOptions type. For example, a gRPC
service's the maximum incoming message size can be configured via AddGrpc :
 public void ConfigureServices(IServiceCollection services)
{
services.AddGrpc(options =>
{
options.ReceiveMaxMessageSize = 16384; // 16 MB
});
}

For more information on configuration, see gRPC for ASP.NET Core configuration.

Logging
C -core-based apps rely on the GrpcEnvironment to configure the logger for debugging purposes. The ASP.NET
Core stack provides this functionality through the Logging API. For example, a logger can be added to the gRPC
service via constructor injection:

public class GreeterService : Greeter.GreeterBase

{
public GreeterService(ILogger<GreeterService> logger)
{
}
}

HTTPS
C -core-based apps configure HTTPS through the Server.Ports property. A similar concept is used to configure
servers in ASP.NET Core. For example, Kestrel uses endpoint configuration for this functionality.

Interceptors and Middleware

ASP.NET Core middleware offers similar functionalities compared to interceptors in C -core-based gRPC apps.
Middleware and interceptors are conceptually the same as both are used to construct a pipeline that handles a
gRPC request. They both allow work to be performed before or after the next component in the pipeline.
However, ASP.NET Core middleware operates on the underlying HTTP/2 messages, while interceptors operate
on the gRPC layer of abstraction using the ServerCallContext.

Additional resources
Introduction to gRPC on ASP.NET Core
gRPC services with C#
gRPC services with ASP.NET Core
Create a .NET Core gRPC client and server in ASP.NET Core
 Comparing gRPC services with HTTP APIs
5/29/2019 • 4 minutes to read • Edit Online

By James Newton-King
This article explains how gRPC services compare to HTTP APIs (including ASP.NET Core Web APIs). The
technology used to provide an API for your app is an important choice, and gRPC offers unique benefits compared
to HTTP APIs. This article discusses the strengths and weaknesses of gRPC and recommends scenarios for using
gRPC over other technologies.
Overview

FEATURE GRPC HTTP APIS WITH JSON

Contract Required ( *.proto ) Optional (OpenAPI)

Transport HTTP/2 HTTP

Payload Protobuf (small, binary) JSON (large, human readable)

Prescriptiveness Strict specification Loose. Any HTTP is valid

Streaming Client, server, bi-directional Client, server

Browser support No (requires grpc-web) Yes

Security Transport (HTTPS) Transport (HTTPS)

Client code-gen Yes OpenAPI + third-party tooling

gRPC strengths
Performance
gRPC messages are serialized using Protobuf, an efficient binary message format. Protobuf serializes very quickly
on the server and client. Protobuf serialization results in small message payloads, important in limited bandwidth
scenarios like mobile apps.
gRPC is designed for HTTP/2, a major revision of HTTP that provides significant performance benefits over HTTP
1.x:
Binary framing and compression. HTTP/2 protocol is compact and efficient both in sending and receiving.
Multiplexing of multiple HTTP/2 calls over a single TCP connection. Multiplexing eliminates head-of-line
blocking.
Code generation
All gRPC frameworks provide first-class support for code generation. A core file to gRPC development is the
*.proto file, which defines the contract of gRPC services and messages. From this file gRPC frameworks will code
generate a service base class, messages, and a complete client.
By sharing the *.proto file between the server and client, messages and client code can be generated from end to
end. Code generation of the client eliminates duplication of messages on the client and server, and creates a
strongly-typed client for you. Not having to write a client saves significant development time in applications with
many services.
Strict specification
A formal specification for HTTP API with JSON doesn't exist. Developers debate the best format of URLs, HTTP
verbs, and response codes.
The gRPC specification is prescriptive about the format a gRPC service must follow. gRPC eliminates debate and
saves developer time because gPRC is consistent across platforms and implementations.
Streaming
HTTP/2 provides a foundation for long-lived, real-time communication streams. gRPC provides first-class support
for streaming through HTTP/2.
A gRPC service supports all streaming combinations:
Unary (no streaming)
Server to client streaming
Client to server streaming
Bi-directional streaming
Deadline/timeouts and cancellation
gRPC allows clients to specify how long they are willing to wait for an RPC to complete. The deadline is sent to the
server, and the server can decide what action to take if it exceeds the deadline. For example, the server might cancel
in-progress gRPC/HTTP/database requests on timeout.
Propagating the deadline and cancellation through child gRPC calls helps enforce resource usage limits.

gRPC recommended scenarios

gRPC is well suited to the following scenarios:
Microservices – gRPC is designed for low latency and high throughput communication. gRPC is great for
lightweight microservices where efficiency is critical.
Point-to-point real-time communication – gRPC has excellent support for bi-directional streaming. gRPC
services can push messages in real-time without polling.
Polyglot environments – gRPC tooling supports all popular development languages, making gRPC a good
choice for multi-language environments.
Network constrained environments – gRPC messages are serialized with Protobuf, a lightweight message
format. A gRPC message is always smaller than an equivalent JSON message.

gRPC weaknesses
Limited browser support
It's impossible to directly call a gRPC service from a browser today. gRPC heavily uses HTTP/2 features and no
browser provides the level of control required over web requests to support a gRPC client. For example, browsers
do not allow a caller to require that HTTP/2 be used, or provide access to underlying HTTP/2 frames.
gRPC -Web is an additional technology from the gRPC team that provides limited gRPC support in the browser.
gRPC -Web consists of two parts: a JavaScript client that supports all modern browsers, and a gRPC -Web proxy on
the server. The gRPC -Web client calls the proxy and the proxy will forward on the gRPC requests to the gRPC
server.
Not all of gRPC's features are supported by gRPC -Web. Client and bi-directional streaming isn't supported, and
there is limited support for server streaming.
Not human readable
HTTP API requests are sent as text and can be read and created by humans.
gRPC messages are encoded with Protobuf by default. While Protobuf is efficient to send and receive, its binary
format isn't human readable. Protobuf requires the message's interface description specified in the *.proto file to
properly deserialize. Additional tooling is required to analyze Protobuf payloads on the wire and to compose
requests by hand.
Features such as server reflection and the gRPC command line tool exist to assist with binary Protobuf messages.
Also, Protobuf messages support conversion to and from JSON. The built-in JSON conversion provides an
efficient way to convert Protobuf messages to and from human readable form when debugging.

Alternative framework scenarios

Other frameworks are recommended over gRPC in the following scenarios:
Browser accessible APIs – gRPC isn't fully supported in the browser. gRPC -Web can offer browser support,
but it has limitations and introduces a server proxy.
Broadcast real-time communication – gRPC supports real-time communication via streaming, but the
concept of broadcasting a message out to registered connections doesn't exist. For example in a chat room
scenario where new chat messages should be sent to all clients in the chat room, each gRPC call is required to
individually stream new chat messages to the client. SignalR is a useful framework for this scenario. SignalR has
the concept of persistent connections and built-in support for broadcasting messages.
Inter-process communication – A process must host an HTTP/2 server to accept incoming gRPC calls. For
Windows, inter-process communication pipes is a fast, lightweight method of communication.

Additional resources
Create a .NET Core gRPC client and server in ASP.NET Core
Introduction to gRPC on ASP.NET Core
gRPC services with C#
Migrating gRPC services from C -core to ASP.NET Core
 Razor Pages unit tests in ASP.NET Core
7/8/2019 • 9 minutes to read • Edit Online

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:
Introduction to Razor Pages in ASP.NET Core
Tutorial: Get started with Razor Pages in ASP.NET Core
Unit testing C# in .NET Core using dotnet test and xUnit
View or download sample code (how to download)
The sample project is composed of two apps:

APP PROJECT FOLDER DESCRIPTION

Message app src/RazorPagesTestSample Allows a user to add a message, delete

one message, delete all messages, and
analyze messages (find the average
number of words per message).

Test app tests/RazorPagesTestSample.Tests Used to unit test the DAL and Index
page model of the message app.

The tests can be run using the built-in test features of an IDE, such as Visual Studio or Visual Studio for Mac. 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 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 (find the average number of 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 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 sample 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 and Test controller logic in ASP.NET Core (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 TestDbContextOptions 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 TestDbContextOptions
(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.TestDbContextOptions()))

{
// 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);
await db.SaveChangesAsync();
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(m => m.Id).Select(m => m.Text),
actualMessages.OrderBy(m => m.Id).Select(m => m.Text));
}
}

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);
await db.SaveChangesAsync();
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
await db.DeleteMessageAsync(recId);

Finally, the method obtains the Messages from the context and compares it to the expectedMessages asserting that
the two are equal:

// Assert
var actualMessages = await db.Messages.AsNoTracking().ToListAsync();
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);
await db.SaveChangesAsync();
var recId = 4;

// Act
await db.DeleteMessageAsync(recId);

// Assert
var actualMessages = await db.Messages.AsNoTracking().ToListAsync();
Assert.Equal(
expectedMessages.OrderBy(m => m.Id).Select(m => m.Text),
actualMessages.OrderBy(m => m.Id).Select(m => m.Text));
}
}

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.

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);

var expectedMessages = AppDbContext.GetSeedingMessages();
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):

public async Task OnGetAsync()

{
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(
expectedMessages.OrderBy(m => m.Id).Select(m => m.Text),
actualMessages.OrderBy(m => m.Id).Select(m => m.Text));

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);
var expectedMessages = AppDbContext.GetSeedingMessages();
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);
}

Additional resources
Unit testing C# in .NET Core using dotnet test and xUnit
Test controller logic in ASP.NET Core
Unit Test Your Code (Visual Studio)
Integration tests in ASP.NET Core
xUnit.net
Building a complete .NET Core solution on macOS using Visual Studio for Mac
Getting started with xUnit.net: Using .NET Core with the .NET SDK command line
Moq
Moq Quickstart
 Test controller logic in ASP.NET Core
8/4/2019 • 12 minutes to read • Edit Online

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.
View or download sample code (how to download)

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 class HomeController : Controller
{
private readonly IBrainstormSessionRepository _sessionRepository;

public HomeController(IBrainstormSessionRepository sessionRepository)

{
_sessionRepository = sessionRepository;
}

public async Task<IActionResult> Index()

{
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)
{
if (!ModelState.IsValid)
{
return BadRequest(ModelState);
}
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"
});
sessions.Add(new BrainstormSession()
{
DateCreated = new DateTime(2016, 7, 1),
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
var mockRepo = new Mock<IBrainstormSessionRepository>();
mockRepo.Setup(repo => repo.ListAsync())
.ReturnsAsync(GetTestSessions());
var controller = new HomeController(mockRepo.Object);
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
var mockRepo = new Mock<IBrainstormSessionRepository>();
mockRepo.Setup(repo => repo.AddAsync(It.IsAny<BrainstormSession>()))
.Returns(Task.CompletedTask)
.Verifiable();
var controller = new HomeController(mockRepo.Object);
var newSession = new HomeController.NewSessionModel()
{
SessionName = "Test Name"
};

// Act
var result = await controller.Index(newSession);

// 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.
SessionController 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
(Controllers/SessionController.cs):

public class SessionController : Controller

{
private readonly IBrainstormSessionRepository _sessionRepository;

public SessionController(IBrainstormSessionRepository sessionRepository)

{
_sessionRepository = 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()

{
DateCreated = session.DateCreated,
Name = session.Name,
Id = session.Id
};

return View(viewModel);
}
}

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);
Assert.Equal("Index", redirectToActionResult.ActionName);
}

[Fact]
public async Task IndexReturnsContentWithSessionNotFoundWhenSessionNotFound()
{
// Arrange
int testSessionId = 1;
var mockRepo = new Mock<IBrainstormSessionRepository>();
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
int testSessionId = 1;
var mockRepo = new Mock<IBrainstormSessionRepository>();
mockRepo.Setup(repo => repo.GetByIdAsync(testSessionId))
.ReturnsAsync(GetTestSessions().FirstOrDefault(
s => s.Id == testSessionId));
var controller = new SessionController(mockRepo.Object);

// Act
var result = await controller.Index(testSessionId);

// Assert
var viewResult = Assert.IsType<ViewResult>(result);
var model = Assert.IsType<StormSessionViewModel>(
viewResult.ViewData.Model);
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);
if (session == null)
{
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)
{
if (!ModelState.IsValid)
{
return BadRequest(ModelState);
}

var session = await _sessionRepository.GetByIdAsync(model.SessionId);

if (session == null)
{
return NotFound(model.SessionId);
}

var idea = new Idea()

{
DateCreated = DateTimeOffset.Now,
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
int testSessionId = 123;
var mockRepo = new Mock<IBrainstormSessionRepository>();
mockRepo.Setup(repo => repo.GetByIdAsync(testSessionId))
.ReturnsAsync((BrainstormSession)null);
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
int testSessionId = 123;
var mockRepo = new Mock<IBrainstormSessionRepository>();
mockRepo.Setup(repo => repo.GetByIdAsync(testSessionId))
.ReturnsAsync(GetTestSession());
var controller = new IdeasController(mockRepo.Object);

// Act
var result = await controller.ForSession(testSessionId);

// 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
var mockRepo = new Mock<IBrainstormSessionRepository>();
var controller = new IdeasController(mockRepo.Object);
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
int testSessionId = 123;
var mockRepo = new Mock<IBrainstormSessionRepository>();
mockRepo.Setup(repo => repo.GetByIdAsync(testSessionId))
.ReturnsAsync((BrainstormSession)null);
var controller = new IdeasController(mockRepo.Object);

// 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
int testSessionId = 123;
string testName = "test name";
string testDescription = "test description";
var testSession = GetTestSession();
var mockRepo = new Mock<IBrainstormSessionRepository>();
mockRepo.Setup(repo => repo.GetByIdAsync(testSessionId))
.ReturnsAsync(testSession);
var controller = new IdeasController(mockRepo.Object);

var newIdea = new NewIdeaModel()

{
Description = testDescription,
Name = testName,
SessionId = testSessionId
};
mockRepo.Setup(repo => repo.UpdateAsync(testSession))
.Returns(Task.CompletedTask)
.Verifiable();

// Act
var result = await controller.Create(newIdea);

// Assert
var okResult = Assert.IsType<OkObjectResult>(result);
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}")]
[ProducesResponseType(200)]
[ProducesResponseType(404)]
public async Task<ActionResult<List<IdeaDTO>>> ForSessionActionResult(int sessionId)
{
var session = await _sessionRepository.GetByIdAsync(sessionId);

if (session == null)
{
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 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 mockRepo = new Mock<IBrainstormSessionRepository>();
var controller = new IdeasController(mockRepo.Object);
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 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
int testSessionId = 123;
var mockRepo = new Mock<IBrainstormSessionRepository>();
mockRepo.Setup(repo => repo.GetByIdAsync(testSessionId))
.ReturnsAsync(GetTestSession());
var controller = new IdeasController(mockRepo.Object);

// Act
var result = await controller.ForSessionActionResult(testSessionId);

// Assert
var actionResult = Assert.IsType<ActionResult<List<IdeaDTO>>>(result);
var returnValue = Assert.IsType<List<IdeaDTO>>(actionResult.Value);
var idea = returnValue.FirstOrDefault();
Assert.Equal("One", idea.Name);
}

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")]
[ProducesResponseType(201)]
[ProducesResponseType(400)]
[ProducesResponseType(404)]
public async Task<ActionResult<BrainstormSession>> CreateActionResult([FromBody]NewIdeaModel model)
{
if (!ModelState.IsValid)
{
return BadRequest(ModelState);
}

var session = await _sessionRepository.GetByIdAsync(model.SessionId);

if (session == null)
{
return NotFound(model.SessionId);
}

var idea = new Idea()

{
DateCreated = DateTimeOffset.Now,
Description = model.Description,
Name = model.Name
};
session.AddIdea(idea);

await _sessionRepository.UpdateAsync(session);

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
var mockRepo = new Mock<IBrainstormSessionRepository>();
var controller = new IdeasController(mockRepo.Object);
controller.ModelState.AddModelError("error", "some error");

// 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
var nonExistentSessionId = 999;
string testName = "test name";
string testDescription = "test description";
var mockRepo = new Mock<IBrainstormSessionRepository>();
var controller = new IdeasController(mockRepo.Object);

var newIdea = new NewIdeaModel()

{
Description = testDescription,
Name = testName,
SessionId = nonExistentSessionId
};

// Act
var result = await controller.CreateActionResult(newIdea);

// Assert
var actionResult = Assert.IsType<ActionResult<BrainstormSession>>(result);
Assert.IsType<NotFoundObjectResult>(actionResult.Result);
}

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
int testSessionId = 123;
string testName = "test name";
string testDescription = "test description";
var testSession = GetTestSession();
var mockRepo = new Mock<IBrainstormSessionRepository>();
mockRepo.Setup(repo => repo.GetByIdAsync(testSessionId))
.ReturnsAsync(testSession);
var controller = new IdeasController(mockRepo.Object);

var newIdea = new NewIdeaModel()

{
Description = testDescription,
Name = testName,
SessionId = testSessionId
};
mockRepo.Setup(repo => repo.UpdateAsync(testSession))
.Returns(Task.CompletedTask)
.Verifiable();

// Act
var result = await controller.CreateActionResult(newIdea);

// Assert
var actionResult = Assert.IsType<ActionResult<BrainstormSession>>(result);
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);
}

Additional resources
Integration tests in ASP.NET Core
Create and run unit tests with Visual Studio.
 Integration tests in ASP.NET Core
8/6/2019 • 17 minutes to read • Edit Online

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.
View or download sample code (how to download)
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:
Introduction to Razor Pages
Get started with Razor Pages
Razor Pages unit tests

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 directory.
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 accidentally 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.App
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

SUT environment
If the SUT's environment isn't set, the environment defaults to Development.

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());
}

By default, non-essential cookies aren't preserved across requests when the GDPR consent policy is enabled. To
preserve non-essential cookies, such as those used by the TempData provider, mark them as essential in your
tests. For instructions on marking a cookie as essential, see Essential cookies.
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()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2)
.AddRazorPagesOptions(options =>
{
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<TStartup> where TStartup: class
{
protected override void ConfigureWebHost(IWebHostBuilder builder)
{
builder.ConfigureServices(services =>
{
// Create a new service provider.
var serviceProvider = new ServiceCollection()
.AddEntityFrameworkInMemoryDatabase()
.BuildServiceProvider();

// Add a database context (ApplicationDbContext) using an in-memory

// database for testing.
services.AddDbContext<ApplicationDbContext>(options =>
{
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);
}
catch (Exception ex)
{
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
{
AllowAutoRedirect = false
});
}

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(HttpStatusCode.Redirect, response.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 =>
{
builder.ConfigureServices(services =>
{
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);
}
catch (Exception ex)
{
logger.LogError(ex, "An error occurred seeding " +
"the database with test messages. Error: " +
ex.Message);
}
}
});
})
.CreateClient(new WebApplicationFactoryClientOptions
{
AllowAutoRedirect = false
});
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='deleteBtn1']"));

// Assert
Assert.Equal(HttpStatusCode.OK, defaultPage.StatusCode);
Assert.Equal(HttpStatusCode.Redirect, response.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:
 public class IndexModel : PageModel
{
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; }

public async Task OnGetAsync()

{
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&#x27;ve an appointment in

London, and we&#x27;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 content = await HtmlHelpers.GetDocumentAsync(defaultPage);
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&#x27;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.

Disable shadow copying

Shadow copying causes the tests to execute in a different directory than the output directory. 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 with JSON.
Add the xunit.runner.json file to root of the test project with the following content:

{
"shadowCopy": false
}

Disposal of objects
After the tests of the IClassFixture implementation are executed, TestServer and HttpClient are disposed when
xUnit disposes of the WebApplicationFactory. If objects instantiated by the developer require disposal, dispose of
them in the IClassFixture implementation. For more information, see Implementing a Dispose method.
Integration tests sample
The sample app is composed of two apps:

APP PROJECT DIRECTORY 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 directory:

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 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 directory.

TEST APP DIRECTORY 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.
 TEST APP DIRECTORY DESCRIPTION

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." }
};
}

Additional resources
Unit tests
Razor Pages unit tests
Middleware
Test controllers
 ASP.NET Core load/stress testing
7/11/2019 • 2 minutes to read • Edit Online

Load testing and stress testing are important to ensure a web app is performant and scalable. Their goals are
different even though they often share similar tests.
Load tests – Test whether the app can handle a specified load of users for a certain scenario while still satisfying
the response goal. The app is run under normal conditions.
Stress tests – Test app stability when running under extreme conditions, often for a long period of time. The tests
place high user load, either spikes or gradually increasing load, on the app, or they limit the app's computing
resources.
Stress tests determine if an app under stress can recover from failure and gracefully return to expected behavior.
Under stress, the app isn't run under normal conditions.
Visual Studio 2019 is the last version of Visual Studio with load test features. For customers requiring load testing
tools in the future, we recommend alternate tools, such as Apache JMeter, Akamai CloudTest, and BlazeMeter. For
more information, see the Visual Studio 2019 Release Notes.
The load testing service in Azure DevOps is ending in 2020. For more information, see Cloud-based load testing
service end of life.

Visual Studio tools

Visual Studio allows users to create, develop, and debug web performance and load tests. An option is available to
create tests by recording actions in a web browser.
For information on how to create, configure, and run a load test projects using Visual Studio 2017, see Quickstart:
Create a load test project. For more information, see the Additional resources section.
Load tests can be configured to run on-premise or run in the cloud using Azure DevOps.

Azure DevOps
Load test runs can be started using the Azure DevOps Test Plans service.
The service supports the following test formats:
Visual Studio – Web test created in Visual Studio.
HTTP Archive – Captured HTTP traffic inside archive is replayed during testing.
URL -based – Allows specifying URLs to load test, request types, headers, and query strings. Run setting
parameters such as duration, load pattern, and number of users can be configured.
Apache JMeter.

Azure portal
Azure portal allows setting up and running load testing of web apps directly from the Performance tab of the App
Service in Azure portal.

The test can be a manual test with a specified URL or a Visual Studio Web Test file, which can test multiple URLs.
At end of the test, generated reports show the performance characteristics of the app. Example statistics include:
Average response time
Max throughput: requests per second
Failure percentage

Third-party tools
The following list contains third-party web performance tools with various feature sets:
Apache JMeter
ApacheBench (ab)
Gatling
Locust
West Wind WebSurge
Netling
Vegeta

Additional resources
Load Test blog series
 Troubleshoot ASP.NET Core projects
7/18/2019 • 4 minutes to read • Edit Online

By Rick Anderson
The following links provide troubleshooting guidance:
Troubleshoot ASP.NET Core on Azure App Service and IIS
Common errors reference for Azure App Service and IIS with ASP.NET Core
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-bit and 64-bit versions of the .NET Core SDK are installed. Only templates from the 64-bit versions
installed at 'C:\Program Files\dotnet\sdk\' are 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
In the New Project dialog for ASP.NET Core, you may see the following warning:

The .NET Core SDK is installed in multiple locations. Only templates from the SDKs installed at 'C:\Program
Files\dotnet\sdk\' are 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 all 32-bit .NET Core SDKs and runtimes 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
In the Visual Studio New Project dialog for ASP.NET Core, you may see the following warning:

No .NET Core SDKs were detected, ensure they are included in the environment variable PATH .
 When executing a dotnet command, the warning appears as:

It was not possible to find any installed dotnet SDKs.

These warnings appear when the environment variable PATH doesn't point to any .NET Core SDKs on the
machine. To resolve this problem:
Install the .NET Core SDK. Obtain the latest installer from .NET Downloads.
Verify that the PATH environment variable points to the location where the SDK is installed (
C:\Program Files\dotnet\ for 64 -bit/x64 or C:\Program Files (x86)\dotnet\ for 32 -bit/x86 ). The SDK installer
normally sets the PATH . Always install the same bitness SDKs and runtimes on the same machine.
Missing SDK after installing the .NET Core Hosting Bundle
Installing the .NET Core Hosting Bundle modifies the PATH when it installs the .NET Core runtime to point to the
32-bit (x86) version of .NET Core ( C:\Program Files (x86)\dotnet\ ). This can result in missing SDKs when the
32-bit (x86) .NET Core dotnet command is used (No .NET Core SDKs were detected). To resolve this problem,
move C:\Program Files\dotnet\ to a position before C:\Program Files (x86)\dotnet\ on the PATH .

Obtain data from an app

If an app is capable of responding to requests, you can obtain the following data from the app using middleware:
Request – Method, scheme, host, pathbase, path, query string, headers
Connection – Remote IP address, remote port, local IP address, local port, client certificate
Identity – Name, display name
Configuration settings
Environment variables
Place the following middleware code at the beginning of the Startup.Configure method's request processing
pipeline. The environment is checked before the middleware is run to ensure that the code is only executed in the
Development environment.
To obtain the environment, use either of the following approaches:
Inject the IHostingEnvironment into the Startup.Configure method and check the environment with the
local variable. The following sample code demonstrates this approach.
Assign the environment to a property in the Startup class. Check the environment using the property
(for example, if (Environment.IsDevelopment()) ).

public void Configure(IApplicationBuilder app, IHostingEnvironment env,

IConfiguration config)
{
if (env.IsDevelopment())
{
app.Run(async (context) =>
{
var sb = new StringBuilder();
var nl = System.Environment.NewLine;
var rule = string.Concat(nl, new string('-', 40), nl);
var authSchemeProvider = app.ApplicationServices
.GetRequiredService<IAuthenticationSchemeProvider>();

sb.Append($"Request{rule}");
sb.Append($"{DateTimeOffset.Now}{nl}");
sb.Append($"{context.Request.Method} {context.Request.Path}{nl}");
sb.Append($"Scheme: {context.Request.Scheme}{nl}");
sb.Append($"Host: {context.Request.Headers["Host"]}{nl}");
 sb.Append($"PathBase: {context.Request.PathBase.Value}{nl}");
sb.Append($"Path: {context.Request.Path.Value}{nl}");
sb.Append($"Query: {context.Request.QueryString.Value}{nl}{nl}");

sb.Append($"Connection{rule}");
sb.Append($"RemoteIp: {context.Connection.RemoteIpAddress}{nl}");
sb.Append($"RemotePort: {context.Connection.RemotePort}{nl}");
sb.Append($"LocalIp: {context.Connection.LocalIpAddress}{nl}");
sb.Append($"LocalPort: {context.Connection.LocalPort}{nl}");
sb.Append($"ClientCert: {context.Connection.ClientCertificate}{nl}{nl}");

sb.Append($"Identity{rule}");
sb.Append($"User: {context.User.Identity.Name}{nl}");
var scheme = await authSchemeProvider
.GetSchemeAsync(IISDefaults.AuthenticationScheme);
sb.Append($"DisplayName: {scheme?.DisplayName}{nl}{nl}");

sb.Append($"Headers{rule}");
foreach (var header in context.Request.Headers)
{
sb.Append($"{header.Key}: {header.Value}{nl}");
}
sb.Append(nl);

sb.Append($"Websockets{rule}");
if (context.Features.Get<IHttpUpgradeFeature>() != null)
{
sb.Append($"Status: Enabled{nl}{nl}");
}
else
{
sb.Append($"Status: Disabled{nl}{nl}");
}

sb.Append($"Configuration{rule}");
foreach (var pair in config.AsEnumerable())
{
sb.Append($"{pair.Path}: {pair.Value}{nl}");
}
sb.Append(nl);

sb.Append($"Environment Variables{rule}");
var vars = System.Environment.GetEnvironmentVariables();
foreach (var key in vars.Keys.Cast<string>().OrderBy(key => key,
StringComparer.OrdinalIgnoreCase))
{
var value = vars[key];
sb.Append($"{key}: {value}{nl}");
}

context.Response.ContentType = "text/plain";
await context.Response.WriteAsync(sb.ToString());
});
}
}
 Logging in .NET Core and ASP.NET Core
8/13/2019 • 29 minutes to read • Edit Online

By Tom Dykstra and Steve Smith

.NET Core supports a logging API that works with a variety of built-in and third-party logging providers. This
article shows how to use the logging API with built-in providers.
Most of the code examples shown in this article are from ASP.NET Core apps. The logging-specific parts of
these code snippets apply to any .NET Core app that uses the Generic host. For information about how to use
the Generic Host in non-web console apps, see Hosted services.
Logging code for apps without Generic Host differs in the way providers are added and loggers are created.
Non-host code examples are shown in those sections of the article.
View or download sample code (how to download)

Add providers
A logging provider displays or stores logs. For example, the Console provider displays logs on the console,
and the Azure Application Insights provider stores them in Azure Application Insights. Logs can be sent to
multiple destinations by adding multiple providers.
To add a provider in an app that uses Generic Host, call the provider's Add{provider name} extension method
in Program.cs:

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureLogging(logging =>
{
logging.ClearProviders();
logging.AddConsole();
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});

In a non-host console app, call the provider's Add{provider name} extension method while creating a
LoggerFactory :

var loggerFactory = LoggerFactory.Create(builder =>

{
builder
.AddFilter("Microsoft", LogLevel.Warning)
.AddFilter("System", LogLevel.Warning)
.AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
.AddConsole()
.AddEventLog();
});
ILogger logger = loggerFactory.CreateLogger<Program>();
logger.LogInformation("Example log message");

LoggerFactory and AddConsole require a using statement for Microsoft.Extensions.Logging .

The default ASP.NET Core project templates call CreateDefaultBuilder, which adds the following logging
providers:
Console
Debug
EventSource
EventLog (only when running on Windows)
You can replace the default providers with your own choices. Call ClearProviders, and add the providers you
want.

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureLogging(logging =>
{
logging.ClearProviders();
logging.AddConsole();
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});

To add a provider, call the provider's Add{provider name} extension method in Program.cs:

public static void Main(string[] args)

{
var webHost = new WebHostBuilder()
.UseKestrel()
.UseContentRoot(Directory.GetCurrentDirectory())
.ConfigureAppConfiguration((hostingContext, config) =>
{
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) =>
{
// Requires `using Microsoft.Extensions.Logging;`
logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
logging.AddConsole();
logging.AddDebug();
logging.AddEventSourceLogger();
})
.UseStartup<Startup>()
.Build();

webHost.Run();
}

The preceding code requires references to Microsoft.Extensions.Logging and

Microsoft.Extensions.Configuration .

The default project template calls CreateDefaultBuilder, which adds the following logging providers:
Console
Debug
EventSource (starting in ASP.NET Core 2.2)
 public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>();

If you use CreateDefaultBuilder , you can replace the default providers with your own choices. Call
ClearProviders, and add the providers you want.

public static void Main(string[] args)

{
var host = CreateWebHostBuilder(args).Build();

var todoRepository = host.Services.GetRequiredService<ITodoRepository>();

todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

var logger = host.Services.GetRequiredService<ILogger<Program>>();

logger.LogInformation("Seeded the database.");

host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureLogging(logging =>
{
logging.ClearProviders();
logging.AddConsole();
});

Learn more about built-in logging providers and third-party logging providers later in the article.

Create logs
To create logs, use an ILogger<TCategoryName> object. In a web app or hosted service, get an ILogger
from dependency injection (DI). In non-host console apps, use the LoggerFactory to create an ILogger .
The following ASP.NET Core example creates a logger with TodoApiSample.Pages.AboutModel as the category.
The log category is a string that is associated with each log. The ILogger<T> instance provided by DI creates
logs that have the fully qualified name of type T as the category.

public class AboutModel : PageModel

{
private readonly ILogger _logger;

public AboutModel(ILogger<AboutModel> logger)

{
_logger = logger;
}

The following non-host console app example creates a logger with LoggingConsoleApp.Program as the
category.
 var loggerFactory = LoggerFactory.Create(builder =>
{
builder
.AddFilter("Microsoft", LogLevel.Warning)
.AddFilter("System", LogLevel.Warning)
.AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
.AddConsole()
.AddEventLog();
});
ILogger logger = loggerFactory.CreateLogger<Program>();
logger.LogInformation("Example log message");

public class AboutModel : PageModel

{
private readonly ILogger _logger;

public AboutModel(ILogger<AboutModel> logger)

{
_logger = logger;
}

In the following ASP.NET Core and console app examples, the logger is used to create logs with Information
as the level. The Log level indicates the severity of the logged event.

public void OnGet()

{
Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
_logger.LogInformation("Message displayed: {Message}", Message);
}

var loggerFactory = LoggerFactory.Create(builder =>

{
builder
.AddFilter("Microsoft", LogLevel.Warning)
.AddFilter("System", LogLevel.Warning)
.AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
.AddConsole()
.AddEventLog();
});
ILogger logger = loggerFactory.CreateLogger<Program>();
logger.LogInformation("Example log message");

public void OnGet()

{
Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
_logger.LogInformation("Message displayed: {Message}", Message);
}

Levels and categories are explained in more detail later in this article.
Create logs in the Program class
To write logs in the Program class of an ASP.NET Core app, get an ILogger instance from DI after building
the host:
 public static void Main(string[] args)
{
var host = CreateHostBuilder(args).Build();

var todoRepository = host.Services.GetRequiredService<ITodoRepository>();

todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

var logger = host.Services.GetRequiredService<ILogger<Program>>();

logger.LogInformation("Seeded the database.");

IMyService myService = host.Services.GetRequiredService<IMyService>();

myService.WriteLog("Logged from MyService.");

host.Run();
}

Create logs in the Startup class

To write logs in the Startup.Configure method of an ASP.NET Core app, include an ILogger parameter in
the method signature:

public void Configure(IApplicationBuilder app, IHostEnvironment env, ILogger<Startup> logger)

{
if (env.IsDevelopment())
{
logger.LogInformation("In Development environment");
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}

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

app.UseRouting();

app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
endpoints.MapRazorPages();
});
}

Writing logs before completion of the DI container setup in the Startup.ConfigureServices method is not
supported:
Logger injection into the Startup constructor is not supported.
Logger injection into the Startup.ConfigureServices method signature is not supported

The reason for this restriction is that logging depends on DI and on configuration, which in turns depends on
DI. The DI container isn't set up until ConfigureServices finishes.
Constructor injection of a logger into Startup works in earlier versions of ASP.NET Core because a separate
DI container is created for the Web Host. For information about why only one container is created for the
Generic Host, see the breaking change announcement.
If you need to configure a service that depends on ILogger<T> , you can still do that by using constructor
injection or by providing a factory method. The factory method approach is recommended only if there is no
other option. For example, suppose you need to fill a property with a service from DI:

public void ConfigureServices(IServiceCollection services)

{
services.AddControllers();
services.AddRazorPages();

services.AddSingleton<IMyService>((container) =>
{
var logger = container.GetRequiredService<ILogger<MyService>>();
return new MyService() { Logger = logger };
});

services.AddSingleton<ITodoRepository, TodoRepository>();
}

The preceding highlighted code is a Func that runs the first time the DI container needs to construct an
instance of MyService . You can access any of the registered services in this way.
Create logs in Startup
To write logs in the Startup class, include an ILogger parameter in the constructor signature:
 public class Startup
{
private readonly ILogger _logger;

public Startup(IConfiguration configuration, ILogger<Startup> logger)

{
Configuration = configuration;
_logger = logger;
}

public IConfiguration Configuration { get; }

public void ConfigureServices(IServiceCollection services)

{
services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

// Add our repository type

services.AddSingleton<ITodoRepository, TodoRepository>();
_logger.LogInformation("Added TodoRepository to services");
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
if (env.IsDevelopment())
{
_logger.LogInformation("In Development environment");
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}

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

app.UseMvc();
}
}

Create logs in the Program class

To write logs in the Program class, get an ILogger instance from DI:
 public static void Main(string[] args)
{
var host = CreateWebHostBuilder(args).Build();

var todoRepository = host.Services.GetRequiredService<ITodoRepository>();

todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

var logger = host.Services.GetRequiredService<ILogger<Program>>();

logger.LogInformation("Seeded the database.");

host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureLogging(logging =>
{
logging.ClearProviders();
logging.AddConsole();
});

No asynchronous logger methods

Logging should be so fast that it isn't worth the performance cost of asynchronous code. If your logging data
store is slow, don't write to it directly. Consider writing the log messages to a fast store initially, then move
them to the slow store later. For example, if you're logging to SQL Server, you don't want to do that directly in
a Log method, since the Log methods are synchronous. Instead, synchronously add log messages to an in-
memory queue and have a background worker pull the messages out of the queue to do the asynchronous
work of pushing data to SQL Server.

Configuration
Logging provider configuration is provided by one or more configuration providers:
File formats (INI, JSON, and XML ).
Command-line arguments.
Environment variables.
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
}
}
}

The Logging property can have LogLevel and log provider properties (Console is shown).
The LogLevel property under Logging specifies the minimum level to log for selected categories. In the
example, System and Microsoft categories log at Information level, and all others log at Debug level.
Other properties under Logging specify logging providers. The example is for the Console provider. If a
provider supports log scopes, IncludeScopes indicates whether they're enabled. A provider property (such as
Console in the example) may also specify a LogLevel property. LogLevel under a provider specifies levels to
log for that provider.
If levels are specified in Logging.{providername}.LogLevel , they override anything set in Logging.LogLevel .
For information on implementing configuration providers, see Configuration in ASP.NET Core.

Sample logging output

With the sample code shown in the preceding section, logs appear in the console when the app is run from
the command line. Here's an example of console output:

info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
Request starting HTTP/1.1 GET http://localhost:5000/api/todo/0
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
Request finished in 84.26180000000001ms 307
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
Request starting HTTP/2 GET https://localhost:5001/api/todo/0
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
Executing endpoint 'TodoApiSample.Controllers.TodoController.GetById (TodoApiSample)'
info: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[3]
Route matched with {action = "GetById", controller = "Todo", page = ""}. Executing controller
action with signature Microsoft.AspNetCore.Mvc.IActionResult GetById(System.String) on controller
TodoApiSample.Controllers.TodoController (TodoApiSample).
info: TodoApiSample.Controllers.TodoController[1002]
Getting item 0
warn: TodoApiSample.Controllers.TodoController[4000]
GetById(0) NOT FOUND
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
Executing HttpStatusCodeResult, setting HTTP status code 404
 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
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 42.9286ms
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]
Request finished in 148.889ms 404

The preceding logs were generated by making an HTTP Get request to the sample app at
http://localhost:5000/api/todo/0 .

Here's an example of the same logs as they appear in the Debug window when you run the sample app in
Visual Studio:

Microsoft.AspNetCore.Hosting.Diagnostics: Information: Request starting HTTP/2.0 GET

https://localhost:44328/api/todo/0
Microsoft.AspNetCore.Routing.EndpointMiddleware: Information: Executing endpoint
'TodoApiSample.Controllers.TodoController.GetById (TodoApiSample)'
Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker: Information: Route matched with {action
= "GetById", controller = "Todo", page = ""}. Executing controller action with signature
Microsoft.AspNetCore.Mvc.IActionResult GetById(System.String) on controller
TodoApiSample.Controllers.TodoController (TodoApiSample).
TodoApiSample.Controllers.TodoController: Information: Getting item 0
TodoApiSample.Controllers.TodoController: Warning: GetById(0) NOT FOUND
Microsoft.AspNetCore.Mvc.StatusCodeResult: Information: Executing HttpStatusCodeResult, setting HTTP
status code 404
Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker: Information: Executed action
TodoApiSample.Controllers.TodoController.GetById (TodoApiSample) in 34.167ms
Microsoft.AspNetCore.Routing.EndpointMiddleware: Information: Executed endpoint
'TodoApiSample.Controllers.TodoController.GetById (TodoApiSample)'
Microsoft.AspNetCore.Hosting.Diagnostics: Information: Request finished in 98.41300000000001ms 404

The logs that are created by the ILogger calls shown in the preceding section begin with "TodoApiSample".
The logs that begin with "Microsoft" categories are from ASP.NET Core framework code. ASP.NET Core and
application code are using the same logging API and providers.

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 are created by the ILogger calls shown in the preceding section begin with "TodoApi". The logs
that begin with "Microsoft" categories are from ASP.NET Core framework code. ASP.NET Core and
application code are using the same logging API and 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
When an ILogger object is created, a category is specified for it. That category is included with each log
message created by that instance of ILogger . The category may be any string, but the convention is to use
the class name, such as "TodoApi.Controllers.TodoController".
Use ILogger<T> to get an ILogger instance that uses the fully qualified type name of T as the category:

public class TodoController : Controller

{
private readonly ITodoRepository _todoRepository;
private readonly ILogger _logger;

public TodoController(ITodoRepository todoRepository,

ILogger<TodoController> logger)
{
_todoRepository = todoRepository;
_logger = logger;
}

public class TodoController : Controller

{
private readonly ITodoRepository _todoRepository;
private readonly ILogger _logger;

public TodoController(ITodoRepository todoRepository,

ILogger<TodoController> logger)
{
_todoRepository = todoRepository;
_logger = logger;
}

To explicitly specify the category, call ILoggerFactory.CreateLogger :

public class TodoController : Controller

{
private readonly ITodoRepository _todoRepository;
private readonly ILogger _logger;

public TodoController(ITodoRepository todoRepository,

ILoggerFactory logger)
{
_todoRepository = todoRepository;
_logger = logger.CreateLogger("TodoApiSample.Controllers.TodoController");
}
 public class TodoController : Controller
{
private readonly ITodoRepository _todoRepository;
private readonly ILogger _logger;

public TodoController(ITodoRepository todoRepository,

ILoggerFactory logger)
{
_todoRepository = todoRepository;
_logger = logger.CreateLogger("TodoApiSample.Controllers.TodoController");
}

ILogger<T> is equivalent to calling CreateLogger with the fully qualified type name of T .

Log level
Every log specifies a LogLevel value. The log level indicates the severity or importance. For example, you
might write an Information log when a method ends normally and a Warning log when a method returns a
404 Not Found status code.
The following code creates Information and Warning logs:

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);
}

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);
}

In the preceding code, 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 the message template section later in this article.
Log methods that include the level in the method name (for example, LogInformation and LogWarning ) are
extension methods for ILogger. 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 ILogger and the logger extensions source code.
ASP.NET Core defines the following log levels, ordered here from lowest to highest severity.
Trace = 0
 For information that's typically valuable only for debugging. These messages may contain sensitive
application data and so shouldn't be enabled in a production environment. Disabled by default.
Debug = 1
For information that may be useful in development and debugging. Example:
Entering method Configure with flag set to true. Enable Debug level logs in production only when
troubleshooting, due to the high volume of logs.
Information = 2
For tracking the general flow of the app. These logs typically have some long-term value. Example:
Request received for path /api/todo

Warning = 3
For abnormal or unexpected events in the app flow. These may include errors or other conditions that
don't cause the app to stop but might 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 app-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.
Use the log level to control how much log output is written to a particular storage medium or display window.
For example:
In production, send Trace through Information level to a volume data store. Send Warning through
Critical to a value data store.
During development, send Warning through Critical to the console, and add Trace through
Information when troubleshooting.

The Log filtering section later in this article explains how to control which log levels a provider handles.
ASP.NET Core writes logs for framework events. The log examples earlier in this article excluded logs below
Information level, so no Debug or Trace level logs were created. Here's an example of console logs
produced by running the sample app configured to show Debug logs:
info: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[3]
Route matched with {action = "GetById", controller = "Todo", page = ""}. Executing controller
action with signature Microsoft.AspNetCore.Mvc.IActionResult GetById(System.String) on controller
TodoApiSample.Controllers.TodoController (TodoApiSample).
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
Execution plan of authorization filters (in the following order): None
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
Execution plan of resource filters (in the following order):
Microsoft.AspNetCore.Mvc.ViewFeatures.Filters.SaveTempDataFilter
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
Execution plan of action filters (in the following order):
Microsoft.AspNetCore.Mvc.Filters.ControllerActionFilter (Order: -2147483648),
Microsoft.AspNetCore.Mvc.ModelBinding.UnsupportedContentTypeFilter (Order: -3000)
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
Execution plan of exception filters (in the following order): None
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
Execution plan of result filters (in the following order):
Microsoft.AspNetCore.Mvc.ViewFeatures.Filters.SaveTempDataFilter
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder[22]
Attempting to bind parameter 'id' of type 'System.String' ...
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.Binders.SimpleTypeModelBinder[44]
Attempting to bind parameter 'id' of type 'System.String' using the name 'id' in request data ...
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.Binders.SimpleTypeModelBinder[45]
Done attempting to bind parameter 'id' of type 'System.String'.
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder[23]
Done attempting to bind parameter 'id' of type 'System.String'.
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder[26]
Attempting to validate the bound parameter 'id' of type 'System.String' ...
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder[27]
Done attempting to validate the bound parameter 'id' of type 'System.String'.
info: TodoApiSample.Controllers.TodoController[1002]
Getting item 0
warn: TodoApiSample.Controllers.TodoController[4000]
GetById(0) NOT FOUND
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[2]
Executed action TodoApiSample.Controllers.TodoController.GetById (TodoApiSample) in
32.690400000000004ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
Executed endpoint 'TodoApiSample.Controllers.TodoController.GetById (TodoApiSample)'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
Request finished in 176.9103ms 404
 info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
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)
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
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
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 0.8788ms
dbug: Microsoft.AspNetCore.Server.Kestrel[9]
Connection id "0HL6L7NEFF2QD" completed keep alive response.
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]
Request finished in 2.7286ms 404

Log event ID
Each log can specify an event ID. The sample app does this by using a locally defined LoggingEvents class:

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);
}

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;
}
 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);
}

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 associates a set of events. For example, all logs related to displaying a list of items on a page
might be 1001.
The logging provider may store the event ID in an ID field, in the logging message, or not at all. The Debug
provider doesn't show event IDs. The console provider shows event IDs in brackets after the category:

info: TodoApi.Controllers.TodoController[1002]
Getting item invalidid
warn: TodoApi.Controllers.TodoController[4000]
GetById(invalidid) NOT FOUND

Log message template

Each log specifies a message template. The message template can contain placeholders for which arguments
are provided. Use names for the placeholders, not numbers.

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);
}
 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);
}

The order of placeholders, not their names, determines which parameters are used to provide their values. In
the following code, notice that the parameter names are out of sequence in the message template:

string p1 = "parm1";
string p2 = "parm2";
_logger.LogInformation("Parameter values: {p2}, {p1}", p1, p2);

This code creates a log message with the parameter values in sequence:

Parameter values: parm1, parm2

The logging framework works this way so that logging providers can implement semantic logging, also
known as structured logging. The arguments themselves are passed to the logging system, not just the
formatted message template. This information enables logging providers to store the parameter values as
fields. For example, suppose logger method calls look like this:

_logger.LogInformation("Getting item {ID} at {RequestTime}", id, DateTime.Now);

If you're sending the logs to Azure Table Storage, each Azure Table entity can have ID and RequestTime
properties, which simplifies queries on log data. A query can find all logs within a particular RequestTime
range without parsing 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:

catch (Exception ex)

{
_logger.LogWarning(LoggingEvents.GetItemNotFound, ex, "GetById({ID}) NOT FOUND", id);
return NotFound();
}
return new ObjectResult(item);

catch (Exception ex)

{
_logger.LogWarning(LoggingEvents.GetItemNotFound, ex, "GetById({ID}) NOT FOUND", id);
return NotFound();
}
return new ObjectResult(item);

Different providers handle the exception information in different ways. Here's an example of Debug provider
output from the code shown above.
 TodoApiSample.Controllers.TodoController: Warning: GetById(55) NOT FOUND

System.Exception: Item not found exception.

at TodoApiSample.Controllers.TodoController.GetById(String id) in
C:\TodoApiSample\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.
To suppress all logs, 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 template code calls CreateDefaultBuilder to set up logging for the Console and Debug providers.
The CreateDefaultBuilder method sets up logging to look for configuration in a Logging section, as
explained earlier in this article.
The configuration data specifies minimum log levels by provider and category, as in the following example:

{
"Logging": {
"Debug": {
"LogLevel": {
"Default": "Information"
}
},
"Console": {
"IncludeScopes": false,
"LogLevel": {
"Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
"Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
"Microsoft.AspNetCore.Mvc.Razor": "Error",
"Default": "Information"
}
},
"LogLevel": {
"Default": "Debug"
}
}
}
 {
"Logging": {
"Debug": {
"LogLevel": {
"Default": "Information"
}
},
"Console": {
"IncludeScopes": false,
"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 for all
providers. A single rule is chosen for each provider when an ILogger object is created.
Filter rules in code
The following example shows how to register filter rules in code:

.ConfigureLogging(logging =>
logging.AddFilter("System", LogLevel.Debug)
.AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Trace))

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureLogging(logging =>
logging.AddFilter("System", LogLevel.Debug)
.AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Trace));

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
 CATEGORIES THAT BEGIN
NUMBER PROVIDER WITH ... MINIMUM LOG LEVEL

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 an ILogger object is created, the ILoggerFactory object selects a single rule per provider to apply to
that logger. All messages written by an ILogger instance 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 no match is found, select all rules with an empty
provider.
From the result of the preceding step, select rules with longest matching category prefix. If no match is
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 .
With the preceding list of rules, suppose 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.
The resulting ILogger instance sends logs of Trace level and above to the Debug provider. Logs of Debug
level and above are sent to the Console provider.
Provider aliases
Each provider defines an alias that can be used in configuration in place of the fully qualified type name. For
the built-in providers, use the following aliases:
Console
Debug
EventSource
EventLog
TraceSource
AzureAppServicesFile
AzureAppServicesBlob
ApplicationInsights
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:
 public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning));

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
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. For
example:

.ConfigureLogging(logBuilder =>
{
logBuilder.AddFilter((provider, category, logLevel) =>
{
if (provider == "Microsoft.Extensions.Logging.Console.ConsoleLoggerProvider" &&
category == "TodoApiSample.Controllers.TodoController")
{
return false;
}
return true;
});
})

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureLogging(logBuilder =>
{
logBuilder.AddFilter((provider, category, logLevel) =>
{
if (provider == "Microsoft.Extensions.Logging.Console.ConsoleLoggerProvider" &&
category == "TodoApiSample.Controllers.TodoController")
{
return false;
}
return true;
});
});

System categories and levels

Here are some categories used by ASP.NET Core and Entity Framework Core, with notes about what logs to
expect from them:

CATEGORY NOTES

Microsoft.AspNetCore General ASP.NET Core diagnostics.

Microsoft.AspNetCore.DataProtection Which keys were considered, found, and used.

 CATEGORY NOTES

Microsoft.AspNetCore.HostFiltering Hosts allowed.

Microsoft.AspNetCore.Hosting How long HTTP requests took to complete and what time
they started. Which hosting startup assemblies were
loaded.

Microsoft.AspNetCore.Mvc MVC and Razor diagnostics. Model binding, filter execution,

view compilation, action selection.

Microsoft.AspNetCore.Routing Route matching information.

Microsoft.AspNetCore.Server Connection start, stop, and keep alive responses. HTTPS

certificate information.

Microsoft.AspNetCore.StaticFiles Files served.

Microsoft.EntityFrameworkCore General Entity Framework Core diagnostics. Database

activity and configuration, change detection, migrations.

Log scopes
A scope can group a set of logical operations. This grouping can be used to attach the same data to each log
that's created as part of a set. For example, every log created as part of processing a transaction can include
the transaction ID.
A scope is an IDisposable type that's returned by the BeginScope method and lasts until it's disposed. Use a
scope by wrapping logger calls in a using block:

public IActionResult GetById(string id)

{
TodoItem item;
using (_logger.BeginScope("Message attached to logs created in the using block"))
{
_logger.LogInformation(LoggingEvents.GetItem, "Getting item {ID}", id);
item = _todoRepository.Find(id);
if (item == null)
{
_logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({ID}) NOT FOUND", id);
return NotFound();
}
}
return new ObjectResult(item);
}
 public IActionResult GetById(string id)
{
TodoItem item;
using (_logger.BeginScope("Message attached to logs created in the using block"))
{
_logger.LogInformation(LoggingEvents.GetItem, "Getting item {ID}", id);
item = _todoRepository.Find(id);
if (item == null)
{
_logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({ID}) NOT FOUND", id);
return NotFound();
}
}
return new ObjectResult(item);
}

The following code enables scopes for the console provider:

Program.cs:

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureLogging((hostingContext, logging) =>
{
logging.ClearProviders();
logging.AddConsole(options => options.IncludeScopes = true);
logging.AddDebug();
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});

.ConfigureLogging((hostingContext, logging) =>

{
logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
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.

Each log message includes the scoped information:

info: TodoApiSample.Controllers.TodoController[1002]
=> RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 =>
TodoApiSample.Controllers.TodoController.GetById (TodoApi) => Message attached to logs created in the
using block
Getting item 0
warn: TodoApiSample.Controllers.TodoController[4000]
=> RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 =>
TodoApiSample.Controllers.TodoController.GetById (TodoApi) => Message attached to logs created in the
using block
GetById(0) NOT FOUND
Built-in logging providers
ASP.NET Core ships the following providers:
Console
Debug
EventSource
EventLog
TraceSource
AzureAppServicesFile
AzureAppServicesBlob
ApplicationInsights
For information on stdout and debug logging with the ASP.NET Core Module, see Troubleshoot ASP.NET
Core on Azure App Service and IIS and ASP.NET Core Module.
Console provider
The Microsoft.Extensions.Logging.Console provider package sends log output to the console.

logging.AddConsole();

To see console logging output, open a command prompt in the project folder and run the following
command:

dotnet run

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();

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();

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 Core.
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();

AddEventLog overloads let you pass in EventLogSettings.

TraceSource provider
The Microsoft.Extensions.Logging.TraceSource provider package uses the TraceSource libraries and
providers.

logging.AddTraceSource(sourceSwitchName);

AddTraceSource overloads let you pass in a source switch and a trace listener.
To use this provider, an app has to run on the .NET Framework (rather than .NET Core). The provider can
route messages to a variety of listeners, such as the TextWriterTraceListener used in the sample app.
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.

logging.AddAzureWebAppDiagnostics();

The provider package isn't included in the shared framework. To use the provider, add the provider package to
the project.
The provider package isn't included in the Microsoft.AspNetCore.App metapackage. When targeting .NET
Framework or referencing the Microsoft.AspNetCore.App metapackage, add the provider package to the
project.
To configure provider settings, use AzureFileLoggerOptions and AzureBlobLoggerOptions, as shown in the
following example:
 public static void Main(string[] args)
{
var host = CreateHostBuilder(args).Build();

var todoRepository = host.Services.GetRequiredService<ITodoRepository>();

todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

var logger = host.Services.GetRequiredService<ILogger<Program>>();

logger.LogInformation("Seeded the database.");

host.Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureLogging(logging => logging.AddAzureWebAppDiagnostics())
.ConfigureServices(serviceCollection => serviceCollection
.Configure<AzureFileLoggerOptions>(options =>
{
options.FileName = "azure-diagnostics-";
options.FileSizeLimit = 50 * 1024;
options.RetainedFileCountLimit = 5;
}).Configure<AzureBlobLoggerOptions>(options =>
{
options.BlobName = "log.txt";
})
)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});

To configure provider settings, use AzureFileLoggerOptions and AzureBlobLoggerOptions, as shown in the

following example:

public static void Main(string[] args)

{
var host = CreateWebHostBuilder(args).Build();

var todoRepository = host.Services.GetRequiredService<ITodoRepository>();

todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

var logger = host.Services.GetRequiredService<ILogger<Program>>();

logger.LogInformation("Seeded the database.");

host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.ConfigureLogging(logging => logging.AddAzureWebAppDiagnostics())
.ConfigureServices(serviceCollection => serviceCollection
.Configure<AzureFileLoggerOptions>(options =>
{
options.FileName = "azure-diagnostics-";
options.FileSizeLimit = 50 * 1024;
options.RetainedFileCountLimit = 5;
}).Configure<AzureBlobLoggerOptions>(options =>
{
options.BlobName = "log.txt";
}))
.UseStartup<Startup>();
An AddAzureWebAppDiagnostics overload lets you pass in AzureAppServicesDiagnosticsSettings. The
settings object 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 in addition to what's provided with an
ILogger method call.)

When you deploy to an App Service app, the application honors the settings in the App Service logs section
of the App Service page of the Azure portal. When the following settings are updated, the changes take
effect immediately without requiring a restart or redeployment of the app.
Application Logging (Filesystem )
Application Logging (Blob)
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.
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.
Azure log streaming
Azure log streaming lets you view log activity in real time from:
The app server
The web server
Failed request tracing
To configure Azure log streaming:
Navigate to the App Service logs page from your app's portal page.
Set Application Logging (Filesystem ) to On.
Choose the log Level.
Navigate to the Log Stream page to view app messages. They're logged by the app through the ILogger
interface.
Azure Application Insights trace logging
The Microsoft.Extensions.Logging.ApplicationInsights provider package writes logs to Azure Application
Insights. Application Insights is a service that monitors a web app and provides tools for querying and
analyzing the telemetry data. If you use this provider, you can query and analyze your logs by using the
Application Insights tools.
The logging provider is included as a dependency of Microsoft.ApplicationInsights.AspNetCore, which is the
package that provides all available telemetry for ASP.NET Core. If you use this package, you don't have to
install the provider package.
Don't use the Microsoft.ApplicationInsights.Web package—that's for ASP.NET 4.x.
For more information, see the following resources:
Application Insights overview
Application Insights for ASP.NET Core applications - Start here if you want to implement the full range of
Application Insights telemetry along with logging.
ApplicationInsightsLoggerProvider for .NET Core ILogger logs - Start here if you want to implement the
logging provider without the rest of Application Insights telemetry.
Application Insights logging adapters.
Install, configure, and initialize the Application Insights SDK - Interactive tutorial on the Microsoft Learn
site.
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)
Sentry (GitHub repo)
Serilog (GitHub repo)
Stackdriver (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 ILoggerFactory .
For more information, see each provider's documentation. Third-party logging providers aren't supported by
Microsoft.

Additional resources
High-performance logging with LoggerMessage in ASP.NET Core
 Troubleshoot ASP.NET Core on Azure App Service
and IIS
7/24/2019 • 23 minutes to read • Edit Online

By Luke Latham and Justin Kotalik

This article provides information on common app startup errors and instructions on how to diagnose errors when
an app is deployed to Azure App Service or IIS:
App startup errors
Explains common startup HTTP status code scenarios.
Troubleshoot on Azure App Service
Provides troubleshooting advice for apps deployed to Azure App Service.
Troubleshoot on IIS
Provides troubleshooting advice for apps deployed to IIS or running on IIS Express locally. The guidance applies to
both Windows Server and Windows desktop deployments.
Clear package caches
Explains what to do when incoherent packages break an app when performing major upgrades or changing
package versions.
Additional resources
Lists additional troubleshooting topics.

App startup errors

In Visual Studio, an ASP.NET Core project defaults to IIS Express hosting during debugging. A 502.5 - Process
Failure or a 500.30 - Start Failure that occurs when debugging locally can be diagnosed using the advice in this
topic.
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 diagnosed using the advice in this topic.
403.14 Forbidden
The app fails to start. The following error is logged:

The Web server is configured to not list the contents of this directory.

The error is usually caused by a broken deployment on the hosting system, which includes any of the following
scenarios:
The app is deployed to the wrong folder on the hosting system.
The deployment process failed to move all of the app's files and folders to the deployment folder on the hosting
system.
The web.config file is missing from the deployment, or the web.config file contents are malformed.
Perform the following steps:
1. Delete all of the files and folders from the deployment folder on the hosting system.
2. Redeploy the contents of the app's publish folder to the hosting system using your normal method of
 deployment, such as Visual Studio, PowerShell, or manual deployment:
Confirm that the web.config file is present in the deployment and that its contents are correct.
When hosting on Azure App Service, confirm that the app is deployed to the D:\home\site\wwwroot folder.
When the app is hosted by IIS, confirm that the app is deployed to the IIS Physical path shown in IIS
Manager's Basic Settings.
3. Confirm that all of the app's files and folders are deployed by comparing the deployment on the hosting system
to the contents of the project's publish folder.
For more information on the layout of a published ASP.NET Core app, see ASP.NET Core directory structure. For
more information on the web.config file, see ASP.NET Core Module.
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.
500.0 In-Process Handler Load Failure
The worker process fails. The app doesn't start.
The ASP.NET Core Module fails to find the .NET Core CLR and find the in-process request handler
(aspnetcorev2_inprocess.dll). Check that:
The app targets either the Microsoft.AspNetCore.Server.IIS NuGet package or the Microsoft.AspNetCore.App
metapackage.
The version of the ASP.NET Core shared framework that the app targets is installed on the target machine.
500.0 Out-Of-Process Handler Load Failure
The worker process fails. The app doesn't start.
The ASP.NET Core Module fails to find the out-of-process hosting request handler. Make sure the
aspnetcorev2_outofprocess.dll is present in a subfolder next to aspnetcorev2.dll.
500.0 In-Process Handler Load Failure
The worker process fails. The app doesn't start.
An unknown error occurred loading ASP.NET Core Module components. Take one of the following actions:
Contact Microsoft Support (select Developer Tools then ASP.NET Core).
Ask a question on Stack Overflow.
File an issue on our GitHub repository.
500.30 In-Process Startup Failure
The worker process fails. The app doesn't start.
The ASP.NET Core Module attempts to start the .NET Core CLR in-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.
A common failure condition is the app is misconfigured due to targeting a version of the ASP.NET Core shared
framework that isn't present. Check which versions of the ASP.NET Core shared framework are installed on the
target machine.
500.31 ANCM Failed to Find Native Dependencies
The worker process fails. The app doesn't start.
The ASP.NET Core Module attempts to start the .NET Core runtime in-process, but it fails to start. The most
common cause of this startup failure is when the Microsoft.NETCore.App or Microsoft.AspNetCore.App runtime isn't
installed. If the app is deployed to target ASP.NET Core 3.0 and that version doesn't exist on the machine, this error
occurs. An example error message follows:

The specified framework 'Microsoft.NETCore.App', version '3.0.0' was not found.

- The following frameworks were found:
2.2.1 at [C:\Program Files\dotnet\x64\shared\Microsoft.NETCore.App]
3.0.0-preview5-27626-15 at [C:\Program Files\dotnet\x64\shared\Microsoft.NETCore.App]
3.0.0-preview6-27713-13 at [C:\Program Files\dotnet\x64\shared\Microsoft.NETCore.App]
3.0.0-preview6-27714-15 at [C:\Program Files\dotnet\x64\shared\Microsoft.NETCore.App]
3.0.0-preview6-27723-08 at [C:\Program Files\dotnet\x64\shared\Microsoft.NETCore.App]

The error message lists all the installed .NET Core versions and the version requested by the app. To fix this error,
either:
Install the appropriate version of .NET Core on the machine.
Change the app to target a version of .NET Core that's present on the machine.
Publish the app as a self-contained deployment.
When running in development (the ASPNETCORE_ENVIRONMENT environment variable is set to Development ), the
specific error is written to the HTTP response. The cause of a process startup failure is also found in the Application
Event Log.
500.32 ANCM Failed to Load dll
The worker process fails. The app doesn't start.
The most common cause for this error is that the app is published for an incompatible processor architecture. If the
worker process is running as a 32-bit app and the app was published to target 64-bit, this error occurs.
To fix this error, either:
Republish the app for the same processor architecture as the worker process.
Publish the app as a framework-dependent deployment.
500.33 ANCM Request Handler Load Failure
The worker process fails. The app doesn't start.
The app didn't reference the Microsoft.AspNetCore.App framework. Only apps targeting the
Microsoft.AspNetCore.App framework can be hosted by the ASP.NET Core Module.

To fix this error, confirm that the app is targeting the Microsoft.AspNetCore.App framework. Check the
.runtimeconfig.json to verify the framework targeted by the app.

500.34 ANCM Mixed Hosting Models Not Supported

The worker process can't run both an in-process app and an out-of-process app in the same process.
To fix this error, run apps in separate IIS application pools.
500.35 ANCM Multiple In-Process Applications in same Process
The worker process can't run both an in-process app and an out-of-process app in the same process.
To fix this error, run apps in separate IIS application pools.
500.36 ANCM Out-Of-Process Handler Load Failure
The out-of-process request handler, aspnetcorev2_outofprocess.dll, isn't next to the aspnetcorev2.dll file. This
indicates a corrupted installation of the ASP.NET Core Module.
To fix this error, repair the installation of the .NET Core Hosting Bundle (for IIS ) or Visual Studio (for IIS Express).
500.37 ANCM Failed to Start Within Startup Time Limit
ANCM failed to start within the provied startup time limit. By default, the timeout is 120 seconds.
This error can occur when starting a large number of apps on the same machine. Check for CPU/Memory usage
spikes on the server during startup. You may need to stagger the startup process of multiple apps.
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.
A common failure condition is the app is misconfigured due to targeting a version of the ASP.NET Core shared
framework that isn't present. Check which versions of the ASP.NET Core shared framework are installed on the
target machine. The shared framework is the set of assemblies (.dll files) that are installed on the machine and
referenced by a metapackage such as Microsoft.AspNetCore.App . The metapackage reference can specify a
minimum required version. For more information, see The shared framework.
The 502.5 Process Failure error page is returned when a hosting or app misconfiguration causes the worker
process to fail:
Failed to start application (ErrorCode '0x800700c1')

EventID: 1010
Source: IIS AspNetCore Module V2
Failed to start application '/LM/W3SVC/6/ROOT/', ErrorCode '0x800700c1'.

The app failed to start because the app's assembly (.dll) couldn't be loaded.
This error occurs when there's a bitness mismatch between the published app and the w3wp/iisexpress process.
Confirm that the app pool's 32-bit setting is correct:
1. Select the app pool in IIS Manager's Application Pools.
2. Select Advanced Settings under Edit Application Pool in the Actions panel.
3. Set Enable 32-Bit Applications:
If deploying a 32-bit (x86) app, set the value to True .
If deploying a 64-bit (x64) app, set the value to False .
Confirm that there isn't a conflict between a <Platform> MSBuild property in the project file and the published
bitness of the app.
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 on Azure App Service
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.

Application Event Log (Azure App Service )

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 in App Services.
2. Select Diagnose and solve problems.
3. Select the Diagnostic Tools heading.
4. Under Support Tools, select the Application Events button.
5. Examine the latest error provided by the IIS AspNetCoreModule or IIS AspNetCoreModule V2 entry 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. Open Advanced Tools 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. Open Advanced Tools 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.
Test a 32-bit (x86) app
Current release
1. cd d:\home\site\wwwroot
2. Run the app:
If the app is a framework-dependent deployment:

dotnet .\{ASSEMBLY NAME}.dll

If the app is a self-contained deployment:

{ASSEMBLY NAME}.exe

The console output from the app, showing any errors, is piped to the Kudu console.
Framework-dependent deployment running on a preview release
 Requires installing the ASP.NET Core {VERSION } (x86 ) Runtime site extension.
1. cd D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.x32 ( {X.Y} is the runtime version)
2. Run the app: dotnet \home\site\wwwroot\{ASSEMBLY NAME}.dll
The console output from the app, showing any errors, is piped to the Kudu console.
Test a 64-bit (x64) app
Current release
If the app is a 64-bit (x64) framework-dependent deployment:
1. cd D:\Program Files\dotnet
2. Run the app: dotnet \home\site\wwwroot\{ASSEMBLY NAME}.dll
If the app is a self-contained deployment:
1. cd D:\home\site\wwwroot
2. Run the app: {ASSEMBLY NAME}.exe

The console output from the app, showing any errors, is piped to the Kudu console.
Framework-dependent deployment running on a preview release
Requires installing the ASP.NET Core {VERSION } (x64 ) Runtime site extension.
1. cd D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.x64 ( {X.Y} is the runtime version)
2. Run the app: dotnet \home\site\wwwroot\{ASSEMBLY NAME}.dll

The console output from the app, showing any errors, is piped to the Kudu console.
ASP.NET Core Module stdout log (Azure App Service )
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.
10. Using the navigation bar at the top of the page, open Debug console and select CMD.
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.
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.
For more information, see ASP.NET Core Module.

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.

ASP.NET Core Module debug log (Azure App Service )

The ASP.NET Core Module debug log provides additional, deeper logging from the ASP.NET Core Module. To
enable and view stdout logs:
1. To enable the enhanced diagnostic log, perform either of the following:
Follow the instructions in Enhanced diagnostic logs to configure the app for an enhanced diagnostic
logging. Redeploy the app.
Add the <handlerSettings> shown in Enhanced diagnostic logs to the live app's web.config file using the
Kudu console:
a. Open Advanced Tools in the Development Tools area. Select the Go→ button. The Kudu
console opens in a new browser tab or window.
b. Using the navigation bar at the top of the page, open Debug console and select CMD.
c. Open the folders to the path site > wwwroot. Edit the web.config file by selecting the pencil
button. Add the <handlerSettings> section as shown in Enhanced diagnostic logs. Select the Save
button.
2. Open Advanced Tools in the Development Tools area. Select the Go→ button. The Kudu console opens in a
new browser tab or window.
3. Using the navigation bar at the top of the page, open Debug console and select CMD.
4. Open the folders to the path site > wwwroot. If you didn't supply a path for the aspnetcore-debug.log file, the
file appears in the list. If you supplied a path, navigate to the location of the log file.
5. Open the log file with the pencil button next to the file name.
Disable debug logging when troubleshooting is complete:
To disable the enhanced debug log, perform either of the following:
Remove the <handlerSettings> from the web.config file locally and redeploy the app.
Use the Kudu console to edit the web.config file and remove the <handlerSettings> section. Save the file.

For more information, see ASP.NET Core Module.

WARNING
Failure to disable the debug log can lead to app or server failure. There's no limit on log file size. Only use debug 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.

Slow or hanging app (Azure App Service )

When an app responds slowly or hangs on a request, see the following articles:
 Troubleshoot slow web app performance issues in Azure App Service
Use Crash Diagnoser Site Extension to Capture Dump for Intermittent Exception issues or performance issues
on Azure Web App
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.
2. Using the navigation bar at the top of the page, open Debug console and select CMD.
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.
5. Make a request to the app.
6. Within the log stream data, the cause of the error is indicated.
Be sure to disable stdout logging when troubleshooting is complete.
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
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.
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 on IIS
Application Event Log (IIS )
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 hosting 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 hosting configuration and less likely within
the app.
ASP.NET Core Module stdout log (IIS )
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.
6. Make a request to the app.
7. Navigate to the logs folder. Find and open the most recent stdout log.
8. Study the log for errors.
Disable stdout logging when troubleshooting is complete:
1. Edit the web.config file.
2. Set stdoutLogEnabled to false .
3. Save the file.
For more information, see ASP.NET Core Module.

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.
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.

ASP.NET Core Module debug log (IIS )

Add the following handler settings to the app's web.config file to enable ASP.NET Core Module debug log:

<aspNetCore ...>
<handlerSettings>
<handlerSetting name="debugLevel" value="file" />
<handlerSetting name="debugFile" value="c:\temp\ancm.log" />
</handlerSettings>
</aspNetCore>

Confirm that the path specified for the log exists and that the app pool's identity has write permissions to the
location.
For more information, see ASP.NET Core Module.
Enable 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.

<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile=".\logs\stdout"
hostingModel="InProcess">
<environmentVariables>
<environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
</environmentVariables>
</aspNetCore>
 <aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
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.
Obtain data from an app
If an app is capable of responding to requests, obtain request, connection, and additional data from the app using
terminal inline middleware. For more information and sample code, see Troubleshoot ASP.NET Core projects.
Slow or hanging app (IIS )
A crash dump is a snapshot of the system's memory and can help determine the cause of an app crash, startup
failure, or slow app.
App crashes or encounters an exception
Obtain and analyze a dump from Windows Error Reporting (WER ):
1. Create a folder to hold crash dump files at c:\dumps . The app pool must have write access to the folder.
2. Run the EnableDumps PowerShell script:
If the app uses the in-process hosting model, run the script for w3wp.exe:

.\EnableDumps w3wp.exe c:\dumps

If the app uses the out-of-process hosting model, run the script for dotnet.exe:

.\EnableDumps dotnet.exe c:\dumps

3. Run the app under the conditions that cause the crash to occur.
4. After the crash has occurred, run the DisableDumps PowerShell script:
If the app uses the in-process hosting model, run the script for w3wp.exe:

.\DisableDumps w3wp.exe

If the app uses the out-of-process hosting model, run the script for dotnet.exe:

.\DisableDumps dotnet.exe

After an app crashes and dump collection is complete, the app is allowed to terminate normally. The PowerShell
script configures WER to collect up to five dumps per app.
 WARNING
Crash dumps might take up a large amount of disk space (up to several gigabytes each).

App hangs, fails during startup, or runs normally

When an app hangs (stops responding but doesn't crash), fails during startup, or runs normally, see User-Mode
Dump Files: Choosing the Best Tool to select an appropriate tool to produce the dump.
Analyze the dump
A dump can be analyzed using several approaches. For more information, see Analyzing a User-Mode Dump File.

Clear package caches

Sometimes a functioning app fails immediately after upgrading either the .NET Core SDK on the development
machine or changing 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 by executing dotnet nuget locals all --clear from a command shell.
Clearing package caches can also be accomplished with 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.
3. Restore and rebuild the project.
4. Delete all of the files in the deployment folder on the server prior to redeploying the app.

Additional resources
Troubleshoot ASP.NET Core projects
Common errors reference for Azure App Service and IIS with ASP.NET Core
Handle errors in ASP.NET Core
ASP.NET Core Module
Azure documentation
Application Insights for ASP.NET Core
Remote debugging web apps section of Troubleshoot a web app in Azure App Service using Visual Studio
Azure App Service diagnostics overview
How to: Monitor Apps in Azure App Service
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)
Visual Studio documentation
Remote Debug ASP.NET Core on IIS in Azure in Visual Studio 2017
Remote Debug ASP.NET Core on a Remote IIS Computer in Visual Studio 2017
Learn to debug using Visual Studio
Visual Studio Code documentation
Debugging with Visual Studio Code
 Common errors reference for Azure App Service and
IIS with ASP.NET Core
7/18/2019 • 14 minutes to read • Edit Online

By Luke Latham
This topic offers troubleshooting advice for common errors when hosting ASP.NET Core apps on Azure Apps
Service and IIS.
Collect the following information:
Browser behavior (status code and error message)
Application Event Log entries
Azure App Service – See Troubleshoot ASP.NET Core on Azure App Service and IIS.
IIS
1. Select Start on the Windows menu, type Event Viewer, and press Enter.
2. After the Event Viewer opens, expand Windows Logs > Application in the sidebar.
ASP.NET Core Module stdout and debug log entries
Azure App Service – See Troubleshoot ASP.NET Core on Azure App Service and IIS.
IIS – Follow the instructions in the Log creation and redirection and Enhanced diagnostic logs sections of
the ASP.NET Core Module topic.
Compare error information to the following common errors. If a match is found, follow the troubleshooting advice.
The list of errors in this topic isn't exhaustive. If you encounter an error not listed here, open a new issue using the
Content feedback button at the bottom of this topic with detailed instructions on how to reproduce the error.

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.

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 .NET Core 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 or Apps & features. If a specific runtime is required, download the runtime
from the .NET Download Archives and install it on the system. 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 app pool 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.

Missing site extension, 32-bit (x86) and 64-bit (x64) site extensions
installed, or wrong process bitness set
Applies to apps hosted by Azure App Services.
Browser: HTTP Error 500.0 - ANCM In-Process Handler Load Failure
Application Log: Invoking hostfxr to find the inprocess request handler failed without finding any native
dependencies. Could not find inprocess request handler. Captured output from invoking hostfxr: It was not
possible to find any compatible framework version. The specified framework 'Microsoft.AspNetCore.App',
version '{VERSION }-preview -*' was not found. Failed to start application
'/LM/W3SVC/1416782824/ROOT', ErrorCode '0x8000ffff'.
ASP.NET Core Module stdout Log: It was not possible to find any compatible framework version. The
specified framework 'Microsoft.AspNetCore.App', version '{VERSION }-preview -*' was not found.
ASP.NET Core Module Debug Log: Invoking hostfxr to find the inprocess request handler failed without
finding any native dependencies. This most likely means the app is misconfigured, please check the versions of
Microsoft.NetCore.App and Microsoft.AspNetCore.App that are targeted by the application and are installed on
the machine. Failed HRESULT returned: 0x8000ffff. Could not find inprocess request handler. It was not possible
to find any compatible framework version. The specified framework 'Microsoft.AspNetCore.App', version
'{VERSION }-preview -*' was not found.
Troubleshooting:
If running the app on a preview runtime, install either the 32-bit (x86) or 64-bit (x64) site extension that
matches the bitness of the app and the app's runtime version. Don't install both extensions or multiple
runtime versions of the extension.
ASP.NET Core {RUNTIME VERSION } (x86) Runtime
ASP.NET Core {RUNTIME VERSION } (x64) Runtime
Restart the app. Wait several seconds for the app to restart.
If running the app on a preview runtime and both the 32-bit (x86) and 64-bit (x64) site extensions are
installed, uninstall the site extension that doesn't match the bitness of the app. After removing the site
extension, restart the app. Wait several seconds for the app to restart.
If running the app on a preview runtime and the site extension's bitness matches that of the app, confirm that
the preview site extension's runtime version matches the app's runtime version.
Confirm that the app's Platform in Application Settings matches the bitness of the app.
For more information, see Deploy ASP.NET Core apps to Azure App Service.
An x86 app is deployed but the app pool isn't enabled for 32-bit apps
Browser: HTTP Error 500.30 - ANCM In-Process Start Failure
Application Log: Application '/LM/W3SVC/5/ROOT' with physical root '{PATH}' hit unexpected managed
exception, exception code = '0xe0434352'. Please check the stderr logs for more information. Application
'/LM/W3SVC/5/ROOT' with physical root '{PATH}' failed to load clr and managed application. CLR worker
thread exited prematurely
ASP.NET Core Module stdout Log: The log file is created but empty.
ASP.NET Core Module Debug Log: Failed HRESULT returned: 0x8007023e
This scenario is trapped by the SDK when publishing a self-contained app. The SDK produces an error if the RID
doesn't match the platform target (for example, win10-x64 RID with <PlatformTarget>x86</PlatformTarget> in the
project file).
Troubleshooting:
For an x86 framework-dependent deployment ( <PlatformTarget>x86</PlatformTarget> ), enable the IIS app pool for
32-bit apps. In IIS Manager, open the app pool's Advanced Settings and set Enable 32-Bit Applications to
True.

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 stdout 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 Troubleshoot ASP.NET Core on Azure App Service and IIS.
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 --OR-- Unable to connect
Application Log: No entry
ASP.NET Core Module stdout Log: The log file isn't created.
ASP.NET Core Module Debug Log: The log file isn't created.
Troubleshooting:
Confirm the correct URI endpoint for the app is in use. 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.
Application Log: No entry
ASP.NET Core Module stdout Log: The log file isn't created.
ASP.NET Core Module Debug Log: The log file isn't created.
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, ASP.NET Core 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. --OR-- This page can't be displayed
Application Log: No entry
ASP.NET Core Module stdout Log: The log file isn't created.
ASP.NET Core Module Debug Log: The log file isn't created.
Troubleshooting:
Confirm that the proper role is enabled. See IIS Configuration.
Open Programs & Features or Apps & features and confirm that Windows Server Hosting is installed.
If Windows Server Hosting isn't present in the list of installed programs, download and install the .NET
Core Hosting Bundle.
Current .NET Core Hosting Bundle installer (direct download)
For more information, 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.
If you uninstalled the ASP.NET Core Hosting Bundle and installed an earlier version of the hosting bundle,
the applicationHost.config file doesn't include a section for the ASP.NET Core Module. Open
applicationHost.config at %windir%/System32/inetsrv/config and find the
<configuration><configSections><sectionGroup name="system.webServer"> section group. If the section for the
ASP.NET Core Module is missing from the section group, add the section element:
 <section name="aspNetCore" overrideModeDefault="Allow" />

Alternatively, install the latest version of the ASP.NET Core Hosting Bundle. The latest version is backwards-
compatible with supported ASP.NET Core apps.

Incorrect processPath, missing PATH variable, Hosting Bundle not

installed, system/IIS not restarted, VC++ Redistributable not installed,
or dotnet.exe access violation
Browser: HTTP Error 500.0 - ANCM In-Process Handler Load Failure
Application Log: Application 'MACHINE/WEBROOT/APPHOST/{ASSEMBLY }' with physical root 'C:
{PATH}' failed to start process with commandline '"{...}" ', ErrorCode = '0x80070002 : 0. Application '{PATH}'
wasn't able to start. Executable was not found at '{PATH}'. Failed to start application '/LM/W3SVC/2/ROOT',
ErrorCode '0x8007023e'.
ASP.NET Core Module stdout Log: The log file isn't created.
ASP.NET Core Module Debug Log: Event Log: 'Application '{PATH}' wasn't able to start. Executable was
not found at '{PATH}'. Failed HRESULT returned: 0x8007023e
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 '"{...}" ', ErrorCode = '0x80070002 : 0.
ASP.NET Core Module stdout Log: The log file is created but empty.
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 Troubleshoot ASP.NET Core on Azure App Service and IIS.
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 app pool. Confirm that the app
pool user identity has access to the C:\Program Files\dotnet directory. Confirm that there are no deny rules
configured for the app pool 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.
Current .NET Core Hosting Bundle installer (direct download)
For more information, see Install the .NET Core Hosting Bundle.
If a specific runtime is required, download the runtime from the .NET Download Archives and install it on
the system. 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

Browser: HTTP Error 500.0 - ANCM In-Process Handler Load Failure
Application Log: Invoking hostfxr to find the inprocess request handler failed without finding any native
dependencies. This most likely means the app is misconfigured, please check the versions of
Microsoft.NetCore.App and Microsoft.AspNetCore.App that are targeted by the application and are installed
on the machine. Could not find inprocess request handler. Captured output from invoking hostfxr: Did you
mean to run dotnet SDK commands? Please install dotnet SDK from: https://go.microsoft.com/fwlink/?
LinkID=798306&clcid=0x409 Failed to start application '/LM/W3SVC/3/ROOT', ErrorCode '0x8000ffff'.
ASP.NET Core Module stdout Log: Did you mean to run dotnet SDK commands? Please install dotnet
SDK from: https://go.microsoft.com/fwlink/?LinkID=798306&clcid=0x409
ASP.NET Core Module Debug Log: Invoking hostfxr to find the inprocess request handler failed without
finding any native dependencies. This most likely means the app is misconfigured, please check the versions
of Microsoft.NetCore.App and Microsoft.AspNetCore.App that are targeted by the application and are
installed on the machine. Failed HRESULT returned: 0x8000ffff Could not find inprocess request handler.
Captured output from invoking hostfxr: Did you mean to run dotnet SDK commands? Please install dotnet
SDK from: https://go.microsoft.com/fwlink/?LinkID=798306&clcid=0x409 Failed HRESULT returned:
0x8000ffff
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 '"dotnet" .{ASSEMBLY }.dll', ErrorCode = '0x80004005 :
80008081.
ASP.NET Core Module stdout Log: The application to execute does not exist: 'PATH{ASSEMBLY }.dll'
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 Troubleshoot ASP.NET Core on Azure App Service and IIS.
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="{ARGUMENT_1}, {ARGUMENT_2}, ... {ARGUMENT_X}" )
for a self-contained deployment (SCD ).

Missing .NET Core shared framework

Browser: HTTP Error 500.0 - ANCM In-Process Handler Load Failure
Application Log: Invoking hostfxr to find the inprocess request handler failed without finding any native
dependencies. This most likely means the app is misconfigured, please check the versions of
Microsoft.NetCore.App and Microsoft.AspNetCore.App that are targeted by the application and are installed
on the machine. Could not find inprocess request handler. Captured output from invoking hostfxr: It was not
possible to find any compatible framework version. The specified framework 'Microsoft.AspNetCore.App',
version '{VERSION }' was not found.
Failed to start application '/LM/W3SVC/5/ROOT', ErrorCode '0x8000ffff'.
ASP.NET Core Module stdout Log: It was not possible to find any compatible framework version. The
specified framework 'Microsoft.AspNetCore.App', version '{VERSION }' was not found.
 ASP.NET Core Module Debug Log: Failed HRESULT returned: 0x8000ffff
Troubleshooting:
For a framework-dependent deployment (FDD ), confirm that the correct runtime installed on the system.

Stopped Application Pool

Browser: 503 Service Unavailable
Application Log: No entry
ASP.NET Core Module stdout Log: The log file isn't created.
ASP.NET Core Module Debug Log: The log file isn't created.
Troubleshooting:
Confirm that the Application Pool isn't in the Stopped state.

Sub-application includes a <handlers> section

Browser: HTTP Error 500.19 - Internal Server Error
Application Log: No entry
ASP.NET Core Module stdout Log: The root app's log file is created and shows normal operation. The
sub-app's log file isn't created.
ASP.NET Core Module Debug Log: The root app's log file is created and shows normal operation. The sub-
app's log file isn't created.
Troubleshooting:
Confirm that the sub-app's web.config file doesn't include a <handlers> section or that the sub-app doesn't inherit
the parent app's handlers.
The parent app's <system.webServer> section of web.config is placed inside of a <location> element. The
InheritInChildApplications property is set to false to indicate that the settings specified within the <location>
element aren't inherited by apps that reside in a subdirectory of the parent app. For more information, see
ASP.NET Core Module.
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: Could not start stdout redirection in C:\Program Files\IIS\Asp.Net Core
Module\V2\aspnetcorev2.dll. Exception message: HRESULT 0x80070005 returned at
{PATH}\aspnetcoremodulev2\commonlib\fileoutputmanager.cpp:84. Could not stop stdout redirection in
C:\Program Files\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll. Exception message: HRESULT
0x80070002 returned at {PATH}. Could not start stdout redirection in {PATH}\aspnetcorev2_inprocess.dll.
ASP.NET Core Module stdout Log: The log file isn't created.
ASP.NET Core Module debug Log: Could not start stdout redirection in C:\Program Files\IIS\Asp.Net
Core Module\V2\aspnetcorev2.dll. Exception message: HRESULT 0x80070005 returned at
{PATH}\aspnetcoremodulev2\commonlib\fileoutputmanager.cpp:84. Could not stop stdout redirection in
 C:\Program Files\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll. Exception message: HRESULT
0x80070002 returned at {PATH}. Could not start stdout redirection in {PATH}\aspnetcorev2_inprocess.dll.
Application Log: Warning: Could not create stdoutLogFile \?{PATH}\path_doesnt_exist\stdout_{PROCESS
ID }_{TIMESTAMP }.log, ErrorCode = -2147024893.
ASP.NET Core Module stdout Log: The log file isn't created.
Troubleshooting:
The stdoutLogFile path specified in the <aspNetCore> element of web.config doesn't exist. For more
information, see ASP.NET Core Module: Log creation and redirection.
The app pool user doesn't have write access to the stdout log path.

Application configuration general issue

Browser: HTTP Error 500.0 - ANCM In-Process Handler Load Failure --OR-- HTTP Error 500.30 - ANCM
In-Process Start Failure
Application Log: Variable
ASP.NET Core Module stdout Log: The log file is created but empty or created with normal entries until
the point of the app failing.
ASP.NET Core Module Debug Log: Variable
Browser: HTTP Error 502.5 - Process Failure
Application Log: Application 'MACHINE/WEBROOT/APPHOST/{ASSEMBLY }' with physical root 'C:
{PATH}' created process with commandline '"C:{PATH}{ASSEMBLY }.{exe|dll}" ' but either crashed or did not
respond or did not listen on the given port '{PORT}', ErrorCode = '{ERROR CODE }'
ASP.NET Core Module stdout Log: The log file is created but empty.
Troubleshooting:
The process failed to start, most likely due to an app configuration or programming issue.
For more information, see the following topics:
Troubleshoot ASP.NET Core on Azure App Service and IIS
Troubleshoot ASP.NET Core projects
 Razor Pages with Entity Framework Core in
ASP.NET Core - Tutorial 1 of 8
8/9/2019 • 32 minutes to read • Edit Online

By Tom Dykstra and Rick Anderson

This is the first in a series of tutorials that show how to use Entity Framework (EF ) Core in an ASP.NET Core
Razor Pages app. The tutorials build a web site for a fictional Contoso University. The site includes
functionality such as student admission, course creation, and instructor assignments.
Download or view the completed app. Download instructions.

Prerequisites
If you're new to Razor Pages, go through the Get started with Razor Pages tutorial series before starting
this one.
Visual Studio
Visual Studio Code
Visual Studio 2019 with the ASP.NET and web development workload
.NET Core SDK 3.0 Preview

Database engines
The Visual Studio instructions use SQL Server LocalDB, a version of SQL Server Express that runs only on
Windows.
The Visual Studio Code instructions use SQLite, a cross-platform database engine.
If you choose to use SQLite, download and install a third-party tool for managing and viewing a SQLite
database, such as DB Browser for SQLite.

Troubleshooting
If you run into a problem you can't resolve, compare your code to the completed project. A good way to get
help is by posting a question to StackOverflow.com, using the ASP.NET Core tag or the EF Core tag.

The sample 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 based on the built-in project templates. The tutorial's focus is on how to use EF
Core, not how to customize the UI.
Follow the link at the top of the page to get the source code for the completed project. The cu30 folder has
the code for the ASP.NET Core 3.0 version of the tutorial. Files that reflect the state of the code for tutorials
1-7 can be found in the cu30snapshots folder.
Visual Studio
Visual Studio Code
To run the app after downloading the completed project:
 Delete three files and one folder that have SQLite in the name.
Build the project.
In Package Manager Console (PMC ) run the following command:

Update-Database

Run the project to seed the database.

Create the web app project

Visual Studio
Visual Studio Code
From the Visual Studio File menu, select New > Project.
Select ASP.NET Core Web Application.
Name the project ContosoUniversity. It's important to use this exact name including capitalization, so the
namespaces match when code is copied and pasted.
Select .NET Core and ASP.NET Core 3.0 in the dropdowns, and then select Web Application.

Set up the site style

Set up the site header, footer, and menu by updatingPages/Shared/_Layout.cshtml:
Change each occurrence of "ContosoUniversity" to "Contoso University". There are three occurrences.
Delete the Home and Privacy menu entries, and add entries for About, Students, Courses,
Instructors, and Departments.
The changes are highlighted.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@ViewData["Title"] - Contoso University</title>
<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
<link rel="stylesheet" href="~/css/site.css" />
</head>
<body>
<header>
<nav class="navbar navbar-expand-sm navbar-toggleable-sm navbar-light bg-white border-bottom box-
shadow mb-3">
<div class="container">
<a class="navbar-brand" asp-area="" asp-page="/Index">Contoso University</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target=".navbar-
collapse" aria-controls="navbarSupportedContent"
aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="navbar-collapse collapse d-sm-inline-flex flex-sm-row-reverse">
<ul class="navbar-nav flex-grow-1">
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-page="/About">About</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-
page="/Students/Index">Students</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-
page="/Courses/Index">Courses</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-
page="/Instructors/Index">Instructors</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-
page="/Departments/Index">Departments</a>
</li>
</ul>
</div>
</div>
</nav>
</header>
<div class="container">
<main role="main" class="pb-3">
@RenderBody()
</main>
</div>

<footer class="border-top footer text-muted">

<div class="container">
&copy; 2019 - Contoso University - <a asp-area="" asp-page="/Privacy">Privacy</a>
</div>
</footer>

<script src="~/lib/jquery/dist/jquery.js"></script>
<script src="~/lib/bootstrap/dist/js/bootstrap.bundle.js"></script>
<script src="~/js/site.js" asp-append-version="true"></script>

@RenderSection("Scripts", required: false)

</body>
</html>
In Pages/Index.cshtml, replace the contents of the file with the following code to replace the text about
ASP.NET Core with text about this app:

@page
@model IndexModel
@{
ViewData["Title"] = "Home page";
}

<div class="row mb-auto">

<div class="col-md-4">
<div class="row no-gutters border mb-4">
<div class="col p-4 mb-4 ">
<p class="card-text">
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>
</div>
</div>
<div class="col-md-4">
<div class="row no-gutters border mb-4">
<div class="col p-4 d-flex flex-column position-static">
<p class="card-text mb-auto">
You can build the application by following the steps in a series of tutorials.
</p>
<p>
<a href="https://docs.microsoft.com/aspnet/core/data/ef-rp/intro" class="stretched-
link">See the tutorial</a>
</p>
</div>
</div>
</div>
<div class="col-md-4">
<div class="row no-gutters border mb-4">
<div class="col p-4 d-flex flex-column">
<p class="card-text mb-auto">
You can download the completed project from GitHub.
</p>
<p>
<a href="https://github.com/aspnet/AspNetCore.Docs/tree/master/aspnetcore/data/ef-
rp/intro/samples" class="stretched-link">See project source code</a>
</p>
</div>
</div>
</div>
</div>

Run the app to verify that the home page appears.

The data model

The following sections create a data model:
A student can enroll in any number of courses, and a course can have any number of students enrolled in it.

The Student entity

Create a Models folder in the project folder.

Create Models/Student.cs with the following code:

using System;
using System.Collections.Generic;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
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 table that corresponds to this class. By
default, EF Core interprets a property that's named ID or classnameID as the primary key. So the alternative
automatically recognized name for the Student class primary key is StudentID .
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 holds all of the Enrollment entities
that are related to that Student. For example, if a Student row in the database has two related Enrollment
rows, the Enrollments navigation property contains those two Enrollment entities.
In the database, an Enrollment row is related to a Student row if its StudentID column contains the student's
ID value. For example, suppose a Student row has ID=1. Related Enrollment rows will have StudentID = 1.
StudentID is a foreign key in the Enrollment table.
The Enrollments property is defined as ICollection<Enrollment> because there may be multiple related
Enrollment entities. You can use other collection types, such as List<Enrollment> or HashSet<Enrollment> .
When ICollection<Enrollment> is used, EF Core creates a HashSet<Enrollment> collection by default.

The Enrollment entity

Create Models/Enrollment.cs with the following code:

namespace ContosoUniversity.Models
{
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 EnrollmentID property is the primary key; this entity uses the classnameID pattern instead of ID by
itself. For a production data model, choose one pattern and use it consistently. This tutorial uses both just to
illustrate that both work. Using ID without classname makes it easier to implement some kinds of data
model changes.
The Gradeproperty 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 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 is the foreign key 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

Create Models/Course.cs with the following code:

using System.Collections.Generic;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Course
{
[DatabaseGenerated(DatabaseGeneratedOption.None)]
public int CourseID { get; set; }
public string Title { get; set; }
public int Credits { get; set; }

public ICollection<Enrollment> Enrollments { 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 database
generate it.
Build the project to validate that there are no compiler errors.

Scaffold Student pages

In this section, you use the ASP.NET Core scaffolding tool to generate:
An EF Core context class. The context is the main class that coordinates Entity Framework functionality for
a given data model. It derives from the Microsoft.EntityFrameworkCore.DbContext class.
Razor pages that handle Create, Read, Update, and Delete (CRUD ) operations for the Student entity.

Visual Studio
Visual Studio Code
Create a Students folder in the Pages folder.
In Solution Explorer, right-click the Pages/Students folder and select Add > New Scaffolded Item.
In the Add Scaffold dialog, select Razor Pages using Entity Framework (CRUD ) > ADD.
In the Add Razor Pages using Entity Framework (CRUD ) dialog:
In the Model class drop-down, select Student (ContosoUniversity.Models).
In the Data context class row, select the + (plus) sign.
Change the data context name from ContosoUniversity.Models.ContosoUniversityContext to
ContosoUniversity.Data.SchoolContext.
Select Add.
The following packages are automatically installed:
Microsoft.VisualStudio.Web.CodeGeneration.Design
Microsoft.EntityFrameworkCore.SqlServer
Microsoft.Extensions.Logging.Debug
Microsoft.EntityFrameworkCore.Tools

If you have a problem with the preceding step, build the project and retry the scaffold step.
The scaffolding process:
Creates Razor pages in the Pages/Students folder:
Create.cshtml and Create.cshtml.cs
Delete.cshtml and Delete.cshtml.cs
Details.cshtml and Details.cshtml.cs
Edit.cshtml and Edit.cshtml.cs
Index.cshtml and Index.cshtml.cs
Creates Data/SchoolContext.cs.
Adds the context to dependency injection in Startup.cs.
Adds a database connection string to appsettings.json.

Database connection string

Visual Studio
Visual Studio Code
The connection string specifies SQL Server LocalDB.

{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*",
"ConnectionStrings": {
"SchoolContext": "Server=
(localdb)\\mssqllocaldb;Database=SchoolContext;Trusted_Connection=True;MultipleActiveResultSets=true"
}
}

LocalDB is a lightweight version of the SQL Server Express Database Engine and is intended for app
development, not production use. By default, LocalDB creates .mdf files in the C:/Users/<user> directory.

Update the database context class

The main class that coordinates EF Core functionality for a given data model is the database context class.
The context is derived from Microsoft.EntityFrameworkCore.DbContext. The 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:
 using Microsoft.EntityFrameworkCore;
using ContosoUniversity.Models;

namespace ContosoUniversity.Data
{
public class SchoolContext : DbContext
{
public SchoolContext (DbContextOptions<SchoolContext> options)
: base(options)
{
}

public DbSet<Student> Students { get; set; }

public DbSet<Enrollment> Enrollments { get; set; }
public DbSet<Course> Courses { get; set; }

protected override void OnModelCreating(ModelBuilder modelBuilder)

{
modelBuilder.Entity<Course>().ToTable("Course");
modelBuilder.Entity<Enrollment>().ToTable("Enrollment");
modelBuilder.Entity<Student>().ToTable("Student");
}
}
}

The highlighted code creates a DbSet<TEntity> property for each entity set. In EF Core terminology:
An entity set typically corresponds to a database table.
An entity corresponds to a row in the table.
Since an entity set contains multiple entities, the DBSet properties should be plural names. Since the
scaffolding tool created a Student DBSet, this step changes it to plural Students .
To make the Razor Pages code match the new DBSet name, make a global change across the whole project
of _context.Student to _context.Students . There are 8 occurrences.
Build the project to verify there are no compiler errors.

Startup.cs
ASP.NET Core is built with dependency injection. Services (such as the EF Core database 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 database context instance is shown later in the tutorial.
The scaffolding tool automatically registered the context class with the dependency injection container.
Visual Studio
Visual Studio Code
In ConfigureServices , the highlighted lines were added by the scaffolder:

public void ConfigureServices(IServiceCollection services)

{
services.AddRazorPages();

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
appsettings.json file.

Create the database

Update Program.cs to create the database if it doesn't exist:

using ContosoUniversity.Data;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using System;

namespace ContosoUniversity
{
public class Program
{
public static void Main(string[] args)
{
var host = CreateHostBuilder(args).Build();

CreateDbIfNotExists(host);

host.Run();
}

private static void CreateDbIfNotExists(IHost host)

{
using (var scope = host.Services.CreateScope())
{
var services = scope.ServiceProvider;

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

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
}

The EnsureCreated method takes no action if a database for the context exists. If no database exists, it creates
the database and schema. EnsureCreated enables the following workflow for handling data model changes:
Delete the database. Any existing data is lost.
Change the data model. For example, add an EmailAddress field.
Run the app.
EnsureCreated creates a database with the new schema.
This workflow works well early in development when the schema is rapidly evolving, as long as you don't
need to preserve data. The situation is different when data that has been entered into the database needs to
be preserved. When that is the case, use migrations.
Later in the tutorial series, you delete the database that was created by EnsureCreated and use migrations
instead. A database that is created by EnsureCreated can't be updated by using migrations.
Test the app
Run the app.
Select the Students link and then Create New.
Test the Edit, Details, and Delete links.

Seed the database

The EnsureCreated method creates an empty database. This section adds code that populates the database
with test data.
Create Data/DbInitializer.cs with the following code:

using ContosoUniversity.Data;
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.Students.Any())
{
return; // DB has been seeded
}

var students = new Student[]

{
new
Student{FirstMidName="Carson",LastName="Alexander",EnrollmentDate=DateTime.Parse("2019-09-01")},
new
Student{FirstMidName="Meredith",LastName="Alonso",EnrollmentDate=DateTime.Parse("2017-09-01")},
new Student{FirstMidName="Arturo",LastName="Anand",EnrollmentDate=DateTime.Parse("2018-
09-01")},
new
Student{FirstMidName="Gytis",LastName="Barzdukas",EnrollmentDate=DateTime.Parse("2017-09-01")},
new Student{FirstMidName="Yan",LastName="Li",EnrollmentDate=DateTime.Parse("2017-09-
01")},
new Student{FirstMidName="Peggy",LastName="Justice",EnrollmentDate=DateTime.Parse("2016-
09-01")},
new Student{FirstMidName="Laura",LastName="Norman",EnrollmentDate=DateTime.Parse("2018-
09-01")},
new Student{FirstMidName="Nino",LastName="Olivetto",EnrollmentDate=DateTime.Parse("2019-
09-01")}
};
foreach (Student s in students)
{
context.Students.Add(s);
}
context.SaveChanges();

var courses = new Course[]

 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.Courses.Add(c);
}
context.SaveChanges();

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=1045,Grade=Grade.B},
new Enrollment{StudentID=2,CourseID=3141,Grade=Grade.F},
new Enrollment{StudentID=2,CourseID=2021,Grade=Grade.F},
new Enrollment{StudentID=3,CourseID=1050},
new Enrollment{StudentID=4,CourseID=1050},
new Enrollment{StudentID=4,CourseID=4022,Grade=Grade.F},
new Enrollment{StudentID=5,CourseID=4041,Grade=Grade.C},
new Enrollment{StudentID=6,CourseID=1045},
new Enrollment{StudentID=7,CourseID=3141,Grade=Grade.A},
};
foreach (Enrollment e in enrollments)
{
context.Enrollments.Add(e);
}
context.SaveChanges();
}
}
}

The code checks if there are any students in the database. If there are no students, it adds test data to the
database. It creates the test data in arrays rather than List<T> collections to optimize performance.
In Program.cs, replace the EnsureCreated call with a DbInitializer.Initialize call:

// context.Database.EnsureCreated();
DbInitializer.Initialize(context);

Visual Studio
Visual Studio Code
Run the app, delete any student records you created earlier, and stop the app.
Restart the app.
Select the Students page to see the seeded data.

View the database

Visual Studio
Visual Studio Code
Open SQL Server Object Explorer (SSOX) from the View menu in Visual Studio.
 In SSOX, select (localdb)\MSSQLLocalDB > Databases > SchoolContext-{GUID }. The database
name is generated from the context name you provided earlier plus a dash and a GUID.
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.
Right-click the Student table and click View Code to see how the Student model maps to the Student
table schema.

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 can 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.

public async Task OnGetAsync()

{
Students = await _context.Students.ToListAsync();
}

The async keyword tells the compiler to:

Generate callbacks for parts of the method body.
Create the Task object that's returned.
The Task<T> return type 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 database 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 database.
For more information about asynchronous programming in .NET, see Async Overview and Asynchronous
programming with async and await.
Next steps

NEXT
T U T O R IA L

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
Visual Studio Code
Visual Studio 2019 with the following workloads:
ASP.NET and web development
.NET Core cross-platform development
.NET Core 2.1 SDK or later
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
Visual Studio Code
From the Visual Studio File menu, select New > Project.
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.
Select ASP.NET Core 2.1 in the dropdown, and then select Web Application.
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>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@ViewData["Title"] : Contoso University</title>

<environment include="Development">
<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
<link rel="stylesheet" href="~/css/site.css" />
</environment>
<environment exclude="Development">
<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>
</head>
<body>
<nav class="navbar navbar-inverse navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-
collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a asp-page="/Index" class="navbar-brand">Contoso University</a>
</div>
<div class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<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" />

<div class="container body-content">

@RenderBody()
<hr />
<footer>
<p>&copy; 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">
<div class="col-md-4">
<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>
<div class="col-md-4">
<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 &raquo;
</a>
</p>
</div>
<div class="col-md-4">
<h2>Download it</h2>
<p>You can download the completed project from GitHub.</p>
<p>
<a class="btn btn-default"
href="https://github.com/aspnet/AspNetCore.Docs/tree/master/aspnetcore/data/ef-
rp/intro/samples/cu-final">
See project source code &raquo;
</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;
using System.Collections.Generic;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
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:

namespace ContosoUniversity.Models
{
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 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 property is a foreign key, and the corresponding navigation property is Student . An
StudentID
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:

 using System.Collections.Generic;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Course
{
[DatabaseGenerated(DatabaseGeneratedOption.None)]
public int CourseID { get; set; }
public string Title { get; set; }
public int Credits { get; set; }

public ICollection<Enrollment> Enrollments { 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
Visual Studio Code
In Solution Explorer, right click on the Pages/Students 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 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.
The scaffold process created and changed the following files:
Files created
Pages/Students Create, Delete, Details, Edit, Index.
Data/SchoolContext.cs
File 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 ConfigureServices method in Startup.cs. The highlighted line was added by the scaffolder:
 public void ConfigureServices(IServiceCollection services)
{
services.Configure<CookiePolicyOptions>(options =>
{
// This lambda determines whether user consent for
//non -essential cookies is needed for a given request.
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

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
appsettings.json file.

Update main
In Program.cs, modify the Main method to do the following:
Get a DB context instance from the dependency injection container.
Call the EnsureCreated.
Dispose the context when the EnsureCreated method completes.
The following code shows the updated Program.cs file.
 using ContosoUniversity.Models; // SchoolContext
using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection; // CreateScope
using Microsoft.Extensions.Logging;
using System;

namespace ContosoUniversity
{
public class Program
{
public static void Main(string[] args)
{
var host = CreateWebHostBuilder(args).Build();

using (var scope = host.Services.CreateScope())

{
var services = scope.ServiceProvider;

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

host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>();
}
}

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.
Test the Edit, Details, and Delete links.
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:

using Microsoft.EntityFrameworkCore;

namespace ContosoUniversity.Models
{
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 .
SQL Server Express LocalDB
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.Models
{
public static class DbInitializer
{
public static void Initialize(SchoolContext context)
{
// context.Database.EnsureCreated();

// Look for any students.

if (context.Student.Any())
{
 {
return; // DB has been seeded
}

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);
}
context.SaveChanges();

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);
}
context.SaveChanges();

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=1045,Grade=Grade.B},
new Enrollment{StudentID=2,CourseID=3141,Grade=Grade.F},
new Enrollment{StudentID=2,CourseID=2021,Grade=Grade.F},
new Enrollment{StudentID=3,CourseID=1050},
new Enrollment{StudentID=4,CourseID=1050},
new Enrollment{StudentID=4,CourseID=4022,Grade=Grade.F},
new Enrollment{StudentID=5,CourseID=4041,Grade=Grade.C},
new Enrollment{StudentID=6,CourseID=1045},
new Enrollment{StudentID=7,CourseID=3141,Grade=Grade.A},
};
foreach (Enrollment e in enrollments)
{
context.Enrollment.Add(e);
}
context.SaveChanges();
}
}
}
Note: The preceding code uses Models for the namespace ( namespace ContosoUniversity.Models ) rather than
Data . Models is consistent with the scaffolder -generated code. For more information, see this GitHub
scaffolding issue.
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 :

public class Program

{
public static void Main(string[] args)
{
var host = CreateWebHostBuilder(args).Build();

using (var scope = host.Services.CreateScope())

{
var services = scope.ServiceProvider;

try
{
var context = services.GetRequiredService<SchoolContext>();
// using ContosoUniversity.Data;
DbInitializer.Initialize(context);
}
catch (Exception ex)
{
var logger = services.GetRequiredService<ILogger<Program>>();
logger.LogError(ex, "An error occurred creating the DB.");
}
}

host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>();
}

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
The database name is generated from the context name you provided earlier plus a dash and a GUID. Thus,
the database name will be "SchoolContext-{GUID }". The GUID will be different for each user. Open SQL
Server Object Explorer (SSOX) from the View menu in Visual Studio. In SSOX, click
(localdb)\MSSQLLocalDB > Databases > SchoolContext-{GUID }.
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.

public async Task OnGetAsync()

{
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.

Additional resources
YouTube version of this tutorial

NEXT
 Razor Pages with EF Core in ASP.NET Core - CRUD
- 2 of 8
8/9/2019 • 22 minutes to read • Edit Online

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.
If you run into problems you can't solve, download the completed app and compare that code to what you
created by following the tutorial.
In this tutorial, the scaffolded CRUD (create, read, update, delete) code is reviewed and customized.

No repository
Some developers use a service layer or repository pattern to create an abstraction layer between the UI (Razor
Pages) and the data access layer. This tutorial doesn't do that. To minimize complexity and keep the tutorial
focused on EF Core, EF Core code is added directly to the page model classes.

Update the Details page

The scaffolded code for the Students pages doesn't include enrollment data. In this section, you add enrollments
to the Details page.
Read enrollments
To display a student's enrollment data on the page, you need to read it. The scaffolded code in
Pages/Students/Details.cshtml.cs reads only the Student data, without the Enrollment data:

public async Task<IActionResult> OnGetAsync(int? id)

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

Student = await _context.Students.FirstOrDefaultAsync(m => m.ID == id);

if (Student == null)
{
return NotFound();
}
return Page();
}

Replace the OnGetAsync method with the following code to read enrollment data for the selected student. The
changes are highlighted.
 public async Task<IActionResult> OnGetAsync(int? id)
{
if (id == null)
{
return NotFound();
}

Student = await _context.Students

.Include(s => s.Enrollments)
.ThenInclude(e => e.Course)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.ID == id);

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 where the entities returned are not updated in the
current context. AsNoTracking is discussed later in this tutorial.
Display enrollments
Replace the code in Pages/Students/Details.cshtml with the following code to display a list of enrollments. The
changes are highlighted.
 @page
@model ContosoUniversity.Pages.Students.DetailsModel

@{
ViewData["Title"] = "Details";
}

<h1>Details</h1>

<div>
<h4>Student</h4>
<hr />
<dl class="row">
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Student.LastName)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Student.LastName)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Student.FirstMidName)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Student.FirstMidName)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Student.EnrollmentDate)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Student.EnrollmentDate)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Student.Enrollments)
</dt>
<dd class="col-sm-10">
<table class="table">
<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>

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.
Ways to read one entity
The generated code uses FirstOrDefaultAsync to read one entity. This method returns null if nothing is found;
otherwise, it returns the first row found that satisfies the query filter criteria. FirstOrDefaultAsync is generally a
better choice than the following alternatives:
SingleOrDefaultAsync - Throws an exception if there's more than one entity that satisfies the query filter. To
determine if more than one row could be returned by the query, SingleOrDefaultAsync tries to fetch multiple
rows. This extra work is unnecessary if the query can only return one entity, as when it searches on a unique
key.
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 database. This method is optimized to look up a single entity, but you
can't call Include with FindAsync . So if related data is needed, FirstOrDefaultAsync is the better choice.
Route data vs. query string
The URL for the Details page is https://localhost:<port>/Students/Details?id=1 . The entity's primary key value
is in the query string. Some developers prefer to pass the key value in route data:
https://localhost:<port>/Students/Details/1 . For more information, see Update the generated code.

Update the Create page

The scaffolded OnPostAsync code for the Create page is vulnerable to overposting. Replace the OnPostAsync
method in Pages/Students/Create.cshtml.cs with the following code.

public async Task<IActionResult> OnPostAsync()

{
var emptyStudent = new Student();

if (await TryUpdateModelAsync<Student>(
emptyStudent,
"student", // Prefix for form value.
s => s.FirstMidName, s => s.LastName, s => s.EnrollmentDate))
{
_context.Students.Add(emptyStudent);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}

return Page();
}

TryUpdateModelAsync
The preceding code creates a Student object and then uses posted form fields to update the Student object's
properties. The TryUpdateModelAsync method:
Uses the posted form values from the PageContext property in the PageModel.
Updates only the properties listed ( s => s.FirstMidName, s => s.LastName, s => s.EnrollmentDate ).
Looks for form fields with a "student" prefix. For example, Student.FirstMidName . It's not case sensitive.
Uses the model binding system to convert form values from strings to the types in the Student model. For
example, EnrollmentDate has to be converted to DateTime.

Run the app, and create a student entity to test the Create page.

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 class Student

{
public int ID { get; set; }
public string LastName { get; set; }
public string FirstMidName { get; set; }
public DateTime EnrollmentDate { get; set; }
public string Secret { get; set; }
}

Even if the app doesn't have a Secret field on the create or 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 database. 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. That happens even
though the app designer never intended the Secret property to be set with the Create page.
View model
View models provide an alternative way to prevent overposting.
The application model is often called the domain model. The domain model typically contains all the properties
required by the corresponding entity in the database. The view model contains only the properties needed for
the UI that it is used for (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;

namespace ContosoUniversity.Models
{
public class StudentVM
{
public int ID { get; set; }
public string LastName { get; set; }
public string FirstMidName { get; set; }
public DateTime EnrollmentDate { get; set; }
}
}

The following code uses the StudentVM view model to create a new student:

[BindProperty]
public StudentVM StudentVM { get; set; }

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

var entry = _context.Add(new Student());

entry.CurrentValues.SetValues(StudentVM);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}

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 Create.cshtml be updated to use StudentVM rather than Student .

Update the Edit page

In Pages/Students/Edit.cshtml.cs, replace the OnGetAsync and OnPostAsync methods with the following code.
 public async Task<IActionResult> OnGetAsync(int? id)
{
if (id == null)
{
return NotFound();
}

Student = await _context.Students.FindAsync(id);

if (Student == null)
{
return NotFound();
}
return Page();
}

public async Task<IActionResult> OnPostAsync(int id)

{
var studentToUpdate = await _context.Students.FindAsync(id);

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

if (await TryUpdateModelAsync<Student>(
studentToUpdate,
"student",
s => s.FirstMidName, s => s.LastName, s => s.EnrollmentDate))
{
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}

return Page();
}

The code changes are similar to the Create page with a few exceptions:
FirstOrDefaultAsync has been replaced with FindAsync. When you don't have to include related data,
FindAsync is more efficient.
OnPostAsync has an id parameter.
The current student is fetched from the database, rather than creating an empty student.
Run the app, and test it by creating and editing a student.

Entity States
The database context keeps track of whether entities in memory are in sync with their corresponding rows in the
database. This tracking 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 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 : No changes need to be saved with this entity. An entity has this status when it's read from the
database.
Modified : Some or all of the entity's property values have been modified. The 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 app, state changes are typically set automatically. An entity is read, changes are made, and the entity
state is automatically 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 .
Rereading the entity in that new context simulates desktop processing.

Update the Delete page

In this section, you implement a custom error message when the call to SaveChanges fails.
Replace the code in Pages/Students/Delete.cshtml.cs with the following code. The changes are highlighted (other
than cleanup of using statements).

using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Students
{
public class DeleteModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public DeleteModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Student Student { get; set; }
public string ErrorMessage { get; set; }

public async Task<IActionResult> OnGetAsync(int? id, bool? saveChangesError = false)

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

Student = await _context.Students

.AsNoTracking()
.FirstOrDefaultAsync(m => m.ID == id);

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

if (saveChangesError.GetValueOrDefault())
{
ErrorMessage = "Delete failed. Try again";
}

return Page();
}

public async Task<IActionResult> OnPostAsync(int? id)

 public async Task<IActionResult> OnPostAsync(int? id)
{
if (id == null)
{
return NotFound();
}

var student = await _context.Students.FindAsync(id);

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

try
{
_context.Students.Remove(student);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
catch (DbUpdateException /* ex */)
{
//Log the error (uncomment ex variable name and write a log.)
return RedirectToAction("./Delete",
new { id, saveChangesError = true });
}
}
}
}

The preceding code adds the optional parameter saveChangesError to the OnGetAsync method signature.
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 when the
database is in the cloud. The saveChangesError parameter 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 method retrieves the selected entity, then calls the Remove method to set the entity's status to
OnPostAsync
Deleted . When SaveChanges is called, a SQL DELETE command is generated. If Remove fails:

The database exception is caught.

The Delete pages OnGetAsync method is called with saveChangesError=true .

Add an error message to the Delete Razor Page (Pages/Students/Delete.cshtml):

 @page
@model ContosoUniversity.Pages.Students.DeleteModel

@{
ViewData["Title"] = "Delete";
}

<h1>Delete</h1>

<p class="text-danger">@Model.ErrorMessage</p>

<h3>Are you sure you want to delete this?</h3>

<div>
<h4>Student</h4>
<hr />
<dl class="row">
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Student.LastName)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Student.LastName)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Student.FirstMidName)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Student.FirstMidName)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Student.EnrollmentDate)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Student.EnrollmentDate)
</dd>
</dl>

<form method="post">
<input type="hidden" asp-for="Student.ID" />
<input type="submit" value="Delete" class="btn btn-danger" /> |
<a asp-page="./Index">Back to List</a>
</form>
</div>

Run the app and delete a student to test the Delete page.

Next steps

P R E V IO U S NEXT
T U T O R IA L T U T O R IA L

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 Students 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 that 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>
<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>

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:

public async Task<IActionResult> OnGetAsync(int? id)

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

Student = await _context.Student

.Include(s => s.Enrollments)
.ThenInclude(e => e.Course)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.ID == id);

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

@{
ViewData["Title"] = "Details";
}

<h2>Details</h2>

<div>
<h4>Student</h4>
<hr />
<dl class="dl-horizontal">
<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>
<table class="table">
<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:

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
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);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}

return null;
}

TryUpdateModelAsync
Examine the TryUpdateModelAsync code:

var emptyStudent = new Student();

if (await TryUpdateModelAsync<Student>(
emptyStudent,
"student", // Prefix for form value.
s => s.FirstMidName, s => s.LastName, s => s.EnrollmentDate))
{

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 class Student
{
public int ID { get; set; }
public string LastName { get; set; }
public string FirstMidName { get; set; }
public DateTime EnrollmentDate { get; set; }
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;

namespace ContosoUniversity.Models
{
public class StudentVM
{
public int ID { get; set; }
public string LastName { get; set; }
public string FirstMidName { get; set; }
public DateTime EnrollmentDate { get; set; }
}
}

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; }

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

var entry = _context.Add(new Student());

entry.CurrentValues.SetValues(StudentVM);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}

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:
 public class EditModel : PageModel
{
private readonly SchoolContext _context;

public EditModel(SchoolContext context)

{
_context = context;
}

[BindProperty]
public Student Student { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Student = await _context.Student.FindAsync(id);

if (Student == null)
{
return NotFound();
}
return Page();
}

public async Task<IActionResult> OnPostAsync(int? id)

{
if (!ModelState.IsValid)
{
return Page();
}

var studentToUpdate = await _context.Student.FindAsync(id);

if (await TryUpdateModelAsync<Student>(
studentToUpdate,
"student",
s => s.FirstMidName, s => s.LastName, s => s.EnrollmentDate))
{
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}

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.
Modified : Some or all of the entity's property values have been modified. The 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

{
private readonly SchoolContext _context;

public DeleteModel(SchoolContext context)

{
_context = context;
}

[BindProperty]
public Student Student { get; set; }
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()
.FirstOrDefaultAsync(m => m.ID == id);

if (Student == null)
{
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:

public async Task<IActionResult> OnPostAsync(int? id)

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

var student = await _context.Student

.AsNoTracking()
.FirstOrDefaultAsync(m => m.ID == id);

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

try
{
_context.Student.Remove(student);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
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
Students/Index or other links don't work:
Verify the Razor Page contains the correct @page directive. For example, The Students/Index Razor Page should
not contain a route template:

@page "{id:int}"

Each Razor Page must include the @page directive.

Additional resources
YouTube version of this tutorial

P R E V IO U S NEXT
 Razor Pages with EF Core in ASP.NET Core - Sort,
Filter, Paging - 3 of 8
8/9/2019 • 29 minutes to read • Edit Online

By Tom Dykstra, Rick Anderson, and Jon P Smith

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.
If you run into problems you can't solve, download the completed app and compare that code to what you
created by following the tutorial.
This tutorial adds sorting, filtering, and paging functionality to the Students pages.
The following illustration shows a completed page. The column headings are clickable links to sort the column.
Click a column heading repeatedly to switch between ascending and descending sort order.

Add sorting
Replace the code in Pages/Students/Index.cshtml.cs with the following code to add sorting.
 using ContosoUniversity.Data;
using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Students
{
public class IndexModel : PageModel
{
private readonly SchoolContext _context;

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; }

public IList<Student> Students { get; set; }

public async Task OnGetAsync(string sortOrder)

{
NameSort = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";
DateSort = sortOrder == "Date" ? "date_desc" : "Date";

IQueryable<Student> studentsIQ = from s in _context.Students

select s;

switch (sortOrder)
{
case "name_desc":
studentsIQ = studentsIQ.OrderByDescending(s => s.LastName);
break;
case "Date":
studentsIQ = studentsIQ.OrderBy(s => s.EnrollmentDate);
break;
case "date_desc":
studentsIQ = studentsIQ.OrderByDescending(s => s.EnrollmentDate);
break;
default:
studentsIQ = studentsIQ.OrderBy(s => s.LastName);
break;
}

Students = await studentsIQ.AsNoTracking().ToListAsync();

}
}
}

The preceding code:

Adds properties to contain the sorting parameters.
Changes the name of the Student property to Students .
Replaces the code in the OnGetAsync method.

The OnGetAsync method 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:

NameSort = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";

DateSort = sortOrder == "Date" ? "date_desc" : "Date";

The code uses the C# conditional operator ?:. The ?: operator is a ternary operator (it takes three operands).
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.
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:

IQueryable<Student> studentsIQ = from s in _context.Students

select s;

switch (sortOrder)
{
case "name_desc":
studentsIQ = studentsIQ.OrderByDescending(s => s.LastName);
break;
case "Date":
studentsIQ = studentsIQ.OrderBy(s => s.EnrollmentDate);
break;
case "date_desc":
studentsIQ = studentsIQ.OrderByDescending(s => s.EnrollmentDate);
break;
default:
studentsIQ = studentsIQ.OrderBy(s => s.LastName);
break;
}

Students = await studentsIQ.AsNoTracking().ToListAsync();

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:

Students = await studentsIQ.AsNoTracking().ToListAsync();

OnGetAsync could get verbose with a large number of sortable columns. For information about an alternative
way to code this functionality, see Use dynamic LINQ to simplify code in the MVC version of this tutorial series.
Add column heading hyperlinks to the Student Index page
Replace the code in Students/Index.cshtml, with the following code. The changes are highlighted.

@page
@model ContosoUniversity.Pages.Students.IndexModel

@{
ViewData["Title"] = "Students";
}

<h2>Students</h2>
<p>
<a asp-page="Create">Create New</a>
</p>

<table class="table">
<thead>
<tr>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.NameSort">
@Html.DisplayNameFor(model => model.Students[0].LastName)
</a>
</th>
<th>
@Html.DisplayNameFor(model => model.Students[0].FirstMidName)
</th>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.DateSort">
@Html.DisplayNameFor(model => model.Students[0].EnrollmentDate)
</a>
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Students)
{
<tr>
<td>
@Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
@Html.DisplayFor(modelItem => item.FirstMidName)
</td>
<td>
@Html.DisplayFor(modelItem => item.EnrollmentDate)
</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>
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.
Changes the page heading from Index to Students.
Changes Model.Student to Model.Students .

To verify that sorting works:

Run the app and select the Students tab.
Click the column headings.

Add filtering
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.
Update the OnGetAsync method
Replace the code in Students/Index.cshtml.cs with the following code to add filtering:
 using ContosoUniversity.Data;
using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Students
{
public class IndexModel : PageModel
{
private readonly SchoolContext _context;

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; }

public IList<Student> Students { get; set; }

public async Task OnGetAsync(string sortOrder, string searchString)

{
NameSort = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";
DateSort = sortOrder == "Date" ? "date_desc" : "Date";

CurrentFilter = searchString;

IQueryable<Student> studentsIQ = from s in _context.Students

select s;
if (!String.IsNullOrEmpty(searchString))
{
studentsIQ = studentsIQ.Where(s => s.LastName.Contains(searchString)
|| s.FirstMidName.Contains(searchString));
}

switch (sortOrder)
{
case "name_desc":
studentsIQ = studentsIQ.OrderByDescending(s => s.LastName);
break;
case "Date":
studentsIQ = studentsIQ.OrderBy(s => s.EnrollmentDate);
break;
case "date_desc":
studentsIQ = studentsIQ.OrderByDescending(s => s.EnrollmentDate);
break;
default:
studentsIQ = studentsIQ.OrderBy(s => s.LastName);
break;
}

Students = await studentsIQ.AsNoTracking().ToListAsync();

}
}
}

The preceding code:

Adds the searchString parameter to the OnGetAsync method, and saves the parameter value in the
 CurrentFilter property. The search string value is received from a text box that's added in the next section.
Adds 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.
IQueryable vs. IEnumerable
The 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. SQLite defaults to case-sensitive. 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 the filter is case-insensitive even if the Where method is called on an
IEnumerable or runs on SQLite.

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.
Calling Contains on an IQueryable is usually preferable for performance reasons. With IQueryable , the filtering
is done by the database server. If an IEnumerable is created first, all the rows have to be returned from the
database server.
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.
For more information, see How to use case-insensitive query with Sqlite provider.
Update the Razor page
Replace the code in Pages/Students/Index.cshtml to create a Search button and assorted chrome.
@page
@model ContosoUniversity.Pages.Students.IndexModel

@{
ViewData["Title"] = "Students";
}

<h2>Students</h2>

<p>
<a asp-page="Create">Create New</a>
</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-primary" /> |
<a asp-page="./Index">Back to full List</a>
</p>
</div>
</form>

<table class="table">
<thead>
<tr>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.NameSort">
@Html.DisplayNameFor(model => model.Students[0].LastName)
</a>
</th>
<th>
@Html.DisplayNameFor(model => model.Students[0].FirstMidName)
</th>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.DateSort">
@Html.DisplayNameFor(model => model.Students[0].EnrollmentDate)
</a>
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Students)
{
<tr>
<td>
@Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
@Html.DisplayFor(modelItem => item.FirstMidName)
</td>
<td>
@Html.DisplayFor(modelItem => item.EnrollmentDate)
</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>
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. If you're using SQLite, the filter is case-insensitive only
if you implemented the optional ToUpper code shown earlier.
Select Search.
Notice that the URL contains the search string. For example:

https://localhost:<port>/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
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.

Create the PaginatedList class

In the project folder, create PaginatedList.cs with the following code:
 using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.EntityFrameworkCore;

namespace ContosoUniversity
{
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 method is used to create the PaginatedList<T> . A constructor can't create the
CreateAsync
PaginatedList<T> object; constructors can't run asynchronous code.

Add paging to the PageModel class

Replace the code in Students/Index.cshtml.cs to add paging.

using ContosoUniversity.Data;
using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Students
{
public class IndexModel : PageModel
{
private readonly SchoolContext _context;

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; }

public PaginatedList<Student> Students { get; set; }

public async Task OnGetAsync(string sortOrder,

string currentFilter, string searchString, int? pageIndex)
{
CurrentSort = sortOrder;
NameSort = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";
DateSort = sortOrder == "Date" ? "date_desc" : "Date";
if (searchString != null)
{
pageIndex = 1;
}
else
{
searchString = currentFilter;
}

CurrentFilter = searchString;

IQueryable<Student> studentsIQ = from s in _context.Students

select s;
if (!String.IsNullOrEmpty(searchString))
{
studentsIQ = studentsIQ.Where(s => s.LastName.Contains(searchString)
|| s.FirstMidName.Contains(searchString));
}
switch (sortOrder)
{
case "name_desc":
studentsIQ = studentsIQ.OrderByDescending(s => s.LastName);
break;
case "Date":
studentsIQ = studentsIQ.OrderBy(s => s.EnrollmentDate);
break;
case "date_desc":
studentsIQ = studentsIQ.OrderByDescending(s => s.EnrollmentDate);
break;
default:
studentsIQ = studentsIQ.OrderBy(s => s.LastName);
break;
}

int pageSize = 3;
Students = await PaginatedList<Student>.CreateAsync(
studentsIQ.AsNoTracking(), pageIndex ?? 1, pageSize);
}
}
}
 }

The preceding code:

Changes the type of the Students property from IList<Student> to PaginatedList<Student> .
Adds the page index, the current sortOrder , and the currentFilter to the OnGetAsync method signature.
Saves the sort order in the CurrentSort property.
Resets page index to 1 when there's a new search string.
Uses the PaginatedList class to get Student entities.

All the parameters that OnGetAsync receives 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.
The CurrentSort property 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.
The CurrentFilter property 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.
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.
The two question marks after pageIndex in the PaginatedList.CreateAsync call 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 Razor Page
Replace the code in Students/Index.cshtml with the following code. The changes are highlighted:

@page
@model ContosoUniversity.Pages.Students.IndexModel

@{
ViewData["Title"] = "Students";
}

<h2>Students</h2>

<p>
<a asp-page="Create">Create New</a>
</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-primary" /> |
 <input type="submit" value="Search" class="btn btn-primary" /> |
<a asp-page="./Index">Back to full List</a>
</p>
</div>
</form>

<table class="table">
<thead>
<tr>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.NameSort"
asp-route-currentFilter="@Model.CurrentFilter">
@Html.DisplayNameFor(model => model.Students[0].LastName)
</a>
</th>
<th>
@Html.DisplayNameFor(model => model.Students[0].FirstMidName)
</th>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.DateSort"
asp-route-currentFilter="@Model.CurrentFilter">
@Html.DisplayNameFor(model => model.Students[0].EnrollmentDate)
</a>
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Students)
{
<tr>
<td>
@Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
@Html.DisplayFor(modelItem => item.FirstMidName)
</td>
<td>
@Html.DisplayFor(modelItem => item.EnrollmentDate)
</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>

@{
var prevDisabled = !Model.Students.HasPreviousPage ? "disabled" : "";
var nextDisabled = !Model.Students.HasNextPage ? "disabled" : "";
}

<a asp-page="./Index"
asp-route-sortOrder="@Model.CurrentSort"
asp-route-pageIndex="@(Model.Students.PageIndex - 1)"
asp-route-currentFilter="@Model.CurrentFilter"
class="btn btn-primary @prevDisabled">
Previous
</a>
<a asp-page="./Index"
asp-route-sortOrder="@Model.CurrentSort"
asp-route-pageIndex="@(Model.Students.PageIndex + 1)"
asp-route-currentFilter="@Model.CurrentFilter"
class="btn btn-primary @nextDisabled">
Next
</a>
The column header links use the query string to pass the current search string to the OnGetAsync method:

<a asp-page="./Index" asp-route-sortOrder="@Model.NameSort"

asp-route-currentFilter="@Model.CurrentFilter">
@Html.DisplayNameFor(model => model.Students[0].LastName)
</a>

The paging buttons are displayed by tag helpers:

<a asp-page="./Index"
asp-route-sortOrder="@Model.CurrentSort"
asp-route-pageIndex="@(Model.Students.PageIndex - 1)"
asp-route-currentFilter="@Model.CurrentFilter"
class="btn btn-primary @prevDisabled">
Previous
</a>
<a asp-page="./Index"
asp-route-sortOrder="@Model.CurrentSort"
asp-route-pageIndex="@(Model.Students.PageIndex + 1)"
asp-route-currentFilter="@Model.CurrentFilter"
class="btn btn-primary @nextDisabled">
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.

Add grouping
This section creates an About page that displays 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 Models/SchoolViewModels folder.
Create SchoolViewModels/EnrollmentDateGroup.cs with the following code:

using System;
using System.ComponentModel.DataAnnotations;

namespace ContosoUniversity.Models.SchoolViewModels
{
public class EnrollmentDateGroup
{
[DataType(DataType.Date)]
public DateTime? EnrollmentDate { get; set; }

public int StudentCount { get; set; }

}
}

Create the Razor Page

Create a 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>

@foreach (var item in Model.Students)

{
<tr>
<td>
@Html.DisplayFor(modelItem => item.EnrollmentDate)
</td>
<td>
@item.StudentCount
</td>
</tr>
}
</table>

Create the page model

Create a Pages/About.cshtml.cs file with the following code:
 using ContosoUniversity.Models.SchoolViewModels;
using ContosoUniversity.Data;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using ContosoUniversity.Models;

namespace ContosoUniversity.Pages
{
public class AboutModel : PageModel
{
private readonly SchoolContext _context;

public AboutModel(SchoolContext context)

{
_context = context;
}

public IList<EnrollmentDateGroup> Students { get; set; }

public async Task OnGetAsync()

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

Students = 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.
Run the app and navigate to the About page. The count of students for each enrollment date is displayed in a
table.
Next steps
In the next tutorial, the app uses migrations to update the data model.

P R E V IO U S NEXT
T U T O R IA L T U T O R IA L

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 class IndexModel : PageModel

{
private readonly SchoolContext _context;

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:

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 following code contains the C# conditional ?: operator:

NameSort = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";

DateSort = sortOrder == "Date" ? "date_desc" : "Date";

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:
 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();

}

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:

Student = await studentIQ.AsNoTracking().ToListAsync();

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

@{
ViewData["Title"] = "Index";
}

<h2>Index</h2>
<p>
<a asp-page="Create">Create New</a>
</p>

<table class="table">
<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>
<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>

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 Students/Index.cshtml.cs, set a breakpoint on switch (sortOrder) .
Add a watch for NameSort and DateSort .
In Students/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
Update the Students/Index.cshtml.cs OnGetAsync with the following code:

public async Task OnGetAsync(string sortOrder, string searchString)

{
NameSort = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";
DateSort = sortOrder == "Date" ? "date_desc" : "Date";
CurrentFilter = searchString;

IQueryable<Student> studentIQ = from s in _context.Student

select s;
if (!String.IsNullOrEmpty(searchString))
{
studentIQ = studentIQ.Where(s => s.LastName.Contains(searchString)
|| s.FirstMidName.Contains(searchString));
}

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:

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 penalty:
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
@model ContosoUniversity.Pages.Students.IndexModel

@{
ViewData["Title"] = "Index";
}

<h2>Index</h2>

<p>
<a asp-page="Create">Create New</a>
</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>

<table class="table">

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.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.EntityFrameworkCore;

namespace ContosoUniversity
{
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 method is used to create the PaginatedList<T> . A constructor can't create the
CreateAsync
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; }

Update the Students/Index.cshtml.cs OnGetAsync with the following code:

public async Task OnGetAsync(string sortOrder,

string currentFilter, string searchString, int? pageIndex)
{
CurrentSort = sortOrder;
NameSort = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";
DateSort = sortOrder == "Date" ? "date_desc" : "Date";
if (searchString != null)
{
pageIndex = 1;
}
else
{
searchString = currentFilter;
}

CurrentFilter = searchString;

IQueryable<Student> studentIQ = from s in _context.Student

select s;
if (!String.IsNullOrEmpty(searchString))
{
studentIQ = studentIQ.Where(s => s.LastName.Contains(searchString)
|| s.FirstMidName.Contains(searchString));
}
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;
}

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.

if (searchString != null)
{
pageIndex = 1;
}
else
{
searchString = currentFilter;
}

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
@model ContosoUniversity.Pages.Students.IndexModel

@{
ViewData["Title"] = "Index";
}

<h2>Index</h2>

<p>
<a asp-page="Create">Create New</a>
</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>

<table class="table">
<thead>
<tr>
<th>
<a asp-page="./Index" asp-route-sortOrder="@Model.NameSort"
asp-route-currentFilter="@Model.CurrentFilter">
 asp-route-currentFilter="@Model.CurrentFilter">
@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"
asp-route-currentFilter="@Model.CurrentFilter">
@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>
<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>

@{
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>
<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 @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"

asp-route-currentFilter="@Model.CurrentFilter">
@Html.DisplayNameFor(model => model.Student[0].LastName)
</a>
The paging buttons are displayed by tag helpers:

<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>
<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 @nextDisabled">
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 Students/Index.cshtml.cs, set a breakpoint on switch (sortOrder) .
Add a watch for NameSort , DateSort , CurrentSort , and Model.Student.PageIndex .
In Students/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;
using System.ComponentModel.DataAnnotations;

namespace ContosoUniversity.Models.SchoolViewModels
{
public class EnrollmentDateGroup
{
[DataType(DataType.Date)]
public DateTime? EnrollmentDate { get; set; }

public int StudentCount { get; set; }

}
}

Update the About page model

The web templates in ASP.NET Core 2.2 do not include the About page. If you are using ASP.NET Core 2.2,
create the About Razor Page.
Update the Pages/About.cshtml.cs file with the following code:
 using ContosoUniversity.Models.SchoolViewModels;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using ContosoUniversity.Models;

namespace ContosoUniversity.Pages
{
public class AboutModel : PageModel
{
private readonly SchoolContext _context;

public AboutModel(SchoolContext context)

{
_context = context;
}

public IList<EnrollmentDateGroup> Student { get; set; }

public async Task OnGetAsync()

{
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>

@foreach (var item in Model.Student)

{
<tr>
<td>
@Html.DisplayFor(modelItem => item.EnrollmentDate)
</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.

Additional resources
Debugging ASP.NET Core 2.x source
YouTube version of this tutorial
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
8/9/2019 • 11 minutes to read • Edit Online

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.
If you run into problems you can't solve, download the completed app and compare that code to what you
created by following the tutorial.
This tutorial introduces the EF Core migrations feature for managing data model changes.
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 series started by configuring the Entity Framework to create the
database if it doesn't exist. Each time the data model changes, you have to drop the database. The next time the
app runs, the call to EnsureCreated re-creates the database to match the new data model. The DbInitializer
class then runs to seed the new database.
This approach to keeping the database 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 database 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 database schema instead of creating a
new database.
Rather than dropping and recreating the database when the data model changes, migrations updates the
schema and retains existing data.
 NOTE
SQLite limitations
This tutorial uses the Entity Framework Core migrations feature where possible. Migrations updates the database schema
to match changes in the data model. However, migrations only does the kinds of changes that the database engine
supports, and SQLite's schema change capabilities are limited. For example, adding a column is supported, but removing a
column is not supported. If a migration is created to remove a column, the ef migrations add command succeeds but
the ef database update command fails.
The workaround for the SQLite limitations is to manually write migrations code to perform a table rebuild when something
in the table changes. The code would go in the Up and Down methods for a migration and would involve:
Creating a new table.
Copying data from the old table to the new table.
Dropping the old table.
Renaming the new table.
Writing database-specific code of this type is outside the scope of this tutorial. Instead, this tutorial drops and re-creates
the database whenever an attempt to apply a migration would fail. For more information, see the following resources:
SQLite EF Core Database Provider Limitations
Customize migration code
Data seeding
SQLite ALTER TABLE statement

Drop the database

Visual Studio
Visual Studio Code
Use SQL Server Object Explorer (SSOX) to delete the database, or run the following command in the
Package Manager Console (PMC ):

Drop-Database

Create an initial migration

Visual Studio
Visual Studio Code
Run the following commands in the PMC:

Add-Migration InitialCreate
Update-Database

Up and Down methods

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

using System;
using System;
using Microsoft.EntityFrameworkCore.Metadata;
using Microsoft.EntityFrameworkCore.Migrations;

namespace ContosoUniversity.Migrations
{
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);
});

migrationBuilder.CreateTable(
name: "Student",
columns: table => new
{
ID = table.Column<int>(nullable: false)
.Annotation("SqlServer:ValueGenerationStrategy",
SqlServerValueGenerationStrategy.IdentityColumn),
LastName = table.Column<string>(nullable: true),
FirstMidName = table.Column<string>(nullable: true),
EnrollmentDate = table.Column<DateTime>(nullable: false)
},
constraints: table =>
{
table.PrimaryKey("PK_Student", x => x.ID);
});

migrationBuilder.CreateTable(
name: "Enrollment",
columns: table => new
{
EnrollmentID = table.Column<int>(nullable: false)
.Annotation("SqlServer:ValueGenerationStrategy",
SqlServerValueGenerationStrategy.IdentityColumn),
CourseID = table.Column<int>(nullable: false),
StudentID = table.Column<int>(nullable: false),
Grade = table.Column<int>(nullable: true)
},
constraints: table =>
{
table.PrimaryKey("PK_Enrollment", x => x.EnrollmentID);
table.ForeignKey(
name: "FK_Enrollment_Course_CourseID",
column: x => x.CourseID,
principalTable: "Course",
principalColumn: "CourseID",
onDelete: ReferentialAction.Cascade);
table.ForeignKey(
name: "FK_Enrollment_Student_StudentID",
column: x => x.StudentID,
principalTable: "Student",
principalColumn: "ID",
onDelete: ReferentialAction.Cascade);
});

migrationBuilder.CreateIndex(
name: "IX_Enrollment_CourseID",
table: "Enrollment",
 table: "Enrollment",
column: "CourseID");

migrationBuilder.CreateIndex(
name: "IX_Enrollment_StudentID",
table: "Enrollment",
column: "StudentID");
}

protected override void Down(MigrationBuilder migrationBuilder)

{
migrationBuilder.DropTable(
name: "Enrollment");

migrationBuilder.DropTable(
name: "Course");

migrationBuilder.DropTable(
name: "Student");
}
}
}

The preceding code is for the initial migration. The code:

Was generated by the migrations add InitialCreate command.
Is executed by the database update command.
Creates a database for the data model specified by the database context class.
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."

The migrations history table

Use SSOX or your SQLite tool to inspect the database.
Notice the addition of an __EFMigrationsHistory table. The __EFMigrationsHistory table keeps track of which
migrations have been applied to the database.
View the data in the __EFMigrationsHistory table. It shows one row for the first migration.

The data model snapshot

Migrations creates a snapshot of the current data model in Migrations/SchoolContextModelSnapshot.cs. When
you add a migration, EF determines what changed by comparing the current data model to the snapshot file.
Because the snapshot file tracks the state of the data model, you can't delete a migration by deleting the
<timestamp>_<migrationname>.cs file. To back out the most recent migration, you have to use the
migrations remove command. That command deletes the migration and ensures the snapshot is correctly reset.
For more information, see dotnet ef migrations remove.

Remove EnsureCreated
This tutorial series started by using EnsureCreated . EnsureCreated doesn't create a migrations history table and
so can't be used with migrations. It's designed for testing or rapid prototyping where the database is dropped
and re-created frequently.
From this point forward, the tutorials will use migrations.
In Data/DBInitializer.cs, comment out the following line:
 context.Database.EnsureCreated();

Run the app and verify that the database is seeded.

Applying migrations in production

We recommend that production apps not call Database.Migrate at application startup. Migrate shouldn't be
called from an app that is deployed to a server farm. If the app is scaled out to multiple server instances, it's hard
to ensure database schema updates don't happen from multiple servers or conflict with read/write access.
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.

Troubleshooting
If the app uses SQL Server LocalDB and displays the following exception:

SqlException: Cannot open database "ContosoUniversity" requested by the login.

The login failed.
Login failed for user 'user name'.

The solution may be to run dotnet ef database update at a command prompt.

Additional resources
EF Core CLI.
Package Manager Console (Visual Studio)

Next steps
The next tutorial builds out the data model, adding entity properties and new entities.

P R E V IO U S NEXT
T U T O R IA L T U T O R IA L

In this tutorial, the EF Core migrations feature for managing data model changes is used.
If you run into problems you can't solve, download the completed app.
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
Visual Studio Code
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
Visual Studio Code

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);
});

migrationBuilder.CreateTable(
protected override void Down(MigrationBuilder migrationBuilder)
{
migrationBuilder.DropTable(
name: "Enrollment");

migrationBuilder.DropTable(
name: "Course");

migrationBuilder.DropTable(
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
Visual Studio Code
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 EnsureCreated :

context.Database.EnsureCreated();

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.
Login failed for user 'user name'.

Solution: Run dotnet ef database update

Additional resources
YouTube version of this tutorial
.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
8/9/2019 • 56 minutes to read • Edit Online

By Tom Dykstra 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.
If you run into problems you can't solve, download the completed app and compare that code to what you
created by following the tutorial.
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 completed data model is shown in the following illustration:
The Student entity

Replace the code in Models/Student.cs with the following code:

using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
[Required]
[StringLength(50)]
[Display(Name = "Last Name")]
public string LastName { get; set; }
[Required]
[StringLength(50, ErrorMessage = "First name cannot be longer than 50 characters.")]
[Column("FirstName")]
[Display(Name = "First Name")]
public string FirstMidName { get; set; }
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Enrollment Date")]
public DateTime EnrollmentDate { get; set; }
[Display(Name = "Full Name")]
public string FullName
{
get
{
return LastName + ", " + FirstMidName;
}
}

public ICollection<Enrollment> Enrollments { get; set; }

}
}

The preceding code adds a FullName property and adds the following attributes to existing properties:
[DataType]
[DisplayFormat]
[StringLength]
[Column]
[Required]
[Display]

The FullName calculated property

FullName is a calculated property that returns a value that's created by concatenating two other properties.
FullName can't be set, so it has only a get accessor. No FullName column is created in the database.
The DataType attribute

[DataType(DataType.Date)]

For student enrollment dates, all of the pages currently display the time of day along with the date, although only
the date is relevant. By using data annotation attributes, you can make one code change that will fix the display
format in every page that shows the data.
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. The DataType attributes don't
provide validation.
The DisplayFormat attribute

[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]

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 DisplayFormat attribute is used to explicitly specify the date format. 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 DisplayFormat attribute 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, and client-side input validation.
By default, the browser renders data using the correct format based on the locale.
For more information, see the <input> Tag Helper documentation.
The StringLength attribute

[StringLength(50, ErrorMessage = "First name cannot be longer than 50 characters.")]

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 code shown limits
names to no more than 50 characters. An example that sets the minimum string length is shown later.
The StringLength attribute also provides client-side and server-side validation. The minimum value has no
impact on the database schema.
The StringLength attribute doesn't prevent a user from entering white space for a name. The RegularExpression
attribute can be 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:

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

Visual Studio
Visual Studio Code
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) . When
a migration is created and applied later in this tutorial, the name fields become nvarchar(50) as a result of the
string length attributes.
The Column attribute

[Column("FirstName")]
public string FirstMidName { get; set; }

Attributes can control how classes and properties are mapped to the database. In the Student model, the
Column attribute is used to map the name of the FirstMidName property to "FirstName" in the database.

When the database 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.
With the [Column] attribute, Student.FirstMidName in the data model 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. That discrepancy will be resolved by adding a
migration later in this tutorial.
The Required attribute

[Required]

The Required attribute makes the name properties required fields. The Required attribute isn't needed for non-
nullable types such as value types (for example, DateTime , int , and double ). 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:

[Display(Name = "Last Name")]

[StringLength(50, MinimumLength=1)]
public string LastName { get; set; }

The Display attribute

[Display(Name = "Last Name")]

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."
Create a migration
Run the app and go to the Students page. An exception is thrown. The [Column] attribute causes EF to expect to
find a column named FirstName , but the column name in the database is still FirstMidName .
Visual Studio
Visual Studio Code
The error message is similar to the following example:

SqlException: Invalid column name 'FirstName'.

In the PMC, enter the following commands to create a new migration and update the database:

Add-Migration ColumnFirstName
Update-Database

The first of these commands 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
database had more than 50 characters, the 51 to last character would be lost.
Open the Student table in SSOX:
 Before the 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 .

Run the app and go to the Students page.

Notice that times are not input or displayed along with dates.
Select Create New, and try to enter a name longer than 50 characters.

NOTE
In the following sections, building the app at some stages generates compiler errors. The instructions specify when to build
the app.

The Instructor Entity

Create Models/Instructor.cs with the following code:

 using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Instructor
{
public int ID { get; set; }

[Required]
[Display(Name = "Last Name")]
[StringLength(50)]
public string LastName { get; set; }

[Required]
[Column("FirstName")]
[Display(Name = "First Name")]
[StringLength(50)]
public string FirstMidName { get; set; }

[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Hire Date")]
public DateTime HireDate { get; set; }

[Display(Name = "Full Name")]

public string FullName
{
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)]

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.

public ICollection<CourseAssignment> CourseAssignments { get; set; }

An instructor can have at most one office, so the OfficeAssignment property holds a single OfficeAssignment
entity. OfficeAssignment is null if no office is assigned.

public OfficeAssignment OfficeAssignment { get; set; }

The OfficeAssignment entity

Create Models/OfficeAssignment.cs with the following code:

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
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]
public int InstructorID { get; set; }

By default, EF Core treats the key as non-database-generated because the column is for an identifying
relationship.
The Instructor navigation property
The Instructor.OfficeAssignment navigation property can be null because there might not be an
OfficeAssignment row for a given instructor. An instructor might not have an office assignment.

The OfficeAssignment.Instructor navigation property will always have an instructor entity because the foreign
key InstructorID type is int , a non-nullable value type. 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 Course Entity

Update Models/Course.cs with the following code:

using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Course
{
[DatabaseGenerated(DatabaseGeneratedOption.None)]
[Display(Name = "Number")]
public int CourseID { get; set; }

[StringLength(50, MinimumLength = 3)]

public string Title { get; set; }

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

public int DepartmentID { get; set; }

public Department Department { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }
public ICollection<CourseAssignment> CourseAssignments { 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 foreign key 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. However, explicitly including 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 property 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.
 [DatabaseGenerated(DatabaseGeneratedOption.None)]
[Display(Name = "Number")]
public int CourseID { get; set; }

By default, EF Core assumes that PK values are generated by the database. Database-generated 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 database 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.

public int DepartmentID { get; set; }

public Department Department { get; set; }

A course can have any number of students enrolled in it, so the Enrollments navigation property is a collection:

public ICollection<Enrollment> Enrollments { get; set; }

A course may be taught by multiple instructors, so the CourseAssignments navigation property is a collection:

public ICollection<CourseAssignment> CourseAssignments { get; set; }

CourseAssignment is explained later.

The Department entity

Create Models/Department.cs with the following code:

 using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Department
{
public int DepartmentID { get; set; }

[StringLength(50, MinimumLength = 3)]

public string Name { get; set; }

[DataType(DataType.Currency)]
[Column(TypeName = "money")]
public decimal Budget { get; set; }

[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[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; }
}
}

The Column attribute

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 database:

[Column(TypeName="money")]
public decimal Budget { get; set; }

Column mapping is generally not required. EF Core 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.
Foreign key and navigation properties
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:

public int? InstructorID { get; set; }

public Instructor Administrator { get; set; }

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:
 public ICollection<Course> Courses { get; set; }

By convention, EF Core enables cascade delete for non-nullable FKs and for many-to-many relationships. This
default behavior can result in circular cascade delete rules. Circular cascade delete rules cause an exception when
a migration is added.
For example, if the Department.InstructorID property was defined as non-nullable, EF Core would configure a
cascade delete rule. In that case, the department would be deleted when the instructor assigned as its
administrator is deleted. In this scenario, a restrict rule would make more sense. The following fluent API would
set a restrict rule and disable cascade delete.

modelBuilder.Entity<Department>()
.HasOne(d => d.Administrator)
.WithMany()
.OnDelete(DeleteBehavior.Restrict)

The Enrollment entity

An enrollment record is for one course taken by one student.

Update Models/Enrollment.cs with the following code:

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
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; }
[DisplayFormat(NullDisplayText = "No grade")]
public Grade? Grade { get; set; }

public Course Course { get; set; }

public Student Student { get; set; }
}
}

Foreign key and navigation properties

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:

public int CourseID { get; set; }

public Course Course { get; set; }

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

public int StudentID { get; set; }

public Student Student { get; set; }

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 Enrollment table didn't include grade information, it would only need to contain the two FKs ( CourseID
and 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:

namespace ContosoUniversity.Models
{
public class CourseAssignment
{
public int InstructorID { get; set; }
public int CourseID { get; set; }
public Instructor Instructor { get; set; }
public Course Course { get; set; }
}
}

The Instructor-to-Courses many-to-many relationship requires a join table, and the entity for that join table is
CourseAssignment.

It's common to name a join entity EntityName1EntityName2 . For example, the Instructor-to-Courses join table
using this pattern would be CourseInstructor . However, we recommend using a name that describes the
relationship.
Data models start out simple and grow. Join tables without payload (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
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 that:
Multiple rows are allowed for one course.
Multiple rows are allowed for one instructor.
Multiple rows aren't allowed for the same instructor and course.
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 database context

Update Data/SchoolContext.cs with the following code:

using ContosoUniversity.Models;
using Microsoft.EntityFrameworkCore;

namespace ContosoUniversity.Data
{
public class SchoolContext : DbContext
{
public SchoolContext(DbContextOptions<SchoolContext> options) : base(options)
{
}

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

public DbSet<Enrollment> Enrollments { get; set; }
public DbSet<Student> Students { 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:

protected override void OnModelCreating(ModelBuilder modelBuilder)

{
modelBuilder.Entity<Blog>()
.Property(b => b.Url)
.IsRequired();
}

In this tutorial, the fluent API is used only for database 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 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
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 database

Update the code in Data/DbInitializer.cs:

using System;
using System.Linq;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using ContosoUniversity.Models;

namespace ContosoUniversity.Data
{
public static class DbInitializer
{
public static void Initialize(SchoolContext context)
{
//context.Database.EnsureCreated();
// Look for any students.
if (context.Students.Any())
{
return; // DB has been seeded
}

var students = new Student[]

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

foreach (Student s in students)

{
context.Students.Add(s);
}
context.SaveChanges();

var instructors = new Instructor[]

{
new Instructor { FirstMidName = "Kim", LastName = "Abercrombie",
HireDate = DateTime.Parse("1995-03-11") },
new Instructor { FirstMidName = "Fadi", LastName = "Fakhouri",
HireDate = DateTime.Parse("2002-07-06") },
new Instructor { FirstMidName = "Roger", LastName = "Harui",
HireDate = DateTime.Parse("1998-07-01") },
new Instructor { FirstMidName = "Candace", LastName = "Kapoor",
HireDate = DateTime.Parse("2001-01-15") },
new Instructor { FirstMidName = "Roger", LastName = "Zheng",
HireDate = DateTime.Parse("2004-02-12") }
};

foreach (Instructor i in instructors)

{
context.Instructors.Add(i);
}
context.SaveChanges();

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,
StartDate = DateTime.Parse("2007-09-01"),
InstructorID = instructors.Single( i => i.LastName == "Fakhouri").ID },
new Department { Name = "Engineering", Budget = 350000,
StartDate = DateTime.Parse("2007-09-01"),
InstructorID = instructors.Single( i => i.LastName == "Harui").ID },
new Department { Name = "Economics", Budget = 100000,
StartDate = DateTime.Parse("2007-09-01"),
InstructorID = instructors.Single( i => i.LastName == "Kapoor").ID }
};

foreach (Department d in departments)

foreach (Department d in departments)
{
context.Departments.Add(d);
}
context.SaveChanges();

var courses = new Course[]

{
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,
DepartmentID = departments.Single( s => s.Name == "Economics").DepartmentID
},
new Course {CourseID = 1045, Title = "Calculus", Credits = 4,
DepartmentID = departments.Single( s => s.Name == "Mathematics").DepartmentID
},
new Course {CourseID = 3141, Title = "Trigonometry", Credits = 4,
DepartmentID = departments.Single( s => s.Name == "Mathematics").DepartmentID
},
new Course {CourseID = 2021, Title = "Composition", Credits = 3,
DepartmentID = departments.Single( s => s.Name == "English").DepartmentID
},
new Course {CourseID = 2042, Title = "Literature", Credits = 4,
DepartmentID = departments.Single( s => s.Name == "English").DepartmentID
},
};

foreach (Course c in courses)

{
context.Courses.Add(c);
}
context.SaveChanges();

var officeAssignments = new OfficeAssignment[]

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

foreach (OfficeAssignment o in officeAssignments)

{
context.OfficeAssignments.Add(o);
}
context.SaveChanges();

var courseInstructors = new CourseAssignment[]

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

foreach (CourseAssignment ci in courseInstructors)

{
context.CourseAssignments.Add(ci);
}
context.SaveChanges();

var enrollments = new Enrollment[]

{
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alexander").ID,
CourseID = courses.Single(c => c.Title == "Chemistry" ).CourseID,
Grade = Grade.A
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alexander").ID,
CourseID = courses.Single(c => c.Title == "Microeconomics" ).CourseID,
Grade = Grade.C
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alexander").ID,
CourseID = courses.Single(c => c.Title == "Macroeconomics" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alonso").ID,
CourseID = courses.Single(c => c.Title == "Calculus" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alonso").ID,
CourseID = courses.Single(c => c.Title == "Trigonometry" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alonso").ID,
CourseID = courses.Single(c => c.Title == "Composition" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Anand").ID,
CourseID = courses.Single(c => c.Title == "Chemistry" ).CourseID
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Anand").ID,
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
}
};

foreach (Enrollment e in enrollments)

{
var enrollmentInDataBase = context.Enrollments.Where(
s =>
s.Student.ID == e.StudentID &&
s.Course.CourseID == e.CourseID).SingleOrDefault();
if (enrollmentInDataBase == null)
{
context.Enrollments.Add(e);
}
}
context.SaveChanges();
}
}
}

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. See Enrollments and CourseAssignments for examples of
how many-to-many join tables can be seeded.

Add a migration
Build the project.
Visual Studio
Visual Studio Code
In PMC, run the following command.

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.
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'.
In the next section, you see what to do about this error.

Apply the migration or drop and re-create

Now that you have an existing database, you need to think about how to apply changes to it. This tutorial shows
two alternatives:
Drop and re-create the database. Choose this section if you're using SQLite.
Apply the migration to the existing database. The instructions in this section work for SQL Server only, not
for SQLite.
Either choice works for SQL Server. While the apply-migration method is more complex and time-consuming,
it's the preferred approach for real-world, production environments.

Drop and re-create the database

Skip this section if you're using SQL Server and want to do the apply-migration approach in the following
section.
To force EF Core to create a new database, drop and update the database:
Visual Studio
Visual Studio Code
In the Package Manager Console (PMC ), run the following command:

Drop-Database

Delete the Migrations folder, then run the following command:

Add-Migration InitialCreate
Update-Database

Run the app. Running the app runs the DbInitializer.Initialize method. The DbInitializer.Initialize
populates the new database.
Visual Studio
Visual Studio Code
Open the database 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.

Apply the migration

This section is optional. These steps work only for SQL Server LocalDB and only if you skipped the preceding
Drop and re-create the database section.
When migrations are run with existing data, there may be FK constraints that are not satisfied with the existing
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 preceding Drop and re-create the database section.
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 database 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
In the ComplexDataModel migration class, update the 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:
[!code-csharp[](intro/samples/cu30snapshots/5-complex/Migrations/ ComplexDataModel.cs?
name=snippet_CreateDefaultValue&highlight=23-31)]
With the preceding changes, existing Course rows will be related to the "Temp" department after the
ComplexDataModel.Up method runs.

The way of handling the situation shown here is simplified for this tutorial. 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 .

Visual Studio
Visual Studio Code
In the Package Manager Console (PMC ), run the following command:

Update-Database

Because the DbInitializer.Initialize method is designed to work only with an empty database, use SSOX to
delete all the rows in the Student and Course tables. (Cascade delete will take care of the Enrollment table.)
Run the app. Running the app runs the DbInitializer.Initialize method. The DbInitializer.Initialize
populates the new database.

Next steps
The next two tutorials show how to read and update related data.
 P R E V IO U S NEXT
T U T O R IA L T U T O R IA L

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 are shown in the following illustration:

If you run into problems you can't solve, download the completed app.

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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
public string LastName { get; set; }
public string FirstMidName { get; set; }
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
public DateTime EnrollmentDate { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }

}
}

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 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 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 DisplayFormat attribute 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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
[StringLength(50)]
public string LastName { get; set; }
[StringLength(50, ErrorMessage = "First name cannot be longer than 50 characters.")]
public string FirstMidName { get; set; }
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
public DateTime EnrollmentDate { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }

}
}

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:
 [RegularExpression(@"^[A-Z]+[a-zA-Z""'\s-]*$")]

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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
[StringLength(50)]
public string LastName { get; set; }
[StringLength(50, ErrorMessage = "First name cannot be longer than 50 characters.")]
[Column("FirstName")]
public string FirstMidName { get; set; }
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
public DateTime EnrollmentDate { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }

}
}

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
Visual Studio Code

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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
[Required]
[StringLength(50)]
[Display(Name = "Last Name")]
public string LastName { get; set; }
[Required]
[StringLength(50, ErrorMessage = "First name cannot be longer than 50 characters.")]
[Column("FirstName")]
[Display(Name = "First Name")]
public string FirstMidName { get; set; }
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Enrollment Date")]
public DateTime EnrollmentDate { get; set; }
[Display(Name = "Full Name")]
public string FullName
{
get
{
return LastName + ", " + FirstMidName;
}
}

public ICollection<Enrollment> Enrollments { get; set; }

}
}

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:

[Display(Name = "Last Name")]

[StringLength(50, MinimumLength=1)]
public string LastName { get; set; }

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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Instructor
{
public int ID { get; set; }

[Required]
[Display(Name = "Last Name")]
[StringLength(50)]
public string LastName { get; set; }

[Required]
[Column("FirstName")]
[Display(Name = "First Name")]
[StringLength(50)]
public string FirstMidName { get; set; }

[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Hire Date")]
public DateTime HireDate { get; set; }

[Display(Name = "Full Name")]

public string FullName
{
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.
 public ICollection<CourseAssignment> CourseAssignments { get; set; }

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.

public OfficeAssignment OfficeAssignment { get; set; }

Create the OfficeAssignment entity

Create Models/OfficeAssignment.cs with the following code:

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
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]
public int InstructorID { get; set; }

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]
public Instructor Instructor { get; set; }

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:

 using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Course
{
[DatabaseGenerated(DatabaseGeneratedOption.None)]
[Display(Name = "Number")]
public int CourseID { get; set; }

[StringLength(50, MinimumLength = 3)]

public string Title { get; set; }

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

public int DepartmentID { get; set; }

public Department Department { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }
public ICollection<CourseAssignment> CourseAssignments { 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.

[DatabaseGenerated(DatabaseGeneratedOption.None)]
[Display(Name = "Number")]
public int CourseID { get; set; }

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.

public int DepartmentID { get; set; }

public Department Department { get; set; }

A course can have any number of students enrolled in it, so the Enrollments navigation property is a collection:

public ICollection<Enrollment> Enrollments { get; set; }

A course may be taught by multiple instructors, so the CourseAssignments navigation property is a collection:

public ICollection<CourseAssignment> CourseAssignments { get; set; }

CourseAssignment is explained later.

Create the Department entity

Create Models/Department.cs with the following code:

 using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Department
{
public int DepartmentID { get; set; }

[StringLength(50, MinimumLength = 3)]

public string Name { get; set; }

[DataType(DataType.Currency)]
[Column(TypeName = "money")]
public decimal Budget { get; set; }

[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[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; }
}
}

The Column attribute

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")]
public decimal Budget { get; set; }

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.
Foreign key and navigation properties
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:

public int? InstructorID { get; set; }

public Instructor Administrator { get; set; }

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:
 public ICollection<Course> Courses { get; set; }

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 was defined as non-nullable:
EF Core configures a cascade delete rule to delete the department when the instructor is deleted.
Deleting the department when the instructor is deleted isn't the intended behavior.
The following fluent API would set a restrict rule instead of cascade.

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:

 using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
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; }
[DisplayFormat(NullDisplayText = "No grade")]
public Grade? Grade { get; set; }

public Course Course { get; set; }

public Student Student { get; set; }
}
}

Foreign key and navigation properties

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:

public int CourseID { get; set; }

public Course Course { get; set; }

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

public int StudentID { get; set; }

public Student Student { get; set; }

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 Enrollment table didn't include grade information, it would only need to contain the two FKs ( CourseID
and 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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class CourseAssignment
{
public int InstructorID { get; set; }
public int CourseID { get; set; }
public Instructor Instructor { get; set; }
public Course Course { get; set; }
}
}

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:

using ContosoUniversity.Models;
using Microsoft.EntityFrameworkCore;

namespace ContosoUniversity.Models
{
public class SchoolContext : DbContext
{
public SchoolContext(DbContextOptions<SchoolContext> options) : base(options)
{
}

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

public DbSet<Enrollment> Enrollment { get; set; }
public DbSet<Student> Student { 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:

protected override void OnModelCreating(ModelBuilder modelBuilder)

{
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;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using ContosoUniversity.Models;

namespace ContosoUniversity.Data
{
public static class DbInitializer
{
public static void Initialize(SchoolContext context)
{
//context.Database.EnsureCreated();
// Look for any students.
if (context.Student.Any())
{
return; // DB has been seeded
}

var students = new Student[]

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

foreach (Student s in students)

{
context.Student.Add(s);
}
context.SaveChanges();

var instructors = new Instructor[]

{
new Instructor { FirstMidName = "Kim", LastName = "Abercrombie",
HireDate = DateTime.Parse("1995-03-11") },
new Instructor { FirstMidName = "Fadi", LastName = "Fakhouri",
HireDate = DateTime.Parse("2002-07-06") },
new Instructor { FirstMidName = "Roger", LastName = "Harui",
HireDate = DateTime.Parse("1998-07-01") },
new Instructor { FirstMidName = "Candace", LastName = "Kapoor",
HireDate = DateTime.Parse("2001-01-15") },
new Instructor { FirstMidName = "Roger", LastName = "Zheng",
HireDate = DateTime.Parse("2004-02-12") }
};

foreach (Instructor i in instructors)

{
context.Instructors.Add(i);
}
context.SaveChanges();

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,
StartDate = DateTime.Parse("2007-09-01"),
InstructorID = instructors.Single( i => i.LastName == "Fakhouri").ID },
new Department { Name = "Engineering", Budget = 350000,
StartDate = DateTime.Parse("2007-09-01"),
InstructorID = instructors.Single( i => i.LastName == "Harui").ID },
new Department { Name = "Economics", Budget = 100000,
StartDate = DateTime.Parse("2007-09-01"),
InstructorID = instructors.Single( i => i.LastName == "Kapoor").ID }
};

foreach (Department d in departments)

foreach (Department d in departments)
{
context.Departments.Add(d);
}
context.SaveChanges();

var courses = new Course[]

{
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,
DepartmentID = departments.Single( s => s.Name == "Economics").DepartmentID
},
new Course {CourseID = 1045, Title = "Calculus", Credits = 4,
DepartmentID = departments.Single( s => s.Name == "Mathematics").DepartmentID
},
new Course {CourseID = 3141, Title = "Trigonometry", Credits = 4,
DepartmentID = departments.Single( s => s.Name == "Mathematics").DepartmentID
},
new Course {CourseID = 2021, Title = "Composition", Credits = 3,
DepartmentID = departments.Single( s => s.Name == "English").DepartmentID
},
new Course {CourseID = 2042, Title = "Literature", Credits = 4,
DepartmentID = departments.Single( s => s.Name == "English").DepartmentID
},
};

foreach (Course c in courses)

{
context.Courses.Add(c);
}
context.SaveChanges();

var officeAssignments = new OfficeAssignment[]

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

foreach (OfficeAssignment o in officeAssignments)

{
context.OfficeAssignments.Add(o);
}
context.SaveChanges();

var courseInstructors = new CourseAssignment[]

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

foreach (CourseAssignment ci in courseInstructors)

{
context.CourseAssignments.Add(ci);
}
context.SaveChanges();

var enrollments = new Enrollment[]

{
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alexander").ID,
CourseID = courses.Single(c => c.Title == "Chemistry" ).CourseID,
Grade = Grade.A
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alexander").ID,
CourseID = courses.Single(c => c.Title == "Microeconomics" ).CourseID,
Grade = Grade.C
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alexander").ID,
CourseID = courses.Single(c => c.Title == "Macroeconomics" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alonso").ID,
CourseID = courses.Single(c => c.Title == "Calculus" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alonso").ID,
CourseID = courses.Single(c => c.Title == "Trigonometry" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alonso").ID,
CourseID = courses.Single(c => c.Title == "Composition" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Anand").ID,
CourseID = courses.Single(c => c.Title == "Chemistry" ).CourseID
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Anand").ID,
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
}
};

foreach (Enrollment e in enrollments)

{
var enrollmentInDataBase = context.Enrollment.Where(
s =>
s.Student.ID == e.StudentID &&
s.Course.CourseID == e.CourseID).SingleOrDefault();
if (enrollmentInDataBase == null)
{
context.Enrollment.Add(e);
}
}
context.SaveChanges();
}
}
}

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. See Enrollments and CourseAssignments for examples of
how many-to-many join tables can be seeded.

Add a migration
Build the project.
Visual Studio
Visual Studio Code

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'.
Apply the migration
Now that you have an existing database, you need to think about how to apply future changes to it. This tutorial
shows two approaches:
Drop and re-create the database
Apply the migration to the existing database. While this method is more complex and time-consuming, it's the
preferred approach for real-world, production environments. Note: This is an optional section of the tutorial.
You can do the drop and re-create steps and skip this section. If you do want to follow the steps in this section,
don't do the drop and re-create steps.
Drop and re -create 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
Visual Studio Code
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.
Apply the migration to the existing database
This section is optional. These steps work only if you skipped the preceding Drop and re-create the database
section.
When migrations are run with existing data, there may be FK constraints that are not satisfied with the existing
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:

migrationBuilder.CreateTable(
name: "Department",
columns: table => new
{
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)
},
constraints: table =>
{
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.

migrationBuilder.AddColumn<int>(
name: "DepartmentID",
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.

Additional resources
YouTube version of this tutorial(Part 1)
YouTube version of this tutorial(Part 2)

P R E V IO U S NEXT
 Razor Pages with EF Core in ASP.NET Core - Read
Related Data - 6 of 8
8/9/2019 • 28 minutes to read • Edit Online

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.
If you run into problems you can't solve, download the completed app and compare that code to what you
created by following the tutorial.
This tutorial shows how to read and display related data. Related data is data that EF Core loads into navigation
properties.
The following illustrations show the completed pages for this tutorial:
Eager, explicit, and lazy loading
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 an
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 a giant 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 explicit 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 database. With explicit loading, the code specifies the navigation properties to be loaded. Use the
Load method to do explicit loading. For example:

Lazy loading. Lazy loading was added to EF Core in version 2.1. 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 database each time a navigation property is
accessed for the first time.

Create Course pages

The Course entity includes a navigation property that contains the related Department entity.
To display the name of the assigned department for a course:
Load the related Department entity into the Course.Department navigation property.
Get the name from the Department entity's Name property.
Scaffold Course pages
Visual Studio
Visual Studio Code
Follow the instructions in Scaffold Student pages with the following exceptions:
Create a Pages/Courses folder.
Use Course for the model class.
Use the existing context class instead of creating a new one.
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.
Display the department name
Update Pages/Courses/Index.cshtml.cs with the following code:
 using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Collections.Generic;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Courses
{
public class IndexModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public IndexModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

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

public async Task OnGetAsync()

{
Courses = await _context.Courses
.Include(c => c.Department)
.AsNoTracking()
.ToListAsync();
}
}
}

The preceding code changes the Course property to Courses and adds AsNoTracking . AsNoTracking improves
performance because the entities returned are not tracked. The entities don't need to be tracked because they're
not updated in the current context.
Update Pages/Courses/Index.cshtml with the following code.
 @page
@model ContosoUniversity.Pages.Courses.IndexModel

@{
ViewData["Title"] = "Courses";
}

<h1>Courses</h1>

<p>
<a asp-page="Create">Create New</a>
</p>
<table class="table">
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.Courses[0].CourseID)
</th>
<th>
@Html.DisplayNameFor(model => model.Courses[0].Title)
</th>
<th>
@Html.DisplayNameFor(model => model.Courses[0].Credits)
</th>
<th>
@Html.DisplayNameFor(model => model.Courses[0].Department)
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model.Courses)
{
<tr>
<td>
@Html.DisplayFor(modelItem => item.CourseID)
</td>
<td>
@Html.DisplayFor(modelItem => item.Title)
</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 Course property name 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:

@Html.DisplayFor(modelItem => item.Department.Name)

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. The Select method is an alternative that
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; }

public async Task OnGetAsync()

{
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 int CourseID { get; set; }
public string Title { get; set; }
public int Credits { get; set; }
public string DepartmentName { get; set; }
}

See IndexSelect.cshtml and IndexSelect.cshtml.cs for a complete example.

Create Instructor pages

This section scaffolds Instructor pages and adds related Courses and Enrollments to the Instructors Index page.

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, 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, 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
The instructors page shows data from three different tables. A view model is needed that includes three
properties representing the three tables.
Create SchoolViewModels/InstructorIndexData.cs with the following code:
 using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Models.SchoolViewModels
{
public class InstructorIndexData
{
public IEnumerable<Instructor> Instructors { get; set; }
public IEnumerable<Course> Courses { get; set; }
public IEnumerable<Enrollment> Enrollments { get; set; }
}
}

Scaffold Instructor pages

Visual Studio
Visual Studio Code
Follow the instructions in Scaffold the student pages with the following exceptions:
Create a Pages/Instructors folder.
Use Instructor for the model class.
Use the existing context class instead of creating a new one.
To see what the scaffolded page looks like before you update it, run the app and navigate to the Instructors page.
Update Pages/Instructors/Index.cshtml.cs with the following code:
 using ContosoUniversity.Models;
using ContosoUniversity.Models.SchoolViewModels; // Add VM
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Instructors
{
public class IndexModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public IndexModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

public InstructorIndexData InstructorData { get; set; }

public int InstructorID { get; set; }
public int CourseID { get; set; }

public async Task OnGetAsync(int? id, int? courseID)

{
InstructorData = new InstructorIndexData();
InstructorData.Instructors = await _context.Instructors
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.AsNoTracking()
.OrderBy(i => i.LastName)
.ToListAsync();

if (id != null)
{
InstructorID = id.Value;
Instructor instructor = InstructorData.Instructors
.Where(i => i.ID == id.Value).Single();
InstructorData.Courses = instructor.CourseAssignments.Select(s => s.Course);
}

if (courseID != null)
{
CourseID = courseID.Value;
var selectedCourse = InstructorData.Courses
.Where(x => x.CourseID == courseID).Single();
InstructorData.Enrollments = selectedCourse.Enrollments;
}
}
}
}

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:
 InstructorData.Instructors = await _context.Instructors
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.AsNoTracking()
.OrderBy(i => i.LastName)
.ToListAsync();

The code specifies eager loading for the following navigation properties:
Instructor.OfficeAssignment
Instructor.CourseAssignments
CourseAssignments.Course
Course.Department
Course.Enrollments
Enrollment.Student

Notice the repetition of Include and ThenInclude methods for CourseAssignments and Course . This repetition
is necessary to specify eager loading for two navigation properties of the Course entity.
The following code executes when an instructor is selected ( id != null ).

if (id != null)
{
InstructorID = id.Value;
Instructor instructor = InstructorData.Instructors
.Where(i => i.ID == id.Value).Single();
InstructorData.Courses = instructor.CourseAssignments.Select(s => s.Course);
}

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.
The Where method returns a collection. But in this case, the filter will select a single entity. so the Single
method is called to convert 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.
The following code populates the view model's Enrollments property when a course is selected:

if (courseID != null)
{
CourseID = courseID.Value;
var selectedCourse = InstructorData.Courses
.Where(x => x.CourseID == courseID).Single();
InstructorData.Enrollments = selectedCourse.Enrollments;
}

Update the instructors Index page

Update Pages/Instructors/Index.cshtml with the following code.

@page "{id:int?}"
@model ContosoUniversity.Pages.Instructors.IndexModel

@{
ViewData["Title"] = "Instructors";
}

<h2>Instructors</h2>

<p>
<a asp-page="Create">Create New</a>
</p>
<table class="table">
<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.InstructorData.Instructors)
{
string selectedRow = "";
if (item.ID == Model.InstructorID)
{
selectedRow = "table-success";
}
<tr class="@selectedRow">
<td>
@Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
@Html.DisplayFor(modelItem => item.FirstMidName)
</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> |
<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>

@if (Model.InstructorData.Courses != null)

{
<h3>Courses Taught by Selected Instructor</h3>
<table class="table">
<tr>
<th></th>
<th>Number</th>
<th>Title</th>
<th>Department</th>
</tr>

@foreach (var item in Model.InstructorData.Courses)

{
string selectedRow = "";
if (item.CourseID == Model.CourseID)
{
selectedRow = "table-success";
}
<tr class="@selectedRow">
<td>
 <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>
}

@if (Model.InstructorData.Enrollments != null)

{
<h3>
Students Enrolled in Selected Course
</h3>
<table class="table">
<tr>
<th>Name</th>
<th>Grade</th>
</tr>
@foreach (var item in Model.InstructorData.Enrollments)
{
<tr>
<td>
@item.Student.FullName
</td>
<td>
@Html.DisplayFor(modelItem => item.Grade)
</td>
</tr>
}
</table>
}

The preceding code 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:
https://localhost:5001/Instructors?id=2

When the page directive is @page "{id:int?}" , the URL is:

https://localhost:5001/Instructors/2

Adds 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.

@if (item.OfficeAssignment != null)

{
@item.OfficeAssignment.Location
}

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

string selectedRow = "";

if (item.CourseID == Model.CourseID)
{
selectedRow = "success";
}
<tr class="@selectedRow">

Adds 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> |

Adds a table of courses for the selected Instructor.

Adds a table of student enrollments for the selected course.
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 for an instructor. The row style changes and courses assigned to that instructor are
displayed.
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:
 public async Task OnGetAsync(int? id, int? courseID)
{
Instructor = new InstructorIndexData();

Instructor.Instructors = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.AsNoTracking()
.OrderBy(i => i.LastName)
.ToListAsync();

if (id != null)
{
InstructorID = id.Value;
Instructor instructor = Instructor.Instructors.Single(
i => i.ID == id.Value);
InstructorData.Courses = instructor.CourseAssignments.Select(
s => s.Course);
}

if (courseID != null)
{
CourseID = courseID.Value;
Instructor.Enrollments = InstructorData.Courses.Single(
x => x.CourseID == courseID).Enrollments;
}
}

Use of Single with a Where condition is a matter of personal preference. It provides no benefits over using the
Where method.

Explicit loading
The current code specifies eager loading for Enrollments and Students :

InstructorData.Instructors = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.AsNoTracking()
.OrderBy(i => i.LastName)
.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 Pages/Instructors/Index.cshtml.cs with the following code.
 using ContosoUniversity.Models;
using ContosoUniversity.Models.SchoolViewModels; // Add VM
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Instructors
{
public class IndexModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public IndexModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

public InstructorIndexData InstructorData { get; set; }

public int InstructorID { get; set; }
public int CourseID { get; set; }

public async Task OnGetAsync(int? id, int? courseID)

{
InstructorData = new InstructorIndexData();
InstructorData.Instructors = await _context.Instructors
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
//.Include(i => i.CourseAssignments)
// .ThenInclude(i => i.Course)
// .ThenInclude(i => i.Enrollments)
// .ThenInclude(i => i.Student)
//.AsNoTracking()
.OrderBy(i => i.LastName)
.ToListAsync();

if (id != null)
{
InstructorID = id.Value;
Instructor instructor = InstructorData.Instructors
.Where(i => i.ID == id.Value).Single();
InstructorData.Courses = instructor.CourseAssignments.Select(s => s.Course);
}

if (courseID != null)
{
CourseID = courseID.Value;
var selectedCourse = InstructorData.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();
}
InstructorData.Enrollments = selectedCourse.Enrollments;
}
}
}
}

The preceding code drops the ThenInclude method calls for enrollment and student data. If a course is selected,
the explicit loading code retrieves:
The Enrollment entities for the selected course.
 The Student entities for each Enrollment .
Notice that the preceding code comments out .AsNoTracking() . Navigation properties can only be explicitly
loaded for tracked entities.
Test the app. From a user's perspective, the app behaves identically to the previous version.

Next steps
The next tutorial shows how to update related data.

P R E V IO U S NEXT
T U T O R IA L T U T O R IA L

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 explicit 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. Lazy loading was added to EF Core in version 2.1. 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 Course 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
Visual Studio Code
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.
Update the OnGetAsync method with the following code:

public async Task OnGetAsync()

{
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="Create">Create New</a>
</p>
<table class="table">
<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>
@Html.DisplayFor(modelItem => item.Title)
</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:
 @Html.DisplayFor(modelItem => item.Department.Name)

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:

public async Task OnGetAsync()

{
Course = await _context.Courses
.Include(c => c.Department)
.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; }

public async Task OnGetAsync()

{
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 int CourseID { get; set; }
public string Title { get; set; }
public int Credits { get; set; }
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.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Models.SchoolViewModels
{
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
Visual Studio Code
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;
using ContosoUniversity.Models.SchoolViewModels; // Add VM
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Instructors
{
public class IndexModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public IndexModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

public InstructorIndexData Instructor { get; set; }

public int InstructorID { 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:

Instructor.Instructors = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.AsNoTracking()
.OrderBy(i => i.LastName)
.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>
<a asp-page="Create">Create New</a>
</p>
<table class="table">
<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>
@Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
@Html.DisplayFor(modelItem => item.FirstMidName)
</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> |
<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>
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.

@if (item.OfficeAssignment != null)

{
@item.OfficeAssignment.Location
}

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.

string selectedRow = "";

if (item.CourseID == Model.CourseID)
{
selectedRow = "success";
}
<tr class="@selectedRow">

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)
{
Instructor = new InstructorIndexData();
Instructor.Instructors = await _context.Instructors
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.AsNoTracking()
.OrderBy(i => i.LastName)
.ToListAsync();

if (id != null)
{
InstructorID = id.Value;
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 class IndexModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public IndexModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

public InstructorIndexData Instructor { get; set; }

public int InstructorID { get; set; }
public int CourseID { get; set; }

public async Task OnGetAsync(int? id, int? courseID)

{
Instructor = new InstructorIndexData();
Instructor.Instructors = await _context.Instructors
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.AsNoTracking()
.OrderBy(i => i.LastName)
.ToListAsync();

if (id != null)
{
InstructorID = id.Value;
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;
}
}

Examine the updated query:

Instructor.Instructors = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.AsNoTracking()
.OrderBy(i => i.LastName)
.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)
{
InstructorID = id.Value;
Instructor instructor = Instructor.Instructors.Where(
i => i.ID == id.Value).Single();
Instructor.Courses = instructor.CourseAssignments.Select(s => s.Course);
}

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:

if (courseID != null)
{
CourseID = courseID.Value;
Instructor.Enrollments = Instructor.Courses.Where(
x => x.CourseID == courseID).Single().Enrollments;
}

Add the following markup to the end of the Pages/Instructors/Index.cshtml Razor Page:
 <a asp-page="./Delete" asp-route-id="@item.ID">Delete</a>
</td>
</tr>
}
</tbody>
</table>

@if (Model.Instructor.Courses != null)

{
<h3>Courses Taught by Selected Instructor</h3>
<table class="table">
<tr>
<th></th>
<th>Number</th>
<th>Title</th>
<th>Department</th>
</tr>

@foreach (var item in Model.Instructor.Courses)

{
string selectedRow = "";
if (item.CourseID == Model.CourseID)
{
selectedRow = "success";
}
<tr class="@selectedRow">
<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:
 Instructor.Instructors = await _context.Instructors
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.AsNoTracking()
.OrderBy(i => i.LastName)
.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>
<table class="table">
<tr>
<th>Name</th>
<th>Grade</th>
</tr>
@foreach (var item in Model.Instructor.Enrollments)
{
<tr>
<td>
@item.Student.FullName
</td>
<td>
@Html.DisplayFor(modelItem => item.Grade)
</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:
 public async Task OnGetAsync(int? id, int? courseID)
{
Instructor = new InstructorIndexData();

Instructor.Instructors = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.AsNoTracking()
.OrderBy(i => i.LastName)
.ToListAsync();

if (id != null)
{
InstructorID = id.Value;
Instructor instructor = Instructor.Instructors.Single(
i => i.ID == id.Value);
Instructor.Courses = instructor.CourseAssignments.Select(
s => s.Course);
}

if (courseID != null)
{
CourseID = courseID.Value;
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 :

Instructor.Instructors = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.AsNoTracking()
.OrderBy(i => i.LastName)
.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:
 public async Task OnGetAsync(int? id, int? courseID)
{
Instructor = new InstructorIndexData();
Instructor.Instructors = await _context.Instructors
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
//.Include(i => i.CourseAssignments)
// .ThenInclude(i => i.Course)
// .ThenInclude(i => i.Enrollments)
// .ThenInclude(i => i.Student)
// .AsNoTracking()
.OrderBy(i => i.LastName)
.ToListAsync();

if (id != null)
{
InstructorID = id.Value;
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;
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.

Additional resources
YouTube version of this tutorial (part1)
YouTube version of this tutorial (part2)

P R E V IO U S NEXT
 Razor Pages with EF Core in ASP.NET Core - Update
Related Data - 7 of 8
8/13/2019 • 32 minutes to read • Edit Online

By Tom Dykstra, 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.
If you run into problems you can't solve, download the completed app and compare that code to what you
created by following the tutorial.
This tutorial shows how to update related data. The following illustrations show some of the completed pages.
Update the Course Create and Edit pages
The scaffolded code for the Course Create and Edit pages has a Department drop-down list that shows
Department ID (an integer). The drop-down should show the Department name, so both of these pages need a
list of department names. To provide that list, use a base class for the Create and Edit pages.
Create a base class for Course Create and Edit
Create a Pages/Courses/DepartmentNamePageModel.cs file with the following code:
 using ContosoUniversity.Data;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.AspNetCore.Mvc.Rendering;
using Microsoft.EntityFrameworkCore;
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 .
Update the Course Create page model
A Course is assigned to a Department. The base class for the Create and Edit pages provides a SelectList for
selecting the department. The drop-down list that uses the SelectList sets the Course.DepartmentID foreign key
(FK) property. EF Core uses the Course.DepartmentID FK to load the Department navigation property.
Update Pages/Courses/Create.cshtml.cs with the following code:
 using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Courses
{
public class CreateModel : DepartmentNamePageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public CreateModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

public IActionResult OnGet()

{
PopulateDepartmentsDropDownList(_context);
return Page();
}

[BindProperty]
public Course Course { get; set; }

public async Task<IActionResult> OnPostAsync()

{
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);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}

// Select DepartmentID if TryUpdateModelAsync fails.

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

The preceding code:

Derives from DepartmentNamePageModel .
Uses TryUpdateModelAsync to prevent overposting.
Removes ViewData["DepartmentID"] . DepartmentNameSL from the base class is a strongly typed model and will
be used by the Razor page. Strongly typed models are preferred over weakly typed. For more information,
see Weakly typed data (ViewData and ViewBag).
Update the Course Create Razor page
Update Pages/Courses/Create.cshtml with the following code:
 @page
@model ContosoUniversity.Pages.Courses.CreateModel
@{
ViewData["Title"] = "Create Course";
}
<h2>Create</h2>
<h4>Course</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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 class="form-group">
<input type="submit" value="Create" class="btn btn-primary" />
</div>
</form>
</div>
</div>
<div>
<a asp-page="Index">Back to List</a>
</div>
@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

The preceding code makes the following changes:

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" in the drop-down when no
department has been selected yet, rather than the first department.
Adds a validation message when the department isn't selected.
The Razor Page uses the Select Tag Helper:
 <div class="form-group">
<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>

Test the Create page. The Create page displays the department name rather than the department ID.
Update the Course Edit page model
Update Pages/Courses/Edit.cshtml.cs with the following code:

using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Courses
{
public class EditModel : DepartmentNamePageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public EditModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Course Course { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Course = await _context.Courses

.Include(c => c.Department).FirstOrDefaultAsync(m => m.CourseID == id);

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

// Select current DepartmentID.

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

public async Task<IActionResult> OnPostAsync(int? id)

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

var courseToUpdate = await _context.Courses.FindAsync(id);

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

if (await TryUpdateModelAsync<Course>(
courseToUpdate,
"course", // Prefix for form value.
c => c.Credits, c => c.DepartmentID, c => c.Title))
{
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}

// 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 selects that department in the drop-down
list.
Update the Course Edit Razor page
Update Pages/Courses/Edit.cshtml with the following code:
 @page
@model ContosoUniversity.Pages.Courses.EditModel

@{
ViewData["Title"] = "Edit";
}

<h2>Edit</h2>

<h4>Course</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<input type="hidden" asp-for="Course.CourseID" />
<div class="form-group">
<label asp-for="Course.CourseID" class="control-label"></label>
<div>@Html.DisplayFor(model => model.Course.CourseID)</div>
</div>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<label asp-for="Course.Department" class="control-label"></label>
<select asp-for="Course.DepartmentID" class="form-control"
asp-items="@Model.DepartmentNameSL"></select>
<span asp-validation-for="Course.DepartmentID" class="text-danger"></span>
</div>
<div class="form-group">
<input type="submit" value="Save" class="btn btn-primary" />
</div>
</form>
</div>
</div>

<div>
<a asp-page="./Index">Back to List</a>
</div>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

The preceding code makes the following changes:

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 for the Department drop-down 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.

Update the Course Details and Delete pages

AsNoTracking can improve performance when tracking isn't required.
Update the Course page models
Update Pages/Courses/Delete.cshtml.cs with the following code to add AsNoTracking :

using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Courses
{
public class DeleteModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public DeleteModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Course Course { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Course = await _context.Courses

.AsNoTracking()
.Include(c => c.Department)
.FirstOrDefaultAsync(m => m.CourseID == id);

if (Course == null)
{
return NotFound();
}
return Page();
}

public async Task<IActionResult> OnPostAsync(int? id)

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

Course = await _context.Courses.FindAsync(id);

if (Course != null)
{
_context.Courses.Remove(Course);
await _context.SaveChangesAsync();
}

return RedirectToPage("./Index");
}
}
}

Make the same change in the Pages/Courses/Details.cshtml.cs file:

 using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Courses
{
public class DetailsModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public DetailsModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

public Course Course { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Course = await _context.Courses

.AsNoTracking()
.Include(c => c.Department)
.FirstOrDefaultAsync(m => m.CourseID == id);

if (Course == null)
{
return NotFound();
}
return Page();
}
#endregion
}
}

Update the Course Razor pages

Update Pages/Courses/Delete.cshtml with the following code:
 @page
@model ContosoUniversity.Pages.Courses.DeleteModel

@{
ViewData["Title"] = "Delete";
}

<h2>Delete</h2>

<h3>Are you sure you want to delete this?</h3>

<div>
<h4>Course</h4>
<hr />
<dl class="row">
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Course.CourseID)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Course.CourseID)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Course.Title)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Course.Title)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Course.Credits)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Course.Credits)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Course.Department)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Course.Department.Name)
</dd>
</dl>

<form method="post">
<input type="hidden" asp-for="Course.CourseID" />
<input type="submit" value="Delete" class="btn btn-danger" /> |
<a asp-page="./Index">Back to List</a>
</form>
</div>

Make the same changes to the Details page.

 @page
@model ContosoUniversity.Pages.Courses.DetailsModel

@{
ViewData["Title"] = "Details";
}

<h2>Details</h2>

<div>
<h4>Course</h4>
<hr />
<dl class="row">
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Course.CourseID)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Course.CourseID)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Course.Title)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Course.Title)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Course.Credits)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Course.Credits)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Course.Department)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Course.Department.Name)
</dd>
</dl>
</div>
<div>
<a asp-page="./Edit" asp-route-id="@Model.Course.CourseID">Edit</a> |
<a asp-page="./Index">Back to List</a>
</div>

Test the Course pages

Test the create, edit, details, and delete pages.

Update the instructor Create and Edit pages

Instructors may teach any number of courses. The following image shows the instructor Edit page with an array
of course checkboxes.
The checkboxes enable changes to courses an instructor is assigned to. A checkbox is displayed for every course
in the database. Courses that the instructor is assigned to are selected. The user can select or clear checkboxes to
change course assignments. If the number of courses were much greater, a different UI might work better. But
the method of managing a many-to-many relationship shown here wouldn't change. To create or delete
relationships, you manipulate a join entity.
Create a class for assigned courses data
Create SchoolViewModels/AssignedCourseData.cs with the following code:

namespace ContosoUniversity.Models.SchoolViewModels
{
public class AssignedCourseData
{
public int CourseID { get; set; }
public string Title { get; set; }
public bool Assigned { get; set; }
}
}

The AssignedCourseData class contains data to create the check boxes for courses assigned to an instructor.
Create an Instructor page model base class
Create the Pages/Instructors/InstructorCoursesPageModel.cs base class:

using ContosoUniversity.Data;
using ContosoUniversity.Models;
using ContosoUniversity.Models.SchoolViewModels;
using Microsoft.AspNetCore.Mvc.RazorPages;
using System.Collections.Generic;
using System.Linq;

namespace ContosoUniversity.Pages.Instructors
{
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);
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 for
efficient lookups.
Since the Razor page 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:

if (selectedCourses == null)
{
instructorToUpdate.CourseAssignments = new List<CourseAssignment>();
return;
}

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 page. 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.

if (selectedCoursesHS.Contains(course.CourseID.ToString()))
{
if (!instructorCourses.Contains(course.CourseID))
{
instructorToUpdate.CourseAssignments.Add(
new CourseAssignment
{
InstructorID = instructorToUpdate.ID,
CourseID = course.CourseID
});
}
}

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.

else
{
if (instructorCourses.Contains(course.CourseID))
{
CourseAssignment courseToRemove
= instructorToUpdate
.CourseAssignments
.SingleOrDefault(i => i.CourseID == course.CourseID);
context.Remove(courseToRemove);
}
}

Handle office location

Another relationship the edit page has to handle is the one-to-zero-or-one relationship that the Instructor entity
has with the OfficeAssignment entity. The instructor edit code must handle the following scenarios:
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 Instructor Edit page model
Update Pages/Instructors/Edit.cshtml.cs with the following code:

using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using System;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Instructors
{
public class EditModel : InstructorCoursesPageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public EditModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Instructor Instructor { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Instructor = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments).ThenInclude(i => i.Course)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.ID == id);

if (Instructor == null)
{
return NotFound();
}
PopulateAssignedCourseData(_context, Instructor);
return Page();
}

public async Task<IActionResult> OnPostAsync(int? id, string[] selectedCourses)

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

var instructorToUpdate = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.FirstOrDefaultAsync(s => s.ID == id);

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

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;
}
UpdateInstructorCourses(_context, selectedCourses, instructorToUpdate);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
UpdateInstructorCourses(_context, selectedCourses, instructorToUpdate);
PopulateAssignedCourseData(_context, instructorToUpdate);
return Page();
}
}
}

The preceding code:

Gets the current Instructor entity from the database using eager loading for the OfficeAssignment ,
CourseAssignment , and CourseAssignment.Course navigation properties.
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.
Calls PopulateAssignedCourseData in OnGetAsync to provide information for the checkboxes using the
AssignedCourseData view model class.
Calls UpdateInstructorCourses in OnPostAsync to apply information from the checkboxes to the Instructor
entity being edited.
Calls PopulateAssignedCourseData and UpdateInstructorCourses in OnPostAsync if TryUpdateModel fails. These
method calls restore the assigned course data entered on the page when it is redisplayed with an error
message.
Update the Instructor Edit Razor page
Update Pages/Instructors/Edit.cshtml with the following code:

@page
@model ContosoUniversity.Pages.Instructors.EditModel
@{
ViewData["Title"] = "Edit";
}
<h2>Edit</h2>
<h4>Instructor</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<input type="hidden" asp-for="Instructor.ID" />
<div class="form-group">
<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>
<div class="form-group">
 <div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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 class="form-group">
<div class="table">
<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 class="form-group">
<input type="submit" value="Save" class="btn btn-primary" />
</div>
</form>
</div>
</div>

<div>
<a asp-page="./Index">Back to List</a>
</div>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

The preceding code creates an HTML table that has three columns. Each column has a checkbox and a caption
containing the course number and title. The checkboxes 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 checkbox is set to
CourseID . When the page is posted, the model binder passes an array that consists of the CourseID values for
only the checkboxes that are selected.
When the checkboxes are initially rendered, courses assigned to the instructor are selected.
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.
Run the app and test the updated Instructors Edit page. Change some course assignments. The changes are
reflected on the Index page.
Update the Instructor Create page
Update the Instructor Create page model and Razor page with code similar to the Edit page:
using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Instructors
{
public class CreateModel : InstructorCoursesPageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public CreateModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

public IActionResult OnGet()

{
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);
return Page();
}

[BindProperty]
public Instructor Instructor { get; set; }

public async Task<IActionResult> OnPostAsync(string[] selectedCourses)

{
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);
}
}

if (await TryUpdateModelAsync<Instructor>(
newInstructor,
"Instructor",
i => i.FirstMidName, i => i.LastName,
i => i.HireDate, i => i.OfficeAssignment))
{
_context.Instructors.Add(newInstructor);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
PopulateAssignedCourseData(_context, newInstructor);
return Page();
}
}
}

@page
@model ContosoUniversity.Pages.Instructors.CreateModel
@{
ViewData["Title"] = "Create";
}

<h2>Create</h2>

<h4>Instructor</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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 class="form-group">
<div class="table">
<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 class="form-group">
<input type="submit" value="Create" class="btn btn-primary" />
</div>
</form>
</div>
</div>

<div>
<a asp-page="Index">Back to List</a>
</div>
 @section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

Test the instructor Create page.

Update the Instructor Delete page

Update Pages/Instructors/Delete.cshtml.cs with the following code:
using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Instructors
{
public class DeleteModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public DeleteModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Instructor Instructor { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Instructor = await _context.Instructors.FirstOrDefaultAsync(m => m.ID == id);

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

public async Task<IActionResult> OnPostAsync(int? id)

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

Instructor instructor = await _context.Instructors

.Include(i => i.CourseAssignments)
.SingleAsync(i => i.ID == id);

if (instructor == null)
{
return RedirectToPage("./Index");
}

var departments = await _context.Departments

.Where(d => d.InstructorID == id)
.ToListAsync();
departments.ForEach(d => d.InstructorID = null);

_context.Instructors.Remove(instructor);

await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
}
}
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.
Run the app and test the Delete page.

Next steps

P R E V IO U S NEXT
T U T O R IA L T U T O R IA L

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 ContosoUniversity.Data;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.AspNetCore.Mvc.Rendering;
using Microsoft.EntityFrameworkCore;
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:
 using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Courses
{
public class CreateModel : DepartmentNamePageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public CreateModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

public IActionResult OnGet()

{
PopulateDepartmentsDropDownList(_context);
return Page();
}

[BindProperty]
public Course Course { get; set; }

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
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);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}

// 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 code:
 @page
@model ContosoUniversity.Pages.Courses.CreateModel
@{
ViewData["Title"] = "Create Course";
}
<h2>Create</h2>
<h4>Course</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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 class="form-group">
<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");}
}

The preceding markup makes the following changes:

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:
 <div class="form-group">
<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>

Test the Create page. The Create page displays the department name rather than the department ID.
Update the Courses Edit page.
Replace the code in Pages/Courses/Edit.cshtml.cs with the following code:
 using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Courses
{
public class EditModel : DepartmentNamePageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public EditModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Course Course { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Course = await _context.Courses

.Include(c => c.Department).FirstOrDefaultAsync(m => m.CourseID == id);

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

// Select current DepartmentID.

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

public async Task<IActionResult> OnPostAsync(int? id)

{
if (!ModelState.IsValid)
{
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))
{
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}

// 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

@{
ViewData["Title"] = "Edit";
}

<h2>Edit</h2>

<h4>Course</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<input type="hidden" asp-for="Course.CourseID" />
<div class="form-group">
<label asp-for="Course.CourseID" class="control-label"></label>
<div>@Html.DisplayFor(model => model.Course.CourseID)</div>
</div>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<label asp-for="Course.Department" class="control-label"></label>
<select asp-for="Course.DepartmentID" class="form-control"
asp-items="@Model.DepartmentNameSL"></select>
<span asp-validation-for="Course.DepartmentID" class="text-danger"></span>
</div>
<div class="form-group">
<input type="submit" value="Save" class="btn btn-default" />
</div>
</form>
</div>
</div>

<div>
<a asp-page="./Index">Back to List</a>
</div>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

The preceding markup makes the following changes:

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 class DeleteModel : PageModel

{
private readonly ContosoUniversity.Data.SchoolContext _context;

public DeleteModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Course Course { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Course = await _context.Courses

.AsNoTracking()
.Include(c => c.Department)
.FirstOrDefaultAsync(m => m.CourseID == id);

if (Course == null)
{
return NotFound();
}
return Page();
}

public async Task<IActionResult> OnPostAsync(int? id)

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

Course = await _context.Courses

.AsNoTracking()
.FirstOrDefaultAsync(m => m.CourseID == id);

if (Course != null)
{
_context.Courses.Remove(Course);
await _context.SaveChangesAsync();
}

return RedirectToPage("./Index");
}
}

Update the OnGetAsync method in the Pages/Courses/Details.cshtml.cs file:

 public async Task<IActionResult> OnGetAsync(int? id)
{
if (id == null)
{
return NotFound();
}

Course = await _context.Courses

.AsNoTracking()
.Include(c => c.Department)
.FirstOrDefaultAsync(m => m.CourseID == id);

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

@{
ViewData["Title"] = "Delete";
}

<h2>Delete</h2>

<h3>Are you sure you want to delete this?</h3>

<div>
<h4>Course</h4>
<hr />
<dl class="dl-horizontal">
<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>

<form method="post">
<input type="hidden" asp-for="Course.CourseID" />
<input type="submit" value="Delete" class="btn btn-default" /> |
<a asp-page="./Index">Back to List</a>
</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:

public class EditModel : PageModel

{
private readonly ContosoUniversity.Data.SchoolContext _context;

public EditModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Instructor Instructor { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Instructor = await _context.Instructors

.Include(i => i.OfficeAssignment)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.ID == id);

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

public async Task<IActionResult> OnPostAsync(int? id)

{
if (!ModelState.IsValid)
{
return Page();
}

var instructorToUpdate = await _context.Instructors

.Include(i => i.OfficeAssignment)
.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;
}
await _context.SaveChangesAsync();
}
return RedirectToPage("./Index");

}
}

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
@{
ViewData["Title"] = "Edit";
}
<h2>Edit</h2>
<h4>Instructor</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<input type="hidden" asp-for="Instructor.ID" />
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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 class="form-group">
<input type="submit" value="Save" class="btn btn-default" />
</div>
</form>
</div>
</div>

<div>
<a asp-page="./Index">Back to List</a>
</div>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

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:

namespace ContosoUniversity.Models.SchoolViewModels
{
public class AssignedCourseData
{
public int CourseID { get; set; }
public string Title { get; set; }
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 ContosoUniversity.Data;
using ContosoUniversity.Models;
using ContosoUniversity.Models.SchoolViewModels;
using Microsoft.AspNetCore.Mvc.RazorPages;
using System.Collections.Generic;
using System.Linq;

namespace ContosoUniversity.Pages.Instructors
{
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
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public EditModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Instructor Instructor { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Instructor = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments).ThenInclude(i => i.Course)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.ID == id);

if (Instructor == null)
{
return NotFound();
}
PopulateAssignedCourseData(_context, Instructor);
return Page();
}

public async Task<IActionResult> OnPostAsync(int? id, string[] selectedCourses)

{
if (!ModelState.IsValid)
{
return Page();
}

var instructorToUpdate = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.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;
}
UpdateInstructorCourses(_context, selectedCourses, instructorToUpdate);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
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
@{
ViewData["Title"] = "Edit";
}
<h2>Edit</h2>
<h4>Instructor</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<input type="hidden" asp-for="Instructor.ID" />
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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 class="form-group">
<div class="col-md-offset-2 col-md-10">
<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 class="form-group">
<input type="submit" value="Save" class="btn btn-default" />
</div>
</form>
</div>
 </div>
</div>

<div>
<a asp-page="./Index">Back to List</a>
</div>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

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:

using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Instructors
{
public class CreateModel : InstructorCoursesPageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public CreateModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

public IActionResult OnGet()

{
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 Instructor Instructor { get; set; }

public async Task<IActionResult> OnPostAsync(string[] selectedCourses)

{
if (!ModelState.IsValid)
{
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);
}
}

if (await TryUpdateModelAsync<Instructor>(
newInstructor,
"Instructor",
i => i.FirstMidName, i => i.LastName,
i => i.HireDate, i => i.OfficeAssignment))
{
_context.Instructors.Add(newInstructor);
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
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

@{
ViewData["Title"] = "Create";
}

<h2>Create</h2>

<h4>Instructor</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<div class="form-group">
<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>
 </div>
<div class="form-group">
<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>
<div class="form-group">
<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>

<div class="form-group">
<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 class="form-group">
<div class="col-md-offset-2 col-md-10">
<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 class="form-group">
<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");}
}

Test the instructor Create page.

Update the Delete page

Update the Delete page model with the following code:
 using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Instructors
{
public class DeleteModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public DeleteModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Instructor Instructor { get; set; }

public async Task<IActionResult> OnGetAsync(int? id)

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

Instructor = await _context.Instructors.SingleAsync(m => m.ID == id);

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

public async Task<IActionResult> OnPostAsync(int id)

{
Instructor instructor = await _context.Instructors
.Include(i => i.CourseAssignments)
.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);

await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
}
}

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.
Additional resources
YouTube version of this tutorial (Part 1)
YouTube version of this tutorial (Part 2)

P R E V IO U S NEXT
 Razor Pages with EF Core in ASP.NET Core -
Concurrency - 8 of 8
8/9/2019 • 36 minutes to read • Edit Online

By Rick Anderson, Tom Dykstra, and Jon P Smith

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.
If you run into problems you can't solve, download the completed app and compare that code to what you
created by following the tutorial.
This tutorial shows how to handle conflicts when multiple users update an entity concurrently (at the same time).

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 database.
If concurrency detection isn't enabled, whoever updates the database last overwrites the other user's changes. If
this risk is acceptable, the cost of programming for concurrency might outweigh the benefit.
Pessimistic concurrency (locking)
One way to prevent concurrency conflicts is to use database locks. This is called pessimistic concurrency. Before
the app reads a database row that it intends to update, it requests a lock. Once a row is locked for update access,
no other users are allowed to lock the row until the first lock is released.
Managing locks has disadvantages. It can be complex to program and can cause performance problems as the
number of users increases. Entity Framework Core provides no built-in support for it, and this tutorial doesn't
show how to implement it.
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 take effect, since the browser displays the Index page with zero as the
Budget amount.
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:
You can keep track of which property a user has modified and update only the corresponding columns in
the database.
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 has some
disadvantages:
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 database. 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.

Conflict detection in EF Core

EF Core throws DbConcurrencyException exceptions when it detects conflicts. The data model has to be
configured to enable conflict detection. Options for enabling conflict detection include the following:
Configure EF Core to include the original values of columns configured as concurrency tokens in the
Where clause of Update and Delete commands.
When SaveChanges is called, the Where clause looks for the original values of any properties annotated
with the ConcurrencyCheck attribute. The update statement won't find a row to update if any of the
concurrency token properties changed since the row was first read. EF Core interprets that as a
concurrency conflict. For database tables that have many columns, this approach can result in very large
Where clauses, and can require large amounts of state. Therefore this approach is generally not
recommended, and it isn't the method used in this tutorial.
In the database table, include a tracking column that can be used to determine when a row has been
changed.
In a SQL Server database, the data type of the tracking column is 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 number). If
the row being updated has been changed by another user, the value in the rowversion column is different
than the original value. In that case, the Update or Delete statement can't find the row to update because
 of the Where clause. EF Core throws a concurrency exception when no rows are affected by an Update or
Delete command.

Add a tracking property

In Models/Department.cs, add a tracking property named RowVersion:

using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Department
{
public int DepartmentID { get; set; }

[StringLength(50, MinimumLength = 3)]

public string Name { get; set; }

[DataType(DataType.Currency)]
[Column(TypeName = "money")]
public decimal Budget { get; set; }

[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Start Date")]
public DateTime StartDate { get; set; }

public int? InstructorID { get; set; }

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

public Instructor Administrator { get; set; }

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

The Timestamp attribute is what identifies the column as a concurrency tracking column. The fluent API is an
alternative way to specify the tracking property:

modelBuilder.Entity<Department>()
.Property<byte[]>("RowVersion")
.IsRowVersion();

Visual Studio
Visual Studio Code
For a SQL Server database, the [Timestamp] attribute on an entity property defined as byte array:
Causes the column to be included in DELETE and UPDATE WHERE clauses.
Sets the column type in the database to rowversion.
The database generates a sequential row version number that's incremented each time the row is updated. In an
Update or Delete command, the Where clause includes the fetched row version value. If the row being updated
has changed since it was fetched:
The current row version value doesn't match the fetched value.
 The Update or Delete commands don't find a row because the Where clause looks for the fetched row
version value.
A DbUpdateConcurrencyException is thrown.

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 database 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. If no rows are updated, EF Core
throws a DbUpdateConcurrencyException .
Update the database
Adding the RowVersion property changes the data model, which requires a migration.
Build the project.
Visual Studio
Visual Studio Code
Run the following command in the PMC:

Add-Migration RowVersion

This command:
Creates 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()
.HasAnnotation("SqlServer:ValueGenerationStrategy",
SqlServerValueGenerationStrategy.IdentityColumn);

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");
});

Visual Studio
Visual Studio Code
Run the following command in the PMC:

Update-Database

Scaffold Department pages

Visual Studio
Visual Studio Code
Follow the instructions in Scaffold Student pages with the following exceptions:
Create a Pages/Departments folder.
Use Department for the model class.
Use the existing context class instead of creating a new one.
Build the project.

Update the Index page

The scaffolding tool created a RowVersion column for the Index page, but that field wouldn't be displayed in a
production app. In this tutorial, the last byte of the RowVersion is displayed to help show how concurrency
handling works. The last byte isn't guaranteed to be unique by itself.
Update the Index page:
Replace Index with Departments.
 Change the code containing RowVersion to show just the last byte of the byte array.
Replace FirstMidName with FullName.
The following code shows the updated page:

@page
@model ContosoUniversity.Pages.Departments.IndexModel

@{
ViewData["Title"] = "Departments";
}

<h2>Departments</h2>

<p>
<a asp-page="Create">Create New</a>
</p>
<table class="table">
<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 ContosoUniversity.Data;
using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.AspNetCore.Mvc.Rendering;
using Microsoft.EntityFrameworkCore;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Departments
{
public class EditModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public EditModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

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

public async Task<IActionResult> OnGetAsync(int id)

{
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();
}

public async Task<IActionResult> OnPostAsync(int id)

{
if (!ModelState.IsValid)
{
return Page();
}

var departmentToUpdate = await _context.Departments

.Include(i => i.Administrator)
.FirstOrDefaultAsync(m => m.DepartmentID == id);

if (departmentToUpdate == null)
{
return HandleDeletedDepartment();
}

_context.Entry(departmentToUpdate)
.Property("RowVersion").OriginalValue = Department.RowVersion;

if (await TryUpdateModelAsync<Department>(
 if (await TryUpdateModelAsync<Department>(
departmentToUpdate,
"Department",
s => s.Name, s => s.StartDate, s => s.Budget, s => s.InstructorID))
{
try
{
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
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;
// Clear the model error for the next postback.
ModelState.Remove("Department.RowVersion");
}
}

InstructorNameSL = new SelectList(_context.Instructors,

"ID", "FullName", departmentToUpdate.InstructorID);

return Page();
}

private IActionResult HandleDeletedDepartment()

{
var 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}");
}

ModelState.AddModelError(string.Empty,
"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.");
}
}
}

The OriginalValue is updated with the rowVersion value from the entity when it was fetched in the OnGet
method. 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.

public async Task<IActionResult> OnPostAsync(int id)

{
if (!ModelState.IsValid)
{
return Page();
}

var departmentToUpdate = await _context.Departments

.Include(i => i.Administrator)
.FirstOrDefaultAsync(m => m.DepartmentID == id);

if (departmentToUpdate == null)
{
return HandleDeletedDepartment();
}

_context.Entry(departmentToUpdate)
.Property("RowVersion").OriginalValue = Department.RowVersion;

In the preceding highlighted code:

The value in Department.RowVersion is what was in the entity when it was originally fetched in the Get request
for the Edit page. The value is provided to the OnPost method by a hidden field in the Razor page that
displays the entity to be edited. The hidden field value is copied to Department.RowVersion by the model
binder.
OriginalValue is what EF Core will use in the Where clause. Before the highlighted line of code executes,
OriginalValue has the value that was in the database when FirstOrDefaultAsync was called in this method,
which might be different from what was displayed on the Edit page.
The highlighted code makes sure that EF Core uses the original RowVersion value from the displayed
Department entity in the SQL UPDATE statement's Where clause.

When a concurrency error happens, the following highlighted code gets the client values (the values posted to
this method) and the database values.
 if (await TryUpdateModelAsync<Department>(
departmentToUpdate,
"Department",
s => s.Name, s => s.StartDate, s => s.Budget, s => s.InstructorID))
{
try
{
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
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;
// Clear the model error for the next postback.
ModelState.Remove("Department.RowVersion");
}

The following code adds a custom error message for each column that has database 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}");
}

ModelState.AddModelError(string.Empty,
"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.");
}

The following highlighted code sets the RowVersion value to the new value retrieved from the database. The next
time the user clicks Save, only concurrency errors that happen since the last display of the Edit page will be
caught.
 if (await TryUpdateModelAsync<Department>(
departmentToUpdate,
"Department",
s => s.Name, s => s.StartDate, s => s.Budget, s => s.InstructorID))
{
try
{
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
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;
// Clear the model error for the next postback.
ModelState.Remove("Department.RowVersion");
}

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 the Razor page
Update Pages/Departments/Edit.cshtml with the following code:
 @page "{id:int}"
@model ContosoUniversity.Pages.Departments.EditModel
@{
ViewData["Title"] = "Edit";
}
<h2>Edit</h2>
<h4>Department</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<input type="hidden" asp-for="Department.DepartmentID" />
<input type="hidden" asp-for="Department.RowVersion" />
<div class="form-group">
<label>RowVersion</label>
@Model.Department.RowVersion[7]
</div>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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 class="form-group">
<input type="submit" value="Save" class="btn btn-primary" />
</div>
</form>
</div>
</div>
<div>
<a asp-page="./Index">Back to List</a>
</div>
@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

The preceding code:

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 database 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

Update Pages/Departments/Delete.cshtml.cs with the following code:

using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Departments
{
public class DeleteModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public DeleteModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

[BindProperty]
public Department Department { get; set; }
public string ConcurrencyErrorMessage { get; set; }

public async Task<IActionResult> OnGetAsync(int id, bool? concurrencyError)

{
Department = await _context.Departments
.Include(d => d.Administrator)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.DepartmentID == id);

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();
}

public async Task<IActionResult> OnPostAsync(int id)

{
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);
await _context.SaveChangesAsync();
 }
return RedirectToPage("./Index");
}
catch (DbUpdateConcurrencyException)
{
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 database.
A DbUpdateConcurrencyException exception is thrown.
OnGetAsync is called with the concurrencyError .

Update the Delete Razor page

Update Pages/Departments/Delete.cshtml with the following code:
 @page "{id:int}"
@model ContosoUniversity.Pages.Departments.DeleteModel

@{
ViewData["Title"] = "Delete";
}

<h2>Delete</h2>

<p class="text-danger">@Model.ConcurrencyErrorMessage</p>

<h3>Are you sure you want to delete this?</h3>

<div>
<h4>Department</h4>
<hr />
<dl class="dl-horizontal">
<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>

<form method="post">
<input type="hidden" asp-for="Department.DepartmentID" />
<input type="hidden" asp-for="Department.RowVersion" />
<div class="form-actions no-color">
<input type="submit" value="Delete" class="btn btn-danger" /> |
<a asp-page="./Index">Back to List</a>
</div>
</form>
</div>

The preceding code makes the following changes:

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 postgit add back binds the value.
Test concurrency conflicts
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
database. Clicking Delete deletes the entity, unless RowVersion has been updated.department has been deleted.

Additional resources
Concurrency Tokens in EF Core
Handle concurrency in EF Core
Debugging ASP.NET Core 2.x source

Next steps
This is the last tutorial in the series. Additional topics are covered in the MVC version of this tutorial series.

P R E V IO U S
T U T O R IA L

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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Department
{
public int DepartmentID { get; set; }

[StringLength(50, MinimumLength = 3)]

public string Name { get; set; }

[DataType(DataType.Currency)]
[Column(TypeName = "money")]
public decimal Budget { get; set; }

[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Start Date")]
public DateTime StartDate { get; set; }

public int? InstructorID { get; set; }

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

public Instructor Administrator { get; set; }

public ICollection<Course> Courses { 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:

modelBuilder.Entity<Department>()
.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

dotnet ef database update

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:

Runs migrations to update the DB.

Scaffold the Departments model

Visual Studio
Visual Studio Code
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>
<a asp-page="Create">Create New</a>
</p>
<table class="table">
<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 ContosoUniversity.Data;
using ContosoUniversity.Models;
using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.AspNetCore.Mvc.Rendering;
using Microsoft.EntityFrameworkCore;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Departments
{
public class EditModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;

public EditModel(ContosoUniversity.Data.SchoolContext context)

{
_context = context;
}

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

public async Task<IActionResult> OnGetAsync(int id)

{
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();
}

public async Task<IActionResult> OnPostAsync(int id)

{
if (!ModelState.IsValid)
{
return Page();
}

var departmentToUpdate = await _context.Departments

.Include(i => i.Administrator)
.FirstOrDefaultAsync(m => m.DepartmentID == id);

// null means Department was deleted by another user.

if (departmentToUpdate == null)
{
return 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>(
 if (await TryUpdateModelAsync<Department>(
departmentToUpdate,
"Department",
s => s.Name, s => s.StartDate, s => s.Budget, s => s.InstructorID))
{
try
{
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
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 IActionResult HandleDeletedDepartment()

{
var 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}");
}

ModelState.AddModelError(string.Empty,
"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.

public async Task<IActionResult> OnPostAsync(int id)

{
if (!ModelState.IsValid)
{
return Page();
}

var departmentToUpdate = await _context.Departments

.Include(i => i.Administrator)
.FirstOrDefaultAsync(m => m.DepartmentID == id);

// null means Department was deleted by another user.

if (departmentToUpdate == null)
{
return 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
{
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
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");
}

The following 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}");
}

ModelState.AddModelError(string.Empty,
"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.");
}
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
{
await _context.SaveChangesAsync();
return RedirectToPage("./Index");
}
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");
}

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 the Edit page

Update Pages/Departments/Edit.cshtml with the following markup:
 @page "{id:int}"
@model ContosoUniversity.Pages.Departments.EditModel
@{
ViewData["Title"] = "Edit";
}
<h2>Edit</h2>
<h4>Department</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form method="post">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<input type="hidden" asp-for="Department.DepartmentID" />
<input type="hidden" asp-for="Department.RowVersion" />
<div class="form-group">
<label>RowVersion</label>
@Model.Department.RowVersion[7]
</div>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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 class="form-group">
<input type="submit" value="Save" class="btn btn-default" />
</div>
</form>
</div>
</div>
<div>
<a asp-page="./Index">Back to List</a>
</div>
@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

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

Update the Delete page model with the following code:

using ContosoUniversity.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.EntityFrameworkCore;
using System.Threading.Tasks;

namespace ContosoUniversity.Pages.Departments
{
public class DeleteModel : PageModel
{
private readonly ContosoUniversity.Data.SchoolContext _context;
 public DeleteModel(ContosoUniversity.Data.SchoolContext context)
{
_context = context;
}

[BindProperty]
public Department Department { get; set; }
public string ConcurrencyErrorMessage { get; set; }

public async Task<IActionResult> OnGetAsync(int id, bool? concurrencyError)

{
Department = await _context.Departments
.Include(d => d.Administrator)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.DepartmentID == id);

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();
}

public async Task<IActionResult> OnPostAsync(int id)

{
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);
await _context.SaveChangesAsync();
}
return RedirectToPage("./Index");
}
catch (DbUpdateConcurrencyException)
{
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 the Delete page
Update Pages/Departments/Delete.cshtml with the following code:

@page "{id:int}"
@model ContosoUniversity.Pages.Departments.DeleteModel

@{
ViewData["Title"] = "Delete";
}

<h2>Delete</h2>

<p class="text-danger">@Model.ConcurrencyErrorMessage</p>

<h3>Are you sure you want to delete this?</h3>

<div>
<h4>Department</h4>
<hr />
<dl class="dl-horizontal">
<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>

<form method="post">
<input type="hidden" asp-for="Department.DepartmentID" />
<input type="hidden" asp-for="Department.RowVersion" />
<div class="form-actions no-color">
<input type="submit" value="Delete" class="btn btn-default" /> |
<a asp-page="./Index">Back to List</a>
</div>
</form>
</div>

The preceding code makes the following changes:

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.
Additional resources
Concurrency Tokens in EF Core
Handle concurrency in EF Core
YouTube version of this tutorial(Handling Concurrency Conflicts)
YouTube version of this tutorial(Part 2)
YouTube version of this tutorial(Part 3)

P R E V IO U S
 ASP.NET Core MVC with EF Core - tutorial series
4/26/2019 • 2 minutes to read • Edit Online

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:
Is easier to follow.
Provides more EF Core best practices.
Uses more efficient queries.
Is more current with the latest API.
Covers more features.
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
9. Inheritance
10. Advanced topics
 Tutorial: Get started with EF Core in an ASP.NET
MVC web app
5/14/2019 • 20 minutes to read • Edit Online

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:
Is easier to follow.
Provides more EF Core best practices.
Uses more efficient queries.
Is more current with the latest API.
Covers more features.
The Contoso University sample web application demonstrates how to create ASP.NET Core 2.2 MVC web
applications using Entity Framework (EF ) Core 2.2 and Visual Studio 2017 or 2019.
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.
In this tutorial, you:
Create an ASP.NET Core MVC web app
Set up the site style
Learn about EF Core NuGet packages
Create the data model
Create the database context
Register the context for dependency injection
Initialize the database with test data
Create a controller and views
View the database

Prerequisites
.NET Core SDK 2.2
Visual Studio 2019 with the following workloads:
ASP.NET and web development workload
.NET Core cross-platform development workload

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.

Contoso University web app

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.
Create web app
Open Visual Studio.
From the File menu, select New > Project.
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 dialog to appear.
Select .NET Core, ASP.NET Core 2.2 and the Web Application (Model-View-Controller) template.
Make sure Authentication is set to No Authentication.
Select OK
Set up the site style
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 About, Students, Courses, Instructors, and Departments, and delete the Privacy
menu entry.
The changes are highlighted.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@ViewData["Title"] - Contoso University</title>

<environment include="Development">
<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
</environment>
<environment exclude="Development">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-
bootstrap/4.1.3/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"
crossorigin="anonymous"
integrity="sha256-eSi1q2PG6J7g7ib17yAaWMcrr5GrtohYChqibrV7PBE="/>
</environment>
<link rel="stylesheet" href="~/css/site.css" />
</head>
<body>
<header>
<nav class="navbar navbar-expand-sm navbar-toggleable-sm navbar-light bg-white border-bottom box-
shadow mb-3">
shadow mb-3">
<div class="container">
<a class="navbar-brand" asp-area="" asp-controller="Home" asp-action="Index">Contoso
University</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target=".navbar-
collapse" aria-controls="navbarSupportedContent"
aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="navbar-collapse collapse d-sm-inline-flex flex-sm-row-reverse">
<ul class="navbar-nav flex-grow-1">
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-
action="Index">Home</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-
action="About">About</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Students" asp-
action="Index">Students</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Courses" asp-
action="Index">Courses</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Instructors" asp-
action="Index">Instructors</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Departments" asp-
action="Index">Departments</a>
</li>
</ul>
</div>
</div>
</nav>
</header>
<div class="container">
<partial name="_CookieConsentPartial" />
<main role="main" class="pb-3">
@RenderBody()
</main>
</div>

<footer class="border-top footer text-muted">

<div class="container">
&copy; 2019 - Contoso University - <a asp-area="" asp-controller="Home" asp-
action="Privacy">Privacy</a>
</div>
</footer>

<environment include="Development">
<script src="~/lib/jquery/dist/jquery.js"></script>
<script src="~/lib/bootstrap/dist/js/bootstrap.bundle.js"></script>
</environment>
<environment exclude="Development">
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js"
asp-fallback-src="~/lib/jquery/dist/jquery.min.js"
asp-fallback-test="window.jQuery"
crossorigin="anonymous"
integrity="sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8=">
</script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-
bootstrap/4.1.3/js/bootstrap.bundle.min.js"
asp-fallback-src="~/lib/bootstrap/dist/js/bootstrap.bundle.min.js"
asp-fallback-test="window.jQuery && window.jQuery.fn && window.jQuery.fn.modal"
crossorigin="anonymous"
 crossorigin="anonymous"
integrity="sha256-E/V4cWE4qvAeO5MOhjtGtqDzPndRO1LBk8lJ/PR7CA4=">
</script>
</environment>
<script src="~/js/site.js" asp-append-version="true"></script>

@RenderSection("Scripts", required: false)

</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 class="jumbotron">
<h1>Contoso University</h1>
</div>
<div class="row">
<div class="col-md-4">
<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 MVC web application.
</p>
</div>
<div class="col-md-4">
<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.asp.net/en/latest/data/ef-mvc/intro.html">See the
tutorial &raquo;</a></p>
</div>
<div class="col-md-4">
<h2>Download it</h2>
<p>You can download the completed project from GitHub.</p>
<p><a class="btn btn-default"
href="https://github.com/aspnet/AspNetCore.Docs/tree/master/aspnetcore/data/ef-mvc/intro/samples/cu-
final">See project source code &raquo;</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.
About EF 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.App metapackage, so you don't need to reference the package.
The EF SQL Server 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.

Create the data model

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;
using System.Collections.Generic;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
public string LastName { get; set; }
public string FirstMidName { get; set; }
public DateTime EnrollmentDate { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }

}
}

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.
The Enrollment entity

In the Models folder, create Enrollment.cs and replace the existing code with the following code:

namespace ContosoUniversity.Models
{
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 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:

using System.Collections.Generic;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Course
{
[DatabaseGenerated(DatabaseGeneratedOption.None)]
public int CourseID { get; set; }
public string Title { get; set; }
public int Credits { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }

}
}

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:
 using ContosoUniversity.Models;
using Microsoft.EntityFrameworkCore;

namespace ContosoUniversity.Data
{
public class SchoolContext : DbContext
{
public SchoolContext(DbContextOptions<SchoolContext> options) : base(options)
{
}

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

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.

using ContosoUniversity.Models;
using Microsoft.EntityFrameworkCore;

namespace ContosoUniversity.Data
{
public class SchoolContext : DbContext
{
public SchoolContext(DbContextOptions<SchoolContext> options) : base(options)
{
}

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

public DbSet<Enrollment> Enrollments { get; set; }
public DbSet<Student> Students { get; set; }

protected override void OnModelCreating(ModelBuilder modelBuilder)

{
modelBuilder.Entity<Course>().ToTable("Course");
modelBuilder.Entity<Enrollment>().ToTable("Enrollment");
modelBuilder.Entity<Student>().ToTable("Student");
}
}
}

Register the SchoolContext

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.

public void ConfigureServices(IServiceCollection services)

{
services.Configure<CookiePolicyOptions>(options =>
{
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddDbContext<SchoolContext>(options =>
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
appsettings.json file.
Add using statements for ContosoUniversity.Data and Microsoft.EntityFrameworkCore namespaces, and then
build the project.

using ContosoUniversity.Data;
using Microsoft.EntityFrameworkCore;
using Microsoft.AspNetCore.Http;

Open the appsettings.json file and add a connection string as shown in the following example.

{
"ConnectionStrings": {
"DefaultConnection": "Server=
(localdb)\\mssqllocaldb;Database=ContosoUniversity1;Trusted_Connection=True;MultipleActiveResultSets=true"
},
"Logging": {
"IncludeScopes": false,
"LogLevel": {
"Default": "Warning"
}
}
}

SQL Server Express LocalDB

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.

Initialize DB 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 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.Students.Any())
{
return; // DB has been seeded
}

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.Students.Add(s);
}
context.SaveChanges();

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.Courses.Add(c);
}
context.SaveChanges();

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=1045,Grade=Grade.B},
new Enrollment{StudentID=2,CourseID=3141,Grade=Grade.F},
new Enrollment{StudentID=2,CourseID=2021,Grade=Grade.F},
new Enrollment{StudentID=3,CourseID=1050},
new Enrollment{StudentID=4,CourseID=1050},
new Enrollment{StudentID=4,CourseID=4022,Grade=Grade.F},
 new Enrollment{StudentID=4,CourseID=4022,Grade=Grade.F},
new Enrollment{StudentID=5,CourseID=4041,Grade=Grade.C},
new Enrollment{StudentID=6,CourseID=1045},
new Enrollment{StudentID=7,CourseID=3141,Grade=Grade.A},
};
foreach (Enrollment e in enrollments)
{
context.Enrollments.Add(e);
}
context.SaveChanges();
}
}
}

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.

public static void Main(string[] args)

{
var host = CreateWebHostBuilder(args).Build();

using (var scope = host.Services.CreateScope())

{
var services = scope.ServiceProvider;
try
{
var context = services.GetRequiredService<SchoolContext>();
DbInitializer.Initialize(context);
}
catch (Exception ex)
{
var logger = services.GetRequiredService<ILogger<Program>>();
logger.LogError(ex, "An error occurred while seeding the database.");
}
}

host.Run();
}

Add using statements:

using Microsoft.Extensions.DependencyInjection;
using ContosoUniversity.Data;

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 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.
In the Add Scaffold dialog box:
Select MVC controller with views, using Entity Framework.
Click Add. The Add MVC Controller with views, using Entity Framework dialog box appears.

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
{
private readonly SchoolContext _context;

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:

public async Task<IActionResult> Index()

{
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>

@{
ViewData["Title"] = "Index";
}

<h2>Index</h2>

<p>
<a asp-action="Create">Create New</a>
</p>
<table class="table">
<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>
@foreach (var item in Model) {
<tr>
<td>
@Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
@Html.DisplayFor(modelItem => item.FirstMidName)
</td>
<td>
@Html.DisplayFor(modelItem => item.EnrollmentDate)
</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>

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 Students 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\<yourusername> 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 <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, 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
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, 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.

public async Task<IActionResult> Index()

{
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.
ToListAsync is the asynchronous version of the ToList extension method.

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
var students = context.Students.Where(s => s.LastName == "Davolio") .

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.

Get the code

Download or view the completed application.

Next steps
In this tutorial, you:
Created ASP.NET Core MVC web app
 Set up the site style
Learned about EF Core NuGet packages
Created the data model
Created the database context
Registered the SchoolContext
Initialized DB with test data
Created controller and views
Viewed the database
In the following tutorial, you'll learn how to perform basic CRUD (create, read, update, delete) operations.
Advance to the next tutorial to learn how to perform basic CRUD (create, read, update, delete) operations.
Implement basic CRUD functionality
 Tutorial: Implement CRUD Functionality - ASP.NET
MVC with EF Core
6/6/2019 • 19 minutes to read • Edit Online

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:

Customize the Details page
Update the Create page
Update the Edit page
Update the Delete page
Close database connections

Prerequisites
Get started with EF Core and ASP.NET Core MVC

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.
 public async Task<IActionResult> Details(int? id)
{
if (id == null)
{
return NotFound();
}

var student = await _context.Students

.Include(s => s.Enrollments)
.ThenInclude(e => e.Course)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.ID == id);

if (student == null)
{
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:

app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});

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 class="col-sm-2">
@Html.DisplayNameFor(model => model.LastName)
</dt>
<dd class="col-sm-10">
@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 class="col-sm-2">
@Html.DisplayNameFor(model => model.Enrollments)
</dt>
<dd class="col-sm-10">
<table class="table">
<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>
@Html.DisplayFor(modelItem => item.Grade)
</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]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Create(
[Bind("EnrollmentDate,FirstMidName,LastName")] Student student)
{
try
{
if (ModelState.IsValid)
{
_context.Add(student);
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}
}
catch (DbUpdateException /* ex */)
{
//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.");
}
return View(student);
}

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 class Student

{
public int ID { get; set; }
public string LastName { get; set; }
public string FirstMidName { get; set; }
public DateTime EnrollmentDate { get; 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]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Create(
[Bind("EnrollmentDate,FirstMidName,LastName")] Student student)
{
try
{
if (ModelState.IsValid)
{
_context.Add(student);
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}
}
catch (DbUpdateException /* ex */)
{
//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.");
}
return View(student);
}

Change the date to a valid value and click Create to see the new student appear in the Index page.

Update the Edit 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")]
[ValidateAntiForgeryToken]
public async Task<IActionResult> EditPost(int? id)
{
if (id == null)
{
return NotFound();
}
var studentToUpdate = await _context.Students.FirstOrDefaultAsync(s => s.ID == id);
if (await TryUpdateModelAsync<Student>(
studentToUpdate,
"",
s => s.FirstMidName, s => s.LastName, s => s.EnrollmentDate))
{
try
{
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}
catch (DbUpdateException /* ex */)
{
//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.");
}
}
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();
}
if (ModelState.IsValid)
{
try
{
_context.Update(student);
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}
catch (DbUpdateException /* ex */)
{
//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.");
}
}
return View(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.
Modified . Some or all of the entity's property values have been modified. The 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.

Update the Delete page

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();
}

var student = await _context.Students

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

if (saveChangesError.GetValueOrDefault())
{
ViewData["ErrorMessage"] =
"Delete failed. Try again, and if the problem persists " +
"see your system administrator.";
}

return View(student);
}

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.

[HttpPost, ActionName("Delete")]
[ValidateAntiForgeryToken]
public async Task<IActionResult> DeleteConfirmed(int id)
{
var student = await _context.Students.FindAsync(id);
if (student == null)
{
return RedirectToAction(nameof(Index));
}

try
{
_context.Students.Remove(student);
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}
catch (DbUpdateException /* ex */)
{
//Log the error (uncomment ex variable name and write a log.)
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]
[ValidateAntiForgeryToken]
public async Task<IActionResult> DeleteConfirmed(int id)
{
try
{
Student studentToDelete = new Student() { ID = id };
_context.Entry(studentToDelete).State = EntityState.Deleted;
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}
catch (DbUpdateException /* ex */)
{
//Log the error (uncomment ex variable name and write a log.)
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>
<h3>Are you sure you want to delete this?</h3>

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.)

Close 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.

Handle 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.

Get the code

Download or view the completed application.

Next steps
In this tutorial, you:
Customized the Details page
Updated the Create page
Updated the Edit page
Updated the Delete page
Closed database connections
Advance to the next tutorial to learn how to expand the functionality of the Index page by adding sorting,
filtering, and paging.
Next: Sorting, filtering, and paging
 Tutorial: Add sorting, filtering, and paging - ASP.NET
MVC with EF Core
5/7/2019 • 14 minutes to read • Edit Online

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.

In this tutorial, you:

Add column sort links
Add a Search box
Add paging to Students Index
Add paging to Index method
Add paging links
Create an About page

Prerequisites
Implement CRUD Functionality

Add column sort links

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)
{
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());
}

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>

@{
ViewData["Title"] = "Index";
}

<h2>Index</h2>

<p>
<a asp-action="Create">Create New</a>
</p>
<table class="table">
<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>
@foreach (var item in Model) {
<tr>
<td>
@Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
@Html.DisplayFor(modelItem => item.FirstMidName)
</td>
<td>
@Html.DisplayFor(modelItem => item.EnrollmentDate)
</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>

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 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["NameSortParm"] = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";
ViewData["DateSortParm"] = sortOrder == "Date" ? "date_desc" : "Date";
ViewData["CurrentFilter"] = searchString;

var students = from s in _context.Students

select s;
if (!String.IsNullOrEmpty(searchString))
{
students = students.Where(s => s.LastName.Contains(searchString)
|| s.FirstMidName.Contains(searchString));
}
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());
}
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>
<a asp-action="Create">Create New</a>
</p>

<form asp-action="Index" method="get">

<div class="form-actions no-color">
<p>
Find by name: <input type="text" name="SearchString" value="@ViewData["currentFilter"]" />
<input type="submit" value="Search" class="btn btn-default" /> |
<a asp-action="Index">Back to Full List</a>
</p>
</div>
</form>

<table class="table">

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 to Students Index

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.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.EntityFrameworkCore;

namespace ContosoUniversity
{
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 to 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? pageNumber)
{
ViewData["CurrentSort"] = sortOrder;
ViewData["NameSortParm"] = String.IsNullOrEmpty(sortOrder) ? "name_desc" : "";
ViewData["DateSortParm"] = sortOrder == "Date" ? "date_desc" : "Date";

if (searchString != null)
{
pageNumber = 1;
}
else
{
searchString = currentFilter;
}

ViewData["CurrentFilter"] = searchString;

var students = from s in _context.Students

select s;
if (!String.IsNullOrEmpty(searchString))
{
students = students.Where(s => s.LastName.Contains(searchString)
|| s.FirstMidName.Contains(searchString));
}
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;
}

int pageSize = 3;
return View(await PaginatedList<Student>.CreateAsync(students.AsNoTracking(), pageNumber ?? 1,
pageSize));
}

This code adds a page number parameter, a current sort order parameter, and a current filter parameter to the
method signature.

public async Task<IActionResult> Index(

string sortOrder,
string currentFilter,
string searchString,
int? pageNumber)

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.

if (searchString != null)
{
pageNumber = 1;
}
else
{
searchString = currentFilter;
}

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(), pageNumber ?? 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
(pageNumber ?? 1) means return the value of pageNumber if it has a value, or return 1 if pageNumber is null.

Add paging links

In Views/Students/Index.cshtml, replace the existing code with the following code. The changes are highlighted.

@model PaginatedList<ContosoUniversity.Models.Student>

@{
ViewData["Title"] = "Index";
}

<h2>Index</h2>

<p>
<a asp-action="Create">Create New</a>
</p>

<form asp-action="Index" method="get">

<div class="form-actions no-color">
<p>
Find by name: <input type="text" name="SearchString" value="@ViewData["CurrentFilter"]" />
<input type="submit" value="Search" class="btn btn-default" /> |
<a asp-action="Index">Back to Full List</a>
</p>
</div>
</form>

<table class="table">
<thead>
<tr>
<th>
<a asp-action="Index" asp-route-sortOrder="@ViewData["NameSortParm"]" asp-route-
currentFilter="@ViewData["CurrentFilter"]">Last Name</a>
</th>
<th>
 <th>
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>
@Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
@Html.DisplayFor(modelItem => item.FirstMidName)
</td>
<td>
@Html.DisplayFor(modelItem => item.EnrollmentDate)
</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>

@{
var prevDisabled = !Model.HasPreviousPage ? "disabled" : "";
var nextDisabled = !Model.HasNextPage ? "disabled" : "";
}

<a asp-action="Index"
asp-route-sortOrder="@ViewData["CurrentSort"]"
asp-route-pageNumber="@(Model.PageIndex - 1)"
asp-route-currentFilter="@ViewData["CurrentFilter"]"
class="btn btn-default @prevDisabled">
Previous
</a>
<a asp-action="Index"
asp-route-sortOrder="@ViewData["CurrentSort"]"
asp-route-pageNumber="@(Model.PageIndex + 1)"
asp-route-currentFilter="@ViewData["CurrentFilter"]"
class="btn btn-default @nextDisabled">
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:

 <a asp-action="Index"
asp-route-sortOrder="@ViewData["CurrentSort"]"
asp-route-pageNumber="@(Model.PageIndex - 1)"
asp-route-currentFilter="@ViewData["CurrentFilter"]"
class="btn btn-default @prevDisabled">
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

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.
Create the About method in the Home controller.
Create 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;
using System.ComponentModel.DataAnnotations;

namespace ContosoUniversity.Models.SchoolViewModels
{
public class EnrollmentDateGroup
{
[DataType(DataType.Date)]
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:

using Microsoft.EntityFrameworkCore;
using ContosoUniversity.Data;
using ContosoUniversity.Models.SchoolViewModels;

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

{
private readonly SchoolContext _context;

public HomeController(SchoolContext context)

{
_context = context;
}

Add an 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.
Create the About View
Add a 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>

@foreach (var item in Model)

{
<tr>
<td>
@Html.DisplayFor(modelItem => item.EnrollmentDate)
</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.

Get the code

Download or view the completed application.

Next steps
In this tutorial, you:
Added column sort links
Added a Search box
Added paging to Students Index
Added paging to Index method
Added paging links
Created an About page
Advance to the next tutorial to learn how to handle data model changes by using migrations.
Next: Handle data model changes
 Tutorial: Using the migrations feature - ASP.NET
MVC with EF Core
7/11/2019 • 6 minutes to read • Edit Online

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.
In this tutorial, you:
Learn about migrations
Change the connection string
Create an initial migration
Examine Up and Down methods
Learn about the data model snapshot
Apply the migration

Prerequisites
Sorting, filtering, and paging

About 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.
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.

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.

{
"ConnectionStrings": {
"DefaultConnection": "Server=
(localdb)\\mssqllocaldb;Database=ContosoUniversity2;Trusted_Connection=True;MultipleActiveResultSets=true"
},

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 Folder 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.EntityFrameworkCore.Infrastructure[10403]
Entity Framework Core 2.2.0-rtm-35687 initialized 'SchoolContext' using provider
'Microsoft.EntityFrameworkCore.SqlServer' with options: None
Done. To undo this action, use 'ef migrations remove'

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 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

{
protected override void Up(MigrationBuilder migrationBuilder)
{
migrationBuilder.CreateTable(
name: "Course",
columns: table => new
{
CourseID = table.Column<int>(nullable: false),
Credits = table.Column<int>(nullable: false),
Title = table.Column<string>(nullable: true)
},
constraints: table =>
{
table.PrimaryKey("PK_Course", x => x.CourseID);
});

// Additional code not shown

}

protected override void Down(MigrationBuilder migrationBuilder)

{
migrationBuilder.DropTable(
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

In the command window, enter the following command to create the database and tables in it.

dotnet ef database update

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 Logging in .NET Core and ASP.NET Core.

info: Microsoft.EntityFrameworkCore.Infrastructure[10403]
Entity Framework Core 2.2.0-rtm-35687 initialized 'SchoolContext' using provider
'Microsoft.EntityFrameworkCore.SqlServer' with options: None
info: Microsoft.EntityFrameworkCore.Database.Command[20101]
Executed DbCommand (274ms) [Parameters=[], CommandType='Text', CommandTimeout='60']
CREATE DATABASE [ContosoUniversity2];
info: Microsoft.EntityFrameworkCore.Database.Command[20101]
Executed DbCommand (60ms) [Parameters=[], CommandType='Text', CommandTimeout='60']
IF SERVERPROPERTY('EngineEdition') <> 5
BEGIN
ALTER DATABASE [ContosoUniversity2] SET READ_COMMITTED_SNAPSHOT ON;
END;
info: Microsoft.EntityFrameworkCore.Database.Command[20101]
Executed DbCommand (15ms) [Parameters=[], CommandType='Text', CommandTimeout='30']
CREATE TABLE [__EFMigrationsHistory] (
[MigrationId] nvarchar(150) NOT NULL,
[ProductVersion] nvarchar(32) NOT NULL,
CONSTRAINT [PK___EFMigrationsHistory] PRIMARY KEY ([MigrationId])
);

<logs omitted for brevity>

info: Microsoft.EntityFrameworkCore.Database.Command[20101]
Executed DbCommand (3ms) [Parameters=[], CommandType='Text', CommandTimeout='30']
INSERT INTO [__EFMigrationsHistory] ([MigrationId], [ProductVersion])
VALUES (N'20190327172701_InitialCreate', N'2.2.0-rtm-35687');
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.

Compare CLI and 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 included in the Microsoft.AspNetCore.App metapackage, so you don't need to add a package
reference if your app has a package reference for Microsoft.AspNetCore.App .
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).

Get the code

Download or view the completed application.

Next step
In this tutorial, you:
Learned about migrations
Learned about NuGet migration packages
 Changed the connection string
Created an initial migration
Examined Up and Down methods
Learned about the data model snapshot
Applied the migration
Advance to the next tutorial to begin looking at more advanced topics about expanding the data model. Along
the way you'll create and apply additional migrations.
Create and apply additional migrations
 Tutorial: Create a complex data model - ASP.NET
MVC with EF Core
7/11/2019 • 30 minutes to read • Edit Online

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:

In this tutorial, you:

Customize the Data model
Make changes to Student entity
Create Instructor entity
Create OfficeAssignment entity
 Modify Course entity
Create Department entity
Modify Enrollment entity
Update the database context
Seed database with test data
Add a migration
Change the connection string
Update the database

Prerequisites
Using EF Core migrations

Customize the Data model

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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
public string LastName { get; set; }
public string FirstMidName { get; set; }
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
public DateTime EnrollmentDate { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }

}
}

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.
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 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 :
The browser can enable HTML5 features (for example to show a calendar control, the locale-appropriate
currency symbol, email links, some client-side input validation, etc.).
By default, the browser will render data using the correct format based on your locale.
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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
[StringLength(50)]
public string LastName { get; set; }
[StringLength(50)]
public string FirstMidName { get; set; }
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
public DateTime EnrollmentDate { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }

}
}

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:

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

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

dotnet ef database update

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 try to enter either name longer than 50 characters.
The application should prevent you from doing this.
The Column attribute
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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
[StringLength(50)]
public string LastName { get; set; }
[StringLength(50)]
[Column("FirstName")]
public string FirstMidName { get; set; }
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
public DateTime EnrollmentDate { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }

}
}

The addition of the Column attribute changes the model backing the SchoolContext , so it won't match the
database.
Save your changes and build the project. Then open the command window in the project folder and enter the
following commands to create another migration:

dotnet ef migrations add ColumnFirstName

dotnet ef database update

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.

Changes to Student entity

In Models/Student.cs, replace the code you added earlier with the following code. The changes are highlighted.
 using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Student
{
public int ID { get; set; }
[Required]
[StringLength(50)]
[Display(Name = "Last Name")]
public string LastName { get; set; }
[Required]
[StringLength(50)]
[Column("FirstName")]
[Display(Name = "First Name")]
public string FirstMidName { get; set; }
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Enrollment Date")]
public DateTime EnrollmentDate { get; set; }
[Display(Name = "Full Name")]
public string FullName
{
get
{
return LastName + ", " + FirstMidName;
}
}

public ICollection<Enrollment> Enrollments { get; set; }

}
}

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:

[Display(Name = "Last Name")]

[StringLength(50, MinimumLength=1)]
public string LastName { get; set; }

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 Instructor entity

Create Models/Instructor.cs, replacing the template code with the following code:

using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Instructor
{
public int ID { get; set; }

[Required]
[Display(Name = "Last Name")]
[StringLength(50)]
public string LastName { get; set; }

[Required]
[Column("FirstName")]
[Display(Name = "First Name")]
[StringLength(50)]
public string FirstMidName { get; set; }

[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Hire Date")]
public DateTime HireDate { get; set; }

[Display(Name = "Full Name")]

public string FullName
{
get { return LastName + ", " + FirstMidName; }
}

public ICollection<CourseAssignment> CourseAssignments { get; set; }

public OfficeAssignment OfficeAssignment { get; set; }
}
}

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.

public ICollection<CourseAssignment> CourseAssignments { get; set; }

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).

public OfficeAssignment OfficeAssignment { get; set; }

Create OfficeAssignment entity

Create Models/OfficeAssignment.cs with the following code:

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
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

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]
public int InstructorID { get; set; }
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 Course entity

In Models/Course.cs, replace the code you added earlier with the following code. The changes are highlighted.

using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Course
{
[DatabaseGenerated(DatabaseGeneratedOption.None)]
[Display(Name = "Number")]
public int CourseID { get; set; }

[StringLength(50, MinimumLength = 3)]

public string Title { get; set; }

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

public int DepartmentID { get; set; }

public Department Department { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }
public ICollection<CourseAssignment> CourseAssignments { get; set; }
}
}

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.

[DatabaseGenerated(DatabaseGeneratedOption.None)]
[Display(Name = "Number")]
public int CourseID { get; set; }

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.
Foreign key and navigation 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.

public int DepartmentID { get; set; }

public Department Department { get; set; }

A course can have any number of students enrolled in it, so the Enrollments navigation property is a collection:

public ICollection<Enrollment> Enrollments { get; set; }

A course may be taught by multiple instructors, so the CourseAssignments navigation property is a collection
(the type CourseAssignment is explained later):

public ICollection<CourseAssignment> CourseAssignments { get; set; }

Create Department entity

Create Models/Department.cs with the following code:

using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Department
{
public int DepartmentID { get; set; }

[StringLength(50, MinimumLength = 3)]

public string Name { get; set; }

[DataType(DataType.Currency)]
[Column(TypeName = "money")]
public decimal Budget { get; set; }

[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[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; }
}
}

The Column attribute

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")]
public decimal Budget { get; set; }

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.
Foreign key and navigation properties
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:

public int? InstructorID { get; set; }

public Instructor Administrator { get; set; }

A department may have many courses, so there's a Courses navigation property:

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

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 department when you delete the instructor, 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:

modelBuilder.Entity<Department>()
.HasOne(d => d.Administrator)
.WithMany()
.OnDelete(DeleteBehavior.Restrict)

Modify Enrollment entity

In Models/Enrollment.cs, replace the code you added earlier with the following code:
 using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
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; }
[DisplayFormat(NullDisplayText = "No grade")]
public Grade? Grade { get; set; }

public Course Course { get; set; }

public Student Student { get; set; }
}
}

Foreign key and navigation properties

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:

public int CourseID { get; set; }

public Course Course { get; set; }

An enrollment record is for a single student, so there's a StudentID foreign key property and a Student
navigation property:

public int StudentID { get; set; }

public Student Student { get; set; }

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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class CourseAssignment
{
public int InstructorID { get; set; }
public int CourseID { get; set; }
public Instructor Instructor { get; set; }
public Course Course { get; set; }
}
}

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:
 using ContosoUniversity.Models;
using Microsoft.EntityFrameworkCore;

namespace ContosoUniversity.Data
{
public class SchoolContext : DbContext
{
public SchoolContext(DbContextOptions<SchoolContext> options) : base(options)
{
}

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

public DbSet<Enrollment> Enrollments { get; set; }
public DbSet<Student> Students { 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 });
}
}
}

This code adds the new entities and configures the CourseAssignment entity's composite primary key.

About a fluent API alternative

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:

protected override void OnModelCreating(ModelBuilder modelBuilder)

{
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 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;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using ContosoUniversity.Models;

namespace ContosoUniversity.Data
namespace ContosoUniversity.Data
{
public static class DbInitializer
{
public static void Initialize(SchoolContext context)
{
//context.Database.EnsureCreated();

// Look for any students.

if (context.Students.Any())
{
return; // DB has been seeded
}

var students = new Student[]

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

foreach (Student s in students)

{
context.Students.Add(s);
}
context.SaveChanges();

var instructors = new Instructor[]

{
new Instructor { FirstMidName = "Kim", LastName = "Abercrombie",
HireDate = DateTime.Parse("1995-03-11") },
new Instructor { FirstMidName = "Fadi", LastName = "Fakhouri",
HireDate = DateTime.Parse("2002-07-06") },
new Instructor { FirstMidName = "Roger", LastName = "Harui",
HireDate = DateTime.Parse("1998-07-01") },
new Instructor { FirstMidName = "Candace", LastName = "Kapoor",
HireDate = DateTime.Parse("2001-01-15") },
new Instructor { FirstMidName = "Roger", LastName = "Zheng",
HireDate = DateTime.Parse("2004-02-12") }
};

foreach (Instructor i in instructors)

{
context.Instructors.Add(i);
}
context.SaveChanges();

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,
StartDate = DateTime.Parse("2007-09-01"),
InstructorID = instructors.Single( i => i.LastName == "Fakhouri").ID },
new Department { Name = "Engineering", Budget = 350000,
StartDate = DateTime.Parse("2007-09-01"),
 StartDate = DateTime.Parse("2007-09-01"),
InstructorID = instructors.Single( i => i.LastName == "Harui").ID },
new Department { Name = "Economics", Budget = 100000,
StartDate = DateTime.Parse("2007-09-01"),
InstructorID = instructors.Single( i => i.LastName == "Kapoor").ID }
};

foreach (Department d in departments)

{
context.Departments.Add(d);
}
context.SaveChanges();

var courses = new Course[]

{
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,
DepartmentID = departments.Single( s => s.Name == "Economics").DepartmentID
},
new Course {CourseID = 1045, Title = "Calculus", Credits = 4,
DepartmentID = departments.Single( s => s.Name == "Mathematics").DepartmentID
},
new Course {CourseID = 3141, Title = "Trigonometry", Credits = 4,
DepartmentID = departments.Single( s => s.Name == "Mathematics").DepartmentID
},
new Course {CourseID = 2021, Title = "Composition", Credits = 3,
DepartmentID = departments.Single( s => s.Name == "English").DepartmentID
},
new Course {CourseID = 2042, Title = "Literature", Credits = 4,
DepartmentID = departments.Single( s => s.Name == "English").DepartmentID
},
};

foreach (Course c in courses)

{
context.Courses.Add(c);
}
context.SaveChanges();

var officeAssignments = new OfficeAssignment[]

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

foreach (OfficeAssignment o in officeAssignments)

{
context.OfficeAssignments.Add(o);
}
context.SaveChanges();

var courseInstructors = new CourseAssignment[]

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

foreach (CourseAssignment ci in courseInstructors)

{
context.CourseAssignments.Add(ci);
}
context.SaveChanges();

var enrollments = new Enrollment[]

{
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alexander").ID,
CourseID = courses.Single(c => c.Title == "Chemistry" ).CourseID,
Grade = Grade.A
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alexander").ID,
CourseID = courses.Single(c => c.Title == "Microeconomics" ).CourseID,
Grade = Grade.C
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alexander").ID,
CourseID = courses.Single(c => c.Title == "Macroeconomics" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alonso").ID,
CourseID = courses.Single(c => c.Title == "Calculus" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alonso").ID,
CourseID = courses.Single(c => c.Title == "Trigonometry" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Alonso").ID,
CourseID = courses.Single(c => c.Title == "Composition" ).CourseID,
Grade = Grade.B
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Anand").ID,
 StudentID = students.Single(s => s.LastName == "Anand").ID,
CourseID = courses.Single(c => c.Title == "Chemistry" ).CourseID
},
new Enrollment {
StudentID = students.Single(s => s.LastName == "Anand").ID,
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
}
};

foreach (Enrollment e in enrollments)

{
var enrollmentInDataBase = context.Enrollments.Where(
s =>
s.Student.ID == e.StudentID &&
s.Course.CourseID == e.CourseID).SingleOrDefault();
if (enrollmentInDataBase == null)
{
context.Enrollments.Add(e);
}
}
context.SaveChanges();
}
}
}

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
Save your changes and build the project. Then open the command window in the project folder and enter the
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.
Done. To undo this action, use 'ef migrations remove'

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:
 migrationBuilder.CreateTable(
name: "Department",
columns: table => new
{
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)
},
constraints: table =>
{
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.

migrationBuilder.AddColumn<int>(
name: "DepartmentID",
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

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.

{
"ConnectionStrings": {
"DefaultConnection": "Server=
(localdb)\\mssqllocaldb;Database=ContosoUniversity3;Trusted_Connection=True;MultipleActiveResultSets=true"
},

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:

dotnet ef database drop

Update the database

After you have changed the database name or deleted the database, run the database update command in the
command window to execute the migrations.

dotnet ef database update

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.
Get the code
Download or view the completed application.

Next steps
In this tutorial, you:
Customized the Data model
Made changes to Student entity
Created Instructor entity
Created OfficeAssignment entity
Modified Course entity
Created Department entity
Modified Enrollment entity
Updated the database context
Seeded database with test data
Added a migration
Changed the connection string
Updated the database
Advance to the next tutorial to learn more about how to access related data.
Next: Access related data
 Tutorial: Read related data - ASP.NET MVC with EF
Core
8/6/2019 • 14 minutes to read • Edit Online

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.
In this tutorial, you:
Learn how to load related data
Create a Courses page
Create an Instructors page
Learn about explicit loading

Prerequisites
Create a complex data model

Learn how to load 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

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 ):

public async Task<IActionResult> Index()

{
var courses = _context.Courses
.Include(c => c.Department)
.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>
<a asp-action="Create">Create New</a>
</p>
<table class="table">
<thead>
<tr>
<th>
@Html.DisplayNameFor(model => model.CourseID)
</th>
<th>
@Html.DisplayNameFor(model => model.Title)
</th>
<th>
@Html.DisplayNameFor(model => model.Credits)
</th>
<th>
@Html.DisplayNameFor(model => model.Department)
</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach (var item in Model)
{
<tr>
<td>
@Html.DisplayFor(modelItem => item.CourseID)
</td>
<td>
@Html.DisplayFor(modelItem => item.Title)
</td>
<td>
@Html.DisplayFor(modelItem => item.Credits)
</td>
<td>
@Html.DisplayFor(modelItem => item.Department.Name)
</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:
 @Html.DisplayFor(modelItem => item.Department.Name)

Run the app and select the Courses tab to see the list with department names.

Create an Instructors page

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.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Models.SchoolViewModels
{
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:

using ContosoUniversity.Models.SchoolViewModels;

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
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.AsNoTracking()
.OrderBy(i => i.LastName)
.ToListAsync();

if (id != null)
{
ViewData["InstructorID"] = id.Value;
Instructor instructor = viewModel.Instructors.Where(
i => i.ID == id.Value).Single();
viewModel.Courses = instructor.CourseAssignments.Select(s => s.Course);
}

if (courseID != null)
{
ViewData["CourseID"] = courseID.Value;
viewModel.Enrollments = viewModel.Courses.Where(
x => x.CourseID == courseID).Single().Enrollments;
}

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.

viewModel.Instructors = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.AsNoTracking()
.OrderBy(i => i.LastName)
.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 .

viewModel.Instructors = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.AsNoTracking()
.OrderBy(i => i.LastName)
.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 .

viewModel.Instructors = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Enrollments)
.ThenInclude(i => i.Student)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.AsNoTracking()
.OrderBy(i => i.LastName)
.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)
{
ViewData["InstructorID"] = id.Value;
Instructor instructor = viewModel.Instructors.Where(
i => i.ID == id.Value).Single();
viewModel.Courses = instructor.CourseAssignments.Select(s => s.Course);
}

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.

if (courseID != null)
{
ViewData["CourseID"] = courseID.Value;
viewModel.Enrollments = viewModel.Courses.Where(
x => x.CourseID == courseID).Single().Enrollments;
}

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>
<a asp-action="Create">Create New</a>
</p>
<table class="table">
<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)
{
string selectedRow = "";
if (item.ID == (int?)ViewData["InstructorID"])
{
selectedRow = "success";
}
<tr class="@selectedRow">
<td>
@Html.DisplayFor(modelItem => item.LastName)
</td>
<td>
@Html.DisplayFor(modelItem => item.FirstMidName)
</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-action="Index" asp-route-id="@item.ID">Select</a> |
<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>

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.)

@if (item.OfficeAssignment != null)

{
@item.OfficeAssignment.Location
}

Added a Courses column that displays courses taught by each instructor. For more information, see the
Explicit line transition with @: section of the Razor syntax article.
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.

string selectedRow = "";

if (item.ID == (int?)ViewData["InstructorID"])
{
selectedRow = "success";
}
<tr class="@selectedRow">

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.

<a asp-action="Index" asp-route-id="@item.ID">Select</a> |

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>
<table class="table">
<tr>
<th></th>
<th>Number</th>
<th>Title</th>
<th>Department</th>
</tr>

@foreach (var item in Model.Courses)

{
string selectedRow = "";
if (item.CourseID == (int?)ViewData["CourseID"])
{
selectedRow = "success";
}
<tr class="@selectedRow">
<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>
<table class="table">
<tr>
<th>Name</th>
<th>Grade</th>
</tr>
@foreach (var item in Model.Enrollments)
{
<tr>
<td>
@item.Student.FullName
</td>
<td>
@Html.DisplayFor(modelItem => item.Grade)
</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.

About 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();
viewModel.Instructors = await _context.Instructors
.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.ThenInclude(i => i.Department)
.OrderBy(i => i.LastName)
.ToListAsync();

if (id != null)
{
ViewData["InstructorID"] = id.Value;
Instructor instructor = viewModel.Instructors.Where(
i => i.ID == id.Value).Single();
viewModel.Courses = instructor.CourseAssignments.Select(s => s.Course);
}

if (courseID != null)
{
ViewData["CourseID"] = courseID.Value;
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;
}

return View(viewModel);
}

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.

Get the code

Download or view the completed application.

Next steps
In this tutorial, you:
Learned how to load related data
Created a Courses page
Created an Instructors page
Learned about explicit loading
Advance to the next tutorial to learn how to update related data.
Update related data
 Tutorial: Update related data - ASP.NET MVC with EF
Core
4/26/2019 • 18 minutes to read • Edit Online

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.
In this tutorial, you:
Customize Courses pages
Add Instructors Edit page
Add courses to Edit page
Update Delete page
Add office location and courses to Create page

Prerequisites
Read related data

Customize Courses pages

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:
public IActionResult Create()
{
PopulateDepartmentsDropDownList();
return View();
}

[HttpPost]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Create([Bind("CourseID,Credits,DepartmentID,Title")] Course course)
{
if (ModelState.IsValid)
{
_context.Add(course);
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}
PopulateDepartmentsDropDownList(course.DepartmentID);
return View(course);
}

public async Task<IActionResult> Edit(int? id)

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

var course = await _context.Courses

.AsNoTracking()
.FirstOrDefaultAsync(m => m.CourseID == id);
if (course == null)
{
return NotFound();
}
PopulateDepartmentsDropDownList(course.DepartmentID);
return View(course);
}
 [HttpPost, ActionName("Edit")]
[ValidateAntiForgeryToken]
public async Task<IActionResult> EditPost(int? id)
{
if (id == null)
{
return NotFound();
}

var courseToUpdate = await _context.Courses

.FirstOrDefaultAsync(c => c.CourseID == id);

if (await TryUpdateModelAsync<Course>(courseToUpdate,
"",
c => c.Credits, c => c.DepartmentID, c => c.Title))
{
try
{
await _context.SaveChangesAsync();
}
catch (DbUpdateException /* ex */)
{
//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.");
}
return RedirectToAction(nameof(Index));
}
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:

public IActionResult Create()

{
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:

public async Task<IActionResult> Edit(int? id)

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

var course = await _context.Courses

.AsNoTracking()
.FirstOrDefaultAsync(m => m.CourseID == id);
if (course == null)
{
return NotFound();
}
PopulateDepartmentsDropDownList(course.DepartmentID);
return View(course);
}

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.

public async Task<IActionResult> Details(int? id)

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

var course = await _context.Courses

.Include(c => c.Department)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.CourseID == id);
if (course == null)
{
return NotFound();
}

return View(course);
}
 public async Task<IActionResult> Delete(int? id)
{
if (id == null)
{
return NotFound();
}

var course = await _context.Courses

.Include(c => c.Department)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.CourseID == id);
if (course == null)
{
return NotFound();
}

return View(course);
}

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.

<div class="form-group">
<label asp-for="Department" class="control-label"></label>
<select asp-for="DepartmentID" class="form-control" asp-items="ViewBag.DepartmentID">
<option value="">-- Select Department --</option>
</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.

<div class="form-group">
<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

@{
ViewData["Title"] = "Delete";
}

<h2>Delete</h2>

<h3>Are you sure you want to delete this?</h3>

<div>
<h4>Course</h4>
<hr />
<dl class="row">
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.CourseID)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.CourseID)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Title)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Title)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Credits)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Credits)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Department)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Department.Name)
</dd>
</dl>

<form asp-action="Delete">
<div class="form-actions no-color">
<input type="submit" value="Delete" class="btn btn-default" /> |
<a asp-action="Index">Back to List</a>
</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 Instructors Edit page

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 :
 public async Task<IActionResult> Edit(int? id)
{
if (id == null)
{
return NotFound();
}

var instructor = await _context.Instructors

.Include(i => i.OfficeAssignment)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.ID == id);
if (instructor == null)
{
return NotFound();
}
return View(instructor);
}

Replace the HttpPost Edit method with the following code to handle office assignment updates:

[HttpPost, ActionName("Edit")]
[ValidateAntiForgeryToken]
public async Task<IActionResult> EditPost(int? id)
{
if (id == null)
{
return NotFound();
}

var instructorToUpdate = await _context.Instructors

.Include(i => i.OfficeAssignment)
.FirstOrDefaultAsync(s => s.ID == id);

if (await TryUpdateModelAsync<Instructor>(
instructorToUpdate,
"",
i => i.FirstMidName, i => i.LastName, i => i.HireDate, i => i.OfficeAssignment))
{
if (String.IsNullOrWhiteSpace(instructorToUpdate.OfficeAssignment?.Location))
{
instructorToUpdate.OfficeAssignment = null;
}
try
{
await _context.SaveChangesAsync();
}
catch (DbUpdateException /* ex */)
{
//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.");
}
return RedirectToAction(nameof(Index));
}
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.

if (await TryUpdateModelAsync<Instructor>(
instructorToUpdate,
"",
i => i.FirstMidName, i => i.LastName, i => i.HireDate, i => i.OfficeAssignment))

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.

if (String.IsNullOrWhiteSpace(instructorToUpdate.OfficeAssignment?.Location))
{
instructorToUpdate.OfficeAssignment = null;
}

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:

<div class="form-group">
<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 courses to 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.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace ContosoUniversity.Models.SchoolViewModels
{
public class AssignedCourseData
{
public int CourseID { get; set; }
public string Title { get; set; }
public bool Assigned { get; set; }
}
}

In InstructorsController.cs, replace the HttpGet Edit method with the following code. The changes are
highlighted.

public async Task<IActionResult> Edit(int? id)

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

var instructor = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments).ThenInclude(i => i.Course)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.ID == id);
if (instructor == null)
{
return NotFound();
}
PopulateAssignedCourseData(instructor);
return View(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]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Edit(int? id, string[] selectedCourses)
{
if (id == null)
{
return NotFound();
}

var instructorToUpdate = await _context.Instructors

.Include(i => i.OfficeAssignment)
.Include(i => i.CourseAssignments)
.ThenInclude(i => i.Course)
.FirstOrDefaultAsync(m => m.ID == id);

if (await TryUpdateModelAsync<Instructor>(
instructorToUpdate,
"",
i => i.FirstMidName, i => i.LastName, i => i.HireDate, i => i.OfficeAssignment))
{
if (String.IsNullOrWhiteSpace(instructorToUpdate.OfficeAssignment?.Location))
{
instructorToUpdate.OfficeAssignment = null;
}
UpdateInstructorCourses(selectedCourses, instructorToUpdate);
try
{
await _context.SaveChangesAsync();
}
catch (DbUpdateException /* ex */)
{
//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.");
}
return RedirectToAction(nameof(Index));
}
UpdateInstructorCourses(selectedCourses, instructorToUpdate);
PopulateAssignedCourseData(instructorToUpdate);
return View(instructorToUpdate);
}
 private void UpdateInstructorCourses(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.FirstOrDefault(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:
 private void UpdateInstructorCourses(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.FirstOrDefault(i =>
i.CourseID == course.CourseID);
_context.Remove(courseToRemove);
}
}
}
}

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.
 private void UpdateInstructorCourses(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.FirstOrDefault(i =>
i.CourseID == course.CourseID);
_context.Remove(courseToRemove);
}
}
}
}

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.
 private void UpdateInstructorCourses(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.FirstOrDefault(i =>
i.CourseID == course.CourseID);
_context.Remove(courseToRemove);
}
}
}
}

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 might be changed in a way that breaks the code. If the code looks
different after pasting, 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. This problem is fixed in Visual Studio 2019.
 <div class="form-group">
<div class="col-md-offset-2 col-md-10">
<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>
<input type="checkbox"
name="selectedCourses"
value="@course.CourseID"
@(Html.Raw(course.Assigned ? "checked=\"checked\"" : "")) />
@course.CourseID @: @course.Title
@:</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.

Update Delete page

In InstructorsController.cs, delete the DeleteConfirmed method and insert the following code in its place.
 [HttpPost, ActionName("Delete")]
[ValidateAntiForgeryToken]
public async Task<IActionResult> DeleteConfirmed(int id)
{
Instructor instructor = await _context.Instructors
.Include(i => i.CourseAssignments)
.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);

await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}

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 Create page

In InstructorsController.cs, delete the HttpGet and HttpPost Create methods, and then add the following code in
their place:
 public IActionResult Create()
{
var instructor = new Instructor();
instructor.CourseAssignments = new List<CourseAssignment>();
PopulateAssignedCourseData(instructor);
return View();
}

// POST: Instructors/Create
[HttpPost]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Create([Bind("FirstMidName,HireDate,LastName,OfficeAssignment")] Instructor
instructor, string[] selectedCourses)
{
if (selectedCourses != null)
{
instructor.CourseAssignments = new List<CourseAssignment>();
foreach (var course in selectedCourses)
{
var courseToAdd = new CourseAssignment { InstructorID = instructor.ID, CourseID =
int.Parse(course) };
instructor.CourseAssignments.Add(courseToAdd);
}
}
if (ModelState.IsValid)
{
_context.Add(instructor);
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}
PopulateAssignedCourseData(instructor);
return View(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:

instructor.CourseAssignments = new List<CourseAssignment>();

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.

<div class="form-group">
<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>

<div class="form-group">
<div class="col-md-offset-2 col-md-10">
<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>
<input type="checkbox"
name="selectedCourses"
value="@course.CourseID"
@(Html.Raw(course.Assigned ? "checked=\"checked\"" : "")) />
@course.CourseID @: @course.Title
@:</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.
Get the code
Download or view the completed application.

Next steps
In this tutorial, you:
Customized Courses pages
Added Instructors Edit page
Added courses to Edit page
Updated Delete page
Added office location and courses to Create page
Advance to the next tutorial to learn how to handle concurrency conflicts.
Handle concurrency conflicts
 Tutorial: Handle concurrency - ASP.NET MVC with EF
Core
6/17/2019 • 18 minutes to read • Edit Online

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.
In this tutorial, you:
Learn about concurrency conflicts
Add a tracking property
Create Departments controller and views
Update Index view
Update Edit methods
Update Edit view
Test concurrency conflicts
Update the Delete page
Update Details and Create views

Prerequisites
Update related data

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

In Models/Department.cs, add a tracking property named RowVersion:

using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Department
{
public int DepartmentID { get; set; }

[StringLength(50, MinimumLength = 3)]

public string Name { get; set; }

[DataType(DataType.Currency)]
[Column(TypeName = "money")]
public decimal Budget { get; set; }

[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Start Date")]
public DateTime StartDate { get; set; }

public int? InstructorID { get; set; }

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

public Instructor Administrator { get; set; }

public ICollection<Course> Courses { 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:

modelBuilder.Entity<Department>()
.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

dotnet ef database update

Create 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 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>
<a asp-action="Create">Create New</a>
</p>
<table class="table">
<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>
@foreach (var item in Model)
{
<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>
<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 Edit methods

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
.Include(i => i.Administrator)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.DepartmentID == id);

Replace the existing code for the HttpPost Edit method with the following code:

[HttpPost]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Edit(int? id, byte[] rowVersion)
{
if (id == null)
{
return NotFound();
}

var departmentToUpdate = await _context.Departments.Include(i => i.Administrator).FirstOrDefaultAsync(m

=> m.DepartmentID == id);

if (departmentToUpdate == null)
{
Department deletedDepartment = new Department();
await TryUpdateModelAsync(deletedDepartment);
ModelState.AddModelError(string.Empty,
"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;

if (await TryUpdateModelAsync<Department>(
departmentToUpdate,
"",
s => s.Name, s => s.StartDate, s => s.Budget, s => s.InstructorID))
{
try
{
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}
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 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.FirstOrDefaultAsync(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 "
+ "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. 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 FirstOrDefaultAsync 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.

var exceptionEntry = ex.Entries.Single();

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.

var clientValues = (Department)exceptionEntry.Entity;

var databaseEntry = exceptionEntry.GetDatabaseValues();

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 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

@{
ViewData["Title"] = "Edit";
}

<h2>Edit</h2>

<h4>Department</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form asp-action="Edit">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<input type="hidden" asp-for="DepartmentID" />
<input type="hidden" asp-for="RowVersion" />
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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 class="form-group">
<input type="submit" value="Save" class="btn btn-default" />
</div>
</form>
</div>
</div>

<div>
<a asp-action="Index">Back to List</a>
</div>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

Test concurrency conflicts

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.

Update the Delete page

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();
}

var department = await _context.Departments

.Include(d => d.Administrator)
.AsNoTracking()
.FirstOrDefaultAsync(m => m.DepartmentID == id);
if (department == null)
{
if (concurrencyError.GetValueOrDefault())
{
return RedirectToAction(nameof(Index));
}
return NotFound();
}

if (concurrencyError.GetValueOrDefault())
{
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]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Delete(Department department)
{
try
{
if (await _context.Departments.AnyAsync(m => m.DepartmentID == department.DepartmentID))
{
_context.Departments.Remove(department);
await _context.SaveChangesAsync();
}
return RedirectToAction(nameof(Index));
}
catch (DbUpdateConcurrencyException /* ex */)
{
//Log the error (uncomment ex variable name and write a log.)
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:
 public async Task<IActionResult> DeleteConfirmed(int 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.
 @model ContosoUniversity.Models.Department

@{
ViewData["Title"] = "Delete";
}

<h2>Delete</h2>

<p class="text-danger">@ViewData["ConcurrencyErrorMessage"]</p>

<h3>Are you sure you want to delete this?</h3>

<div>
<h4>Department</h4>
<hr />
<dl class="row">
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Name)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Name)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Budget)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Budget)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.StartDate)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.StartDate)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Administrator)
</dt>
<dd class="col-sm-10">
@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 class="form-actions no-color">
<input type="submit" value="Delete" class="btn btn-default" /> |
<a asp-action="Index">Back to List</a>
</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.
 @model ContosoUniversity.Models.Department

@{
ViewData["Title"] = "Details";
}

<h2>Details</h2>

<div>
<h4>Department</h4>
<hr />
<dl class="row">
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Name)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Name)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Budget)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Budget)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.StartDate)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.StartDate)
</dd>
<dt class="col-sm-2">
@Html.DisplayNameFor(model => model.Administrator)
</dt>
<dd class="col-sm-10">
@Html.DisplayFor(model => model.Administrator.FullName)
</dd>
</dl>
</div>
<div>
<a asp-action="Edit" asp-route-id="@Model.DepartmentID">Edit</a> |
<a asp-action="Index">Back to List</a>
</div>

Replace the code in Views/Departments/Create.cshtml to add a Select option to the drop-down list.
 @model ContosoUniversity.Models.Department

@{
ViewData["Title"] = "Create";
}

<h2>Create</h2>

<h4>Department</h4>
<hr />
<div class="row">
<div class="col-md-4">
<form asp-action="Create">
<div asp-validation-summary="ModelOnly" class="text-danger"></div>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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>
<div class="form-group">
<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 class="form-group">
<input type="submit" value="Create" class="btn btn-default" />
</div>
</form>
</div>
</div>

<div>
<a asp-action="Index">Back to List</a>
</div>

@section Scripts {
@{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
}

Get the code

Download or view the completed application.

Additional resources
For more information about how to handle concurrency in EF Core, see Concurrency conflicts.

Next steps
In this tutorial, you:
Learned about concurrency conflicts
 Added a tracking property
Created Departments controller and views
Updated Index view
Updated Edit methods
Updated Edit view
Tested concurrency conflicts
Updated the Delete page
Updated Details and Create views
Advance to the next tutorial to learn how to implement table-per-hierarchy inheritance for the Instructor and
Student entities.
Next: Implement table-per-hierarchy inheritance
 Tutorial: Implement inheritance - ASP.NET MVC with
EF Core
4/26/2019 • 8 minutes to read • Edit Online

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.
In this tutorial, you:
Map inheritance to database
Create the Person class
Update Instructor and Student
Add Person to the model
Create and update migrations
Test the implementation

Prerequisites
Handle Concurrency

Map inheritance to database

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:

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public abstract class Person
{
public int ID { get; set; }

[Required]
[StringLength(50)]
[Display(Name = "Last Name")]
public string LastName { get; set; }
[Required]
[StringLength(50, ErrorMessage = "First name cannot be longer than 50 characters.")]
[Column("FirstName")]
[Display(Name = "First Name")]
public string FirstMidName { get; set; }

[Display(Name = "Full Name")]

public string FullName
{
get
{
return LastName + ", " + FirstMidName;
}
}
}
}

Update Instructor and Student

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;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Instructor : Person
{
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Hire Date")]
public DateTime HireDate { get; set; }

public ICollection<CourseAssignment> CourseAssignments { get; set; }

public OfficeAssignment OfficeAssignment { get; set; }
}
}

Make the same changes in Student.cs.

using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace ContosoUniversity.Models
{
public class Student : Person
{
[DataType(DataType.Date)]
[DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
[Display(Name = "Enrollment Date")]
public DateTime EnrollmentDate { get; set; }

public ICollection<Enrollment> Enrollments { get; set; }

}
}

Add Person to the model

Add the Person entity type to SchoolContext.cs. The new lines are highlighted.
 using ContosoUniversity.Models;
using Microsoft.EntityFrameworkCore;

namespace ContosoUniversity.Data
{
public class SchoolContext : DbContext
{
public SchoolContext(DbContextOptions<SchoolContext> options) : base(options)
{
}

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

public DbSet<Enrollment> Enrollments { get; set; }
public DbSet<Student> Students { 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; }
public DbSet<Person> People { 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<Person>().ToTable("Person");

modelBuilder.Entity<CourseAssignment>()
.HasKey(c => new { c.CourseID, c.InstructorID });
}
}
}

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 update migrations

Save your changes and build the project. Then open the command window in the project folder and enter the
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:
 protected override void Up(MigrationBuilder migrationBuilder)
{
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");

migrationBuilder.DropTable(
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",
principalColumn: "ID",
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:

dotnet ef database update

(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 the implementation

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.
Get the code
Download or view the completed application.

Additional resources
For more information about inheritance in Entity Framework Core, see Inheritance.

Next steps
In this tutorial, you:
Mapped inheritance to database
Created the Person class
Updated Instructor and Student
Added Person to the model
Created and update migrations
Tested the implementation
Advance to the next tutorial to learn how to handle a variety of relatively advanced Entity Framework scenarios.
Next: Advanced topics
 Tutorial: Learn about advanced scenarios - ASP.NET
MVC with EF Core
8/13/2019 • 13 minutes to read • Edit Online

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.
In this tutorial, you:
Perform raw SQL queries
Call a query to return entities
Call a query to return other types
Call an update query
Examine SQL queries
Create an abstraction layer
Learn about Automatic change detection
Learn about EF Core source code and development plans
Learn how to use dynamic LINQ to simplify code

Prerequisites
Implement Inheritance

Perform 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 to return entities

The DbSet<TEntity> class provides a method that you can use to execute a query that returns an entity of type
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:

public async Task<IActionResult> Details(int? id)

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

string query = "SELECT * FROM Department WHERE DepartmentID = {0}";

var department = await _context.Departments
.FromSql(query, id)
.Include(d => d.Administrator)
.AsNoTracking()
.FirstOrDefaultAsync();

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 to return 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 CoursesController.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 Core under Installed in the left pane, click Razor View, 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">
<div class="form-actions no-color">
<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 queries

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.

Create an abstraction layer

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;

EF 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 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.
 public async Task<IActionResult> Index(
string sortOrder,
string currentFilter,
string searchString,
int? pageNumber)
{
ViewData["CurrentSort"] = sortOrder;
ViewData["NameSortParm"] =
String.IsNullOrEmpty(sortOrder) ? "LastName_desc" : "";
ViewData["DateSortParm"] =
sortOrder == "EnrollmentDate" ? "EnrollmentDate_desc" : "EnrollmentDate";

if (searchString != null)
{
pageNumber = 1;
}
else
{
searchString = currentFilter;
}

ViewData["CurrentFilter"] = searchString;

var students = from s in _context.Students

select s;

if (!String.IsNullOrEmpty(searchString))
{
students = students.Where(s => s.LastName.Contains(searchString)
|| s.FirstMidName.Contains(searchString));
}

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(),
pageNumber ?? 1, pageSize));
}

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. John Parente and Paul Goldman worked on updating the tutorial for
ASP.NET Core 2.2.
Troubleshoot 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:

dotnet ef database drop

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.

Get the code

Download or view the completed application.
Additional resources
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 ASP.NET Core.
For information about other topics related to ASP.NET Core MVC, such as authentication and authorization, see
Introduction to ASP.NET Core.

Next steps
In this tutorial, you:
Performed raw SQL queries
Called a query to return entities
Called a query to return other types
Called an update query
Examined SQL queries
Created an abstraction layer
Learned about Automatic change detection
Learned about EF Core source code and development plans
Learned how to use dynamic LINQ to simplify code
This completes this series of tutorials on using the Entity Framework Core in an ASP.NET Core MVC application.
This series worked with a new database; an alternative is to reverse engineer a model from an existing database.
Tutorial: EF Core with MVC, existing database
 Get Started with ASP.NET Core and Entity Framework
6
4/26/2019 • 3 minutes to read • Edit Online

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 class SchoolContext : DbContext

{
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.

public void ConfigureServices(IServiceCollection services)

{
// Add framework services.
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

{
private readonly SchoolContext _context;

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.

Additional resources
Entity Framework - Code-Based Configuration
 Host and deploy ASP.NET Core
5/21/2019 • 3 minutes to read • Edit Online

In general, to deploy an ASP.NET Core app to a hosting environment:

Deploy the published 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.
For configuration of a reverse proxy, set up a reverse proxy to forward requests to the app.

Publish to a folder
The dotnet publish command compiles app code and copies the files required to run the app into a publish
folder. When deploying from Visual Studio, the dotnet publish step occurs automatically before the files are
copied to the deployment destination.
Folder contents
The publish folder contains one or more app assembly files, dependencies, and optionally the .NET runtime.
A .NET Core app can be published as self-contained deployment or framework-dependent deployment. If the
app is self-contained, the assembly 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 ASP.NET Core 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

If the app uses the Kestrel 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.
Either configuration—with or without a reverse proxy server—is a supported hosting configuration. For more
information, see When to use Kestrel with a reverse proxy.

Proxy server and load balancer scenarios

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.

Use Visual Studio and MSBuild to automate deployments

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 Visual Studio publish profiles for ASP.NET Core app deployment 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. For
more information, see DevOps with ASP.NET Core and Azure.

Publish to Azure
See Publish an ASP.NET Core app to Azure with Visual Studio for instructions on how to publish an app to
Azure using Visual Studio. An additional example is provided by Create an ASP.NET Core web app in Azure.

Publish with MSDeploy on Windows

See Visual Studio publish profiles for ASP.NET Core app deployment for instructions on how to publish an app
with a Visual Studio publish profile, including from a Windows command prompt using the dotnet msbuild
command.

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.

Perform health checks

Use Health Check Middleware to perform health checks on an app and its dependencies. For more information,
see Health checks in ASP.NET Core.

Additional resources
Host ASP.NET Core in Docker containers
Troubleshoot ASP.NET Core projects
 Deploy ASP.NET Core apps to Azure App Service
7/29/2019 • 10 minutes to read • Edit Online

Azure App Service is a Microsoft cloud computing platform service for hosting web apps, including ASP.NET
Core.

Useful resources
App Service 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:
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.
Create an ASP.NET Core 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 an ASP.NET Core app to Azure with Visual Studio
Learn how to publish an ASP.NET Core app to Azure App Service using Visual Studio.
Continuous deployment to Azure with Visual Studio and Git with ASP.NET Core
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.
Create your first pipeline
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.
Troubleshoot ASP.NET Core projects
Understand and troubleshoot warnings and errors with ASP.NET Core projects.

Application configuration
Platform
Runtimes for 64-bit (x64) and 32-bit (x86) apps are present on Azure App Service. The .NET Core SDK available
on App Service is 32-bit, but you can deploy 64-bit apps built locally using the Kudu console or the publish
process in Visual Studio. For more information, see the Publish and deploy the app section.
For apps with native dependencies, runtimes for 32-bit (x86) apps are present on Azure App Service. The .NET
Core SDK available on App Service is 32-bit.
For more information on .NET Core framework components and distribution methods, such as information on
the .NET Core runtime and the .NET Core SDK, see About .NET Core: Composition.
Packages
Include the following NuGet packages to 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.
The preceding packages aren't available from the Microsoft.AspNetCore.App metapackage. Apps that target .NET
Framework or reference the Microsoft.AspNetCore.App metapackage must explicitly reference the individual
packages in the app's project file.

Override app configuration using the Azure Portal

App settings in the Azure Portal permit you to set environment variables for the app. Environment variables can
be consumed by the Environment Variables Configuration Provider.
When an app setting is created or modified in the Azure Portal and the Save button is selected, the Azure App is
restarted. The environment variable is available to the app after the service restarts.
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.
When an app 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.

Proxy server and load balancer scenarios

The IIS Integration Middleware, which configures Forwarded Headers Middleware when hosting out-of-process,
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

ASP.NET Core apps deployed to App Service automatically receive an App Service extension, ASP.NET Core
Logging Integration. The extension enables logging integration for ASP.NET Core apps on Azure App Service.
ASP.NET Core apps deployed to App Service automatically receive an App Service extension, ASP.NET Core
Logging Extensions. The extension enables logging integration for ASP.NET Core apps on Azure App Service.
For monitoring, logging, and troubleshooting information, see the following articles:
Monitor apps in Azure App Service
Learn how to review quotas and metrics for apps and App Service plans.
Enable diagnostics logging for apps in Azure App Service
Discover how to enable and access diagnostic logging for HTTP status codes, failed requests, and web server
activity.
Handle errors in ASP.NET Core
Understand common approaches to handling errors in ASP.NET Core apps.
Troubleshoot ASP.NET Core on Azure App Service and IIS
Learn how to diagnose issues with Azure App Service deployments with ASP.NET Core apps.
Common errors reference for Azure App Service and IIS with ASP.NET Core
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 in ASP.NET Core.

Deploy ASP.NET Core preview release to Azure App Service

Use one of the following approaches if the app relies on a preview release of .NET Core:
Install the preview site extension.
Deploy a self-contained preview app.
Use Docker with Web Apps for containers.
Install the preview site extension
If a problem occurs using the preview site extension, open an aspnet/AspNetCore issue.
1. From the Azure Portal, navigate to the App Service.
2. Select the web app.
3. Type "ex" in the search box to filter for "Extensions" or scroll down the list of management tools.
4. Select Extensions.
5. Select Add.
6. Select the ASP.NET Core {X.Y } ({x64|x86}) Runtime extension from the list, where {X.Y} is the ASP.NET
Core preview version and {x64|x86} specifies the platform.
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.
2. Select Go in Advanced Tools.
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} and the platform for {PLATFORM} in the command:
 Test-Path D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.{PLATFORM}\

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 app's settings in the Azure Portal 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.
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\

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'))]"
]
}

Deploy a self-contained preview app

A self-contained deployment (SCD ) that targets a preview runtime carries the preview runtime in the deployment.
When deploying a self-contained app:
The site in Azure App Service doesn't require the preview site extension.
The app must be published following a different approach than when publishing for a framework-dependent
deployment (FDD ).
Follow the guidance in the Deploy the app self-contained section.
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.

Publish and deploy the app

Deploy the app framework-dependent
For a 64-bit framework-dependent deployment:
Use a 64-bit .NET Core SDK to build a 64-bit app.
Set the Platform to 64 Bit in the App Service's Configuration > General settings. The app must use a
Basic or higher service plan to enable the choice of platform bitness.
Visual Studio
.NET Core CLI
1. Select Build > Publish {Application Name} from the Visual Studio toolbar or right-click the project in
Solution Explorer and select Publish.
2. In the Pick a publish target dialog, confirm that App Service is selected.
3. Select Advanced. The Publish dialog opens.
4. In the Publish dialog:
Confirm that the Release configuration is selected.
Open the Deployment Mode drop-down list and select Framework-Dependent.
Select Portable as the Target Runtime.
If you need to remove additional files upon deployment, open File Publish Options and select the
check box to remove additional files at the destination.
Select Save.
5. Create a new site or update an existing site by following the remaining prompts of the publish wizard.
Deploy the app self-contained
Use Visual Studio or the command-line interface (CLI) tools for a self-contained deployment (SCD ).
Visual Studio
.NET Core CLI
1. Select Build > Publish {Application Name} from the Visual Studio toolbar or right-click the project in
Solution Explorer and select Publish.
2. In the Pick a publish target dialog, confirm that App Service is selected.
3. Select Advanced. The Publish dialog opens.
4. In the Publish dialog:
Confirm that the Release configuration is selected.
Open the Deployment Mode drop-down list and select Self-Contained.
Select the target runtime from the Target Runtime drop-down list. The default is win-x86 .
If you need to remove additional files upon deployment, open File Publish Options and select the
check box to remove additional files at the destination.
Select Save.
5. Create a new site or update an existing site by following the remaining prompts of the publish wizard.

Protocol settings (HTTPS)

Secure protocol bindings allow you specify a certificate to use when responding to requests over HTTPS. Binding
requires a valid private certificate (.pfx) issued for the specific hostname. For more information, see Tutorial: Bind
an existing custom SSL certificate to Azure App Service.
Transform web.config
If you need to transform web.config on publish (for example, set environment variables based on the
configuration, profile, or environment), see Transform web.config.

Additional resources
App Service overview
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
Host ASP.NET Core in a web farm
Azure App Service on Windows Server uses Internet Information Services (IIS ). The following topics pertain to
the underlying IIS technology:
Host ASP.NET Core on Windows with IIS
ASP.NET Core Module
IIS modules with ASP.NET Core
Windows Server - IT administrator content for current and previous releases
 Publish an ASP.NET Core app to Azure with Visual
Studio
7/18/2019 • 3 minutes to read • Edit Online

By Rick Anderson

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 and
IIS.

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...

Complete the New Project dialog:

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 Additional 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 publishes 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
@{
ViewData["Title"] = "About";
}
<h2>@ViewData["Title"]</h2>
<h3>@Model.Message</h3>

<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 with ASP.NET Core

Additional resources
For Visual Studio Code, see Publish profiles.
Azure App Service
Azure resource groups
Azure SQL Database
Visual Studio publish profiles for ASP.NET Core app deployment
Troubleshoot ASP.NET Core on Azure App Service and IIS
 Continuous deployment to Azure with Visual Studio
and Git with ASP.NET Core
4/26/2019 • 6 minutes to read • Edit Online

By Erik Reitan

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.

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
.NET Core SDK 2.0 or later
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

Additional resources
Create your first pipeline with Azure Pipelines
Project Kudu
Visual Studio publish profiles for ASP.NET Core app deployment
 ASP.NET Core Module
7/1/2019 • 20 minutes to read • Edit Online

By Tom Dykstra, Rick Strahl, Chris Ross, Rick Anderson, Sourabh Shirhatti, Justin Kotalik, and Luke Latham
The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to either:
Host an ASP.NET Core app inside of the IIS worker process ( w3wp.exe ), called the in-process hosting model.
Forward web requests to a backend ASP.NET Core app running the Kestrel server, called the out-of-process
hosting model.
Supported Windows versions:
Windows 7 or later
Windows Server 2008 R2 or later
When hosting in-process, the module uses an in-process server implementation for IIS, called IIS HTTP Server (
IISHttpServer ).

When hosting out-of-process, the module only works with Kestrel. The module is incompatible with HTTP.sys.

Hosting models
In-process hosting model
To configure an app for in-process hosting, add the <AspNetCoreHostingModel> property to the app's project file with
a value of InProcess (out-of-process hosting is set with OutOfProcess ):

<PropertyGroup>
<AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
</PropertyGroup>

The in-process hosting model isn't supported for ASP.NET Core apps that target the .NET Framework.
If the <AspNetCoreHostingModel> property isn't present in the file, the default value is OutOfProcess .
The following characteristics apply when hosting in-process:
IIS HTTP Server ( IISHttpServer ) is used instead of Kestrel server. For in-process, CreateDefaultBuilder calls
UseIIS to:
Register the IISHttpServer .
Configure the port and base path the server should listen on when running behind the ASP.NET Core
Module.
Configure the host to capture startup errors.
The requestTimeout attribute doesn't apply to in-process hosting.
Sharing an app pool among apps isn't supported. Use one app pool per app.
When using Web Deploy or manually placing an app_offline.htm file in the deployment, the app might not
shut down immediately if there's an open connection. For example, a websocket connection may delay app
shut down.
The architecture (bitness) of the app and installed runtime (x64 or x86) must match the architecture of the
 app pool.
If setting up the app's host manually with WebHostBuilder (not using CreateDefaultBuilder) and the app is
ever run directly on the Kestrel server (self-hosted), call UseKestrel before calling UseIISIntegration . If the
order is reversed, the host fails to start.
Client disconnects are detected. The HttpContext.RequestAborted cancellation token is cancelled when the
client disconnects.
In ASP.NET Core 2.2.1 or earlier, GetCurrentDirectory returns the worker directory of the process started by
IIS rather than the app's directory (for example, C:\Windows\System32\inetsrv for w3wp.exe).
For sample code that sets the app's current directory, see the CurrentDirectoryHelpers class. Call the
SetCurrentDirectory method. Subsequent calls to GetCurrentDirectory provide the app's directory.

When hosting in-process, AuthenticateAsync isn't called internally to initialize a user. Therefore, an
IClaimsTransformation implementation used to transform claims after every authentication isn't activated by
default. When transforming claims with an IClaimsTransformation implementation, call AddAuthentication
to add authentication services:

public void ConfigureServices(IServiceCollection services)

{
services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
}

public void Configure(IApplicationBuilder app)

{
app.UseAuthentication();
}

Out-of-process hosting model

To configure an app for out-of-process hosting, use either of the following approaches in the project file:
Don't specify the <AspNetCoreHostingModel> property. If the <AspNetCoreHostingModel> property isn't present in
the file, the default value is OutOfProcess .
Set the value of the <AspNetCoreHostingModel> property to OutOfProcess (in-process hosting is set with
InProcess ):

<PropertyGroup>
<AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>

Kestrel server is used instead of IIS HTTP Server ( IISHttpServer ).

For out-of-process, CreateDefaultBuilder calls UseIISIntegration to:
Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
Configure the host to capture startup errors.
When hosting out-of-process, AuthenticateAsync isn't called internally to initialize a user. Therefore, an
IClaimsTransformation implementation used to transform claims after every authentication isn't activated by
default. When transforming claims with an IClaimsTransformation implementation, call AddAuthentication to add
authentication services:
 public void ConfigureServices(IServiceCollection services)
{
services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
services.AddAuthentication(IISDefaults.AuthenticationScheme);
}

public void Configure(IApplicationBuilder app)

{
app.UseAuthentication();
}

Hosting model changes

If the hostingModel setting is changed in the web.config file (explained in the Configuration with web.config
section), the module recycles the worker process for IIS.
For IIS Express, the module doesn't recycle the worker process but instead triggers a graceful shutdown of the
current IIS Express process. The next request to the app spawns a new IIS Express process.
Process name
Process.GetCurrentProcess().ProcessName reports w3wp / iisexpress (in-process) or dotnet (out-of-process).
The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to forward web requests to
backend ASP.NET Core apps.
Supported Windows versions:
Windows 7 or later
Windows Server 2008 R2 or later
The module only works with Kestrel. The module is incompatible with HTTP.sys.
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 an app:

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 or 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 the 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. Middleware added by IIS Integration updates the scheme, remote IP, and pathbase to account for forwarding
the request to Kestrel. The app's response is passed back to IIS, which pushes it back out to the HTTP client that
initiated the request.
Many native modules, such as Windows Authentication, remain active. To learn more about IIS modules active with
the ASP.NET Core Module, see IIS modules with ASP.NET Core.
The ASP.NET Core Module can also:
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 instructions on how to install the ASP.NET Core Module, see Install the .NET Core Hosting Bundle.

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:

<?xml version="1.0" encoding="utf-8"?>

<configuration>
<location path="." inheritInChildApplications="false">
<system.webServer>
<handlers>
<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
</handlers>
<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile=".\logs\stdout"
hostingModel="InProcess" />
</system.webServer>
</location>
</configuration>

<?xml version="1.0" encoding="utf-8"?>

<configuration>
<system.webServer>
<handlers>
<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
</handlers>
<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile=".\logs\stdout" />
</system.webServer>
</configuration>

The following web.config is published for a self-contained deployment:

 <?xml version="1.0" encoding="utf-8"?>
<configuration>
<location path="." inheritInChildApplications="false">
<system.webServer>
<handlers>
<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
</handlers>
<aspNetCore processPath=".\MyApp.exe"
stdoutLogEnabled="false"
stdoutLogFile=".\logs\stdout"
hostingModel="InProcess" />
</system.webServer>
</location>
</configuration>

The InheritInChildApplications property is set to false to indicate that the settings specified within the <location>
element aren't inherited by apps that reside in a subdirectory of the app.

<?xml version="1.0" encoding="utf-8"?>

<configuration>
<system.webServer>
<handlers>
<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
</handlers>
<aspNetCore processPath=".\MyApp.exe"
stdoutLogEnabled="false"
stdoutLogFile=".\logs\stdout" />
</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.
For information on IIS sub-application configuration, see Host ASP.NET Core on Windows with IIS.
Attributes of the aspNetCore element
ATTRIBUTE DESCRIPTION DEFAULT

arguments Optional string attribute.

Arguments to the executable
specified in processPath.

disableStartUpErrorPage Optional Boolean attribute. false

If true, the 502.5 - Process Failure

page is suppressed, and the 502
status code page configured in the
web.config takes precedence.
ATTRIBUTE DESCRIPTION DEFAULT

forwardWindowsAuthToken Optional Boolean attribute. 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.

hostingModel Optional string attribute. OutOfProcess

Specifies the hosting model as in-

process ( InProcess ) or out-of-
process ( OutOfProcess ).

processesPerApplication Optional integer attribute. Default: 1

Min: 1
Specifies the number of instances of Max: 100 †
the process specified in the
processPath setting that can be
spun up per app.
†For in-process hosting, the value is
limited to 1 .
Setting processesPerApplication
is discouraged. This attribute will be
removed in a future release.

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. Default: 10

Min: 0
Specifies the number of times the Max: 100
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.
Not supported with in-process
hosting.
ATTRIBUTE DESCRIPTION DEFAULT

requestTimeout Optional timespan attribute. Default: 00:02:00

Min: 00:00:00
Specifies the duration for which the Max: 360:00:00
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.
Doesn't apply to in-process hosting.
For in-process hosting, the module
waits for the app to process the
request.
Valid values for minutes and
seconds segments of the string are
in the range 0-59. Use of 60 in the
value for minutes or seconds results
in a 500 - Internal Server Error.

shutdownTimeLimit Optional integer attribute. Default: 10

Min: 0
Duration in seconds that the Max: 600
module waits for the executable to
gracefully shutdown when the
app_offline.htm file is detected.

startupTimeLimit Optional integer attribute. Default: 120

Min: 0
Duration in seconds that the Max: 3600
module waits for the executable to
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.
A value of 0 (zero) is not considered
an infinite timeout.

stdoutLogEnabled Optional Boolean attribute. false

If true, stdout and stderr for the

process specified in processPath
are redirected to the file specified in
stdoutLogFile.
ATTRIBUTE DESCRIPTION DEFAULT

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 are
created by the module when the log
file is created. 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.log
in the logs folder when saved on
2/5/2018 at 19:41:32 with a
process ID of 1934.

ATTRIBUTE DESCRIPTION DEFAULT

arguments Optional string attribute.

Arguments to the executable
specified in processPath.

disableStartUpErrorPage Optional Boolean attribute. 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 Optional Boolean attribute. 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.
ATTRIBUTE DESCRIPTION DEFAULT

processesPerApplication Optional integer attribute. Default: 1

Min: 1
Specifies the number of instances of Max: 100
the process specified in the
processPath setting that can be
spun up per app.
Setting processesPerApplication
is discouraged. This attribute will be
removed in a future release.

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. Default: 10

Min: 0
Specifies the number of times the Max: 100
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. Default: 00:02:00

Min: 00:00:00
Specifies the duration for which the Max: 360:00:00
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. Default: 10

Min: 0
Duration in seconds that the Max: 600
module waits for the executable to
gracefully shutdown when the
app_offline.htm file is detected.
 ATTRIBUTE DESCRIPTION DEFAULT

startupTimeLimit Optional integer attribute. Default: 120

Min: 0
Duration in seconds that the Max: 3600
module waits for the executable to
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.
A value of 0 (zero) is not considered
an infinite timeout.

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.log
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.
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.
 WARNING
Environment variables set in this section conflict with system environment variables set with the same name. If an
environment variable is set in both the web.config file and at the system level in Windows, the value from the web.config file
becomes appended to the system environment variable value (for example,
ASPNETCORE_ENVIRONMENT: Development;Development ), which prevents the app from starting.

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.

<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile="\\?\%home%\LogFiles\stdout"
hostingModel="InProcess">
<environmentVariables>
<environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
<environmentVariable name="CONFIG_DIR" value="f:\application_config" />
</environmentVariables>
</aspNetCore>

<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile="\\?\%home%\LogFiles\stdout">
<environmentVariables>
<environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
<environmentVariable name="CONFIG_DIR" value="f:\application_config" />
</environmentVariables>
</aspNetCore>

NOTE
An alternative to setting the environment directly in web.config is to include the <EnvironmentName> property in the publish
profile (.pubxml) or project file. This approach sets the environment in web.config when the project is published:

<PropertyGroup>
<EnvironmentName>Development</EnvironmentName>
</PropertyGroup>

WARNING
Only set the ASPNETCORE_ENVIRONMENT environment 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.
When using the out-of-process hosting model, the app might not shut down immediately if there's an open
connection. For example, a websocket connection may delay app shut down.

Start-up error page

Both in-process and out-of-process hosting produce custom error pages when they fail to start the app.
If the ASP.NET Core Module fails to find either the in-process or out-of-process request handler, a 500.0 - In-
Process/Out-Of-Process Handler Load Failure status code page appears.
For in-process hosting if the ASP.NET Core Module fails to start the app, a 500.30 - Start Failure status code page
appears.
For out-of-process hosting 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 5xx status code page, use the disableStartUpErrorPage attribute.
For more information on configuring custom error messages, see HTTP Errors <httpErrors>.
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 are created by
the module when the log file is created. 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.
If stdoutLogEnabled is false, errors that occur on app startup are captured and emitted to the event log up to 30 KB.
After startup, all additional logs are discarded.
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.

<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="true"
stdoutLogFile="\\?\%home%\LogFiles\stdout"
hostingModel="InProcess">
</aspNetCore>

<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="true"
stdoutLogFile="\\?\%home%\LogFiles\stdout">
</aspNetCore>

Enhanced diagnostic logs

The ASP.NET Core Module is configurable to provide enhanced diagnostics logs. Add the <handlerSettings>
element to the <aspNetCore> element in web.config. Setting the debugLevel to TRACE exposes a higher fidelity of
diagnostic information:

<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile="\\?\%home%\LogFiles\stdout"
hostingModel="InProcess">
<handlerSettings>
<handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
<handlerSetting name="debugLevel" value="FILE,TRACE" />
</handlerSettings>
</aspNetCore>

Any folders in the path (logs in the preceding example) are created by the module when the log file is created. 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).
Folders in the path provided to the <handlerSetting> value (logs in the preceding example) aren't created by the
module automatically and should pre-exist in the deployment. 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).
Debug level ( debugLevel ) values can include both the level and the location.
Levels (in order from least to most verbose):
ERROR
WARNING
INFO
TRACE
Locations (multiple locations are permitted):
CONSOLE
EVENTLOG
FILE
The handler settings can also be provided via environment variables:
ASPNETCORE_MODULE_DEBUG_FILE – Path to the debug log file. (Default: aspnetcore-debug.log)
ASPNETCORE_MODULE_DEBUG – Debug level setting.

WARNING
Do not leave debug logging enabled in the deployment for longer than required to troubleshoot an issue. The size of the log
isn't limited. Leaving the debug log enabled can exhaust the available disk space and crash the server or app service.

See Configuration with web.config for an example of the aspNetCore element in the web.config file.

Modify the stack size

Configure the managed stack size using the stackSize setting in bytes. The default size is 1048576 bytes (1 MB ).

<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile="\\?\%home%\LogFiles\stdout"
hostingModel="InProcess">
<handlerSettings>
<handlerSetting name="stackSize" value="2097152" />
</handlerSettings>
</aspNetCore>

Proxy configuration uses HTTP protocol and a pairing token

Only applies to out-of-process hosting.
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 ( MS-ASPNETCORE-TOKEN ) 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 TrustedInstaller account. Because the local
system account doesn't have modify permission for the share path used by the IIS Shared Configuration, the
installer throws an access denied error when attempting to configure the module settings in the
applicationHost.config file on the share.
When using an IIS Shared Configuration on the same machine as the IIS installation, run the ASP.NET Core
Hosting Bundle installer with the OPT_NO_SHARED_CONFIG_CHECK parameter set to 1 :

dotnet-hosting-{VERSION}.exe OPT_NO_SHARED_CONFIG_CHECK=1

When the path to the shared configuration isn't on the same machine as the IIS installation, 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.
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
%ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll
%ProgramFiles(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll
IIS Express (x86/amd64):
%ProgramFiles%\IIS Express\aspnetcore.dll
%ProgramFiles(x86)%\IIS Express\aspnetcore.dll
 %ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll
%ProgramFiles(x86)%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll
Schema
IIS
%windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml
%windir%\System32\inetsrv\config\schema\aspnetcore_schema_v2.xml
IIS Express
%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml
%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema_v2.xml
Configuration
IIS
%windir%\System32\inetsrv\config\applicationHost.config
IIS Express
Visual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.config
iisexpress.exe CLI: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config
The files can be found by searching for aspnetcore in the applicationHost.config file.

Additional resources
Host ASP.NET Core on Windows with IIS
ASP.NET Core Module GitHub repository (reference source)
IIS modules with ASP.NET Core
 Troubleshoot ASP.NET Core on Azure App Service
and IIS
7/24/2019 • 23 minutes to read • Edit Online

By Luke Latham and Justin Kotalik

This article provides information on common app startup errors and instructions on how to diagnose errors when
an app is deployed to Azure App Service or IIS:
App startup errors
Explains common startup HTTP status code scenarios.
Troubleshoot on Azure App Service
Provides troubleshooting advice for apps deployed to Azure App Service.
Troubleshoot on IIS
Provides troubleshooting advice for apps deployed to IIS or running on IIS Express locally. The guidance applies to
both Windows Server and Windows desktop deployments.
Clear package caches
Explains what to do when incoherent packages break an app when performing major upgrades or changing
package versions.
Additional resources
Lists additional troubleshooting topics.

App startup errors

In Visual Studio, an ASP.NET Core project defaults to IIS Express hosting during debugging. A 502.5 - Process
Failure or a 500.30 - Start Failure that occurs when debugging locally can be diagnosed using the advice in this
topic.
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 diagnosed using the advice in this topic.
403.14 Forbidden
The app fails to start. The following error is logged:

The Web server is configured to not list the contents of this directory.

The error is usually caused by a broken deployment on the hosting system, which includes any of the following
scenarios:
The app is deployed to the wrong folder on the hosting system.
The deployment process failed to move all of the app's files and folders to the deployment folder on the hosting
system.
The web.config file is missing from the deployment, or the web.config file contents are malformed.
Perform the following steps:
1. Delete all of the files and folders from the deployment folder on the hosting system.
2. Redeploy the contents of the app's publish folder to the hosting system using your normal method of
 deployment, such as Visual Studio, PowerShell, or manual deployment:
Confirm that the web.config file is present in the deployment and that its contents are correct.
When hosting on Azure App Service, confirm that the app is deployed to the D:\home\site\wwwroot folder.
When the app is hosted by IIS, confirm that the app is deployed to the IIS Physical path shown in IIS
Manager's Basic Settings.
3. Confirm that all of the app's files and folders are deployed by comparing the deployment on the hosting system
to the contents of the project's publish folder.
For more information on the layout of a published ASP.NET Core app, see ASP.NET Core directory structure. For
more information on the web.config file, see ASP.NET Core Module.
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.
500.0 In-Process Handler Load Failure
The worker process fails. The app doesn't start.
The ASP.NET Core Module fails to find the .NET Core CLR and find the in-process request handler
(aspnetcorev2_inprocess.dll). Check that:
The app targets either the Microsoft.AspNetCore.Server.IIS NuGet package or the Microsoft.AspNetCore.App
metapackage.
The version of the ASP.NET Core shared framework that the app targets is installed on the target machine.
500.0 Out-Of-Process Handler Load Failure
The worker process fails. The app doesn't start.
The ASP.NET Core Module fails to find the out-of-process hosting request handler. Make sure the
aspnetcorev2_outofprocess.dll is present in a subfolder next to aspnetcorev2.dll.
500.0 In-Process Handler Load Failure
The worker process fails. The app doesn't start.
An unknown error occurred loading ASP.NET Core Module components. Take one of the following actions:
Contact Microsoft Support (select Developer Tools then ASP.NET Core).
Ask a question on Stack Overflow.
File an issue on our GitHub repository.
500.30 In-Process Startup Failure
The worker process fails. The app doesn't start.
The ASP.NET Core Module attempts to start the .NET Core CLR in-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.
A common failure condition is the app is misconfigured due to targeting a version of the ASP.NET Core shared
framework that isn't present. Check which versions of the ASP.NET Core shared framework are installed on the
target machine.
500.31 ANCM Failed to Find Native Dependencies
The worker process fails. The app doesn't start.
The ASP.NET Core Module attempts to start the .NET Core runtime in-process, but it fails to start. The most
common cause of this startup failure is when the Microsoft.NETCore.App or Microsoft.AspNetCore.App runtime isn't
installed. If the app is deployed to target ASP.NET Core 3.0 and that version doesn't exist on the machine, this error
occurs. An example error message follows:

The specified framework 'Microsoft.NETCore.App', version '3.0.0' was not found.

- The following frameworks were found:
2.2.1 at [C:\Program Files\dotnet\x64\shared\Microsoft.NETCore.App]
3.0.0-preview5-27626-15 at [C:\Program Files\dotnet\x64\shared\Microsoft.NETCore.App]
3.0.0-preview6-27713-13 at [C:\Program Files\dotnet\x64\shared\Microsoft.NETCore.App]
3.0.0-preview6-27714-15 at [C:\Program Files\dotnet\x64\shared\Microsoft.NETCore.App]
3.0.0-preview6-27723-08 at [C:\Program Files\dotnet\x64\shared\Microsoft.NETCore.App]

The error message lists all the installed .NET Core versions and the version requested by the app. To fix this error,
either:
Install the appropriate version of .NET Core on the machine.
Change the app to target a version of .NET Core that's present on the machine.
Publish the app as a self-contained deployment.
When running in development (the ASPNETCORE_ENVIRONMENT environment variable is set to Development ), the
specific error is written to the HTTP response. The cause of a process startup failure is also found in the Application
Event Log.
500.32 ANCM Failed to Load dll
The worker process fails. The app doesn't start.
The most common cause for this error is that the app is published for an incompatible processor architecture. If the
worker process is running as a 32-bit app and the app was published to target 64-bit, this error occurs.
To fix this error, either:
Republish the app for the same processor architecture as the worker process.
Publish the app as a framework-dependent deployment.
500.33 ANCM Request Handler Load Failure
The worker process fails. The app doesn't start.
The app didn't reference the Microsoft.AspNetCore.App framework. Only apps targeting the
Microsoft.AspNetCore.App framework can be hosted by the ASP.NET Core Module.

To fix this error, confirm that the app is targeting the Microsoft.AspNetCore.App framework. Check the
.runtimeconfig.json to verify the framework targeted by the app.

500.34 ANCM Mixed Hosting Models Not Supported

The worker process can't run both an in-process app and an out-of-process app in the same process.
To fix this error, run apps in separate IIS application pools.
500.35 ANCM Multiple In-Process Applications in same Process
The worker process can't run both an in-process app and an out-of-process app in the same process.
To fix this error, run apps in separate IIS application pools.
500.36 ANCM Out-Of-Process Handler Load Failure
The out-of-process request handler, aspnetcorev2_outofprocess.dll, isn't next to the aspnetcorev2.dll file. This
indicates a corrupted installation of the ASP.NET Core Module.
To fix this error, repair the installation of the .NET Core Hosting Bundle (for IIS ) or Visual Studio (for IIS Express).
500.37 ANCM Failed to Start Within Startup Time Limit
ANCM failed to start within the provied startup time limit. By default, the timeout is 120 seconds.
This error can occur when starting a large number of apps on the same machine. Check for CPU/Memory usage
spikes on the server during startup. You may need to stagger the startup process of multiple apps.
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.
A common failure condition is the app is misconfigured due to targeting a version of the ASP.NET Core shared
framework that isn't present. Check which versions of the ASP.NET Core shared framework are installed on the
target machine. The shared framework is the set of assemblies (.dll files) that are installed on the machine and
referenced by a metapackage such as Microsoft.AspNetCore.App . The metapackage reference can specify a
minimum required version. For more information, see The shared framework.
The 502.5 Process Failure error page is returned when a hosting or app misconfiguration causes the worker
process to fail:
Failed to start application (ErrorCode '0x800700c1')

EventID: 1010
Source: IIS AspNetCore Module V2
Failed to start application '/LM/W3SVC/6/ROOT/', ErrorCode '0x800700c1'.

The app failed to start because the app's assembly (.dll) couldn't be loaded.
This error occurs when there's a bitness mismatch between the published app and the w3wp/iisexpress process.
Confirm that the app pool's 32-bit setting is correct:
1. Select the app pool in IIS Manager's Application Pools.
2. Select Advanced Settings under Edit Application Pool in the Actions panel.
3. Set Enable 32-Bit Applications:
If deploying a 32-bit (x86) app, set the value to True .
If deploying a 64-bit (x64) app, set the value to False .
Confirm that there isn't a conflict between a <Platform> MSBuild property in the project file and the published
bitness of the app.
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 on Azure App Service
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.

Application Event Log (Azure App Service )

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 in App Services.
2. Select Diagnose and solve problems.
3. Select the Diagnostic Tools heading.
4. Under Support Tools, select the Application Events button.
5. Examine the latest error provided by the IIS AspNetCoreModule or IIS AspNetCoreModule V2 entry 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. Open Advanced Tools 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. Open Advanced Tools 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.
Test a 32-bit (x86) app
Current release
1. cd d:\home\site\wwwroot
2. Run the app:
If the app is a framework-dependent deployment:

dotnet .\{ASSEMBLY NAME}.dll

If the app is a self-contained deployment:

{ASSEMBLY NAME}.exe

The console output from the app, showing any errors, is piped to the Kudu console.
Framework-dependent deployment running on a preview release
 Requires installing the ASP.NET Core {VERSION } (x86 ) Runtime site extension.
1. cd D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.x32 ( {X.Y} is the runtime version)
2. Run the app: dotnet \home\site\wwwroot\{ASSEMBLY NAME}.dll
The console output from the app, showing any errors, is piped to the Kudu console.
Test a 64-bit (x64) app
Current release
If the app is a 64-bit (x64) framework-dependent deployment:
1. cd D:\Program Files\dotnet
2. Run the app: dotnet \home\site\wwwroot\{ASSEMBLY NAME}.dll
If the app is a self-contained deployment:
1. cd D:\home\site\wwwroot
2. Run the app: {ASSEMBLY NAME}.exe

The console output from the app, showing any errors, is piped to the Kudu console.
Framework-dependent deployment running on a preview release
Requires installing the ASP.NET Core {VERSION } (x64 ) Runtime site extension.
1. cd D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.x64 ( {X.Y} is the runtime version)
2. Run the app: dotnet \home\site\wwwroot\{ASSEMBLY NAME}.dll

The console output from the app, showing any errors, is piped to the Kudu console.
ASP.NET Core Module stdout log (Azure App Service )
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.
10. Using the navigation bar at the top of the page, open Debug console and select CMD.
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.
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.
For more information, see ASP.NET Core Module.

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.

ASP.NET Core Module debug log (Azure App Service )

The ASP.NET Core Module debug log provides additional, deeper logging from the ASP.NET Core Module. To
enable and view stdout logs:
1. To enable the enhanced diagnostic log, perform either of the following:
Follow the instructions in Enhanced diagnostic logs to configure the app for an enhanced diagnostic
logging. Redeploy the app.
Add the <handlerSettings> shown in Enhanced diagnostic logs to the live app's web.config file using the
Kudu console:
a. Open Advanced Tools in the Development Tools area. Select the Go→ button. The Kudu
console opens in a new browser tab or window.
b. Using the navigation bar at the top of the page, open Debug console and select CMD.
c. Open the folders to the path site > wwwroot. Edit the web.config file by selecting the pencil
button. Add the <handlerSettings> section as shown in Enhanced diagnostic logs. Select the Save
button.
2. Open Advanced Tools in the Development Tools area. Select the Go→ button. The Kudu console opens in a
new browser tab or window.
3. Using the navigation bar at the top of the page, open Debug console and select CMD.
4. Open the folders to the path site > wwwroot. If you didn't supply a path for the aspnetcore-debug.log file, the
file appears in the list. If you supplied a path, navigate to the location of the log file.
5. Open the log file with the pencil button next to the file name.
Disable debug logging when troubleshooting is complete:
To disable the enhanced debug log, perform either of the following:
Remove the <handlerSettings> from the web.config file locally and redeploy the app.
Use the Kudu console to edit the web.config file and remove the <handlerSettings> section. Save the file.

For more information, see ASP.NET Core Module.

WARNING
Failure to disable the debug log can lead to app or server failure. There's no limit on log file size. Only use debug 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.

Slow or hanging app (Azure App Service )

When an app responds slowly or hangs on a request, see the following articles:
 Troubleshoot slow web app performance issues in Azure App Service
Use Crash Diagnoser Site Extension to Capture Dump for Intermittent Exception issues or performance issues
on Azure Web App
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.
2. Using the navigation bar at the top of the page, open Debug console and select CMD.
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.
5. Make a request to the app.
6. Within the log stream data, the cause of the error is indicated.
Be sure to disable stdout logging when troubleshooting is complete.
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
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.
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 on IIS
Application Event Log (IIS )
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 hosting 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 hosting configuration and less likely within
the app.
ASP.NET Core Module stdout log (IIS )
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.
6. Make a request to the app.
7. Navigate to the logs folder. Find and open the most recent stdout log.
8. Study the log for errors.
Disable stdout logging when troubleshooting is complete:
1. Edit the web.config file.
2. Set stdoutLogEnabled to false .
3. Save the file.
For more information, see ASP.NET Core Module.

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.
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.

ASP.NET Core Module debug log (IIS )

Add the following handler settings to the app's web.config file to enable ASP.NET Core Module debug log:

<aspNetCore ...>
<handlerSettings>
<handlerSetting name="debugLevel" value="file" />
<handlerSetting name="debugFile" value="c:\temp\ancm.log" />
</handlerSettings>
</aspNetCore>

Confirm that the path specified for the log exists and that the app pool's identity has write permissions to the
location.
For more information, see ASP.NET Core Module.
Enable 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.

<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile=".\logs\stdout"
hostingModel="InProcess">
<environmentVariables>
<environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
</environmentVariables>
</aspNetCore>
 <aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
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.
Obtain data from an app
If an app is capable of responding to requests, obtain request, connection, and additional data from the app using
terminal inline middleware. For more information and sample code, see Troubleshoot ASP.NET Core projects.
Slow or hanging app (IIS )
A crash dump is a snapshot of the system's memory and can help determine the cause of an app crash, startup
failure, or slow app.
App crashes or encounters an exception
Obtain and analyze a dump from Windows Error Reporting (WER ):
1. Create a folder to hold crash dump files at c:\dumps . The app pool must have write access to the folder.
2. Run the EnableDumps PowerShell script:
If the app uses the in-process hosting model, run the script for w3wp.exe:

.\EnableDumps w3wp.exe c:\dumps

If the app uses the out-of-process hosting model, run the script for dotnet.exe:

.\EnableDumps dotnet.exe c:\dumps

3. Run the app under the conditions that cause the crash to occur.
4. After the crash has occurred, run the DisableDumps PowerShell script:
If the app uses the in-process hosting model, run the script for w3wp.exe:

.\DisableDumps w3wp.exe

If the app uses the out-of-process hosting model, run the script for dotnet.exe:

.\DisableDumps dotnet.exe

After an app crashes and dump collection is complete, the app is allowed to terminate normally. The PowerShell
script configures WER to collect up to five dumps per app.
 WARNING
Crash dumps might take up a large amount of disk space (up to several gigabytes each).

App hangs, fails during startup, or runs normally

When an app hangs (stops responding but doesn't crash), fails during startup, or runs normally, see User-Mode
Dump Files: Choosing the Best Tool to select an appropriate tool to produce the dump.
Analyze the dump
A dump can be analyzed using several approaches. For more information, see Analyzing a User-Mode Dump File.

Clear package caches

Sometimes a functioning app fails immediately after upgrading either the .NET Core SDK on the development
machine or changing 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 by executing dotnet nuget locals all --clear from a command shell.
Clearing package caches can also be accomplished with 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.
3. Restore and rebuild the project.
4. Delete all of the files in the deployment folder on the server prior to redeploying the app.

Additional resources
Troubleshoot ASP.NET Core projects
Common errors reference for Azure App Service and IIS with ASP.NET Core
Handle errors in ASP.NET Core
ASP.NET Core Module
Azure documentation
Application Insights for ASP.NET Core
Remote debugging web apps section of Troubleshoot a web app in Azure App Service using Visual Studio
Azure App Service diagnostics overview
How to: Monitor Apps in Azure App Service
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)
Visual Studio documentation
Remote Debug ASP.NET Core on IIS in Azure in Visual Studio 2017
Remote Debug ASP.NET Core on a Remote IIS Computer in Visual Studio 2017
Learn to debug using Visual Studio
Visual Studio Code documentation
Debugging with Visual Studio Code
 Common errors reference for Azure App Service and
IIS with ASP.NET Core
7/18/2019 • 14 minutes to read • Edit Online

By Luke Latham
This topic offers troubleshooting advice for common errors when hosting ASP.NET Core apps on Azure Apps
Service and IIS.
Collect the following information:
Browser behavior (status code and error message)
Application Event Log entries
Azure App Service – See Troubleshoot ASP.NET Core on Azure App Service and IIS.
IIS
1. Select Start on the Windows menu, type Event Viewer, and press Enter.
2. After the Event Viewer opens, expand Windows Logs > Application in the sidebar.
ASP.NET Core Module stdout and debug log entries
Azure App Service – See Troubleshoot ASP.NET Core on Azure App Service and IIS.
IIS – Follow the instructions in the Log creation and redirection and Enhanced diagnostic logs sections of
the ASP.NET Core Module topic.
Compare error information to the following common errors. If a match is found, follow the troubleshooting advice.
The list of errors in this topic isn't exhaustive. If you encounter an error not listed here, open a new issue using the
Content feedback button at the bottom of this topic with detailed instructions on how to reproduce the error.

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.

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 .NET Core 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 or Apps & features. If a specific runtime is required, download the runtime
from the .NET Download Archives and install it on the system. 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 app pool 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.

Missing site extension, 32-bit (x86) and 64-bit (x64) site extensions
installed, or wrong process bitness set
Applies to apps hosted by Azure App Services.
Browser: HTTP Error 500.0 - ANCM In-Process Handler Load Failure
Application Log: Invoking hostfxr to find the inprocess request handler failed without finding any native
dependencies. Could not find inprocess request handler. Captured output from invoking hostfxr: It was not
possible to find any compatible framework version. The specified framework 'Microsoft.AspNetCore.App',
version '{VERSION }-preview -*' was not found. Failed to start application
'/LM/W3SVC/1416782824/ROOT', ErrorCode '0x8000ffff'.
ASP.NET Core Module stdout Log: It was not possible to find any compatible framework version. The
specified framework 'Microsoft.AspNetCore.App', version '{VERSION }-preview -*' was not found.
ASP.NET Core Module Debug Log: Invoking hostfxr to find the inprocess request handler failed without
finding any native dependencies. This most likely means the app is misconfigured, please check the versions of
Microsoft.NetCore.App and Microsoft.AspNetCore.App that are targeted by the application and are installed on
the machine. Failed HRESULT returned: 0x8000ffff. Could not find inprocess request handler. It was not possible
to find any compatible framework version. The specified framework 'Microsoft.AspNetCore.App', version
'{VERSION }-preview -*' was not found.
Troubleshooting:
If running the app on a preview runtime, install either the 32-bit (x86) or 64-bit (x64) site extension that
matches the bitness of the app and the app's runtime version. Don't install both extensions or multiple
runtime versions of the extension.
ASP.NET Core {RUNTIME VERSION } (x86) Runtime
ASP.NET Core {RUNTIME VERSION } (x64) Runtime
Restart the app. Wait several seconds for the app to restart.
If running the app on a preview runtime and both the 32-bit (x86) and 64-bit (x64) site extensions are
installed, uninstall the site extension that doesn't match the bitness of the app. After removing the site
extension, restart the app. Wait several seconds for the app to restart.
If running the app on a preview runtime and the site extension's bitness matches that of the app, confirm that
the preview site extension's runtime version matches the app's runtime version.
Confirm that the app's Platform in Application Settings matches the bitness of the app.
For more information, see Deploy ASP.NET Core apps to Azure App Service.
An x86 app is deployed but the app pool isn't enabled for 32-bit apps
Browser: HTTP Error 500.30 - ANCM In-Process Start Failure
Application Log: Application '/LM/W3SVC/5/ROOT' with physical root '{PATH}' hit unexpected managed
exception, exception code = '0xe0434352'. Please check the stderr logs for more information. Application
'/LM/W3SVC/5/ROOT' with physical root '{PATH}' failed to load clr and managed application. CLR worker
thread exited prematurely
ASP.NET Core Module stdout Log: The log file is created but empty.
ASP.NET Core Module Debug Log: Failed HRESULT returned: 0x8007023e
This scenario is trapped by the SDK when publishing a self-contained app. The SDK produces an error if the RID
doesn't match the platform target (for example, win10-x64 RID with <PlatformTarget>x86</PlatformTarget> in the
project file).
Troubleshooting:
For an x86 framework-dependent deployment ( <PlatformTarget>x86</PlatformTarget> ), enable the IIS app pool for
32-bit apps. In IIS Manager, open the app pool's Advanced Settings and set Enable 32-Bit Applications to
True.

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 stdout 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 Troubleshoot ASP.NET Core on Azure App Service and IIS.
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 --OR-- Unable to connect
Application Log: No entry
ASP.NET Core Module stdout Log: The log file isn't created.
ASP.NET Core Module Debug Log: The log file isn't created.
Troubleshooting:
Confirm the correct URI endpoint for the app is in use. 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.
Application Log: No entry
ASP.NET Core Module stdout Log: The log file isn't created.
ASP.NET Core Module Debug Log: The log file isn't created.
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, ASP.NET Core 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. --OR-- This page can't be displayed
Application Log: No entry
ASP.NET Core Module stdout Log: The log file isn't created.
ASP.NET Core Module Debug Log: The log file isn't created.
Troubleshooting:
Confirm that the proper role is enabled. See IIS Configuration.
Open Programs & Features or Apps & features and confirm that Windows Server Hosting is installed.
If Windows Server Hosting isn't present in the list of installed programs, download and install the .NET
Core Hosting Bundle.
Current .NET Core Hosting Bundle installer (direct download)
For more information, 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.
If you uninstalled the ASP.NET Core Hosting Bundle and installed an earlier version of the hosting bundle,
the applicationHost.config file doesn't include a section for the ASP.NET Core Module. Open
applicationHost.config at %windir%/System32/inetsrv/config and find the
<configuration><configSections><sectionGroup name="system.webServer"> section group. If the section for the
ASP.NET Core Module is missing from the section group, add the section element:
 <section name="aspNetCore" overrideModeDefault="Allow" />

Alternatively, install the latest version of the ASP.NET Core Hosting Bundle. The latest version is backwards-
compatible with supported ASP.NET Core apps.

Incorrect processPath, missing PATH variable, Hosting Bundle not

installed, system/IIS not restarted, VC++ Redistributable not installed,
or dotnet.exe access violation
Browser: HTTP Error 500.0 - ANCM In-Process Handler Load Failure
Application Log: Application 'MACHINE/WEBROOT/APPHOST/{ASSEMBLY }' with physical root 'C:
{PATH}' failed to start process with commandline '"{...}" ', ErrorCode = '0x80070002 : 0. Application '{PATH}'
wasn't able to start. Executable was not found at '{PATH}'. Failed to start application '/LM/W3SVC/2/ROOT',
ErrorCode '0x8007023e'.
ASP.NET Core Module stdout Log: The log file isn't created.
ASP.NET Core Module Debug Log: Event Log: 'Application '{PATH}' wasn't able to start. Executable was
not found at '{PATH}'. Failed HRESULT returned: 0x8007023e
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 '"{...}" ', ErrorCode = '0x80070002 : 0.
ASP.NET Core Module stdout Log: The log file is created but empty.
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 Troubleshoot ASP.NET Core on Azure App Service and IIS.
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 app pool. Confirm that the app
pool user identity has access to the C:\Program Files\dotnet directory. Confirm that there are no deny rules
configured for the app pool 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.
Current .NET Core Hosting Bundle installer (direct download)
For more information, see Install the .NET Core Hosting Bundle.
If a specific runtime is required, download the runtime from the .NET Download Archives and install it on
the system. 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

Browser: HTTP Error 500.0 - ANCM In-Process Handler Load Failure
Application Log: Invoking hostfxr to find the inprocess request handler failed without finding any native
dependencies. This most likely means the app is misconfigured, please check the versions of
Microsoft.NetCore.App and Microsoft.AspNetCore.App that are targeted by the application and are installed
on the machine. Could not find inprocess request handler. Captured output from invoking hostfxr: Did you
mean to run dotnet SDK commands? Please install dotnet SDK from: https://go.microsoft.com/fwlink/?
LinkID=798306&clcid=0x409 Failed to start application '/LM/W3SVC/3/ROOT', ErrorCode '0x8000ffff'.
ASP.NET Core Module stdout Log: Did you mean to run dotnet SDK commands? Please install dotnet
SDK from: https://go.microsoft.com/fwlink/?LinkID=798306&clcid=0x409
ASP.NET Core Module Debug Log: Invoking hostfxr to find the inprocess request handler failed without
finding any native dependencies. This most likely means the app is misconfigured, please check the versions
of Microsoft.NetCore.App and Microsoft.AspNetCore.App that are targeted by the application and are
installed on the machine. Failed HRESULT returned: 0x8000ffff Could not find inprocess request handler.
Captured output from invoking hostfxr: Did you mean to run dotnet SDK commands? Please install dotnet
SDK from: https://go.microsoft.com/fwlink/?LinkID=798306&clcid=0x409 Failed HRESULT returned:
0x8000ffff
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 '"dotnet" .{ASSEMBLY }.dll', ErrorCode = '0x80004005 :
80008081.
ASP.NET Core Module stdout Log: The application to execute does not exist: 'PATH{ASSEMBLY }.dll'
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 Troubleshoot ASP.NET Core on Azure App Service and IIS.
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="{ARGUMENT_1}, {ARGUMENT_2}, ... {ARGUMENT_X}" )
for a self-contained deployment (SCD ).

Missing .NET Core shared framework

Browser: HTTP Error 500.0 - ANCM In-Process Handler Load Failure
Application Log: Invoking hostfxr to find the inprocess request handler failed without finding any native
dependencies. This most likely means the app is misconfigured, please check the versions of
Microsoft.NetCore.App and Microsoft.AspNetCore.App that are targeted by the application and are installed
on the machine. Could not find inprocess request handler. Captured output from invoking hostfxr: It was not
possible to find any compatible framework version. The specified framework 'Microsoft.AspNetCore.App',
version '{VERSION }' was not found.
Failed to start application '/LM/W3SVC/5/ROOT', ErrorCode '0x8000ffff'.
ASP.NET Core Module stdout Log: It was not possible to find any compatible framework version. The
specified framework 'Microsoft.AspNetCore.App', version '{VERSION }' was not found.
 ASP.NET Core Module Debug Log: Failed HRESULT returned: 0x8000ffff
Troubleshooting:
For a framework-dependent deployment (FDD ), confirm that the correct runtime installed on the system.

Stopped Application Pool

Browser: 503 Service Unavailable
Application Log: No entry
ASP.NET Core Module stdout Log: The log file isn't created.
ASP.NET Core Module Debug Log: The log file isn't created.
Troubleshooting:
Confirm that the Application Pool isn't in the Stopped state.

Sub-application includes a <handlers> section

Browser: HTTP Error 500.19 - Internal Server Error
Application Log: No entry
ASP.NET Core Module stdout Log: The root app's log file is created and shows normal operation. The
sub-app's log file isn't created.
ASP.NET Core Module Debug Log: The root app's log file is created and shows normal operation. The sub-
app's log file isn't created.
Troubleshooting:
Confirm that the sub-app's web.config file doesn't include a <handlers> section or that the sub-app doesn't inherit
the parent app's handlers.
The parent app's <system.webServer> section of web.config is placed inside of a <location> element. The
InheritInChildApplications property is set to false to indicate that the settings specified within the <location>
element aren't inherited by apps that reside in a subdirectory of the parent app. For more information, see
ASP.NET Core Module.
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: Could not start stdout redirection in C:\Program Files\IIS\Asp.Net Core
Module\V2\aspnetcorev2.dll. Exception message: HRESULT 0x80070005 returned at
{PATH}\aspnetcoremodulev2\commonlib\fileoutputmanager.cpp:84. Could not stop stdout redirection in
C:\Program Files\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll. Exception message: HRESULT
0x80070002 returned at {PATH}. Could not start stdout redirection in {PATH}\aspnetcorev2_inprocess.dll.
ASP.NET Core Module stdout Log: The log file isn't created.
ASP.NET Core Module debug Log: Could not start stdout redirection in C:\Program Files\IIS\Asp.Net
Core Module\V2\aspnetcorev2.dll. Exception message: HRESULT 0x80070005 returned at
{PATH}\aspnetcoremodulev2\commonlib\fileoutputmanager.cpp:84. Could not stop stdout redirection in
 C:\Program Files\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll. Exception message: HRESULT
0x80070002 returned at {PATH}. Could not start stdout redirection in {PATH}\aspnetcorev2_inprocess.dll.
Application Log: Warning: Could not create stdoutLogFile \?{PATH}\path_doesnt_exist\stdout_{PROCESS
ID }_{TIMESTAMP }.log, ErrorCode = -2147024893.
ASP.NET Core Module stdout Log: The log file isn't created.
Troubleshooting:
The stdoutLogFile path specified in the <aspNetCore> element of web.config doesn't exist. For more
information, see ASP.NET Core Module: Log creation and redirection.
The app pool user doesn't have write access to the stdout log path.

Application configuration general issue

Browser: HTTP Error 500.0 - ANCM In-Process Handler Load Failure --OR-- HTTP Error 500.30 - ANCM
In-Process Start Failure
Application Log: Variable
ASP.NET Core Module stdout Log: The log file is created but empty or created with normal entries until
the point of the app failing.
ASP.NET Core Module Debug Log: Variable
Browser: HTTP Error 502.5 - Process Failure
Application Log: Application 'MACHINE/WEBROOT/APPHOST/{ASSEMBLY }' with physical root 'C:
{PATH}' created process with commandline '"C:{PATH}{ASSEMBLY }.{exe|dll}" ' but either crashed or did not
respond or did not listen on the given port '{PORT}', ErrorCode = '{ERROR CODE }'
ASP.NET Core Module stdout Log: The log file is created but empty.
Troubleshooting:
The process failed to start, most likely due to an app configuration or programming issue.
For more information, see the following topics:
Troubleshoot ASP.NET Core on Azure App Service and IIS
Troubleshoot ASP.NET Core projects
 DevOps with ASP.NET Core and Azure
4/26/2019 • 2 minutes to read • Edit Online

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.
Continuous integration and deployment
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
4/26/2019 • 2 minutes to read • Edit Online

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:
ASP.NET and web development
Azure development
.NET Core cross-platform development
 Deploy an app to App Service
4/26/2019 • 7 minutes to read • Edit Online

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
 Continuous integration and deployment
4/26/2019 • 10 minutes to read • Edit Online

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 Center. 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 Center. 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 check box 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
7/18/2019 • 4 minutes to read • Edit Online

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
Troubleshoot ASP.NET Core on Azure App Service and IIS
Common errors reference for Azure App Service and IIS with ASP.NET Core
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
4/26/2019 • 2 minutes to read • Edit Online

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.
 Host ASP.NET Core on Windows with IIS
8/9/2019 • 30 minutes to read • Edit Online

By Luke Latham
For a tutorial experience on publishing an ASP.NET Core app to an IIS server, see Publish an ASP.NET Core
app to IIS.
Install the .NET Core Hosting Bundle

Supported operating systems

The following operating systems are supported:
Windows 7 or later
Windows Server 2008 R2 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 Deploy ASP.NET Core apps to Azure App Service.
For troubleshooting guidance, see Troubleshoot ASP.NET Core projects.

Supported platforms
Apps published for 32-bit (x86) or 64-bit (x64) deployment are supported. Deploy a 32-bit app with a 32-bit
(x86) .NET Core SDK unless the app:
Requires the larger virtual memory address space available to a 64-bit app.
Requires the larger IIS stack size.
Has 64-bit native dependencies.
Use a 64-bit (x64) .NET Core SDK to publish a 64-bit app. A 64-bit runtime must be present on the host
system.

Hosting models
In-process hosting model
Using in-process hosting, an ASP.NET Core app runs in the same process as its IIS worker process. In-process
hosting provides improved performance over out-of-process hosting because requests aren't proxied over the
loopback adapter, a network interface that returns outgoing network traffic back to the same machine. IIS
handles process management with the Windows Process Activation Service (WAS ).
The ASP.NET Core Module:
Performs app initialization.
Loads the CoreCLR.
Calls Program.Main .
Handles the lifetime of the IIS native request.
The in-process hosting model isn't supported for ASP.NET Core apps that target the .NET Framework.
The following diagram illustrates the relationship between IIS, the ASP.NET Core Module, and an app hosted
in-process:

A request arrives from the web to the kernel-mode HTTP.sys driver. The driver routes the native request to IIS
on the website's configured port, usually 80 (HTTP ) or 443 (HTTPS ). The module receives the native request
and passes it to IIS HTTP Server ( IISHttpServer ). IIS HTTP Server is an in-process server implementation for
IIS that converts the request from native to managed.
After the IIS HTTP Server processes the request, 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 through IIS HTTP Server. IIS sends the response to the client
that initiated the request.
In-process hosting is opt-in for existing apps, but dotnet new templates default to the in-process hosting model
for all IIS and IIS Express scenarios.
CreateDefaultBuilder adds an IServer instance by calling the UseIIS method to boot the CoreCLR and host the
app inside of the IIS worker process (w3wp.exe or iisexpress.exe). Performance tests indicate that hosting a .NET
Core app in-process delivers significantly higher request throughput compared to hosting the app out-of-
process and proxying requests to Kestrel server.

NOTE
Apps published as a single file executable can't be loaded by the in-process hosting model.

Out-of-process hosting model

Because ASP.NET Core apps run in a process separate from the IIS worker process, the module 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 shuts down or crashes. This is essentially the same behavior as seen with apps that run
in-process that are managed by the Windows Process Activation Service (WAS ).
The following diagram illustrates the relationship between IIS, the ASP.NET Core Module, and an app hosted
out-of-process:

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 or 443.
The module specifies the port via an environment variable at startup, and the UseIISIntegration extension
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 the 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. Middleware added by IIS Integration updates the scheme, remote IP, and pathbase to account for
forwarding the request to Kestrel. The app's response is passed back to IIS, which pushes it back out to the
HTTP client that initiated the request.
ASP.NET Core ships with Kestrel server, a default, cross-platform HTTP server.
When using IIS or IIS Express, the app runs in a process separate from the IIS worker process (out-of-process)
with the Kestrel server.
Because ASP.NET Core apps run in a process separate from the IIS worker process, the module 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 shuts down or crashes. This is essentially the same behavior as seen with apps that run
in-process that are managed by the Windows Process Activation Service (WAS ).
The following diagram illustrates the relationship between IIS, the ASP.NET Core Module, and an app hosted
out-of-process:

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 or 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 the 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. Middleware added by IIS Integration updates the scheme, remote IP, and pathbase to account for
forwarding the request to Kestrel. The app's response is passed back to IIS, which pushes it back out to the
HTTP client that initiated the request.
CreateDefaultBuilder configures Kestrel server 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 backend process. CreateDefaultBuilder
calls the UseIISIntegration method. UseIISIntegration configures Kestrel to listen on the dynamic port at the
localhost IP address ( 127.0.0.1 ). If the dynamic port is 1234, Kestrel listens at 127.0.0.1:1234 . This
configuration replaces other URL configurations provided by:
UseUrls
Kestrel's Listen API
Configuration (or command-line --urls option)
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 only when running the app without IIS.
For more information on the in-process and out-of-process hosting models, see ASP.NET Core Module and
ASP.NET Core Module configuration reference.
For ASP.NET Core Module configuration guidance, see ASP.NET Core Module.
For more information on hosting, see Host in ASP.NET Core.
Application configuration
Enable the IISIntegration components
A typical Program.cs calls CreateDefaultBuilder to begin setting up a host that enables integration with IIS:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
...

IIS options
In-process hosting model
To configure IIS Server options, include a service configuration for IISServerOptions in ConfigureServices. The
following example disables AutomaticAuthentication:

services.Configure<IISServerOptions>(options =>
{
options.AutomaticAuthentication = false;
});

OPTION DEFAULT SETTING

AutomaticAuthentication true If true, IIS Server sets the

HttpContext.User authenticated by
Windows Authentication. If false ,
the server 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
Windows Authentication.

AuthenticationDisplayName null Sets the display name shown to users

on login pages.

AllowSynchronousIO false Whether synchronous IO is allowed for

the HttpContext.Request and the
HttpContext.Response .

MaxRequestBodySize 30000000 Gets or sets the max request body size

for the HttpRequest . Note that IIS
itself has the limit
maxAllowedContentLength which will
be processed before the
MaxRequestBodySize set in the
IISServerOptions . Changing the
MaxRequestBodySize won't affect the
maxAllowedContentLength . To
increase maxAllowedContentLength ,
add an entry in the web.config to set
maxAllowedContentLength to a
higher value. For more details, see
Configuration.
Out-of-process hosting model

OPTION DEFAULT SETTING

AutomaticAuthentication true If true, IIS Server sets the

HttpContext.User authenticated by
Windows Authentication. If false ,
the server 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
Windows Authentication.

AuthenticationDisplayName null Sets the display name shown to users

on login pages.

Out-of-process hosting model

To configure IIS options, include a service configuration for IISOptions in ConfigureServices. The following
example prevents the app from populating HttpContext.Connection.ClientCertificate :

services.Configure<IISOptions>(options =>
{
options.ForwardClientCertificate = false;
});

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.

Proxy server and load balancer scenarios

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:

<Project Sdk="Microsoft.NET.Sdk.Web">

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 set up the ASP.NET Core Module correctly, 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 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.
Transform web.config
If you need to transform web.config on publish (for example, set environment variables based on the
configuration, profile, or environment), see Transform web.config.

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
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 allows ASP.NET Core apps to run behind IIS. 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.

IMPORTANT
If the Hosting Bundle is installed before IIS, the bundle installation must be repaired. Run the Hosting Bundle installer
again after installing IIS.
If the Hosting Bundle is installed after installing the 64-bit (x64) version of .NET Core, SDKs might appear to be missing
(No .NET Core SDKs were detected). To resolve the problem, see Troubleshoot ASP.NET Core projects.

Direct download (current version)

Download the installer using the following link:
Current .NET Core Hosting Bundle installer (direct download)
Earlier versions of the installer
To obtain an earlier version of the installer:
1. Navigate to the .NET download archives.
2. Under .NET Core, select the .NET Core version.
3. In the Run apps - Runtime column, find the row of the .NET Core runtime version desired.
4. Download the installer using the Runtime & Hosting Bundle link.

WARNING
Some installers contain release versions that have reached their end of life (EOL) and are no longer supported by
Microsoft. For more information, see the support policy.

Install the Hosting Bundle

1. Run the installer on the server. The following parameters are available when running the installer from
an administrator command shell:
– Skip installing the ASP.NET Core Module.
OPT_NO_ANCM=1
OPT_NO_RUNTIME=1 – Skip installing the .NET Core runtime.
OPT_NO_SHAREDFX=1 – Skip installing the ASP.NET Shared Framework ( ASP.NET runtime).
OPT_NO_X86=1 – Skip installing x86 runtimes. Use this parameter when you know that you won't be
hosting 32-bit apps. If there's any chance that you will host both 32-bit and 64-bit apps in the future,
don't use this parameter and install both runtimes.
OPT_NO_SHARED_CONFIG_CHECK=1 – Disable the check for using an IIS Shared Configuration when the
shared configuration (applicationHost.config) is on the same machine as the IIS installation. Only
available for ASP.NET Core 2.2 or later Hosting Bundler installers. For more information, see
ASP.NET Core Module.
2. Restart the system or execute net stop was /y, followed by net start w3svc from a command shell.
Restarting IIS picks up a change to the system PATH, which is an environment variable, made by the
installer.
 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. In a following step,
the folder's path is provided to IIS as the physical path to the app. For more information on an app's
deployment folder and file layout, see ASP.NET Core directory structure.
2. In IIS Manager, open the server's node in the Connections panel. Right-click the Sites folder. Select
Add Website from the contextual menu.
3. 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
for more information.

4. Under the server's node, select Application Pools.

5. Right-click the site's app pool and select Basic Settings from the contextual menu.
6. 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 (.NET CLR )—the Core Common Language Runtime (CoreCLR ) for .NET Core
is booted to host the app in the worker process. Setting the .NET CLR version to No Managed Code
is optional but recommended.
7. ASP.NET Core 2.2 or later: For a 64-bit (x64) self-contained deployment that uses the in-process hosting
model, disable the app pool for 32-bit (x86) processes.
In the Actions sidebar of IIS Manager > Application Pools, select Set Application Pool Defaults or
Advanced Settings. Locate Enable 32-Bit Applications and set the value to False . This setting
doesn't affect apps deployed for out-of-process hosting.
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 IIS Physical path folder that was established in the Create the IIS site section. Web
Deploy is the recommended mechanism for deployment, but several options exist for moving the app from the
project's publish folder to the hosting system's deployment folder.
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

After the app is deployed to the hosting system, make a request to one of the app's public endpoints.
In the following example, the site is bound to an IIS Host name of www.mysite.com on Port 80 . A request is
made to http://www.mysite.com :
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 drop app_offline.html (requires PowerShell 5 or later):

$pathToApp = 'PATH_TO_APP'

# Stop the AppPool

New-Item -Path $pathToApp app_offline.htm

# Provide script commands here to deploy the app

# Restart the AppPool

Remove-Item -Path $pathToApp app_offline.htm

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 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 . When set to True , keys are stored in the user profile directory and protected
using DPAPI with a key specific to the user account. Keys are persisted to the
%LOCALAPPDATA%/ASP.NET/DataProtection-Keys folder.
The app pool's setProfileEnvironment attribute must also be enabled. The default value of
setProfileEnvironment is true . In some scenarios (for example, Windows OS ), setProfileEnvironment
is set to false . If keys aren't stored in the user profile directory as expected:
1. Navigate to the %windir%/system32/inetsrv/config folder.
2. Open the applicationHost.config file.
3. Locate the <system.applicationHost><applicationPools><applicationPoolDefaults><processModel>
element.
4. Confirm that the setProfileEnvironment attribute isn't present, which defaults the value to true , or
explicitly set the attribute's value to true .
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. For more information, see ASP.NET Core Data Protection.

Virtual Directories
IIS Virtual Directories aren't supported with ASP.NET Core apps. An app can be hosted as a sub-application.

Sub-applications
An ASP.NET Core app can be hosted as an IIS sub-application (sub-app). The sub-app's path becomes part of
the root app's URL.
A sub-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=".\MyApp.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's web.config file:

<?xml version="1.0" encoding="utf-8"?>

<configuration>
<system.webServer>
<handlers>
<remove name="aspNetCore" />
</handlers>
<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile=".\logs\stdout" />
</system.webServer>
</configuration>

Static asset links within the sub-app should use tilde-slash ( ~/ ) notation. Tilde-slash notation triggers a Tag
Helper to prepend the sub-app's pathbase to the rendered relative link. For a sub-app at /subapp_path , an
image linked with src="~/image.png" is rendered as src="/subapp_path/image.png" . The root app's Static File
Middleware doesn't process the static file request. The request is processed by the sub-app's Static File
Middleware.
If a static asset's src attribute is set to an absolute path (for example, src="/image.png" ), the link is rendered
without the sub-app's pathbase. The root app's Static File Middleware attempts to serve the asset from the root
app's web root, which results in a 404 - Not Found response unless the static asset is available from the root
app.
To host an ASP.NET Core app as a sub-app under another ASP.NET Core app:
1. Establish an app pool for the sub-app. Set the .NET CLR Version to No Managed Code because the
Core Common Language Runtime (CoreCLR ) for .NET Core is booted to host the app in the worker
process, not the desktop CLR (.NET CLR ).
2. Add the root site in IIS Manager with the sub-app in a folder under the root site.
3. Right-click the sub-app folder in IIS Manager and select Convert to Application.
4. In the Add Application dialog, use the Select button for the Application Pool to assign the app pool
that you created for the sub-app. Select OK.
The assignment of a separate app pool to the sub-app is a requirement when using the in-process hosting
model.
For more information on the in-process hosting model and configuring the ASP.NET Core Module, see
ASP.NET Core Module and ASP.NET Core Module.

Configuration of IIS with web.config

IIS configuration is influenced by the <system.webServer> section of web.config for IIS scenarios that are
functional for ASP.NET Core apps with the ASP.NET Core Module. For example, IIS configuration is functional
for dynamic compression. 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 an ASP.NET Core app.

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
App pool isolation is determined by the hosting model:
In-process hosting – Apps are required to run in separate app pools.
Out-of-process hosting – We recommend isolating the apps from each other by running each app in its own
app pool.
The IIS Add Website dialog defaults to a single app pool per app. When a 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.
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 a 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.

HTTP/2 support
HTTP/2 is supported with ASP.NET Core in the following IIS deployment scenarios:
In-process
Windows Server 2016/Windows 10 or later; IIS 10 or later
TLS 1.2 or later connection
Out-of-process
Windows Server 2016/Windows 10 or later; IIS 10 or later
Public-facing edge server connections use HTTP/2, but the reverse proxy connection to the Kestrel
server uses HTTP/1.1.
TLS 1.2 or later connection
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 .
For more information on the in-process and out-of-process hosting models, see ASP.NET Core Module.
HTTP/2 is supported for out-of-process deployments that meet the following base requirements:
 Windows Server 2016/Windows 10 or later; IIS 10 or later
Public-facing edge server 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.
TLS 1.2 or later connection
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.

CORS preflight requests

This section only applies to ASP.NET Core apps that target the .NET Framework.
For an ASP.NET Core app that targets the .NET Framework, OPTIONS requests aren't passed to the app by
default in IIS. To learn how to configure the app's IIS handlers in web.config to pass OPTIONS requests, see
Enable cross-origin requests in ASP.NET Web API 2: How CORS Works.

Application Initialization Module and Idle Timeout

When hosted in IIS by the ASP.NET Core Module version 2:
Application Initialization Module – App's hosted in-process or out-of-process can be configured to start
automatically on a worker process restart or server restart.
Idle Timeout – App's hosted in-process can be configured not to timeout during periods of inactivity.
Application Initialization Module
Applies to apps hosted in-process and out-of-process.
IIS Application Initialization is an IIS feature that sends an HTTP request to the app when the app pool starts or
is recycled. The request triggers the app to start. By default, IIS issues a request to the app's root URL ( / ) to
initialize the app (see the additional resources for more details on configuration).
Confirm that the IIS Application Initialization role feature in enabled:
On Windows 7 or later desktop systems when using IIS locally:
1. Navigate to Control Panel > Programs > Programs and Features > Turn Windows features on or off
(left side of the screen).
2. Open Internet Information Services > World Wide Web Services > Application Development
Features.
3. Select the check box for Application Initialization.
On Windows Server 2008 R2 or later:
1. Open the Add Roles and Features Wizard.
2. In the Select role services panel, open the Application Development node.
3. Select the check box for Application Initialization.
Use either of the following approaches to enable the Application Initialization Module for the site:
Using IIS Manager:
1. Select Application Pools in the Connections panel.
2. Right-click the app's app pool in the list and select Advanced Settings.
 3. The default Start Mode is OnDemand. Set the Start Mode to AlwaysRunning. Select OK.
4. Open the Sites node in the Connections panel.
5. Right-click the app and select Manage Website > Advanced Settings.
6. The default Preload Enabled setting is False. Set Preload Enabled to True. Select OK.
Using web.config, add the <applicationInitialization> element with doAppInitAfterRestart set to
true to the <system.webServer> elements in the app's web.config file:

<?xml version="1.0" encoding="utf-8"?>

<configuration>
<location path="." inheritInChildApplications="false">
<system.webServer>
<applicationInitialization doAppInitAfterRestart="true" />
</system.webServer>
</location>
</configuration>

Idle Timeout
Only applies to apps hosted in-process.
To prevent the app from idling, set the app pool's idle timeout using IIS Manager:
1. Select Application Pools in the Connections panel.
2. Right-click the app's app pool in the list and select Advanced Settings.
3. The default Idle Time-out (minutes) is 20 minutes. Set the Idle Time-out (minutes) to 0 (zero). Select
OK.
4. Recycle the worker process.
To prevent apps hosted out-of-process from timing out, use either of the following approaches:
Ping the app from an external service in order to keep it running.
If the app only hosts background services, avoid IIS hosting and use a Windows Service to host the
ASP.NET Core app.
Application Initialization Module and Idle Timeout additional resources
IIS 8.0 Application Initialization
Application Initialization <applicationInitialization>.
Process Model Settings for an Application Pool <processModel>.

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.
ASP.NET Core Module configuration reference
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

Additional resources
Troubleshoot ASP.NET Core projects
Introduction to ASP.NET Core
The Official Microsoft IIS Site
Windows Server technical content library
HTTP/2 on IIS
Transform web.config
 Publish an ASP.NET Core app to IIS
8/9/2019 • 4 minutes to read • Edit Online

By Luke Latham
This tutorial shows how to host an ASP.NET Core app on an IIS server.
This tutorial covers the following subjects:
Install the .NET Core Hosting Bundle on Windows Server.
Create an IIS site in IIS Manager.
Deploy an ASP.NET Core app.

Prerequisites
.NET Core SDK installed on the development machine.
Windows Server configured with the Web Server (IIS ) server role. If your server isn't configured to host
websites with IIS, follow the guidance in the IIS configuration section of the Host ASP.NET Core on Windows
with IIS article and then return to this tutorial.

WARNING
IIS configuration and website security involve concepts that aren't covered by this tutorial. Consult the IIS guidance
in the Microsoft IIS documentation and the ASP.NET Core article on hosting with IIS before hosting production apps on IIS.
Important scenarios for IIS hosting not covered by this tutorial include:
Creation of a registry hive for ASP.NET Core Data Protection
Configuration of the app pool's Access Control List (ACL)
To focus on IIS deployment concepts, this tutorial deploys an app without HTTPS security configured in IIS. For more
information on hosting an app enabled for HTTPS protocol, see the security topics in the Additional resources section of
this article. Further guidance for hosting ASP.NET Core apps is provided in the Host ASP.NET Core on Windows with IIS
article.

Install the .NET Core Hosting Bundle

Install the .NET Core Hosting Bundle on the IIS server. The bundle installs the .NET Core Runtime, .NET Core
Library, and the ASP.NET Core Module. The module allows ASP.NET Core apps to run behind IIS. 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.
Download the installer using the following link:
Current .NET Core Hosting Bundle installer (direct download)
1. Run the installer on the IIS server.
2. Restart the server or execute net stop was /y followed by net start w3svc in a command shell.

Create the IIS site

1. On the IIS server, create a folder to contain the app's published folders and files. In a following step, the
folder's path is provided to IIS as the physical path to the app.
2. In IIS Manager, open the server's node in the Connections panel. Right-click the Sites folder. Select Add
Website from the contextual menu.
3. Provide a Site name and set the Physical path to the app's deployment folder that you created. Provide
the Binding configuration and create the website by selecting OK.

Create an ASP.NET Core Razor Pages app

Follow the Get started with ASP.NET Core tutorial to create a Razor Pages app.

Publish and deploy the app

Publish an app means to produce a compiled app that can be hosted by a server. Deploy an app means to move
the published app to a hosting system. The publish step is handled by the .NET Core SDK, while the deployment
step can be handled by a variety of approaches. This tutorial adopts the folder deployment approach, where:
The app is published to a folder.
The folder's contents are moved to the IIS site's folder (the Physical path to the site in IIS Manager).
Visual Studio
.NET Core CLI
Visual Studio for Mac
1. Right-click on the project in Solution Explorer and select Publish.
2. In the Pick a publish target dialog, select the Folder publish option.
3. Set the Folder or File Share path.
If you created a folder for the IIS site that's available on the development machine as a network share,
provide the path to the share. The current user must have write access to publish to the share.
If you're unable to deploy directly to the IIS site folder on the IIS server, publish to a folder on
removeable media and physically move the published app to the IIS site folder on the server, which is the
site's Physical path in IIS Manager. Move the contents of the bin/Release/{TARGET
FRAMEWORK }/publish folder to the IIS site folder on the server, which is the site's Physical path in IIS
Manager.

Browse the website

The app is accessible in a browser after it receives the first request. Make a request to the app at the endpoint
binding that you established in IIS Manager for the site.

Next steps
In this tutorial, you learned how to:
Install the .NET Core Hosting Bundle on Windows Server.
Create an IIS site in IIS Manager.
Deploy an ASP.NET Core app.
To learn more about hosting ASP.NET Core apps on IIS, see the IIS Overview article:
Host ASP.NET Core on Windows with IIS

Additional resources
Articles in the ASP.NET Core documentation set
 ASP.NET Core Module
ASP.NET Core directory structure
Troubleshoot ASP.NET Core on Azure App Service and IIS
Enforce HTTPS in ASP.NET Core
Articles pertaining to ASP.NET Core app deployment
Publish an ASP.NET Core app to Azure with Visual Studio
Publish an ASP.NET Core app to Azure with Visual Studio Code
Visual Studio publish profiles for ASP.NET Core app deployment
Publish a Web app to a folder using Visual Studio for Mac
Articles on IIS HTTPS configuration
Configuring SSL in IIS Manager
How to Set Up SSL on IIS
Articles on IIS and Windows Server
The Official Microsoft IIS Site
Windows Server technical content library
 ASP.NET Core Module
7/1/2019 • 20 minutes to read • Edit Online

By Tom Dykstra, Rick Strahl, Chris Ross, Rick Anderson, Sourabh Shirhatti, Justin Kotalik, and Luke
Latham
The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to either:
Host an ASP.NET Core app inside of the IIS worker process ( w3wp.exe ), called the in-process
hosting model.
Forward web requests to a backend ASP.NET Core app running the Kestrel server, called the
out-of-process hosting model.
Supported Windows versions:
Windows 7 or later
Windows Server 2008 R2 or later
When hosting in-process, the module uses an in-process server implementation for IIS, called IIS
HTTP Server ( IISHttpServer ).
When hosting out-of-process, the module only works with Kestrel. The module is incompatible
with HTTP.sys.

Hosting models
In-process hosting model
To configure an app for in-process hosting, add the <AspNetCoreHostingModel> property to the
app's project file with a value of InProcess (out-of-process hosting is set with OutOfProcess ):

<PropertyGroup>
<AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
</PropertyGroup>

The in-process hosting model isn't supported for ASP.NET Core apps that target the .NET
Framework.
If the <AspNetCoreHostingModel> property isn't present in the file, the default value is OutOfProcess .
The following characteristics apply when hosting in-process:
IIS HTTP Server ( IISHttpServer ) is used instead of Kestrel server. For in-process,
CreateDefaultBuilder calls UseIIS to:
Register the IISHttpServer .
Configure the port and base path the server should listen on when running behind the
ASP.NET Core Module.
Configure the host to capture startup errors.
The requestTimeout attribute doesn't apply to in-process hosting.
Sharing an app pool among apps isn't supported. Use one app pool per app.
When using Web Deploy or manually placing an app_offline.htm file in the deployment, the
 app might not shut down immediately if there's an open connection. For example, a
websocket connection may delay app shut down.
The architecture (bitness) of the app and installed runtime (x64 or x86) must match the
architecture of the app pool.
If setting up the app's host manually with WebHostBuilder (not using CreateDefaultBuilder)
and the app is ever run directly on the Kestrel server (self-hosted), call UseKestrel before
calling UseIISIntegration . If the order is reversed, the host fails to start.
Client disconnects are detected. The HttpContext.RequestAborted cancellation token is
cancelled when the client disconnects.
In ASP.NET Core 2.2.1 or earlier, GetCurrentDirectory returns the worker directory of the
process started by IIS rather than the app's directory (for example,
C:\Windows\System32\inetsrv for w3wp.exe).
For sample code that sets the app's current directory, see the CurrentDirectoryHelpers class.
Call the SetCurrentDirectory method. Subsequent calls to GetCurrentDirectory provide the
app's directory.
When hosting in-process, AuthenticateAsync isn't called internally to initialize a user.
Therefore, an IClaimsTransformation implementation used to transform claims after every
authentication isn't activated by default. When transforming claims with an
IClaimsTransformation implementation, call AddAuthentication to add authentication
services:

public void ConfigureServices(IServiceCollection services)

{
services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
}

public void Configure(IApplicationBuilder app)

{
app.UseAuthentication();
}

Out-of-process hosting model

To configure an app for out-of-process hosting, use either of the following approaches in the
project file:
Don't specify the <AspNetCoreHostingModel> property. If the <AspNetCoreHostingModel> property
isn't present in the file, the default value is OutOfProcess .
Set the value of the <AspNetCoreHostingModel> property to OutOfProcess (in-process hosting is
set with InProcess ):

<PropertyGroup>
<AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>

Kestrel server is used instead of IIS HTTP Server ( IISHttpServer ).

For out-of-process, CreateDefaultBuilder calls UseIISIntegration to:
Configure the port and base path the server should listen on when running behind the
ASP.NET Core Module.
 Configure the host to capture startup errors.
When hosting out-of-process, AuthenticateAsync isn't called internally to initialize a user.
Therefore, an IClaimsTransformation implementation used to transform claims after every
authentication isn't activated by default. When transforming claims with an IClaimsTransformation
implementation, call AddAuthentication to add authentication services:

public void ConfigureServices(IServiceCollection services)

{
services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
services.AddAuthentication(IISDefaults.AuthenticationScheme);
}

public void Configure(IApplicationBuilder app)

{
app.UseAuthentication();
}

Hosting model changes

If the hostingModel setting is changed in the web.config file (explained in the Configuration with
web.config section), the module recycles the worker process for IIS.
For IIS Express, the module doesn't recycle the worker process but instead triggers a graceful
shutdown of the current IIS Express process. The next request to the app spawns a new IIS Express
process.
Process name
Process.GetCurrentProcess().ProcessName reports w3wp / iisexpress (in-process) or dotnet (out-
of-process).
The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to forward web
requests to backend ASP.NET Core apps.
Supported Windows versions:
Windows 7 or later
Windows Server 2008 R2 or later
The module only works with Kestrel. The module is incompatible with HTTP.sys.
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 an
app:

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 or 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 the 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. Middleware added by IIS Integration updates the scheme,
remote IP, and pathbase to account for forwarding the request to Kestrel. The app's response is
passed back to IIS, which pushes it back out to the HTTP client that initiated the request.
Many native modules, such as Windows Authentication, remain active. To learn more about IIS
modules active with the ASP.NET Core Module, see IIS modules with ASP.NET Core.
The ASP.NET Core Module can also:
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 instructions on how to install the ASP.NET Core Module, see Install the .NET Core Hosting
Bundle.

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:

<?xml version="1.0" encoding="utf-8"?>

<configuration>
<location path="." inheritInChildApplications="false">
<system.webServer>
<handlers>
<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2"
resourceType="Unspecified" />
</handlers>
<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile=".\logs\stdout"
hostingModel="InProcess" />
</system.webServer>
</location>
</configuration>
 <?xml version="1.0" encoding="utf-8"?>
<configuration>
<system.webServer>
<handlers>
<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule"
resourceType="Unspecified" />
</handlers>
<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile=".\logs\stdout" />
</system.webServer>
</configuration>

The following web.config is published for a self-contained deployment:

<?xml version="1.0" encoding="utf-8"?>

<configuration>
<location path="." inheritInChildApplications="false">
<system.webServer>
<handlers>
<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2"
resourceType="Unspecified" />
</handlers>
<aspNetCore processPath=".\MyApp.exe"
stdoutLogEnabled="false"
stdoutLogFile=".\logs\stdout"
hostingModel="InProcess" />
</system.webServer>
</location>
</configuration>

The InheritInChildApplications property is set to false to indicate that the settings specified
within the <location> element aren't inherited by apps that reside in a subdirectory of the app.

<?xml version="1.0" encoding="utf-8"?>

<configuration>
<system.webServer>
<handlers>
<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule"
resourceType="Unspecified" />
</handlers>
<aspNetCore processPath=".\MyApp.exe"
stdoutLogEnabled="false"
stdoutLogFile=".\logs\stdout" />
</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.
For information on IIS sub-application configuration, see Host ASP.NET Core on Windows with
IIS.
Attributes of the aspNetCore element
ATTRIBUTE DESCRIPTION DEFAULT
ATTRIBUTE DESCRIPTION DEFAULT

arguments Optional string attribute.

Arguments to the executable
specified in processPath.

disableStartUpErrorPage Optional Boolean attribute. 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 Optional Boolean attribute. 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.

hostingModel Optional string attribute. OutOfProcess

Specifies the hosting model

as in-process ( InProcess )
or out-of-process (
OutOfProcess ).

processesPerApplication Optional integer attribute. Default: 1

Min: 1
Specifies the number of Max: 100 †
instances of the process
specified in the processPath
setting that can be spun up
per app.
†For in-process hosting, the
value is limited to 1 .
Setting
processesPerApplication
is discouraged. This attribute
will be removed in a future
release.
ATTRIBUTE DESCRIPTION DEFAULT

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. Default: 10

Min: 0
Specifies the number of times Max: 100
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.
Not supported with in-
process hosting.

requestTimeout Optional timespan attribute. Default: 00:02:00

Min: 00:00:00
Specifies the duration for Max: 360:00:00
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.
Doesn't apply to in-process
hosting. For in-process
hosting, the module waits for
the app to process the
request.
Valid values for minutes and
seconds segments of the
string are in the range 0-59.
Use of 60 in the value for
minutes or seconds results in
a 500 - Internal Server Error.

shutdownTimeLimit Optional integer attribute. Default: 10

Min: 0
Duration in seconds that the Max: 600
module waits for the
executable to gracefully
shutdown when the
app_offline.htm file is
detected.
ATTRIBUTE DESCRIPTION DEFAULT

startupTimeLimit Optional integer attribute. Default: 120

Min: 0
Duration in seconds that the Max: 3600
module waits for the
executable to 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.
A value of 0 (zero) is not
considered an infinite
timeout.

stdoutLogEnabled Optional Boolean attribute. false

If true, stdout and stderr for

the process specified in
processPath are redirected
to the file specified in
stdoutLogFile.
ATTRIBUTE DESCRIPTION DEFAULT

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 are created by the
module when the log file is
created. 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_19
34.log in the logs folder
when saved on 2/5/2018 at
19:41:32 with a process ID of
1934.

ATTRIBUTE DESCRIPTION DEFAULT

arguments Optional string attribute.

Arguments to the executable
specified in processPath.

disableStartUpErrorPage Optional Boolean attribute. 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 Optional Boolean attribute. 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.
ATTRIBUTE DESCRIPTION DEFAULT

processesPerApplication Optional integer attribute. Default: 1

Min: 1
Specifies the number of Max: 100
instances of the process
specified in the processPath
setting that can be spun up
per app.
Setting
processesPerApplication
is discouraged. This attribute
will be removed in a future
release.

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. Default: 10

Min: 0
Specifies the number of times Max: 100
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. Default: 00:02:00

Min: 00:00:00
Specifies the duration for Max: 360:00:00
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. Default: 10

Min: 0
Duration in seconds that the Max: 600
module waits for the
executable to gracefully
shutdown when the
app_offline.htm file is
detected.
ATTRIBUTE DESCRIPTION DEFAULT

startupTimeLimit Optional integer attribute. Default: 120

Min: 0
Duration in seconds that the Max: 3600
module waits for the
executable to 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.
A value of 0 (zero) is not
considered an infinite
timeout.

stdoutLogEnabled Optional Boolean attribute. false

If true, stdout and stderr for

the process specified in
processPath are redirected
to the file specified in
stdoutLogFile.
 ATTRIBUTE DESCRIPTION DEFAULT

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_19
34.log 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.
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.

WARNING
Environment variables set in this section conflict with system environment variables set with the same
name. If an environment variable is set in both the web.config file and at the system level in Windows, the
value from the web.config file becomes appended to the system environment variable value (for example,
ASPNETCORE_ENVIRONMENT: Development;Development ), which prevents the app from starting.

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.
 <aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile="\\?\%home%\LogFiles\stdout"
hostingModel="InProcess">
<environmentVariables>
<environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
<environmentVariable name="CONFIG_DIR" value="f:\application_config" />
</environmentVariables>
</aspNetCore>

<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile="\\?\%home%\LogFiles\stdout">
<environmentVariables>
<environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
<environmentVariable name="CONFIG_DIR" value="f:\application_config" />
</environmentVariables>
</aspNetCore>

NOTE
An alternative to setting the environment directly in web.config is to include the <EnvironmentName>
property in the publish profile (.pubxml) or project file. This approach sets the environment in web.config
when the project is published:

<PropertyGroup>
<EnvironmentName>Development</EnvironmentName>
</PropertyGroup>

WARNING
Only set the ASPNETCORE_ENVIRONMENT environment 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.
When using the out-of-process hosting model, the app might not shut down immediately if there's
an open connection. For example, a websocket connection may delay app shut down.

Start-up error page

Both in-process and out-of-process hosting produce custom error pages when they fail to start the
app.
If the ASP.NET Core Module fails to find either the in-process or out-of-process request handler, a
500.0 - In-Process/Out-Of-Process Handler Load Failure status code page appears.
For in-process hosting if the ASP.NET Core Module fails to start the app, a 500.30 - Start Failure
status code page appears.
For out-of-process hosting 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 5xx status code page, use the
disableStartUpErrorPage attribute. For more information on configuring custom error messages,
see HTTP Errors <httpErrors>.
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 are created by the module when the log file is created. 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.
If stdoutLogEnabled is false, errors that occur on app startup are captured and emitted to the event
log up to 30 KB. After startup, all additional logs are discarded.
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.

<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="true"
stdoutLogFile="\\?\%home%\LogFiles\stdout"
hostingModel="InProcess">
</aspNetCore>

<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="true"
stdoutLogFile="\\?\%home%\LogFiles\stdout">
</aspNetCore>

Enhanced diagnostic logs

The ASP.NET Core Module is configurable to provide enhanced diagnostics logs. Add the
<handlerSettings> element to the <aspNetCore> element in web.config. Setting the debugLevel to
TRACE exposes a higher fidelity of diagnostic information:

<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile="\\?\%home%\LogFiles\stdout"
hostingModel="InProcess">
<handlerSettings>
<handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
<handlerSetting name="debugLevel" value="FILE,TRACE" />
</handlerSettings>
</aspNetCore>

Any folders in the path (logs in the preceding example) are created by the module when the log file
is created. 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).

Folders in the path provided to the <handlerSetting> value (logs in the preceding example) aren't
created by the module automatically and should pre-exist in the deployment. 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).
Debug level ( debugLevel ) values can include both the level and the location.
Levels (in order from least to most verbose):
ERROR
WARNING
 INFO
TRACE
Locations (multiple locations are permitted):
CONSOLE
EVENTLOG
FILE
The handler settings can also be provided via environment variables:
ASPNETCORE_MODULE_DEBUG_FILE – Path to the debug log file. (Default: aspnetcore-debug.log)
ASPNETCORE_MODULE_DEBUG – Debug level setting.

WARNING
Do not leave debug logging enabled in the deployment for longer than required to troubleshoot an issue.
The size of the log isn't limited. Leaving the debug log enabled can exhaust the available disk space and
crash the server or app service.

See Configuration with web.config for an example of the aspNetCore element in the web.config
file.

Modify the stack size

Configure the managed stack size using the stackSize setting in bytes. The default size is
1048576 bytes (1 MB ).

<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile="\\?\%home%\LogFiles\stdout"
hostingModel="InProcess">
<handlerSettings>
<handlerSetting name="stackSize" value="2097152" />
</handlerSettings>
</aspNetCore>

Proxy configuration uses HTTP protocol and a pairing token

Only applies to out-of-process hosting.
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 (
MS-ASPNETCORE-TOKEN ) 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 TrustedInstaller account.
Because the local system account doesn't have modify permission for the share path used by the
IIS Shared Configuration, the installer throws an access denied error when attempting to configure
the module settings in the applicationHost.config file on the share.
When using an IIS Shared Configuration on the same machine as the IIS installation, run the
ASP.NET Core Hosting Bundle installer with the OPT_NO_SHARED_CONFIG_CHECK parameter set to 1 :

dotnet-hosting-{VERSION}.exe OPT_NO_SHARED_CONFIG_CHECK=1

When the path to the shared configuration isn't on the same machine as the IIS installation, 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.
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
%ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll
%ProgramFiles(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll
IIS Express (x86/amd64):
%ProgramFiles%\IIS Express\aspnetcore.dll
%ProgramFiles(x86)%\IIS Express\aspnetcore.dll
%ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll
%ProgramFiles(x86)%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll
Schema
IIS
%windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml
%windir%\System32\inetsrv\config\schema\aspnetcore_schema_v2.xml
IIS Express
%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml
%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema_v2.xml
Configuration
IIS
%windir%\System32\inetsrv\config\applicationHost.config
IIS Express
Visual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.config
iisexpress.exe CLI: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config
The files can be found by searching for aspnetcore in the applicationHost.config file.

Additional resources
Host ASP.NET Core on Windows with IIS
ASP.NET Core Module GitHub repository (reference source)
IIS modules with ASP.NET Core
 Development-time IIS support in Visual Studio for
ASP.NET Core
7/11/2019 • 5 minutes to read • Edit Online

By Sourabh Shirhatti and Luke Latham

This article describes Visual Studio support for debugging ASP.NET Core apps running with IIS on Windows
Server. This topic walks through enabling this scenario and setting up a project.

Prerequisites
Visual Studio for Windows
ASP.NET and web development workload
.NET Core cross-platform development workload
X.509 security certificate (for HTTPS support)

Enable IIS
1. In Windows, 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. Select OK.
The IIS installation may require a system restart.

Configure IIS
IIS must have a website configured with the following:
Host name – Typically, the Default Web Site is used with a Host name of localhost . However, any valid IIS
website with a unique host name works.
Site Binding
For apps that require HTTPS, create a binding to port 443 with a certificate. Typically, the IIS Express
Development Certificate is used, but any valid certificate works.
For apps that use HTTP, confirm the existence of a binding to post 80 or create a binding to port 80 for a
new site.
Use a single binding for either HTTP or HTTPS. Binding to both HTTP and HTTPS ports
simultaneously isn't supported.

Enable development-time IIS support in Visual Studio

1. Launch the Visual Studio installer.
2. Select Modify for the Visual Studio installation that you plan to use for IIS development-time support.
3. For the ASP.NET and web development workload, locate and install the Development time IIS
support component.
The component is listed in the Optional section under Development time IIS support in the Installation
details panel to the right of the workloads. The component installs the ASP.NET Core Module, which is a
native IIS module required to run ASP.NET Core apps with IIS.
Configure the project
HTTPS redirection
For a new project that requires HTTPS, select the check box to Configure for HTTPS in the Create a new
ASP.NET Core Web Application window. Selecting the check box adds HTTPS Redirection and HSTS
Middleware to the app when it's created.
For an existing project that requires HTTPS, use HTTPS Redirection and HSTS Middleware in Startup.Configure .
For more information, see Enforce HTTPS in ASP.NET Core.
For a project that uses HTTP, HTTPS Redirection and HSTS Middleware aren't added to the app. No app
configuration is required.
IIS launch profile
Create a new launch profile to add development-time IIS support:
1. Right-click the project in Solution Explorer. Select Properties. Open the Debug tab.
2. For Profile, select the New button. Name the profile "IIS" in the popup window. Select OK to create the
profile.
3. For the Launch setting, select IIS from the list.
4. Select the check box for Launch browser and provide the endpoint URL.
When the app requires HTTPS, use an HTTPS endpoint ( https:// ). For HTTP, use an HTTP ( http:// )
endpoint.
Provide the same host name and port as the IIS configuration specified earlier uses, typically localhost .
Provide the name of the app at the end of the URL.
For example, https://localhost/WebApplication1 (HTTPS ) or http://localhost/WebApplication1 (HTTP ) are
valid endpoint URLs.
5. In the Environment variables section, select the Add button. Provide an environment variable with a
Name of ASPNETCORE_ENVIRONMENT and a Value of Development .
6. In the Web Server Settings area, set the App URL to the same value used for the Launch browser
endpoint URL.
7. For the Hosting Model setting in Visual Studio 2019 or later, select Default to use the hosting model used
by the project. If the project sets the <AspNetCoreHostingModel> property in its project file, the value of the
property ( InProcess or OutOfProcess ) is used. If the property isn't present, the default hosting model of the
app is used, which is in-process. If the app requires an explicit hosting model setting different from the app's
normal hosting model, set the Hosting Model to either In Process or Out Of Process as needed.
8. Save the profile.
1. Right-click the project in Solution Explorer. Select Properties. Open the Debug tab.
2. For Profile, select the New button. Name the profile "IIS" in the popup window. Select OK to create the
profile.
3. For the Launch setting, select IIS from the list.
4. Select the check box for Launch browser and provide the endpoint URL.
When the app requires HTTPS, use an HTTPS endpoint ( https:// ). For HTTP, use an HTTP ( http:// )
endpoint.
 Provide the same host name and port as the IIS configuration specified earlier uses, typically localhost .
Provide the name of the app at the end of the URL.
For example, https://localhost/WebApplication1 (HTTPS ) or http://localhost/WebApplication1 (HTTP ) are
valid endpoint URLs.
5. In the Environment variables section, select the Add button. Provide an environment variable with a
Name of ASPNETCORE_ENVIRONMENT and a Value of Development .
6. In the Web Server Settings area, set the App URL to the same value used for the Launch browser
endpoint URL.
7. For the Hosting Model setting in Visual Studio 2019 or later, select Default to use the hosting model used
by the project. If the project sets the <AspNetCoreHostingModel> property in its project file, the value of the
property ( InProcess or OutOfProcess ) is used. If the property isn't present, the default hosting model of the
app is used, which is out-of-process. If the app requires an explicit hosting model setting different from the
app's normal hosting model, set the Hosting Model to either In Process or Out Of Process as needed.
8. Save the profile.
When not using Visual Studio, manually add a launch profile to the launchSettings.json file in the Properties folder.
The following example configures the profile to use the HTTPS protocol:

{
"iisSettings": {
"windowsAuthentication": false,
"anonymousAuthentication": true,
"iis": {
"applicationUrl": "https://localhost/WebApplication1",
"sslPort": 0
}
},
"profiles": {
"IIS": {
"commandName": "IIS",
"launchBrowser": true,
"launchUrl": "https://localhost/WebApplication1",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
}
}

Confirm that the applicationUrl and launchUrl endpoints match and use the same protocol as the IIS binding
configuration, either HTTP or HTTPS.

Run the project

Run Visual Studio as an administrator:
Confirm that the build configuration drop-down list is set to Debug.
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.
 NOTE
Debugging a Release build configuration with Just My Code and compiler optimizations results in a degraded experience. For
example, break points aren't hit.

Additional resources
Getting Started with the IIS Manager in IIS
Host ASP.NET Core on Windows with IIS
Introduction to ASP.NET Core Module
ASP.NET Core Module configuration reference
Enforce HTTPS
 IIS modules with ASP.NET Core
5/21/2019 • 5 minutes to read • Edit Online

By Luke Latham
Some of the native IIS modules and all of the IIS managed modules aren't able to process requests for ASP.NET
Core apps. In many cases, ASP.NET Core offers an alternative to the scenarios addressed by IIS native and
managed modules.

Native modules
The table indicates native IIS modules that are functional with ASP.NET Core apps and the ASP.NET Core
Module.

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
MODULE FUNCTIONAL WITH ASP.NET CORE APPS ASP.NET CORE OPTION

Failed Requests 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

HTTP Redirection Yes URL Rewriting Middleware

HttpRedirectionModule

HTTP Tracing Yes

TracingModule

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
 MODULE FUNCTIONAL WITH ASP.NET CORE APPS ASP.NET CORE OPTION

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. If the action entry for the module appears as Lock, the module is already unlocked, and no action
is required. 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. If the
action entry for the module section appears as Lock Section, the module section is already unlocked, and
no action is required.
4. Add a <modules> section to the app's local web.config file with a <remove> element to remove the module
from the app. Add multiple <remove> elements 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 using this approach doesn'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>

In order to add or remove modules for IIS Express using web.config, modify applicationHost.config to unlock the
<modules> section:

1. Open {APPLICATION ROOT }\.vs\config\applicationhost.config.

2. Locate the <section> element for IIS modules and change overrideModeDefault from Deny to Allow :

<section name="modules"
allowDefinition="MachineToApplication"
overrideModeDefault="Allow" />

3. Locate the <location path="" overrideMode="Allow"><system.webServer><modules> section. For any modules

that you wish to remove, set lockItem from true to false . In the following example, the CGI Module is
unlocked:

<add name="CgiModule" lockItem="false" />

4. After the <modules> section and individual modules are unlocked, you're free to add or remove IIS
modules using the app's web.config file for running the app on IIS Express.
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.
Additional resources
Host ASP.NET Core on Windows with IIS
Introduction to IIS Architectures: Modules in IIS
IIS Modules Overview
Customizing IIS 7.0 Roles and Modules
IIS <system.webServer>
 Troubleshoot ASP.NET Core on Azure App
Service and IIS
7/24/2019 • 23 minutes to read • Edit Online

By Luke Latham and Justin Kotalik

This article provides information on common app startup errors and instructions on how to diagnose
errors when an app is deployed to Azure App Service or IIS:
App startup errors
Explains common startup HTTP status code scenarios.
Troubleshoot on Azure App Service
Provides troubleshooting advice for apps deployed to Azure App Service.
Troubleshoot on IIS
Provides troubleshooting advice for apps deployed to IIS or running on IIS Express locally. The guidance
applies to both Windows Server and Windows desktop deployments.
Clear package caches
Explains what to do when incoherent packages break an app when performing major upgrades or changing
package versions.
Additional resources
Lists additional troubleshooting topics.

App startup errors

In Visual Studio, an ASP.NET Core project defaults to IIS Express hosting during debugging. A 502.5 -
Process Failure or a 500.30 - Start Failure that occurs when debugging locally can be diagnosed using the
advice in this topic.
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 diagnosed using the advice in this topic.
403.14 Forbidden
The app fails to start. The following error is logged:

The Web server is configured to not list the contents of this directory.

The error is usually caused by a broken deployment on the hosting system, which includes any of the
following scenarios:
The app is deployed to the wrong folder on the hosting system.
The deployment process failed to move all of the app's files and folders to the deployment folder on the
hosting system.
The web.config file is missing from the deployment, or the web.config file contents are malformed.
Perform the following steps:
1. Delete all of the files and folders from the deployment folder on the hosting system.
2. Redeploy the contents of the app's publish folder to the hosting system using your normal method of
 deployment, such as Visual Studio, PowerShell, or manual deployment:
Confirm that the web.config file is present in the deployment and that its contents are correct.
When hosting on Azure App Service, confirm that the app is deployed to the
D:\home\site\wwwroot folder.
When the app is hosted by IIS, confirm that the app is deployed to the IIS Physical path shown
in IIS Manager's Basic Settings.
3. Confirm that all of the app's files and folders are deployed by comparing the deployment on the hosting
system to the contents of the project's publish folder.
For more information on the layout of a published ASP.NET Core app, see ASP.NET Core directory
structure. For more information on the web.config file, see ASP.NET Core Module.
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.
500.0 In-Process Handler Load Failure
The worker process fails. The app doesn't start.
The ASP.NET Core Module fails to find the .NET Core CLR and find the in-process request handler
(aspnetcorev2_inprocess.dll). Check that:
The app targets either the Microsoft.AspNetCore.Server.IIS NuGet package or the
Microsoft.AspNetCore.App metapackage.
The version of the ASP.NET Core shared framework that the app targets is installed on the target
machine.
500.0 Out-Of-Process Handler Load Failure
The worker process fails. The app doesn't start.
The ASP.NET Core Module fails to find the out-of-process hosting request handler. Make sure the
aspnetcorev2_outofprocess.dll is present in a subfolder next to aspnetcorev2.dll.
500.0 In-Process Handler Load Failure
The worker process fails. The app doesn't start.
An unknown error occurred loading ASP.NET Core Module components. Take one of the following actions:
Contact Microsoft Support (select Developer Tools then ASP.NET Core).
Ask a question on Stack Overflow.
File an issue on our GitHub repository.
500.30 In-Process Startup Failure
The worker process fails. The app doesn't start.
The ASP.NET Core Module attempts to start the .NET Core CLR in-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.
A common failure condition is the app is misconfigured due to targeting a version of the ASP.NET Core
shared framework that isn't present. Check which versions of the ASP.NET Core shared framework are
installed on the target machine.
500.31 ANCM Failed to Find Native Dependencies
The worker process fails. The app doesn't start.
The ASP.NET Core Module attempts to start the .NET Core runtime in-process, but it fails to start. The
most common cause of this startup failure is when the Microsoft.NETCore.App or Microsoft.AspNetCore.App
runtime isn't installed. If the app is deployed to target ASP.NET Core 3.0 and that version doesn't exist on
the machine, this error occurs. An example error message follows:

The specified framework 'Microsoft.NETCore.App', version '3.0.0' was not found.

- The following frameworks were found:
2.2.1 at [C:\Program Files\dotnet\x64\shared\Microsoft.NETCore.App]
3.0.0-preview5-27626-15 at [C:\Program Files\dotnet\x64\shared\Microsoft.NETCore.App]
3.0.0-preview6-27713-13 at [C:\Program Files\dotnet\x64\shared\Microsoft.NETCore.App]
3.0.0-preview6-27714-15 at [C:\Program Files\dotnet\x64\shared\Microsoft.NETCore.App]
3.0.0-preview6-27723-08 at [C:\Program Files\dotnet\x64\shared\Microsoft.NETCore.App]

The error message lists all the installed .NET Core versions and the version requested by the app. To fix this
error, either:
Install the appropriate version of .NET Core on the machine.
Change the app to target a version of .NET Core that's present on the machine.
Publish the app as a self-contained deployment.
When running in development (the ASPNETCORE_ENVIRONMENT environment variable is set to Development ),
the specific error is written to the HTTP response. The cause of a process startup failure is also found in the
Application Event Log.
500.32 ANCM Failed to Load dll
The worker process fails. The app doesn't start.
The most common cause for this error is that the app is published for an incompatible processor
architecture. If the worker process is running as a 32-bit app and the app was published to target 64-bit,
this error occurs.
To fix this error, either:
Republish the app for the same processor architecture as the worker process.
Publish the app as a framework-dependent deployment.
500.33 ANCM Request Handler Load Failure
The worker process fails. The app doesn't start.
The app didn't reference the Microsoft.AspNetCore.App framework. Only apps targeting the
Microsoft.AspNetCore.App framework can be hosted by the ASP.NET Core Module.

To fix this error, confirm that the app is targeting the Microsoft.AspNetCore.App framework. Check the
.runtimeconfig.json to verify the framework targeted by the app.

500.34 ANCM Mixed Hosting Models Not Supported

The worker process can't run both an in-process app and an out-of-process app in the same process.
To fix this error, run apps in separate IIS application pools.
500.35 ANCM Multiple In-Process Applications in same Process
The worker process can't run both an in-process app and an out-of-process app in the same process.
To fix this error, run apps in separate IIS application pools.
500.36 ANCM Out-Of-Process Handler Load Failure
The out-of-process request handler, aspnetcorev2_outofprocess.dll, isn't next to the aspnetcorev2.dll file.
This indicates a corrupted installation of the ASP.NET Core Module.
To fix this error, repair the installation of the .NET Core Hosting Bundle (for IIS ) or Visual Studio (for IIS
Express).
500.37 ANCM Failed to Start Within Startup Time Limit
ANCM failed to start within the provied startup time limit. By default, the timeout is 120 seconds.
This error can occur when starting a large number of apps on the same machine. Check for CPU/Memory
usage spikes on the server during startup. You may need to stagger the startup process of multiple apps.
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.
A common failure condition is the app is misconfigured due to targeting a version of the ASP.NET Core
shared framework that isn't present. Check which versions of the ASP.NET Core shared framework are
installed on the target machine. The shared framework is the set of assemblies (.dll files) that are installed
on the machine and referenced by a metapackage such as Microsoft.AspNetCore.App . The metapackage
reference can specify a minimum required version. For more information, see The shared framework.
The 502.5 Process Failure error page is returned when a hosting or app misconfiguration causes the
worker process to fail:
Failed to start application (ErrorCode '0x800700c1')

EventID: 1010
Source: IIS AspNetCore Module V2
Failed to start application '/LM/W3SVC/6/ROOT/', ErrorCode '0x800700c1'.

The app failed to start because the app's assembly (.dll) couldn't be loaded.
This error occurs when there's a bitness mismatch between the published app and the w3wp/iisexpress
process.
Confirm that the app pool's 32-bit setting is correct:
1. Select the app pool in IIS Manager's Application Pools.
2. Select Advanced Settings under Edit Application Pool in the Actions panel.
3. Set Enable 32-Bit Applications:
If deploying a 32-bit (x86) app, set the value to True .
If deploying a 64-bit (x64) app, set the value to False .

Confirm that there isn't a conflict between a <Platform> MSBuild property in the project file and the
published bitness of the app.
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 on Azure App Service

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.

Application Event Log (Azure App Service )

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 in App Services.
2. Select Diagnose and solve problems.
3. Select the Diagnostic Tools heading.
4. Under Support Tools, select the Application Events button.
5. Examine the latest error provided by the IIS AspNetCoreModule or IIS AspNetCoreModule V2 entry 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. Open Advanced Tools 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. Open Advanced Tools 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.
Test a 32-bit (x86) app
Current release
1. cd d:\home\site\wwwroot
2. Run the app:
If the app is a framework-dependent deployment:

dotnet .\{ASSEMBLY NAME}.dll

 If the app is a self-contained deployment:

{ASSEMBLY NAME}.exe

The console output from the app, showing any errors, is piped to the Kudu console.
Framework-dependent deployment running on a preview release
Requires installing the ASP.NET Core {VERSION } (x86 ) Runtime site extension.
1. cd D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.x32 ( {X.Y} is the runtime version)
2. Run the app: dotnet \home\site\wwwroot\{ASSEMBLY NAME}.dll
The console output from the app, showing any errors, is piped to the Kudu console.
Test a 64-bit (x64) app
Current release
If the app is a 64-bit (x64) framework-dependent deployment:
1. cd D:\Program Files\dotnet
2. Run the app: dotnet \home\site\wwwroot\{ASSEMBLY NAME}.dll
If the app is a self-contained deployment:
1. cd D:\home\site\wwwroot
2. Run the app: {ASSEMBLY NAME}.exe

The console output from the app, showing any errors, is piped to the Kudu console.
Framework-dependent deployment running on a preview release
Requires installing the ASP.NET Core {VERSION } (x64 ) Runtime site extension.
1. cd D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.x64 ( {X.Y} is the runtime version)
2. Run the app: dotnet \home\site\wwwroot\{ASSEMBLY NAME}.dll

The console output from the app, showing any errors, is piped to the Kudu console.
ASP.NET Core Module stdout log (Azure App Service )
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.
10. Using the navigation bar at the top of the page, open Debug console and select CMD.
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.
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.
For more information, see ASP.NET Core Module.

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.

ASP.NET Core Module debug log (Azure App Service )

The ASP.NET Core Module debug log provides additional, deeper logging from the ASP.NET Core
Module. To enable and view stdout logs:
1. To enable the enhanced diagnostic log, perform either of the following:
Follow the instructions in Enhanced diagnostic logs to configure the app for an enhanced
diagnostic logging. Redeploy the app.
Add the <handlerSettings> shown in Enhanced diagnostic logs to the live app's web.config file
using the Kudu console:
a. Open Advanced Tools in the Development Tools area. Select the Go→ button. The
Kudu console opens in a new browser tab or window.
b. Using the navigation bar at the top of the page, open Debug console and select CMD.
c. Open the folders to the path site > wwwroot. Edit the web.config file by selecting the
pencil button. Add the <handlerSettings> section as shown in Enhanced diagnostic logs.
Select the Save button.
2. Open Advanced Tools in the Development Tools area. Select the Go→ button. The Kudu console
opens in a new browser tab or window.
3. Using the navigation bar at the top of the page, open Debug console and select CMD.
4. Open the folders to the path site > wwwroot. If you didn't supply a path for the aspnetcore-debug.log
file, the file appears in the list. If you supplied a path, navigate to the location of the log file.
5. Open the log file with the pencil button next to the file name.
Disable debug logging when troubleshooting is complete:
To disable the enhanced debug log, perform either of the following:
Remove the <handlerSettings> from the web.config file locally and redeploy the app.
Use the Kudu console to edit the web.config file and remove the <handlerSettings> section. Save the
file.
For more information, see ASP.NET Core Module.
 WARNING
Failure to disable the debug log can lead to app or server failure. There's no limit on log file size. Only use debug
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.

Slow or hanging app (Azure App Service )

When an app responds slowly or hangs on a request, see the following articles:
Troubleshoot slow web app performance issues in Azure App Service
Use Crash Diagnoser Site Extension to Capture Dump for Intermittent Exception issues or performance
issues on Azure Web App
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.
2. Using the navigation bar at the top of the page, open Debug console and select CMD.
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.
5. Make a request to the app.
6. Within the log stream data, the cause of the error is indicated.
Be sure to disable stdout logging when troubleshooting is complete.
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
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.
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 on IIS
Application Event Log (IIS )
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 hosting 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 hosting configuration
and less likely within the app.
ASP.NET Core Module stdout log (IIS )
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.
6. Make a request to the app.
7. Navigate to the logs folder. Find and open the most recent stdout log.
8. Study the log for errors.
Disable stdout logging when troubleshooting is complete:
1. Edit the web.config file.
2. Set stdoutLogEnabled to false .
3. Save the file.
For more information, see ASP.NET Core Module.

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.
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.

ASP.NET Core Module debug log (IIS )

Add the following handler settings to the app's web.config file to enable ASP.NET Core Module debug log:

<aspNetCore ...>
<handlerSettings>
<handlerSetting name="debugLevel" value="file" />
<handlerSetting name="debugFile" value="c:\temp\ancm.log" />
</handlerSettings>
</aspNetCore>

Confirm that the path specified for the log exists and that the app pool's identity has write permissions to
the location.
For more information, see ASP.NET Core Module.
Enable 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.

<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile=".\logs\stdout"
hostingModel="InProcess">
<environmentVariables>
<environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
</environmentVariables>
</aspNetCore>

<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
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.
Obtain data from an app
If an app is capable of responding to requests, obtain request, connection, and additional data from the app
using terminal inline middleware. For more information and sample code, see Troubleshoot ASP.NET Core
projects.
Slow or hanging app (IIS )
A crash dump is a snapshot of the system's memory and can help determine the cause of an app crash,
startup failure, or slow app.
App crashes or encounters an exception
Obtain and analyze a dump from Windows Error Reporting (WER ):
1. Create a folder to hold crash dump files at c:\dumps . The app pool must have write access to the
folder.
2. Run the EnableDumps PowerShell script:
If the app uses the in-process hosting model, run the script for w3wp.exe:

.\EnableDumps w3wp.exe c:\dumps

If the app uses the out-of-process hosting model, run the script for dotnet.exe:

.\EnableDumps dotnet.exe c:\dumps

3. Run the app under the conditions that cause the crash to occur.
4. After the crash has occurred, run the DisableDumps PowerShell script:
If the app uses the in-process hosting model, run the script for w3wp.exe:
 .\DisableDumps w3wp.exe

If the app uses the out-of-process hosting model, run the script for dotnet.exe:

.\DisableDumps dotnet.exe

After an app crashes and dump collection is complete, the app is allowed to terminate normally. The
PowerShell script configures WER to collect up to five dumps per app.

WARNING
Crash dumps might take up a large amount of disk space (up to several gigabytes each).

App hangs, fails during startup, or runs normally

When an app hangs (stops responding but doesn't crash), fails during startup, or runs normally, see User-
Mode Dump Files: Choosing the Best Tool to select an appropriate tool to produce the dump.
Analyze the dump
A dump can be analyzed using several approaches. For more information, see Analyzing a User-Mode
Dump File.

Clear package caches

Sometimes a functioning app fails immediately after upgrading either the .NET Core SDK on the
development machine or changing 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 by executing dotnet nuget locals all --clear from a command shell.
Clearing package caches can also be accomplished with 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.
3. Restore and rebuild the project.
4. Delete all of the files in the deployment folder on the server prior to redeploying the app.

Additional resources
Troubleshoot ASP.NET Core projects
Common errors reference for Azure App Service and IIS with ASP.NET Core
Handle errors in ASP.NET Core
ASP.NET Core Module
Azure documentation
Application Insights for ASP.NET Core
Remote debugging web apps section of Troubleshoot a web app in Azure App Service using Visual
Studio
Azure App Service diagnostics overview
How to: Monitor Apps in Azure App Service
 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)
Visual Studio documentation
Remote Debug ASP.NET Core on IIS in Azure in Visual Studio 2017
Remote Debug ASP.NET Core on a Remote IIS Computer in Visual Studio 2017
Learn to debug using Visual Studio
Visual Studio Code documentation
Debugging with Visual Studio Code
 Common errors reference for Azure App Service
and IIS with ASP.NET Core
7/18/2019 • 14 minutes to read • Edit Online

By Luke Latham
This topic offers troubleshooting advice for common errors when hosting ASP.NET Core apps on Azure Apps
Service and IIS.
Collect the following information:
Browser behavior (status code and error message)
Application Event Log entries
Azure App Service – See Troubleshoot ASP.NET Core on Azure App Service and IIS.
IIS
1. Select Start on the Windows menu, type Event Viewer, and press Enter.
2. After the Event Viewer opens, expand Windows Logs > Application in the sidebar.
ASP.NET Core Module stdout and debug log entries
Azure App Service – See Troubleshoot ASP.NET Core on Azure App Service and IIS.
IIS – Follow the instructions in the Log creation and redirection and Enhanced diagnostic logs sections
of the ASP.NET Core Module topic.
Compare error information to the following common errors. If a match is found, follow the troubleshooting
advice.
The list of errors in this topic isn't exhaustive. If you encounter an error not listed here, open a new issue using
the Content feedback button at the bottom of this topic with detailed instructions on how to reproduce the
error.

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.

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 .NET Core 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 or Apps & features. If a specific runtime is required, download
the runtime from the .NET Download Archives and install it on the system. 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 app pool 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.

Missing site extension, 32-bit (x86) and 64-bit (x64) site extensions
installed, or wrong process bitness set
Applies to apps hosted by Azure App Services.
Browser: HTTP Error 500.0 - ANCM In-Process Handler Load Failure
Application Log: Invoking hostfxr to find the inprocess request handler failed without finding any native
dependencies. Could not find inprocess request handler. Captured output from invoking hostfxr: It was
not possible to find any compatible framework version. The specified framework
'Microsoft.AspNetCore.App', version '{VERSION }-preview -*' was not found. Failed to start application
'/LM/W3SVC/1416782824/ROOT', ErrorCode '0x8000ffff'.
ASP.NET Core Module stdout Log: It was not possible to find any compatible framework version. The
specified framework 'Microsoft.AspNetCore.App', version '{VERSION }-preview -*' was not found.
ASP.NET Core Module Debug Log: Invoking hostfxr to find the inprocess request handler failed without
finding any native dependencies. This most likely means the app is misconfigured, please check the versions
of Microsoft.NetCore.App and Microsoft.AspNetCore.App that are targeted by the application and are
installed on the machine. Failed HRESULT returned: 0x8000ffff. Could not find inprocess request handler. It
was not possible to find any compatible framework version. The specified framework
'Microsoft.AspNetCore.App', version '{VERSION }-preview -*' was not found.
Troubleshooting:
If running the app on a preview runtime, install either the 32-bit (x86) or 64-bit (x64) site extension that
matches the bitness of the app and the app's runtime version. Don't install both extensions or
multiple runtime versions of the extension.
ASP.NET Core {RUNTIME VERSION } (x86) Runtime
ASP.NET Core {RUNTIME VERSION } (x64) Runtime
Restart the app. Wait several seconds for the app to restart.
If running the app on a preview runtime and both the 32-bit (x86) and 64-bit (x64) site extensions are
installed, uninstall the site extension that doesn't match the bitness of the app. After removing the site
extension, restart the app. Wait several seconds for the app to restart.
If running the app on a preview runtime and the site extension's bitness matches that of the app, confirm
that the preview site extension's runtime version matches the app's runtime version.
Confirm that the app's Platform in Application Settings matches the bitness of the app.
For more information, see Deploy ASP.NET Core apps to Azure App Service.

An x86 app is deployed but the app pool isn't enabled for 32-bit apps
Browser: HTTP Error 500.30 - ANCM In-Process Start Failure
Application Log: Application '/LM/W3SVC/5/ROOT' with physical root '{PATH}' hit unexpected
managed exception, exception code = '0xe0434352'. Please check the stderr logs for more information.
Application '/LM/W3SVC/5/ROOT' with physical root '{PATH}' failed to load clr and managed application.
CLR worker thread exited prematurely
ASP.NET Core Module stdout Log: The log file is created but empty.
ASP.NET Core Module Debug Log: Failed HRESULT returned: 0x8007023e
This scenario is trapped by the SDK when publishing a self-contained app. The SDK produces an error if the RID
doesn't match the platform target (for example, win10-x64 RID with <PlatformTarget>x86</PlatformTarget> in
the project file).
Troubleshooting:
For an x86 framework-dependent deployment ( <PlatformTarget>x86</PlatformTarget> ), enable the IIS app pool
for 32-bit apps. In IIS Manager, open the app pool's Advanced Settings and set Enable 32-Bit Applications
to True.

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 stdout 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 Troubleshoot ASP.NET Core on Azure App Service and IIS.
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 --OR-- Unable to connect
Application Log: No entry
ASP.NET Core Module stdout Log: The log file isn't created.
ASP.NET Core Module Debug Log: The log file isn't created.
Troubleshooting:
Confirm the correct URI endpoint for the app is in use. 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.
Application Log: No entry
ASP.NET Core Module stdout Log: The log file isn't created.
ASP.NET Core Module Debug Log: The log file isn't created.
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, ASP.NET Core 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. --OR-- This page can't be displayed
Application Log: No entry
ASP.NET Core Module stdout Log: The log file isn't created.
ASP.NET Core Module Debug Log: The log file isn't created.
Troubleshooting:
Confirm that the proper role is enabled. See IIS Configuration.
Open Programs & Features or Apps & features and confirm that Windows Server Hosting is
installed. If Windows Server Hosting isn't present in the list of installed programs, download and install
the .NET Core Hosting Bundle.
Current .NET Core Hosting Bundle installer (direct download)
For more information, 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.
If you uninstalled the ASP.NET Core Hosting Bundle and installed an earlier version of the hosting
bundle, the applicationHost.config file doesn't include a section for the ASP.NET Core Module. Open
applicationHost.config at %windir%/System32/inetsrv/config and find the
<configuration><configSections><sectionGroup name="system.webServer"> section group. If the section for
the ASP.NET Core Module is missing from the section group, add the section element:
 <section name="aspNetCore" overrideModeDefault="Allow" />

Alternatively, install the latest version of the ASP.NET Core Hosting Bundle. The latest version is
backwards-compatible with supported ASP.NET Core apps.

Incorrect processPath, missing PATH variable, Hosting Bundle not

installed, system/IIS not restarted, VC++ Redistributable not installed,
or dotnet.exe access violation
Browser: HTTP Error 500.0 - ANCM In-Process Handler Load Failure
Application Log: Application 'MACHINE/WEBROOT/APPHOST/{ASSEMBLY }' with physical root 'C:
{PATH}' failed to start process with commandline '"{...}" ', ErrorCode = '0x80070002 : 0. Application
'{PATH}' wasn't able to start. Executable was not found at '{PATH}'. Failed to start application
'/LM/W3SVC/2/ROOT', ErrorCode '0x8007023e'.
ASP.NET Core Module stdout Log: The log file isn't created.
ASP.NET Core Module Debug Log: Event Log: 'Application '{PATH}' wasn't able to start. Executable
was not found at '{PATH}'. Failed HRESULT returned: 0x8007023e
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 '"{...}" ', ErrorCode = '0x80070002 : 0.
ASP.NET Core Module stdout Log: The log file is created but empty.
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 Troubleshoot ASP.NET Core on Azure App Service and IIS.
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 app pool. Confirm that the app
pool user identity has access to the C:\Program Files\dotnet directory. Confirm that there are no deny
rules configured for the app pool 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.
Current .NET Core Hosting Bundle installer (direct download)
For more information, see Install the .NET Core Hosting Bundle.
If a specific runtime is required, download the runtime from the .NET Download Archives and install it on
the system. 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

Browser: HTTP Error 500.0 - ANCM In-Process Handler Load Failure
Application Log: Invoking hostfxr to find the inprocess request handler failed without finding any native
dependencies. This most likely means the app is misconfigured, please check the versions of
Microsoft.NetCore.App and Microsoft.AspNetCore.App that are targeted by the application and are
installed on the machine. Could not find inprocess request handler. Captured output from invoking
hostfxr: Did you mean to run dotnet SDK commands? Please install dotnet SDK from:
https://go.microsoft.com/fwlink/?LinkID=798306&clcid=0x409 Failed to start application
'/LM/W3SVC/3/ROOT', ErrorCode '0x8000ffff'.
ASP.NET Core Module stdout Log: Did you mean to run dotnet SDK commands? Please install dotnet
SDK from: https://go.microsoft.com/fwlink/?LinkID=798306&clcid=0x409
ASP.NET Core Module Debug Log: Invoking hostfxr to find the inprocess request handler failed
without finding any native dependencies. This most likely means the app is misconfigured, please check
the versions of Microsoft.NetCore.App and Microsoft.AspNetCore.App that are targeted by the
application and are installed on the machine. Failed HRESULT returned: 0x8000ffff Could not find
inprocess request handler. Captured output from invoking hostfxr: Did you mean to run dotnet SDK
commands? Please install dotnet SDK from: https://go.microsoft.com/fwlink/?
LinkID=798306&clcid=0x409 Failed HRESULT returned: 0x8000ffff
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 '"dotnet" .{ASSEMBLY }.dll', ErrorCode = '0x80004005 :
80008081.
ASP.NET Core Module stdout Log: The application to execute does not exist: 'PATH{ASSEMBLY }.dll'
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 Troubleshoot ASP.NET Core on Azure App Service and IIS.
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="{ARGUMENT_1}, {ARGUMENT_2}, ... {ARGUMENT_X}" ) for a self-contained deployment ( SCD ).

Missing .NET Core shared framework

Browser: HTTP Error 500.0 - ANCM In-Process Handler Load Failure
Application Log: Invoking hostfxr to find the inprocess request handler failed without finding any native
dependencies. This most likely means the app is misconfigured, please check the versions of
Microsoft.NetCore.App and Microsoft.AspNetCore.App that are targeted by the application and are
installed on the machine. Could not find inprocess request handler. Captured output from invoking
hostfxr: It was not possible to find any compatible framework version. The specified framework
'Microsoft.AspNetCore.App', version '{VERSION }' was not found.
Failed to start application '/LM/W3SVC/5/ROOT', ErrorCode '0x8000ffff'.
 ASP.NET Core Module stdout Log: It was not possible to find any compatible framework version. The
specified framework 'Microsoft.AspNetCore.App', version '{VERSION }' was not found.
ASP.NET Core Module Debug Log: Failed HRESULT returned: 0x8000ffff
Troubleshooting:
For a framework-dependent deployment (FDD ), confirm that the correct runtime installed on the system.

Stopped Application Pool

Browser: 503 Service Unavailable
Application Log: No entry
ASP.NET Core Module stdout Log: The log file isn't created.
ASP.NET Core Module Debug Log: The log file isn't created.
Troubleshooting:
Confirm that the Application Pool isn't in the Stopped state.

Sub-application includes a <handlers> section

Browser: HTTP Error 500.19 - Internal Server Error
Application Log: No entry
ASP.NET Core Module stdout Log: The root app's log file is created and shows normal operation. The
sub-app's log file isn't created.
ASP.NET Core Module Debug Log: The root app's log file is created and shows normal operation. The
sub-app's log file isn't created.
Troubleshooting:
Confirm that the sub-app's web.config file doesn't include a <handlers> section or that the sub-app doesn't
inherit the parent app's handlers.
The parent app's <system.webServer> section of web.config is placed inside of a <location> element. The
InheritInChildApplications property is set to false to indicate that the settings specified within the <location>
element aren't inherited by apps that reside in a subdirectory of the parent app. For more information, see
ASP.NET Core Module.
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: Could not start stdout redirection in C:\Program Files\IIS\Asp.Net Core
Module\V2\aspnetcorev2.dll. Exception message: HRESULT 0x80070005 returned at
{PATH}\aspnetcoremodulev2\commonlib\fileoutputmanager.cpp:84. Could not stop stdout redirection in
C:\Program Files\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll. Exception message: HRESULT
0x80070002 returned at {PATH}. Could not start stdout redirection in {PATH}\aspnetcorev2_inprocess.dll.
ASP.NET Core Module stdout Log: The log file isn't created.
ASP.NET Core Module debug Log: Could not start stdout redirection in C:\Program Files\IIS\Asp.Net
 Core Module\V2\aspnetcorev2.dll. Exception message: HRESULT 0x80070005 returned at
{PATH}\aspnetcoremodulev2\commonlib\fileoutputmanager.cpp:84. Could not stop stdout redirection in
C:\Program Files\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll. Exception message: HRESULT
0x80070002 returned at {PATH}. Could not start stdout redirection in {PATH}\aspnetcorev2_inprocess.dll.
Application Log: Warning: Could not create stdoutLogFile \?
{PATH}\path_doesnt_exist\stdout_{PROCESS ID }_{TIMESTAMP }.log, ErrorCode = -2147024893.
ASP.NET Core Module stdout Log: The log file isn't created.
Troubleshooting:
The stdoutLogFile path specified in the <aspNetCore> element of web.config doesn't exist. For more
information, see ASP.NET Core Module: Log creation and redirection.
The app pool user doesn't have write access to the stdout log path.

Application configuration general issue

Browser: HTTP Error 500.0 - ANCM In-Process Handler Load Failure --OR-- HTTP Error 500.30 -
ANCM In-Process Start Failure
Application Log: Variable
ASP.NET Core Module stdout Log: The log file is created but empty or created with normal entries
until the point of the app failing.
ASP.NET Core Module Debug Log: Variable
Browser: HTTP Error 502.5 - Process Failure
Application Log: Application 'MACHINE/WEBROOT/APPHOST/{ASSEMBLY }' with physical root 'C:
{PATH}' created process with commandline '"C:{PATH}{ASSEMBLY }.{exe|dll}" ' but either crashed or did
not respond or did not listen on the given port '{PORT}', ErrorCode = '{ERROR CODE }'
ASP.NET Core Module stdout Log: The log file is created but empty.
Troubleshooting:
The process failed to start, most likely due to an app configuration or programming issue.
For more information, see the following topics:
Troubleshoot ASP.NET Core on Azure App Service and IIS
Troubleshoot ASP.NET Core projects
 Transform web.config
7/11/2019 • 2 minutes to read • Edit Online

By Vijay Ramakrishnan and Luke Latham

Transformations to the web.config file can be applied automatically when an app is published based on:
Build configuration
Profile
Environment
Custom
These transformations occur for either of the following web.config generation scenarios:
Generated automatically by the Microsoft.NET.Sdk.Web SDK.
Provided by the developer in the content root of the app.

Build configuration
Build configuration transforms are run first.
Include a web.{CONFIGURATION }.config file for each build configuration (Debug|Release) requiring a web.config
transformation.
In the following example, a configuration-specific environment variable is set in web.Release.config:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
<location>
<system.webServer>
<aspNetCore>
<environmentVariables xdt:Transform="InsertIfMissing">
<environmentVariable name="Configuration_Specific"
value="Configuration_Specific_Value"
xdt:Locator="Match(name)"
xdt:Transform="InsertIfMissing" />
</environmentVariables>
</aspNetCore>
</system.webServer>
</location>
</configuration>

The transform is applied when the configuration is set to Release:

dotnet publish --configuration Release

The MSBuild property for the configuration is $(Configuration) .

Profile
Profile transformations are run second, after Build configuration transforms.
Include a web.{PROFILE }.config file for each profile configuration requiring a web.config transformation.
In the following example, a profile-specific environment variable is set in web.FolderProfile.config for a folder
publish profile:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
<location>
<system.webServer>
<aspNetCore>
<environmentVariables xdt:Transform="InsertIfMissing">
<environmentVariable name="Profile_Specific"
value="Profile_Specific_Value"
xdt:Locator="Match(name)"
xdt:Transform="InsertIfMissing" />
</environmentVariables>
</aspNetCore>
</system.webServer>
</location>
</configuration>

The transform is applied when the profile is FolderProfile:

dotnet publish --configuration Release /p:PublishProfile=FolderProfile

The MSBuild property for the profile name is $(PublishProfile) .

If no profile is passed, the default profile name is FileSystem and web.FileSystem.config is applied if the file is
present in the app's content root.

Environment
Environment transformations are run third, after Build configuration and Profile transforms.
Include a web.{ENVIRONMENT }.config file for each environment requiring a web.config transformation.
In the following example, a environment-specific environment variable is set in web.Production.config for the
Production environment:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
<location>
<system.webServer>
<aspNetCore>
<environmentVariables xdt:Transform="InsertIfMissing">
<environmentVariable name="Environment_Specific"
value="Environment_Specific_Value"
xdt:Locator="Match(name)"
xdt:Transform="InsertIfMissing" />
</environmentVariables>
</aspNetCore>
</system.webServer>
</location>
</configuration>

The transform is applied when the environment is Production:

dotnet publish --configuration Release /p:EnvironmentName=Production

The MSBuild property for the environment is $(EnvironmentName) .

When publishing from Visual Studio and using a publish profile, see Visual Studio publish profiles for ASP.NET
Core app deployment.
The ASPNETCORE_ENVIRONMENT environment variable is automatically added to the web.config file when the
environment name is specified.

Custom
Custom transformations are run last, after Build configuration, Profile, and Environment transforms.
Include a {CUSTOM_NAME }.transform file for each custom configuration requiring a web.config transformation.
In the following example, a custom transform environment variable is set in custom.transform:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
<location>
<system.webServer>
<aspNetCore>
<environmentVariables xdt:Transform="InsertIfMissing">
<environmentVariable name="Custom_Specific"
value="Custom_Specific_Value"
xdt:Locator="Match(name)"
xdt:Transform="InsertIfMissing" />
</environmentVariables>
</aspNetCore>
</system.webServer>
</location>
</configuration>

The transform is applied when the CustomTransformFileName property is passed to the dotnet publish command:

dotnet publish --configuration Release /p:CustomTransformFileName=custom.transform

The MSBuild property for the profile name is $(CustomTransformFileName) .

Prevent web.config transformation

To prevent transformations of the web.config file, set the MSBuild property $(IsWebConfigTransformDisabled) :

dotnet publish /p:IsWebConfigTransformDisabled=true

Additional resources
Web.config Transformation Syntax for Web Application Project Deployment
Web.config Transformation Syntax for Web Project Deployment Using Visual Studio
 Kestrel web server implementation in ASP.NET
Core
7/24/2019 • 25 minutes to read • Edit Online

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 scenarios:
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.
View or download sample code (how to download)

HTTP/2 support
HTTP/2 is available for ASP.NET Core apps if the following base requirements are met:
Operating system†
Windows Server 2016/Windows 10 or later‡
Linux with OpenSSL 1.0.2 or later (for example, Ubuntu 16.04 or later)
Target framework: .NET Core 2.2 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. ‡Kestrel has limited support for HTTP/2 on
Windows Server 2012 R2 and Windows 8.1. Support is limited because the list of supported TLS cipher
suites available on these operating systems is limited. A certificate generated using an Elliptic Curve
Digital Signature Algorithm (ECDSA) may be required to secure TLS connections.
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
ListenOptions.Protocols sections.

When to use Kestrel with a reverse proxy

Kestrel can be used by itself or with a reverse proxy server, such as Internet Information Services (IIS ),
Nginx, or Apache. A reverse proxy server receives HTTP requests from the network and forwards them
to Kestrel.
Kestrel used as an edge (Internet-facing) web server:

Kestrel used in a reverse proxy configuration:

Either configuration—with or without a reverse proxy server—is a supported hosting configuration for
ASP.NET Core 2.1 or later apps that receive requests from the Internet.
Kestrel used as an edge server without a reverse proxy server 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 headers. 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.
A reverse proxy:
Can limit the exposed public surface area of the apps that it hosts.
Provide an additional layer of configuration and defense.
Might integrate better with existing infrastructure.
Simplify load balancing and secure communication (HTTPS ) configuration. Only the reverse proxy
server requires an X.509 certificate, and that server can communicate with your app servers on the
internal network using plain HTTP.

WARNING
Hosting in a reverse proxy configuration requires host filtering.

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.

public static void Main(string[] args)

{
CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>();

To provide additional configuration after calling CreateDefaultBuilder , use ConfigureKestrel :

 public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureKestrel((context, options) =>
{
// Set properties and call methods on options
});

If the app doesn't call CreateDefaultBuilder to set up the host, call UseKestrel before calling
ConfigureKestrel :

public static void Main(string[] args)

{
var host = new WebHostBuilder()
.UseContentRoot(Directory.GetCurrentDirectory())
.UseKestrel()
.UseIISIntegration()
.UseStartup<Startup>()
.ConfigureKestrel((context, options) =>
{
// Set properties and call methods on options
})
.Build();

host.Run();
}

To provide additional configuration after calling CreateDefaultBuilder , call UseKestrel:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.UseKestrel(options =>
{
// Set properties and call methods on options
});

Kestrel options
The Kestrel web server has constraint configuration options that are especially useful in Internet-facing
deployments.
Set constraints on the Limits property of the KestrelServerOptions class. The Limits property holds an
instance of the KestrelServerLimits class.
The following examples use the Microsoft.AspNetCore.Server.Kestrel.Core namespace:

using Microsoft.AspNetCore.Server.Kestrel.Core;

Keep-alive timeout
KeepAliveTimeout
Gets or sets the keep-alive timeout. Defaults to 2 minutes.
 .ConfigureKestrel((context, options) =>
{
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 =
new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
options.Listen(IPAddress.Loopback, 5000);
options.Listen(IPAddress.Loopback, 5001, listenOptions =>
{
listenOptions.UseHttps("testCert.pfx", "testPassword");
});
options.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
options.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.UseKestrel(options =>
{
options.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
});

Maximum client connections

MaxConcurrentConnections MaxConcurrentUpgradedConnections
The maximum number of concurrent open TCP connections can be set for the entire app with the
following code:

.ConfigureKestrel((context, options) =>

{
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 =
new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
options.Listen(IPAddress.Loopback, 5000);
options.Listen(IPAddress.Loopback, 5001, listenOptions =>
{
listenOptions.UseHttps("testCert.pfx", "testPassword");
});
options.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
options.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.UseKestrel(options =>
{
options.Limits.MaxConcurrentConnections = 100;
});

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.

.ConfigureKestrel((context, options) =>

{
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 =
new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
options.Listen(IPAddress.Loopback, 5000);
options.Listen(IPAddress.Loopback, 5001, listenOptions =>
{
listenOptions.UseHttps("testCert.pfx", "testPassword");
});
options.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
options.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.UseKestrel(options =>
{
options.Limits.MaxConcurrentUpgradedConnections = 100;
});

The maximum number of connections is unlimited (null) by default.

Maximum request body size
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
RequestSizeLimitAttribute 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:

.ConfigureKestrel((context, options) =>

{
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 =
new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
options.Listen(IPAddress.Loopback, 5000);
options.Listen(IPAddress.Loopback, 5001, listenOptions =>
{
listenOptions.UseHttps("testCert.pfx", "testPassword");
});
options.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
options.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});
 public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.UseKestrel(options =>
{
options.Limits.MaxRequestBodySize = 10 * 1024;
});

You can override the setting on a specific request in middleware:

app.Run(async (context) =>

{
context.Features.Get<IHttpMaxRequestBodySizeFeature>()
.MaxRequestBodySize = 10 * 1024;

var minRequestRateFeature =
context.Features.Get<IHttpMinRequestBodyDataRateFeature>();
var minResponseRateFeature =
context.Features.Get<IHttpMinResponseDataRateFeature>();

if (minRequestRateFeature != null)
{
minRequestRateFeature.MinDataRate = new MinDataRate(
bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
}

if (minResponseRateFeature != null)
{
minResponseRateFeature.MinDataRate = new MinDataRate(
bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
}

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.
When an app is run out-of-process behind the ASP.NET Core Module, Kestrel's request body size limit
is disabled because IIS already sets the limit.
Minimum request body data rate
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:
 .ConfigureKestrel((context, options) =>
{
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 =
new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
options.Listen(IPAddress.Loopback, 5000);
options.Listen(IPAddress.Loopback, 5001, listenOptions =>
{
listenOptions.UseHttps("testCert.pfx", "testPassword");
});
options.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
options.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.UseKestrel(options =>
{
options.Limits.MinRequestBodyDataRate =
new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
options.Limits.MinResponseDataRate =
new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
});

You can override the minimum rate limits per request in middleware:

app.Run(async (context) =>

{
context.Features.Get<IHttpMaxRequestBodySizeFeature>()
.MaxRequestBodySize = 10 * 1024;

var minRequestRateFeature =
context.Features.Get<IHttpMinRequestBodyDataRateFeature>();
var minResponseRateFeature =
context.Features.Get<IHttpMinResponseDataRateFeature>();

if (minRequestRateFeature != null)
{
minRequestRateFeature.MinDataRate = new MinDataRate(
bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
}

if (minResponseRateFeature != null)
{
minResponseRateFeature.MinDataRate = new MinDataRate(
bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
}

The IHttpMinResponseDataRateFeature referenced in the prior sample is not present in

HttpContext.Features for HTTP/2 requests because modifying rate limits on a per -request basis is
generally not supported for HTTP/2 due to the protocol's support for request multiplexing. However,
the IHttpMinRequestBodyDataRateFeature is still present HttpContext.Features for HTTP/2 requests,
because the read rate limit can still be disabled entirely on a per-request basis by setting
IHttpMinRequestBodyDataRateFeature.MinDataRate to null even for an HTTP/2 request. Attempting to
read IHttpMinRequestBodyDataRateFeature.MinDataRate or attempting to set it to a value other than null
will result in a NotSupportedException being thrown given an HTTP/2 request.
Server-wide rate limits configured via KestrelServerOptions.Limits still apply to both HTTP/1.x and
HTTP/2 connections.
Neither rate feature referenced in the prior sample are present in HttpContext.Features for HTTP/2
requests because modifying rate limits on a per-request basis isn't supported for HTTP/2 due to the
protocol's support for request multiplexing. Server-wide rate limits configured via
KestrelServerOptions.Limits still apply to both HTTP/1.x and HTTP/2 connections.

Request headers timeout

RequestHeadersTimeout
Gets or sets the maximum amount of time the server spends receiving request headers. Defaults to 30
seconds.

.ConfigureKestrel((context, options) =>

{
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 =
new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
options.Listen(IPAddress.Loopback, 5000);
options.Listen(IPAddress.Loopback, 5001, listenOptions =>
{
listenOptions.UseHttps("testCert.pfx", "testPassword");
});
options.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
options.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.UseKestrel(options =>
{
options.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

Maximum streams per connection

Http2.MaxStreamsPerConnection limits the number of concurrent request streams per HTTP/2
connection. Excess streams are refused.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureKestrel((context, options) =>
{
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).

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureKestrel((context, options) =>
{
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).

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureKestrel((context, options) =>
{
options.Limits.Http2.MaxFrameSize = 16384;
});

The default value is 2^14 (16,384).

Maximum request header size
Http2.MaxRequestHeaderFieldSize indicates the maximum allowed size in octets of request header
values. This limit applies to both name and value together in their compressed and uncompressed
representations. The value must be greater than zero (0).

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureKestrel((context, options) =>
{
options.Limits.Http2.MaxRequestHeaderFieldSize = 8192;
});

The default value is 8,192.

Initial connection window size
Http2.InitialConnectionWindowSize indicates the maximum request body data in bytes the server
buffers at one time aggregated across all requests (streams) per connection. Requests are also limited
by Http2.InitialStreamWindowSize . The value must be greater than or equal to 65,535 and less than
2^31 (2,147,483,648).

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureKestrel((context, options) =>
{
options.Limits.Http2.InitialConnectionWindowSize = 131072;
});

The default value is 128 KB (131,072).

Initial stream window size
Http2.InitialStreamWindowSize indicates the maximum request body data in bytes the server buffers at
( )
one time per request stream . Requests are also limited by Http2.InitialStreamWindowSize . The value
must be greater than or equal to 65,535 and less than 2^31 (2,147,483,648).

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureKestrel((context, options) =>
{
options.Limits.Http2.InitialStreamWindowSize = 98304;
});

The default value is 96 KB (98,304).

Synchronous IO
AllowSynchronousIO controls whether synchronous IO is allowed for the request and response. The
default value is false .
AllowSynchronousIO controls whether synchronous IO is allowed for the request and response. The
default value is true .

WARNING
A large number of blocking synchronous IO operations can lead to thread pool starvation, which makes the app
unresponsive. Only enable AllowSynchronousIO when using a library that doesn't support asynchronous IO.

The following example enables synchronous IO:

.ConfigureKestrel((context, options) =>

{
options.AllowSynchronousIO = true;
});

The following example disables synchronous IO:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.UseKestrel(options =>
{
options.AllowSynchronousIO = false;
});

For information about other Kestrel options and limits, see:

KestrelServerOptions
KestrelServerLimits
ListenOptions

Endpoint configuration
By default, ASP.NET Core binds to:
http://localhost:5000
 https://localhost:5001 (when a local development certificate is present)

Specify URLs using the:

ASPNETCORE_URLS environment variable.
--urls command-line argument.
urls host configuration key.
UseUrls extension method.

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" ).

For more information on these approaches, see Server URLs and Override configuration.
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 or later 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.

Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.ConfigureKestrel(serverOptions =>
{
serverOptions.ConfigureEndpointDefaults(configureOptions =>
{
configureOptions.NoDelay = true;
});
});
webBuilder.UseStartup<Startup>();
});
 public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureKestrel((context, options) =>
{
options.ConfigureEndpointDefaults(configureOptions =>
{
configureOptions.NoDelay = true;
});
});

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.

Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.ConfigureKestrel(serverOptions =>
{
serverOptions.ConfigureHttpsDefaults(options =>
{
// certificate is an X509Certificate2
options.ServerCertificate = certificate;
});
});
webBuilder.UseStartup<Startup>();
});

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureKestrel((context, options) =>
{
options.ConfigureHttpsDefaults(httpsOptions =>
{
// certificate is an X509Certificate2
httpsOptions.ServerCertificate = certificate;
});
});

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).
Replace the default certificate from configuration
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": {
"Url": "https://localhost:5002",
"Certificate": {
"Subject": "<subject; required>",
"Store": "<certificate store; required>",
"Location": "<location; defaults to CurrentUser>",
"AllowInvalid": "<true or false; defaults to false>"
}
},

"HttpsDefaultCert": {
"Url": "https://localhost:5003"
},

"Https": {
"Url": "https://*:5004",
"Certificate": {
"Path": "<path to .pfx file>",
"Password": "<certificate password>"
}
}
},
"Certificates": {
"Default": {
"Path": "<path to .pfx file>",
"Password": "<certificate password>"
}
}
}
}

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; required>",
"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
KestrelConfigurationLoaderwith 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 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.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureKestrel((context, options) =>
{
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,
allowInvalid: true);
var subExampleCert = CertificateLoader.LoadFromStoreCert(
"sub.example.com", "My", StoreLocation.CurrentUser,
allowInvalid: true);
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;
};
});
});
});
 public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.UseKestrel((context, options) =>
{
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,
allowInvalid: true);
var subExampleCert = CertificateLoader.LoadFromStoreCert(
"sub.example.com", "My", StoreLocation.CurrentUser,
allowInvalid: true);
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 X.509 certificate
configuration:

public static void Main(string[] args)

{
CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureKestrel((context, options) =>
{
options.Listen(IPAddress.Loopback, 5000);
options.Listen(IPAddress.Loopback, 5001, listenOptions =>
{
listenOptions.UseHttps("testCert.pfx", "testPassword");
});
});
 public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.UseKestrel(options =>
{
options.Listen(IPAddress.Loopback, 5000);
options.Listen(IPAddress.Loopback, 5001, listenOptions =>
{
listenOptions.UseHttps("testCert.pfx", "testPassword");
});
});

public static void Main(string[] args)

{
CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.UseKestrel(options =>
{
options.Listen(IPAddress.Loopback, 5000);
options.Listen(IPAddress.Loopback, 5001, listenOptions =>
{
listenOptions.UseHttps("testCert.pfx", "testPassword");
});
});

The example configures HTTPS 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:

.ConfigureKestrel((context, options) =>

{
options.ListenUnixSocket("/tmp/kestrel-test.sock");
options.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions =>
{
listenOptions.UseHttps("testCert.pfx", "testpassword");
});
});
 public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.UseKestrel(options =>
{
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:

public void Configure(IApplicationBuilder app)

{
var serverAddressesFeature =
app.ServerFeatures.Get<IServerAddressesFeature>();

app.UseStaticFiles();

app.Run(async (context) =>

{
context.Response.ContentType = "text/html";
await context.Response
.WriteAsync("<!DOCTYPE html><html lang=\"en\"><head>" +
"<title></title></head><body><p>Hosted by Kestrel</p>");

if (serverAddressesFeature != null)
{
await context.Response
.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:
 HTTPS 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.
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:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureKestrel((context, options) =>
{
options.Listen(IPAddress.Any, 8000, listenOptions =>
{
listenOptions.Protocols = HttpProtocols.Http1AndHttp2;
listenOptions.UseHttps("testCert.pfx", "testPassword");
});
});
Optionally create an IConnectionAdapter implementation to filter TLS handshakes on a per-connection
basis for specific ciphers:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureKestrel((context, options) =>
{
options.Listen(IPAddress.Any, 8000, listenOptions =>
{
listenOptions.Protocols = HttpProtocols.Http1AndHttp2;
listenOptions.UseHttps("testCert.pfx", "testPassword");
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; }

public void Dispose()

{
}
}
}

Set the protocol from configuration

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": {
"Url": "https://localhost:5001",
"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 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 UseLibuv:

public class Program

{
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseLibuv()
.UseStartup<Startup>();
}

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 HTTPS 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.

IPv6 address with port number

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
Hosting in a reverse proxy configuration requires host filtering.

Host localhost name with port number or loopback IP with port number

http://localhost:5000/
http://127.0.0.1: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.

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. Host headers aren't validated.
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:
 public class Program
{
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>();
}

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 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 a public-facing 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.

Additional resources
Troubleshoot ASP.NET Core projects
Enforce HTTPS in ASP.NET Core
Configure ASP.NET Core to work with proxy servers and load balancers
Kestrel source code
RFC 7230: Message Syntax and Routing (Section 5.4: Host)
 HTTP.sys web server implementation in ASP.NET
Core
7/11/2019 • 10 minutes to read • Edit Online

By Tom Dykstra, Chris Ross, and Luke Latham

HTTP.sys is a web server for ASP.NET Core that only runs on Windows. HTTP.sys is an alternative to Kestrel
server and offers some features that Kestrel doesn't provide.

IMPORTANT
HTTP.sys isn't compatible 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
Windows Server 2008 R2 or later
View or download sample code (how to download)

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:
Windows Server 2016/Windows 10 or later
Application-Layer Protocol Negotiation (ALPN ) connection
TLS 1.2 or later 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 host, specifying any required HttpSysOptions.
The following example sets options to their default values:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.UseHttpSys(options =>
{
options.AllowSynchronousIO = false;
options.Authentication.Schemes = AuthenticationSchemes.None;
options.Authentication.AllowAnonymous = true;
options.MaxConnections = null;
options.MaxRequestBodySize = 30000000;
options.UrlPrefixes.Add("http://localhost:5000");
});
 public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.UseHttpSys(options =>
{
options.AllowSynchronousIO = true;
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 false

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 concurrent 5 × Environment.

accepts. ProcessorCount

MaxConnections The maximum number of concurrent null

connections to accept. Use -1 for (unlimited)
infinite. Use null to use the
registry's machine-wide setting.

MaxRequestBodySize See the MaxRequestBodySize section. 30000000 bytes

(~28.6 MB)

RequestQueueLimit The maximum number of requests 1000

that can be queued.
PROPERTY DESCRIPTION DEFAULT

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.DrainEntityB
ody – 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.HeaderWait
– Time allowed for the HTTP
Server API to parse the
request header.
TimeoutManager.IdleConnecti
on – Time allowed for an idle
connection.
TimeoutManager.MinSendByte
sPerSecond – The minimum
send rate for the response.
TimeoutManager.RequestQue
ue – 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.

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

PROPERTY DESCRIPTION DEFAULT

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 concurrent 5 × Environment.

accepts. ProcessorCount

MaxConnections The maximum number of concurrent null

connections to accept. Use -1 for (unlimited)
infinite. Use null to use the
registry's machine-wide setting.

MaxRequestBodySize See the MaxRequestBodySize section. 30000000 bytes

(~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.
 PROPERTY DESCRIPTION DEFAULT

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.DrainEntityB
ody – 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.HeaderWait
– Time allowed for the HTTP
Server API to parse the
request header.
TimeoutManager.IdleConnecti
on – Time allowed for an idle
connection.
TimeoutManager.MinSendByte
sPerSecond – The minimum
send rate for the response.
TimeoutManager.RequestQue
ue – 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, IServer server)
{
app.Use(async (context, next) =>
{
context.Features.Get<IHttpMaxRequestBodySizeFeature>()
.MaxRequestBodySize = 10 * 1024;

var serverAddressesFeature =
app.ServerFeatures.Get<IServerAddressesFeature>();
var addresses = string.Join(", ", serverAddressesFeature?.Addresses);

logger.LogInformation($"Addresses: {addresses}");

await next.Invoke();
});

if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}

// Enable HTTPS Redirection Middleware when hosting the app securely.

//app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseCookiePolicy();
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. Determine the ports to open for the app and use Windows Firewall or the New -NetFirewallRule
PowerShell cmdlet to open firewall ports to allow traffic to reach HTTP.sys. In the following commands
and app configuration, port 443 is used.
2. When deploying to an Azure VM, open the ports in the Network Security Group. In the following
commands and app configuration, port 443 is used.
3. Obtain and install X.509 certificates, if required.
On Windows, create self-signed certificates using the New -SelfSignedCertificate PowerShell cmdlet.
For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.
Install either self-signed or CA-signed certificates in the server's Local Machine > Personal store.
4. 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 Runtime installer from
.NET Core Downloads. Don't install the full SDK on the server.
.NET Framework – If the app requires .NET Framework, see the .NET Framework installation
guide. Install the required .NET Framework. The installer for the latest .NET Framework is available
from the .NET Core Downloads page.
If the app is a self-contained deployment, the app includes the runtime in its deployment. No
framework installation is required on the server.
5. Configure URLs and ports in the app.
By default, ASP.NET Core binds to http://localhost:5000 . To configure URL prefixes and ports,
options include:
UseUrls
urls command-line argument
ASPNETCORE_URLS environment variable
UrlPrefixes
The following code example shows how to use UrlPrefixes with the server's local IP address 10.0.0.4
on port 443:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.UseHttpSys(options =>
{
options.UrlPrefixes.Add("https://10.0.0.4:443");
});

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.
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
create app security vulnerabilities. This applies to both strong and weak wildcards. Use explicit host names or IP
addresses rather than wildcards. Subdomain wildcard binding (for example, *.mysub.com ) isn't a security risk if
you control the entire parent domain (as opposed to *.com , which is vulnerable). For more information, see
RFC 7230: Section 5.4: Host.

6. Preregister URL prefixes on the server.

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.
Use the netsh.exe tool to register URLs for the app:
 netsh http add urlacl url=<URL> user=<USER>

<URL> – The fully qualified Uniform Resource Locator (URL ). Don't use a wildcard binding. Use a
valid hostname or local IP address. The URL must include a trailing slash.
<USER> – Specifies the user or user -group name.
In the following example, the local IP address of the server is 10.0.0.4 :

netsh http add urlacl url=https://10.0.0.4:443/ user=Users

When a URL is registered, the tool responds with URL reservation successfully added .
To delete a registered URL, use the delete urlacl command:

netsh http delete urlacl url=<URL>

7. Register X.509 certificates on the server.

Use the netsh.exe tool to register certificates for the app:

netsh http add sslcert ipport=<IP>:<PORT> certhash=<THUMBPRINT> appid="{<GUID>}"

<IP> – Specifies the local IP address for the binding. Don't use a wildcard binding. Use a valid IP
address.
<PORT> – Specifies the port for the binding.
<THUMBPRINT> – The X.509 certificate thumbprint.
<GUID> – A developer -generated GUID to represent the app for informational purposes.
For reference purposes, store the GUID in the app as a package tag:
In Visual Studio:
Open the app's project properties by right-clicking on the app in Solution Explorer and
selecting Properties.
Select the Package tab.
Enter the GUID that you created in the Tags field.
When not using Visual Studio:
Open the app's project file.
Add a <PackageTags> property to a new or existing <PropertyGroup> with the GUID that
you created:

<PropertyGroup>
<PackageTags>9412ee86-c21b-4eb8-bd89-f650fbf44931</PackageTags>
</PropertyGroup>

In the following example:

The local IP address of the server is 10.0.0.4 .
An online random GUID generator provides the appid value.
 netsh http add sslcert
ipport=10.0.0.4:443
certhash=b66ee04419d4ee37464ab8785ff02449980eae10
appid="{9412ee86-c21b-4eb8-bd89-f650fbf44931}"

When a certificate is registered, the tool responds with SSL Certificate successfully added .
To delete a certificate registration, use the delete sslcert command:

netsh http delete sslcert ipport=<IP>:<PORT>

Reference documentation for netsh.exe:

Netsh Commands for Hypertext Transfer Protocol (HTTP )
UrlPrefix Strings
8. Run the app.
Administrator privileges aren't required to run the app when binding to localhost using HTTP (not
HTTPS ) with a port number greater than 1024. For other configurations (for example, using a local IP
address or binding to port 443), run the app with administrator privileges.
The app responds at the server's public IP address. In this example, the server is reached from the
Internet at its public IP address of 104.214.79.47 .
A development certificate is used in this example. The page loads securely after bypassing the browser's
untrusted certificate warning.

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.

Additional resources
Enable Windows Authentication with HTTP.sys
HTTP Server API
aspnet/HttpSysServer GitHub repository (source code)
The host
Troubleshoot ASP.NET Core projects
 Host ASP.NET Core in a Windows Service
8/9/2019 • 9 minutes to read • Edit Online

By Luke Latham and Tom Dykstra

An ASP.NET Core app can be hosted on Windows as a Windows Service without using IIS. When hosted as a
Windows Service, the app automatically starts after server reboots.
View or download sample code (how to download)

Prerequisites
ASP.NET Core SDK 2.1 or later
PowerShell 6.2 or later

Worker Service template

The ASP.NET Core Worker Service template provides a starting point for writing long running service apps. To
use the template as a basis for a Windows Service app:
1. Create a Worker Service app from the .NET Core template.
2. Follow the guidance in the App configuration section to update the Worker Service app so that it can run as a
Windows Service.
Visual Studio
.NET Core CLI
1. Create a new project.
2. Select ASP.NET Core Web Application. Select Next.
3. Provide a project name in the Project name field or accept the default project name. Select Create.
4. In the Create a new ASP.NET Core Web Application dialog, confirm that .NET Core and ASP.NET Core
3.0 are selected.
5. Select the Worker Service template. Select Create.

App configuration
IHostBuilder.UseWindowsService , provided by the Microsoft.Extensions.Hosting.WindowsServices package, is
called when building the host. If the app is running as a Windows Service, the method:
Sets the host lifetime to WindowsServiceLifetime .
Sets the content root.
Enables logging to the event log with the application name as the default source name.
The log level can be configured using the Logging:LogLevel:Default key in the
appsettings.Production.json file.
Only administrators can create new event sources. When an event source can't be created using the
application name, a warning is logged to the Application source and event logs are disabled.
 public class Program
{
public static async Task Main(string[] args)
{
await CreateHostBuilder(args).Build().RunAsync();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.UseWindowsService()
.ConfigureAppConfiguration((context, config) =>
{
// Configure the app here.
})
.ConfigureServices((hostContext, services) =>
{
services.AddHostedService<ServiceA>();
services.AddHostedService<ServiceB>();
})
// Only required if the service responds to requests.
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}

The app requires package references for Microsoft.AspNetCore.Hosting.WindowsServices and

Microsoft.Extensions.Logging.EventLog.
To test and debug when running outside of a service, add code to determine if the app is running as a service or a
console app. Inspect if the debugger is attached or a --console switch is present. If either condition is true (the
app isn't run as a service), call Run. If the conditions are false (the app is run as a service):
Call SetCurrentDirectory and use a path to the app's published location. Don't call GetCurrentDirectory to
obtain the path because a Windows Service app returns the C:\WINDOWS\system32 folder when
GetCurrentDirectory is called. For more information, see the Current directory and content root section. This
step is performed before the app is configured in CreateWebHostBuilder .
Call RunAsService to run the app as a service.
Because the Command-line Configuration Provider requires name-value pairs for command-line arguments, the
--console switch is removed from the arguments before CreateDefaultBuilder receives the arguments.

To write to the Windows Event Log, add the EventLog provider to ConfigureLogging. Set the logging level with
the Logging:LogLevel:Default key in the appsettings.Production.json file.
In the following example from the sample app, RunAsCustomService is called instead of RunAsService in order to
handle lifetime events within the app. For more information, see the Handle starting and stopping events section.
 public class Program
{
public static void Main(string[] args)
{
var isService = !(Debugger.IsAttached || args.Contains("--console"));

if (isService)
{
var pathToExe = Process.GetCurrentProcess().MainModule.FileName;
var pathToContentRoot = Path.GetDirectoryName(pathToExe);
Directory.SetCurrentDirectory(pathToContentRoot);
}

var builder = CreateWebHostBuilder(

args.Where(arg => arg != "--console").ToArray());

var host = builder.Build();

if (isService)
{
// To run the app without the CustomWebHostService change the
// next line to host.RunAsService();
host.RunAsCustomService();
}
else
{
host.Run();
}
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

WebHost.CreateDefaultBuilder(args)
.ConfigureLogging((hostingContext, logging) =>
{
logging.AddEventLog();
})
.ConfigureAppConfiguration((context, config) =>
{
// Configure the app here.
})
.UseStartup<Startup>();
}

Deployment type
For information and advice on deployment scenarios, see .NET Core application deployment.
Framework-dependent deployment (FDD)
Framework-dependent deployment (FDD ) relies on the presence of a shared system-wide version of .NET Core
on the target system. When the FDD scenario is adopted following the guidance in this article, the SDK produces
an executable (.exe), called a framework-dependent executable.
Add the following property elements to the project file:
<OutputType> – The app's output type ( Exe for executable).
<LangVersion> – The C# language version ( latest or preview ).

A web.config file, which is normally produced when publishing an ASP.NET Core app, is unnecessary for a
Windows Services app. To disable the creation of the web.config file, add the <IsTransformWebConfigDisabled>
property set to true .
 <PropertyGroup>
<TargetFramework>netcoreapp3.0</TargetFramework>
<OutputType>Exe</OutputType>
<LangVersion>preview</LangVersion>
<IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
</PropertyGroup>

The Windows Runtime Identifier (RID ) (<RuntimeIdentifier>) contains the target framework. In the following
example, the RID is set to win7-x64 . The <SelfContained> property is set to false . These properties instruct the
SDK to generate an executable (.exe) file for Windows and an app that depends on the shared .NET Core
framework.
A web.config file, which is normally produced when publishing an ASP.NET Core app, is unnecessary for a
Windows Services app. To disable the creation of the web.config file, add the <IsTransformWebConfigDisabled>
property set to true .

<PropertyGroup>
<TargetFramework>netcoreapp2.2</TargetFramework>
<RuntimeIdentifier>win7-x64</RuntimeIdentifier>
<SelfContained>false</SelfContained>
<IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
</PropertyGroup>

The Windows Runtime Identifier (RID ) (<RuntimeIdentifier>) contains the target framework. In the following
example, the RID is set to win7-x64 . The <SelfContained> property is set to false . These properties instruct the
SDK to generate an executable (.exe) file for Windows and an app that depends on the shared .NET Core
framework.
The <UseAppHost> property is set to true . This property provides the service with an activation path (an
executable, .exe) for an FDD.
A web.config file, which is normally produced when publishing an ASP.NET Core app, is unnecessary for a
Windows Services app. To disable the creation of the web.config file, add the <IsTransformWebConfigDisabled>
property set to true .

<PropertyGroup>
<TargetFramework>netcoreapp2.1</TargetFramework>
<RuntimeIdentifier>win7-x64</RuntimeIdentifier>
<UseAppHost>true</UseAppHost>
<SelfContained>false</SelfContained>
<IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
</PropertyGroup>

Self-contained deployment (SCD)

Self-contained deployment (SCD ) doesn't rely on the presence of a shared framework on the host system. The
runtime and the app's dependencies are deployed with the app.
A Windows Runtime Identifier (RID ) is included in the <PropertyGroup> that contains the target framework:

<RuntimeIdentifier>win7-x64</RuntimeIdentifier>

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.
A <SelfContained> property is set to true :

<SelfContained>true</SelfContained>

Service user account

To create a user account for a service, use the New -LocalUser cmdlet from an administrative PowerShell 6
command shell.
On Windows 10 October 2018 Update (version 1809/build 10.0.17763) or later:

New-LocalUser -Name {NAME}

On Windows OS earlier than the Windows 10 October 2018 Update (version 1809/build 10.0.17763):

powershell -Command "New-LocalUser -Name {NAME}"

Provide a strong password when prompted.

Unless the -AccountExpires parameter is supplied to the New -LocalUser cmdlet with an expiration DateTime, the
account doesn't expire.
For more information, see Microsoft.PowerShell.LocalAccounts and Service User Accounts.
An alternative approach to managing users when using Active Directory is to use Managed Service Accounts. For
more information, see Group Managed Service Accounts Overview.

Log on as a service rights

To establish Log on as a service rights for a service user account:
1. Open the Local Security Policy editor by running secpol.msc.
2. Expand the Local Policies node and select User Rights Assignment.
3. Open the Log on as a service policy.
4. Select Add User or Group.
5. Provide the object name (user account) using either of the following approaches:
a. Type the user account ( {DOMAIN OR COMPUTER NAME\USER} ) in the object name field and select OK to add
the user to the policy.
b. Select Advanced. Select Find Now. Select the user account from the list. Select OK. Select OK again to
add the user to the policy.
6. Select OK or Apply to accept the changes.

Create and manage the Windows Service

Create a service
Use PowerShell commands to register a service. From an administrative PowerShell 6 command shell, execute the
following commands:
 $acl = Get-Acl "{EXE PATH}"
$aclRuleArgs = {DOMAIN OR COMPUTER NAME\USER}, "Read,Write,ReadAndExecute", "ContainerInherit,ObjectInherit",
"None", "Allow"
$accessRule = New-Object System.Security.AccessControl.FileSystemAccessRule($aclRuleArgs)
$acl.SetAccessRule($accessRule)
$acl | Set-Acl "{EXE PATH}"

New-Service -Name {NAME} -BinaryPathName {EXE FILE PATH} -Credential {DOMAIN OR COMPUTER NAME\USER} -
Description "{DESCRIPTION}" -DisplayName "{DISPLAY NAME}" -StartupType Automatic

{EXE PATH} – Path to the app's folder on the host (for example, d:\myservice ). Don't include the app's
executable in the path. A trailing slash isn't required.
{DOMAIN OR COMPUTER NAME\USER} – Service user account (for example, Contoso\ServiceUser ).
{NAME} – Service name (for example, MyService ).
{EXE FILE PATH} – The app's executable path (for example, d:\myservice\myservice.exe ). Include the
executable's file name with extension.
{DESCRIPTION} – Service description (for example, My sample service ).
{DISPLAY NAME} – Service display name (for example, My Service ).

Start a service
Start a service with the following PowerShell 6 command:

Start-Service -Name {NAME}

The command takes a few seconds to start the service.

Determine a service's status
To check the status of a service, use the following PowerShell 6 command:

Get-Service -Name {NAME}

The status is reported as one of the following values:

Starting
Running
Stopping
Stopped

Stop a service
Stop a service with the following Powershell 6 command:

Stop-Service -Name {NAME}

Remove a service
After a short delay to stop a service, remove a service with the following Powershell 6 command:

Remove-Service -Name {NAME}

Handle starting and stopping events

To handle OnStarting, OnStarted, and OnStopping events:
1. Create a class that derives from WebHostService with the OnStarting , OnStarted , and OnStopping
methods:

[DesignerCategory("Code")]
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.LogInformation("OnStarting method called.");
base.OnStarting(args);
}

protected override void OnStarted()

{
_logger.LogInformation("OnStarted method called.");
base.OnStarted();
}

protected override void OnStopping()

{
_logger.LogInformation("OnStopping method called.");
base.OnStopping();
}
}

2. Create an extension method for IWebHost that passes the CustomWebHostService to 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 RunAsCustomService extension method instead of RunAsService:

host.RunAsCustomService();

To see the location of RunAsService in Program.Main , refer to the code sample shown in the Deployment
type section.

Proxy server and load balancer scenarios

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
To configure a service with a secure endpoint:
1. Create an X.509 certificate for the hosting system using your platform's certificate acquisition and
deployment mechanisms.
2. Specify a Kestrel server HTTPS endpoint configuration to use the certificate.
Use of the ASP.NET Core HTTPS development certificate to secure a service endpoint isn't supported.

Current directory and content root

The current working directory returned by calling 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.
Use ContentRootPath or ContentRootFileProvider
Use IHostEnvironment.ContentRootPath or ContentRootFileProvider to locate an app's resources.
Set the content root path to the app's folder
The ContentRootPath is the same path provided to the binPath argument when a service is created. Instead of
calling GetCurrentDirectory to create paths to settings files, call SetCurrentDirectory with the path to the app's
content root.
In Program.Main , determine the path to the folder of the service's executable and use the path to establish the
app's content root:

var pathToExe = Process.GetCurrentProcess().MainModule.FileName;

var pathToContentRoot = Path.GetDirectoryName(pathToExe);
Directory.SetCurrentDirectory(pathToContentRoot);

CreateWebHostBuilder(args)
.Build()
.RunAsService();

Store a service's files in a suitable location on disk

Specify an absolute path with SetBasePath when using an IConfigurationBuilder to the folder containing the files.

Additional resources
Kestrel endpoint configuration (includes HTTPS configuration and SNI support)
.NET Generic Host
Troubleshoot ASP.NET Core projects
Kestrel endpoint configuration (includes HTTPS configuration and SNI support)
ASP.NET Core Web Host
Troubleshoot ASP.NET Core projects
 Host ASP.NET Core on Linux with Nginx
7/11/2019 • 13 minutes to read • Edit Online

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.
If the app is run locally and isn't configured to make secure connections (HTTPS ), adopt either of the following
approaches:
Configure the app to handle secure local connections. For more information, see the HTTPS configuration
section.
Remove https://localhost:5001 (if present) from the applicationUrl property in the
Properties/launchSettings.json file.
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/www/helloapp).

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.
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 HTTPS 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.
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
});

app.UseAuthentication();

If no ForwardedHeadersOptions are specified to the middleware, the default headers to forward are None .
Proxies running on loopback addresses (127.0.0.0/8, [::1]), including the standard localhost address (127.0.0.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 Startup.ConfigureServices :

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: dotnet <app_assembly.dll> , where app_assembly.dll is the assembly file name of the app.

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.

Monitor 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-helloapp.service

The following is an example service file for the app:

[Unit]
Description=Example .NET Web API App running on Ubuntu

[Service]
WorkingDirectory=/var/www/helloapp
ExecStart=/usr/bin/dotnet /var/www/helloapp/helloapp.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>"

Colon ( : ) separators aren't supported in environment variable names. Use a double underscore ( __ ) in place
of a colon. The Environment Variables configuration provider converts double-underscores into colons when
environment variables are read into configuration. In the following example, the connection string key
ConnectionStrings:DefaultConnection is set into the service definition file as
ConnectionStrings__DefaultConnection :

Environment=ConnectionStrings__DefaultConnection={Connection String}

Save the file and enable the service.

sudo systemctl enable kestrel-helloapp.service

Start the service and verify that it's running.

sudo systemctl start kestrel-helloapp.service

sudo systemctl status kestrel-helloapp.service

● kestrel-helloapp.service - Example .NET Web API App running on Ubuntu

Loaded: loaded (/etc/systemd/system/kestrel-helloapp.service; enabled)
Active: active (running) since Thu 2016-10-18 04:09:35 NZDT; 35s ago
Main PID: 9021 (dotnet)
CGroup: /system.slice/kestrel-helloapp.service
└─9021 /usr/local/bin/dotnet /var/www/helloapp/helloapp.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

View 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-helloapp.service -specific items, use the following command:

sudo journalctl -fu kestrel-helloapp.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-helloapp.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.
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 to persist and encrypt the key ring, see:
Key storage providers in ASP.NET Core
Key encryption At rest in ASP.NET Core

Long request header fields

If the app requires request header fields longer than permitted by the proxy server's default settings (typically 4K
or 8K depending on the platform), the following directives require adjustment. The values to apply are scenario-
dependent. For more information, see your server's documentation.
proxy_buffer_size
proxy_buffers
proxy_busy_buffers_size
large_client_header_buffers
 WARNING
Don't increase the default values of proxy buffers unless necessary. Increasing these values increases the risk of buffer
overrun (overflow) and Denial of Service (DoS) attacks by malicious users.

Secure 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.
Configure 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 allow 80/tcp
sudo ufw allow 443/tcp

sudo ufw enable

Secure 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.
HTTPS configuration
Configure the app for secure (HTTPS ) local connections
The dotnet run command uses the app's Properties/launchSettings.json file, which configures the app to listen on
the URLs provided by the applicationUrl property (for example, https://localhost:5001;http://localhost:5000 ).
Configure the app to use a certificate in development for the dotnet run command or development
environment (F5 or Ctrl+F5 in Visual Studio Code) using one of the following approaches:
Replace the default certificate from configuration (Recommended)
 KestrelServerOptions.ConfigureHttpsDefaults
Configure the reverse proxy for secure (HTTPS ) client connections
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.
Don't add the HSTS header or chose an appropriate max-age if HTTPS 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, 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.
To mitigate clickjacking attacks:
1. Edit the nginx.conf file:

sudo nano /etc/nginx/nginx.conf

Add the line add_header X-Frame-Options "SAMEORIGIN"; .

2. Save the file.
3. 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.

Additional resources
Prerequisites for .NET Core on Linux
Nginx: Binary Releases: Official Debian/Ubuntu packages
Troubleshoot ASP.NET Core projects
Configure ASP.NET Core to work with proxy servers and load balancers
NGINX: Using the Forwarded header
 Host ASP.NET Core on Linux with Apache
7/11/2019 • 12 minutes to read • Edit Online

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 server. The mod_proxy extension and related modules create the
server's reverse proxy.

Prerequisites
Server running CentOS 7 with a standard user account with sudo privilege.
Install the .NET Core runtime on the server.
1. Visit the .NET Core All Downloads page.
2. Select the latest non-preview runtime from the list under Runtime.
3. Select and follow the instructions for CentOS/Oracle.
An existing ASP.NET Core app.

Publish and copy over the app

Configure the app for a framework-dependent deployment.
If the app is run locally and isn't configured to make secure connections (HTTPS ), adopt either of the following
approaches:
Configure the app to handle secure local connections. For more information, see the HTTPS configuration
section.
Remove https://localhost:5001 (if present) from the applicationUrl property in the
Properties/launchSettings.json file.
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/www/helloapp).

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.
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
});

app.UseAuthentication();

If no ForwardedHeadersOptions are specified to the middleware, the default headers to forward are None .
Proxies running on loopback addresses (127.0.0.0/8, [::1]), including the standard localhost address (127.0.0.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 Startup.ConfigureServices :

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 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 helloapp.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}helloapp-error.log
CustomLog ${APACHE_LOG_DIR}helloapp-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

Monitor 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-helloapp.service

An example service file for the app:

[Unit]
Description=Example .NET Web API App running on CentOS 7

[Service]
WorkingDirectory=/var/www/helloapp
ExecStart=/usr/local/bin/dotnet /var/www/helloapp/helloapp.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>"

Colon ( : ) separators aren't supported in environment variable names. Use a double underscore ( __ ) in place
of a colon. The Environment Variables configuration provider converts double-underscores into colons when
environment variables are read into configuration. In the following example, the connection string key
ConnectionStrings:DefaultConnection is set into the service definition file as
ConnectionStrings__DefaultConnection :

Environment=ConnectionStrings__DefaultConnection={Connection String}

Save the file and enable the service:

sudo systemctl enable kestrel-helloapp.service

Start the service and verify that it's running:

sudo systemctl start kestrel-helloapp.service

sudo systemctl status kestrel-helloapp.service

● kestrel-helloapp.service - Example .NET Web API App running on CentOS 7

Loaded: loaded (/etc/systemd/system/kestrel-helloapp.service; enabled)
Active: active (running) since Thu 2016-10-18 04:09:35 NZDT; 35s ago
Main PID: 9021 (dotnet)
CGroup: /system.slice/kestrel-helloapp.service
└─9021 /usr/local/bin/dotnet /var/www/helloapp/helloapp.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

View 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-helloapp.service -specific items, use the following command:

sudo journalctl -fu kestrel-helloapp.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-helloapp.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.
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 to persist and encrypt the key ring, see:
Key storage providers in ASP.NET Core
Key encryption At rest in ASP.NET Core

Secure 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:
HTTPS configuration
Configure the app for secure (HTTPS ) local connections
The dotnet run command uses the app's Properties/launchSettings.json file, which configures the app to listen on
the URLs provided by the applicationUrl property (for example, https://localhost:5001;http://localhost:5000 ).
Configure the app to use a certificate in development for the dotnet run command or development
environment (F5 or Ctrl+F5 in Visual Studio Code) using one of the following approaches:
Replace the default certificate from configuration (Recommended)
KestrelServerOptions.ConfigureHttpsDefaults
Configure the reverse proxy for secure (HTTPS ) client connections
To configure Apache for HTTPS, 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 HTTPS, install the mod_rewrite module to enable URL rewriting:

sudo yum install mod_rewrite

Modify the helloapp.conf file to enable URL rewriting and secure communication on port 443:

<VirtualHost *:*>
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</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/
ProxyPassReverse / http://127.0.0.1:5000/
ErrorLog /var/log/httpd/helloapp-error.log
CustomLog /var/log/httpd/helloapp-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.
To mitigate clickjacking attacks:
1. Edit the httpd.conf file:

sudo nano /etc/httpd/conf/httpd.conf

Add the line Header append X-FRAME-OPTIONS "SAMEORIGIN" .

2. Save the file.
3. 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 helloapp is set up to run on port 5001. The
Proxy section is set with a balancer configuration with two members to load balance byrequests.
 <VirtualHost *:*>
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>

<VirtualHost *:80>
RewriteEngine On
RewriteCond %{HTTPS} !=on
RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]
</VirtualHost>

<VirtualHost *:443>
ProxyPass / balancer://mycluster/

ProxyPassReverse / http://127.0.0.1:5000/
ProxyPassReverse / http://127.0.0.1:5001/

<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/helloapp-error.log
CustomLog /var/log/httpd/helloapp-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>

Long request header fields

If the app requires request header fields longer than permitted by the proxy server's default setting (typically
8,190 bytes), adjust the value of the LimitRequestFieldSize directive. The value to apply is scenario-dependent.
For more information, see your server's documentation.

WARNING
Don't increase the default value of LimitRequestFieldSize unless necessary. Increasing the value increases the risk of
buffer overrun (overflow) and Denial of Service (DoS) attacks by malicious users.
Additional resources
Prerequisites for .NET Core on Linux
Troubleshoot ASP.NET Core projects
Configure ASP.NET Core to work with proxy servers and load balancers
 Host ASP.NET Core in Docker containers
7/18/2019 • 2 minutes to read • Edit Online

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.
Docker images for ASP.NET Core Learn how to build and dockerize an ASP.NET Core app. Explore Docker
images maintained by Microsoft and examine use cases.
Visual Studio Container Tools
Discover how Visual Studio 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 Azure Container Registry
Find out how to use the Visual Studio Container Tools extension to deploy an ASP.NET Core app to a Docker host
on Azure using PowerShell.
Configure ASP.NET Core to work with proxy servers and load balancers
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.
 Docker images for ASP.NET Core
6/18/2019 • 4 minutes to read • Edit Online

This tutorial shows how to run an ASP.NET Core app in Docker containers.
In this tutorial, you:
Learn about Microsoft .NET Core Docker images
Download an ASP.NET Core sample app
Run the sample app locally
Run the sample app in Linux containers
Run the sample app in Windows containers
Build and deploy manually

ASP.NET Core Docker images

For this tutorial, you download an ASP.NET Core sample app and run it in Docker containers. The sample works
with both Linux and Windows containers.
The sample Dockerfile uses the Docker multi-stage build feature to build and run in different containers. The build
and run containers are created from images that are provided in Docker Hub by Microsoft:
dotnet/core/sdk

The sample uses this image for building the app. The image contains the .NET Core SDK, which includes the
Command Line Tools (CLI). The image is optimized for local development, debugging, and unit testing. The
tools installed for development and compilation make this a relatively large image.
dotnet/core/aspnet

The sample uses this image for running the app. The image contains the ASP.NET Core runtime and
libraries and is optimized for running apps in production. Designed for speed of deployment and app
startup, the image is relatively small, so network performance from Docker Registry to Docker host is
optimized. Only the binaries and content needed to run an app are copied to the container. The contents are
ready to run, enabling the fastest time from Docker run to app startup. Dynamic code compilation isn't
needed in the Docker model.

Prerequisites
.NET Core 2.2 SDK
Docker client 18.03 or later
Linux distributions
CentOS
Debian
Fedora
Ubuntu
macOS
Windows
Git
Download the sample app
Download the sample by cloning the .NET Core Docker repository:

git clone https://github.com/dotnet/dotnet-docker

Run the app locally

Navigate to the project folder at dotnet-docker/samples/aspnetapp/aspnetapp.
Run the following command to build and run the app locally:

dotnet run

Go to http://localhost:5000 in a browser to test the app.

Press Ctrl+C at the command prompt to stop the app.

Run in a Linux container

In the Docker client, switch to Linux containers.
Navigate to the Dockerfile folder at dotnet-docker/samples/aspnetapp.
Run the following commands to build and run the sample in Docker:

docker build -t aspnetapp .

docker run -it --rm -p 5000:80 --name aspnetcore_sample aspnetapp

The build command arguments:

Name the image aspnetapp.
Look for the Dockerfile in the current folder (the period at the end).
The run command arguments:
Allocate a pseudo-TTY and keep it open even if not attached. (Same effect as --interactive --tty .)
Automatically remove the container when it exits.
Map port 5000 on the local machine to port 80 in the container.
Name the container aspnetcore_sample.
Specify the aspnetapp image.
Go to http://localhost:5000 in a browser to test the app.

Run in a Windows container

In the Docker client, switch to Windows containers.
Navigate to the docker file folder at dotnet-docker/samples/aspnetapp .
Run the following commands to build and run the sample in Docker:

docker build -t aspnetapp .

docker run -it --rm --name aspnetcore_sample aspnetapp
 For Windows containers, you need the IP address of the container (browsing to http://localhost:5000
won't work):
Open up another command prompt.
Run docker ps to see the running containers. Verify that the "aspnetcore_sample" container is there.
Run docker exec aspnetcore_sample ipconfig to display the IP address of the container. The output
from the command looks like this example:

Ethernet adapter Ethernet:

Connection-specific DNS Suffix . : contoso.com

Link-local IPv6 Address . . . . . : fe80::1967:6598:124:cfa3%4
IPv4 Address. . . . . . . . . . . : 172.29.245.43
Subnet Mask . . . . . . . . . . . : 255.255.240.0
Default Gateway . . . . . . . . . : 172.29.240.1

Copy the container IPv4 address (for example, 172.29.245.43) and paste into the browser address bar to
test the app.

Build and deploy manually

In some scenarios, you might want to deploy an app to a container by copying to it the application files that are
needed at run time. This section shows how to deploy manually.
Navigate to the project folder at dotnet-docker/samples/aspnetapp/aspnetapp.
Run the dotnet publish command:

dotnet publish -c Release -o published

The command arguments:

Build the application in release mode (the default is debug mode).
Create the files in the published folder.
Run the application.
Windows:

dotnet published\aspnetapp.dll

Linux:

dotnet published/aspnetapp.dll

Browse to http://localhost:5000 to see the home page.

The Dockerfile
Here's the Dockerfile used by the docker build command you ran earlier. It uses dotnet publish the same way
you did in this section to build and deploy.
 FROM mcr.microsoft.com/dotnet/core/sdk:2.2 AS build
WORKDIR /app

# copy csproj and restore as distinct layers

COPY *.sln .
COPY aspnetapp/*.csproj ./aspnetapp/
RUN dotnet restore

# copy everything else and build app

COPY aspnetapp/. ./aspnetapp/
WORKDIR /app/aspnetapp
RUN dotnet publish -c Release -o out

FROM mcr.microsoft.com/dotnet/core/aspnet:2.2 AS runtime

WORKDIR /app
COPY --from=build /app/aspnetapp/out ./
ENTRYPOINT ["dotnet", "aspnetapp.dll"]

Additional resources
Docker build command
Docker run command
ASP.NET Core Docker sample (The one used in this tutorial.)
Configure ASP.NET Core to work with proxy servers and load balancers
Working with Visual Studio Docker Tools
Debugging with Visual Studio Code

Next steps
In this tutorial, you:
Learned about Microsoft .NET Core Docker images
Downloaded an ASP.NET Core sample app
Run the sample app locally
Run the sample app in Linux containers
Run the sample with in Windows containers
Built and deployed manually
The Git repository that contains the sample app also includes documentation. For an overview of the resources
available in the repository, see the README file. In particular, learn how to implement HTTPS:
Developing ASP.NET Core Applications with Docker over HTTPS
 Visual Studio Container Tools with ASP.NET Core
7/18/2019 • 9 minutes to read • Edit Online

Visual Studio 2017 and later versions support building, debugging, and running containerized ASP.NET Core apps
targeting .NET Core. Both Windows and Linux containers are supported.
View or download sample code (how to download)

Prerequisites
Docker for Windows
Visual Studio 2019 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 Container Tools 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 mcr.microsoft.com/dotnet/core/aspnet:2.1 AS base

WORKDIR /app
EXPOSE 59518
EXPOSE 44364

FROM mcr.microsoft.com/dotnet/core/sdk:2.1 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 .
ENTRYPOINT ["dotnet", "HelloDockerTools.dll"]

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 Container Tools 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'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 Container Tools 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} .
ENTRYPOINT ["dotnet", "HelloDockerTools.dll"]

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:

REPOSITORY TAG IMAGE ID CREATED SIZE

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 Container Tools 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:

REPOSITORY TAG IMAGE ID CREATED SIZE

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

REPOSITORY TAG IMAGE ID CREATED SIZE

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.

Additional resources
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 development with Docker
Visual Studio Container Tools GitHub repository
 Configure ASP.NET Core to work with proxy
servers and load balancers
7/12/2019 • 13 minutes to read • Edit Online

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 restrict 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 hosted
out-of-process 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 when hosting out-of-process, 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:
 public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();

services.Configure<ForwardedHeadersOptions>(options =>
{
options.ForwardedHeaders =
ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
});
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
app.UseForwardedHeaders();

if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Home/Error");
}

app.UseStaticFiles();
// In ASP.NET Core 1.x, replace the following line with: app.UseIdentity();
app.UseAuthentication();
app.UseMvc();
}

NOTE
If no ForwardedHeadersOptions are specified in Startup.ConfigureServices or directly to the extension method
with UseForwardedHeaders, the default headers to forward are ForwardedHeaders.None. The 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 .
 services.Configure<ForwardedHeadersOptions>(options =>
{
options.ForwardLimit = 2;
options.KnownProxies.Add(IPAddress.Parse("127.0.10.1"));
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.
This option is used when the proxy/forwarder doesn't use
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.
This option is used when the proxy/forwarder doesn't use
the X-Forwarded-Proto header but uses some other
header to forward the information.

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. Setting a non- null value is a precaution (but
not a guarantee) to guard against misconfigured proxies
and malicious requests arriving from side-channels on the
network.

Forwarded Headers Middleware processes headers in

reverse order from right to left. If the default value ( 1 ) is
used, only the rightmost value from the headers is
processed unless the value of ForwardLimit is increased.

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.

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 <IPAddress> containing a single

entry for IPAddress.IPv6Loopback .
 OPTION DESCRIPTION

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 .

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:

app.Use((context, next) =>

{
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:

app.Use((context, next) =>

{
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 and assigning to the Path property:

app.Use((context, next) =>

{
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:

services.Configure<ForwardedHeadersOptions>(options =>
{
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;
services.Configure<ForwardedHeadersOptions>(options =>
{
options.ForwardedHeaders =
ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
options.KnownNetworks.Add(new IPNetwork(
IPAddress.Parse("::ffff:10.11.12.1"), 104));
});

Forward the scheme for Linux and non-IIS reverse proxies

Apps that call UseHttpsRedirection and UseHsts put a site into an infinite loop if deployed to an Azure Linux
App Service, Azure Linux virtual machine (VM ), or behind any other reverse proxy besides IIS. TLS is
terminated by the reverse proxy, and Kestrel isn't made aware of the correct request scheme. OAuth and
OIDC also fail in this configuration because they generate incorrect redirects. UseIISIntegration adds and
configures Forwarded Headers Middleware when running behind IIS, but there's no matching automatic
configuration for Linux (Apache or Nginx integration).
To forward the scheme from the proxy in non-IIS scenarios, add and configure Forwarded Headers
Middleware. In Startup.ConfigureServices , use the following code:

// using Microsoft.AspNetCore.HttpOverrides;

if (string.Equals(
Environment.GetEnvironmentVariable("ASPNETCORE_FORWARDEDHEADERS_ENABLED"),
"true", StringComparison.OrdinalIgnoreCase))
{
services.Configure<ForwardedHeadersOptions>(options =>
{
options.ForwardedHeaders = ForwardedHeaders.XForwardedFor |
ForwardedHeaders.XForwardedProto;
// Only loopback proxies are allowed by default.
// Clear that restriction because forwarders are enabled by explicit
// configuration.
options.KnownNetworks.Clear();
options.KnownProxies.Clear();
});
}

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.
To write the headers to the app's response, place the following terminal inline middleware immediately after
the call to UseForwardedHeaders in Startup.Configure :
 app.Run(async (context) =>
{
context.Response.ContentType = "text/plain";

// Request method, scheme, and path

await context.Response.WriteAsync(
$"Request Method: {context.Request.Method}{Environment.NewLine}");
await context.Response.WriteAsync(
$"Request Scheme: {context.Request.Scheme}{Environment.NewLine}");
await context.Response.WriteAsync(
$"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
await context.Response.WriteAsync(
$"Request RemoteIp: {context.Connection.RemoteIpAddress}");
});

You can write to logs instead of the response body. Writing to logs allows the site to function normally while
debugging.
To write logs rather than to the response body:
Inject ILogger<Startup> into the Startup class as described in Create logs in Startup.
Place the following inline middleware immediately after the call to UseForwardedHeaders in
Startup.Configure .

app.Use(async (context, next) =>

{
// 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, 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.

services.Configure<ForwardedHeadersOptions>(options =>
{
options.KnownProxies.Add(IPAddress.Parse("10.0.0.100"));
});

IMPORTANT
Only allow trusted proxies and networks to forward headers. Otherwise, IP spoofing attacks are possible.

Certificate forwarding
On Azure
See the Azure documentation to configure Azure Web Apps. In your app's Startup.Configure method, add
the following code before the call to app.UseAuthentication(); :

app.UseCertificateForwarding();

You'll also need to configure the Certificate Forwarding middleware to specify the header name that Azure
uses. In your app's Startup.ConfigureServices method, add the following code to configure the header from
which the middleware builds a certificate:

services.AddCertificateForwarding(options =>
options.CertificateHeader = "X-ARR-ClientCert");

With other web proxies

If you're using a proxy that isn't IIS or Azure's Web Apps Application Request Routing, configure your proxy
to forward the certificate it received in an HTTP header. In your app's Startup.Configure method, add the
following code before the call to app.UseAuthentication(); :

app.UseCertificateForwarding();

You'll also need to configure the Certificate Forwarding middleware to specify the header name. In your app's
Startup.ConfigureServices method, add the following code to configure the header from which the
middleware builds a certificate:

services.AddCertificateForwarding(options =>
options.CertificateHeader = "YOUR_CERTIFICATE_HEADER_NAME");

Finally, if the proxy is doing something other than base64 encoding the certificate (as is the case with Nginx),
set the HeaderConverter option. Consider the following example in Startup.ConfigureServices :

services.AddCertificateForwarding(options =>
{
options.CertificateHeader = "YOUR_CUSTOM_HEADER_NAME";
options.HeaderConverter = (headerValue) =>
{
var clientCertificate =
/* some conversion logic to create an X509Certificate2 */
return clientCertificate;
}
});

Additional resources
Host ASP.NET Core in a web farm
Microsoft Security Advisory CVE -2018-0787: ASP.NET Core Elevation Of Privilege Vulnerability
 Host ASP.NET Core in a web farm
5/21/2019 • 4 minutes to read • Edit Online

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.
Configure ASP.NET Core to work with proxy servers and load balancers
Learn about configuration for apps hosted behind proxy servers and load balancers, which often obscure
important request information.
Deploy ASP.NET Core apps to Azure App Service
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 Distributed caching 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 authentication cookies
among ASP.NET apps.

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 Distributed caching
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
Data Protection and caching
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 Distributed
caching in ASP.NET Core.

Obtain data from apps

If the web farm apps are capable of responding to requests, obtain request, connection, and additional data from
the apps using terminal inline middleware. For more information and sample code, see Troubleshoot ASP.NET
Core projects.
 Visual Studio publish profiles for ASP.NET Core app
deployment
6/23/2019 • 13 minutes to read • Edit Online

By Sayed Ibrahim Hashimi and Rick Anderson

This document focuses on using Visual Studio 2019 or later to create and use publish profiles. The publish
profiles created with Visual Studio can be used with MSBuild and Visual Studio. For instructions on publishing to
Azure, see Publish an ASP.NET Core app to Azure with Visual Studio.
The dotnet new mvc command produces a project file containing the following root-level <Project> element:

<Project Sdk="Microsoft.NET.Sdk.Web">
<!-- omitted for brevity -->
</Project>

The preceding <Project> element's Sdk attribute imports the MSBuild properties and targets from
$ (MSBuildSDKsPath)\Microsoft.NET.Sdk.Web\Sdk\Sdk.props and
$ (MSBuildSDKsPath)\Microsoft.NET.Sdk.Web\Sdk\Sdk.targets, respectively. The default location for
$(MSBuildSDKsPath) (with Visual Studio 2019 Enterprise) is the %programfiles(x86 )%\Microsoft Visual
Studio\2019\Enterprise\MSBuild\Sdks folder.
Microsoft.NET.Sdk.Web (Web SDK) depends on other SDKs, including Microsoft.NET.Sdk (.NET Core SDK) and
Microsoft.NET.Sdk.Razor ( Razor SDK ). The MSBuild properties and targets associated with each dependent SDK
are imported. Publish targets import the appropriate 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 MSBuild project items (files) are computed. The item type 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 patterns wwwroot\** , **\*.config , and **\*.json are included in the Content item list. For example, the
wwwroot\** globbing pattern matches all files in the wwwroot folder and its subfolders.

The Web SDK imports the Razor SDK. As a result, files matching the patterns **\*.cshtml and **\*.razor are
also included in the Content item list.
The Web SDK imports the Razor SDK. As a result, files matching the **\*.cshtml pattern are also included in the
Content item list.

To explicitly add a file to the publish list, add the file directly in the .csproj file as shown in the Include Files section.
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
following examples, the .NET Core CLI's dotnet publish command is run from the project directory (which
contains the .csproj file). If the project folder isn't the current working directory, 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:

dotnet new mvc

dotnet publish

The dotnet publish command produces a variation of the following output:

C:\Webs\Web1>dotnet publish
Microsoft (R) Build Engine version {VERSION} for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

Restore completed in 36.81 ms for C:\Webs\Web1\Web1.csproj.

Web1 -> C:\Webs\Web1\bin\Debug\{TARGET FRAMEWORK MONIKER}\Web1.dll
Web1 -> C:\Webs\Web1\bin\Debug\{TARGET FRAMEWORK MONIKER}\Web1.Views.dll
Web1 -> C:\Webs\Web1\bin\Debug\{TARGET FRAMEWORK MONIKER}\publish\

The default publish folder format is bin\Debug\{TARGET FRAMEWORK MONIKER }\publish\. For example,
bin\Debug\netcoreapp2.2\publish\.
The following command specifies a Release build and the publishing directory:

dotnet publish -c Release -o C:\MyWebs\test

The command calls MSBuild, which invokes the Publish target. Any parameters passed to
dotnet publish
dotnet publish are passed to MSBuild. The -c and -o parameters map to MSBuild's Configuration and
OutputPath properties, respectively.

MSBuild properties can be passed using either of the following formats:

p:<NAME>=<VALUE>
/p:<NAME>=<VALUE>

For example, the following command publishes a Release build to a network share. The network share is
specified with forward slashes (//r8/) and works on all .NET Core supported platforms.
dotnet publish -c Release /p:PublishDir=//r8/release/AdminWeb

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 2019 or later to create a publishing profile. Once the profile is 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 capabilities page is displayed. If the project lacks a publish profile, the Pick a publish
target page is displayed. You're asked to select one of the following publish targets:
Azure App Service
Azure App Service on Linux
Azure Virtual Machines
Folder
IIS, FTP, Web Deploy (for any web server)
Import Profile
To determine the most appropriate publish target, see What publishing options are right for me.
When the Folder publish target is selected, specify a folder path to store the published assets. The default folder
path is bin\{PROJECT CONFIGURATION }\{TARGET FRAMEWORK MONIKER }\publish\. For example,
bin\Release\netcoreapp2.2\publish\. Select the Create Profile button to finish.
Once a publish profile is created, the Publish tab's content changes. The newly created profile appears in a drop-
down list. Below the drop-down list, select Create new profile to create another new profile.
Visual Studio's publish tool produces a Properties/PublishProfiles/{PROFILE NAME }.pubxml MSBuild file
describing the publish profile. The .pubxml file:
Contains publish configuration settings and is consumed by the publishing process.
Can be modified to customize the build and publish process.
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 an ASP.NET Core web app, see Host and deploy ASP.NET Core. The MSBuild
tasks and targets necessary to publish an ASP.NET Core web app are open-source at the aspnet/websdk
repository.
The dotnet publish command can use folder, MSDeploy, and Kudu publish profiles. Because MSDeploy lacks
cross-platform support, the following MSDeploy options are supported only on Windows.
Folder (works cross-platform ):
 dotnet publish WebApplication.csproj /p:PublishProfile=<FolderProfileName>

MSDeploy:

dotnet publish WebApplication.csproj /p:PublishProfile=<MsDeployProfileName> /p:Password=<DeploymentPassword>

MSDeploy package:

dotnet publish WebApplication.csproj /p:PublishProfile=<MsDeployPackageProfileName>

In the preceding examples, 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 project's 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}

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

The .NET Core CLI's dotnet build command calls msbuild to run the build and publish process. The
dotnet build and msbuild commands are equivalent when passing in a folder profile. When calling msbuild
directly on Windows, the .NET Framework version of MSBuild is used. Calling dotnet build on a non-folder
profile:
Invokes msbuild , which uses MSDeploy.
Results in a failure (even when running on Windows). 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:
 <?xml version="1.0" encoding="utf-8"?>
<!--
This file is used by the publish/package process of your Web project.
You can customize the behavior of this process by editing this
MSBuild file.
-->
<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>

In the preceding example:

The <ExcludeApp_Data>property is present merely to satisfy an XML schema requirement. The
<ExcludeApp_Data> property has no effect on the publish process, even if there's an App_Data folder in the
project root. The App_Data folder doesn't receive special treatment as it does in ASP.NET 4.x projects.
The <LastUsedBuildConfiguration> property is set to Release . When publishing from Visual Studio, the
value of <LastUsedBuildConfiguration> is set using the value when the publish process is started.
<LastUsedBuildConfiguration> is special and shouldn't be overridden in an imported MSBuild file. This
property can, however, be overridden from the command line using one of the following approaches.
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

For more information, see MSBuild: how to set the configuration property.

Publish to an MSDeploy endpoint from the command line

The following example uses an ASP.NET Core web app created by Visual Studio named AzureWebApp. An
Azure Apps publish profile is added with Visual Studio. For more information on how to create a profile, see the
Publish profiles section.
To deploy the app using a publish profile, execute the msbuild command from a Visual Studio Developer
Command Prompt. The command prompt is available in the Visual Studio folder of the Start menu on the
Windows taskbar. For easier access, you can add the command prompt to the Tools menu in Visual Studio. For
more information, see Developer Command Prompt for Visual Studio.
MSBuild uses the following command syntax:
 msbuild {PATH}
/p:DeployOnBuild=true
/p:PublishProfile={PROFILE}
/p:Username={USERNAME}
/p:Password={PASSWORD}

{PATH} – Path to the app's project file.

{PROFILE } – Name of the publish profile.
{USERNAME } – MSDeploy username. The {USERNAME } can be found in the publish profile.
{PASSWORD } – MSDeploy password. Obtain the {PASSWORD } from the {PROFILE }.PublishSettings file.
Download the .PublishSettings file from either:
Solution Explorer: Select View > Cloud Explorer. Connect with your Azure subscription. Open App
Services. Right-click the app. Select Download Publish Profile.
Azure portal: Select Get publish profile in the web app's Overview panel.
The following example uses a publish profile named AzureWebApp - Web Deploy:

msbuild "AzureWebApp.csproj"
/p:DeployOnBuild=true
/p:PublishProfile="AzureWebApp - Web Deploy"
/p:Username="$AzureWebApp"
/p:Password=".........."

A publish profile can also be used with the .NET Core CLI's dotnet msbuild command from a Windows
command shell:

dotnet msbuild "AzureWebApp.csproj"

/p:DeployOnBuild=true
/p:PublishProfile="AzureWebApp - Web Deploy"
/p:Username="$AzureWebApp"
/p:Password=".........."

IMPORTANT
The dotnet msbuild command is a cross-platform command and can compile ASP.NET Core apps on macOS and Linux.
However, MSBuild on macOS and Linux isn't capable of deploying an app to Azure or other MSDeploy endpoints.

Set the environment

Include the <EnvironmentName> property in the publish profile ( .pubxml) or project file to set the app's
environment:

<PropertyGroup>
<EnvironmentName>Development</EnvironmentName>
</PropertyGroup>

If you require web.config transformations (for example, setting environment variables based on the configuration,
profile, or environment), see Transform web.config.

Exclude files
When publishing ASP.NET Core web apps, the following assets are included:
 Build artifacts
Folders and files matching the following globbing patterns:
**\*.config (for example, web.config )
**\*.json (for example, appsettings.json)
wwwroot\**

MSBuild supports globbing patterns. For example, the following <Content> element suppresses the copying of
text (.txt) files in the wwwroot\content folder and 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
Views/Home/About2.cshtml
Views/Home/About3.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>
</MsDeploySkipRules>

<MsDeploySkipRules Include="CustomSkipFile">
<ObjectName>filePath</ObjectName>
<AbsolutePath>Views\\Home\\About2.cshtml</AbsolutePath>
</MsDeploySkipRules>

<MsDeploySkipRules Include="CustomSkipFile">
<ObjectName>filePath</ObjectName>
<AbsolutePath>Views\\Home\\About3.cshtml</AbsolutePath>
</MsDeploySkipRules>
</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 a variation of the following
output:

MSDeployPublish:
Starting Web deployment task from source: manifest(C:\Webs\Web1\obj\Release\{TARGET FRAMEWORK
MONIKER}\PubTmp\Web1.SourceManifest.
xml) to Destination: auto().
Deleting file (Web11112\Views\Home\About1.cshtml).
Deleting file (Web11112\Views\Home\About2.cshtml).
Deleting file (Web11112\Views\Home\About3.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 sections outline different approaches for file inclusion at publish time. The General file inclusion
section uses the DotNetPublishFiles item, which is provided by a publish targets file in the Web SDK. The
Selective file inclusion section uses the ResolvedFileToPublish item, which is provided by a publish targets file in
the .NET Core SDK. Because the Web SDK depends on the .NET Core SDK, either item can be used in an
ASP.NET Core project.
General file inclusion
The following example's <ItemGroup> element demonstrates copying a folder located outside of the project
directory to a folder of the published site. Any files added to the following markup's <ItemGroup> are included by
default.

<ItemGroup>
<_CustomFiles Include="$(MSBuildProjectDirectory)/../images/**/*" />
<DotNetPublishFiles Include="@(_CustomFiles)">
<DestinationRelativePath>wwwroot/images/%(RecursiveDir)%(Filename)%(Extension)</DestinationRelativePath>
</DotNetPublishFiles>
</ItemGroup>

The preceding 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.
Declares a _CustomFiles item to store files matching the Include attribute's globbing pattern. The images
folder referenced in the pattern is located outside of the project directory. A reserved property, named
$(MSBuildProjectDirectory) , resolves to the project file's absolute path.
Provides a list of files to the DotNetPublishFiles item. By default, the item's <DestinationRelativePath>
element is empty. The default value is overridden in the markup and uses well-known item metadata such as
%(RecursiveDir) . The inner text represents the wwwroot/images folder of the published site.

Selective file inclusion

The highlighted markup in the following example demonstrates:
Copying a file located outside of the project into the published site's wwwroot folder. The file name of
ReadMe2.md is maintained.
Excluding the wwwroot\Content folder.
Excluding Views\Home\About2.cshtml.

<?xml version="1.0" encoding="utf-8"?>

<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>

The preceding example uses the ResolvedFileToPublish item, whose default behavior is to always copy the files
provided in the Include attribute to the published site. Override the default behavior by including a
<CopyToPublishDirectory> child element with inner text of either Never or PreserveNewest . For example:

<ResolvedFileToPublish Include="..\ReadMe2.md">
<RelativePath>wwwroot\ReadMe2.md</RelativePath>
<CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
</ResolvedFileToPublish>

For more deployment samples, see the Web SDK repository Readme.

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.

Additional resources
Web Deploy (MSDeploy) simplifies deployment of web apps and websites to IIS servers.
Web SDK GitHub repository: File issues and request features for deployment.
Publish an ASP.NET Web App to an Azure VM from Visual Studio
Transform web.config
 ASP.NET Core directory structure
6/17/2019 • 2 minutes to read • Edit Online

By Luke Latham
The publish directory contains the app's deployable assets produced by the dotnet publish command. The
directory contains:
Application files
Configuration files
Static assets
Packages
A runtime (self-contained deployment only)

APP TYPE DIRECTORY STRUCTURE

Framework-dependent Deployment publish†

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}.Views.dll
{ASSEMBLY NAME}.Views.pdb
{ASSEMBLY NAME}.runtimeconfig.json
web.config (IIS deployments)

Self-contained Deployment publish†

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}.exe
{ASSEMBLY NAME}.pdb
{ASSEMBLY NAME}.Views.dll
{ASSEMBLY NAME}.Views.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.
Creating a Logs folder is useful for ASP.NET Core Module enhanced debug logging. Folders in the path
provided to the <handlerSetting> value aren't created by the module automatically and should pre-exist in the
deployment to allow the module to write the debug log.
A 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. Folder
creation using this approach fails 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.

Additional resources
dotnet publish
.NET Core application deployment
Target frameworks
.NET Core RID Catalog
 Health checks in ASP.NET Core
7/12/2019 • 22 minutes to read • Edit Online

By Luke Latham and Glenn Condron

ASP.NET Core offers Health Check Middleware and libraries for reporting the health of app infrastructure
components.
Health checks are exposed by an app as HTTP endpoints. Health check endpoints can be configured for a variety
of real-time monitoring scenarios:
Health probes can be used by container orchestrators and load balancers to check an app's status. For example,
a container orchestrator may respond to a failing health check by halting a rolling deployment or restarting a
container. A load balancer might react to an unhealthy app by routing traffic away from the failing instance to a
healthy instance.
Use of memory, disk, and other physical server resources can be monitored for healthy status.
Health checks can test an app's dependencies, such as databases and external service endpoints, to confirm
availability and normal functioning.
View or download sample code (how to download)
The sample app includes examples of the scenarios described in this topic. To run the sample app for a given
scenario, use the dotnet run command from the project's folder in a command shell. See the sample app's
README.md file and the scenario descriptions in this topic for details on how to use the sample app.

Prerequisites
Health checks are usually used with an external monitoring service or container orchestrator to check the status of
an app. Before adding health checks to an app, decide on which monitoring system to use. The monitoring system
dictates what types of health checks to create and how to configure their endpoints.
Reference the Microsoft.AspNetCore.App metapackage or add a package reference to the
Microsoft.AspNetCore.Diagnostics.HealthChecks package.
The sample app provides startup code to demonstrate health checks for several scenarios. The database probe
scenario checks the health of a database connection using AspNetCore.Diagnostics.HealthChecks. The DbContext
probe scenario checks a database using an EF Core DbContext . To explore the database scenarios, the sample app:
Creates a database and provides its connection string in the appsettings.json file.
Has the following package references in its project file:
AspNetCore.HealthChecks.SqlServer
Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore

NOTE
AspNetCore.Diagnostics.HealthChecks is a port of BeatPulse and isn't maintained or supported by Microsoft.

Another health check scenario demonstrates how to filter health checks to a management port. The sample app
requires you to create a Properties/launchSettings.json file that includes the management URL and management
port. For more information, see the Filter by port section.
Basic health probe
For many apps, a basic health probe configuration that reports the app's availability to process requests (liveness)
is sufficient to discover the status of the app.
The basic configuration registers health check services and calls the Health Check Middleware to respond at a
URL endpoint with a health response. By default, no specific health checks are registered to test any particular
dependency or subsystem. The app is considered healthy if it's capable of responding at the health endpoint URL.
The default response writer writes the status (HealthStatus) as a plaintext response back to the client, indicating
either a HealthStatus.Healthy, HealthStatus.Degraded or HealthStatus.Unhealthy status.
Register health check services with AddHealthChecks in Startup.ConfigureServices . Add Health Check
Middleware with UseHealthChecks in the request processing pipeline of Startup.Configure .
In the sample app, the health check endpoint is created at /health (BasicStartup.cs):

public class BasicStartup

{
public void ConfigureServices(IServiceCollection services)
{
services.AddHealthChecks();
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
app.UseHealthChecks("/health");

app.Run(async (context) =>

{
await context.Response.WriteAsync(
"Navigate to /health to see the health status.");
});
}
}

To run the basic configuration scenario using the sample app, execute the following command from the project's
folder in a command shell:

dotnet run --scenario basic

Docker example
Docker offers a built-in HEALTHCHECK directive that can be used to check the status of an app that uses the basic
health check configuration:

HEALTHCHECK CMD curl --fail http://localhost:5000/health || exit

Create health checks

Health checks are created by implementing the IHealthCheck interface. The CheckHealthAsync method returns a
Task< HealthCheckResult > that indicates the health as Healthy , Degraded , or Unhealthy . The result is written
as a plaintext response with a configurable status code (configuration is described in the Health check options
section). HealthCheckResult can also return optional key-value pairs.
Example health check
The following ExampleHealthCheck class demonstrates the layout of a health check:
 public class ExampleHealthCheck : IHealthCheck
{
public ExampleHealthCheck()
{
// Use dependency injection (DI) to supply any required services to the
// health check.
}

public Task<HealthCheckResult> CheckHealthAsync(

HealthCheckContext context,
CancellationToken cancellationToken = default(CancellationToken))
{
// Execute health check logic here. This example sets a dummy
// variable to true.
var healthCheckResultHealthy = true;

if (healthCheckResultHealthy)
{
return Task.FromResult(
HealthCheckResult.Healthy("The check indicates a healthy result."));
}

return Task.FromResult(
HealthCheckResult.Unhealthy("The check indicates an unhealthy result."));
}
}

Register health check services

The ExampleHealthCheck type is added to health check services with AddCheck:

public void ConfigureServices(IServiceCollection services)

{
services.AddHealthChecks()
.AddCheck<ExampleHealthCheck>("example_health_check");
}

The AddCheck overload shown in the following example sets the failure status (HealthStatus) to report when the
health check reports a failure. If the failure status is set to null (default), HealthStatus.Unhealthy is reported. This
overload is a useful scenario for library authors, where the failure status indicated by the library is enforced by the
app when a health check failure occurs if the health check implementation honors the setting.
Tags can be used to filter health checks (described further in the Filter health checks section).

services.AddHealthChecks()
.AddCheck<ExampleHealthCheck>(
"example_health_check",
failureStatus: HealthStatus.Degraded,
tags: new[] { "example" });

AddCheck can also execute a lambda function. In the following example, the health check name is specified as
Example and the check always returns a healthy state:

public void ConfigureServices(IServiceCollection services)

{
services.AddHealthChecks()
.AddCheck("Example", () =>
HealthCheckResult.Healthy("Example is OK!"), tags: new[] { "example" })
}
Use Health Checks Middleware
In Startup.Configure , call UseHealthChecks in the processing pipeline with the endpoint URL or relative path:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
app.UseHealthChecks("/health");
}

If the health checks should listen on a specific port, use an overload of UseHealthChecks to set the port (described
further in the Filter by port section):

app.UseHealthChecks("/health", port: 8000);

Health Checks Middleware is a terminal middleware in the app's request processing pipeline. The first health
check endpoint encountered that's an exact match to the request URL executes and short-circuits the rest of the
middleware pipeline. When short-circuiting occurs, no middleware following the matched health check executes.

Health check options

HealthCheckOptions provide an opportunity to customize health check behavior:
Filter health checks
Customize the HTTP status code
Suppress cache headers
Customize output
Filter health checks
By default, Health Check Middleware runs all registered health checks. To run a subset of health checks, provide a
function that returns a boolean to the Predicate option. In the following example, the Bar health check is filtered
out by its tag ( bar_tag ) in the function's conditional statement, where true is only returned if the health check's
Tags property matches foo_tag or baz_tag :

using System.Threading.Tasks;
using Microsoft.AspNetCore.Diagnostics.HealthChecks;
using Microsoft.Extensions.Diagnostics.HealthChecks;

public void ConfigureServices(IServiceCollection services)

{
services.AddHealthChecks()
.AddCheck("Foo", () =>
HealthCheckResult.Healthy("Foo is OK!"), tags: new[] { "foo_tag" })
.AddCheck("Bar", () =>
HealthCheckResult.Unhealthy("Bar is unhealthy!"), tags: new[] { "bar_tag" })
.AddCheck("Baz", () =>
HealthCheckResult.Healthy("Baz is OK!"), tags: new[] { "baz_tag" });
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
app.UseHealthChecks("/health", new HealthCheckOptions()
{
// Filter out the 'Bar' health check. Only Foo and Baz execute.
Predicate = (check) => check.Tags.Contains("foo_tag") ||
check.Tags.Contains("baz_tag")
});
}
Customize the HTTP status code
Use ResultStatusCodes to customize the mapping of health status to HTTP status codes. The following
StatusCodes assignments are the default values used by the middleware. Change the status code values to meet
your requirements.

using Microsoft.AspNetCore.Diagnostics.HealthChecks;
using Microsoft.Extensions.Diagnostics.HealthChecks;

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
app.UseHealthChecks("/health", new HealthCheckOptions()
{
// The following StatusCodes are the default assignments for
// the HealthStatus properties.
ResultStatusCodes =
{
[HealthStatus.Healthy] = StatusCodes.Status200OK,
[HealthStatus.Degraded] = StatusCodes.Status200OK,
[HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
}
});
}

Suppress cache headers

AllowCachingResponses controls whether the Health Check Middleware adds HTTP headers to a probe response
to prevent response caching. If the value is false (default), the middleware sets or overrides the Cache-Control ,
Expires , and Pragma headers to prevent response caching. If the value is true , the middleware doesn't modify
the cache headers of the response.

using Microsoft.AspNetCore.Diagnostics.HealthChecks;
using Microsoft.Extensions.Diagnostics.HealthChecks;

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
app.UseHealthChecks("/health", new HealthCheckOptions()
{
// The default value is false.
AllowCachingResponses = false
});
}

Customize output
The ResponseWriter option gets or sets a delegate used to write the response. The default delegate writes a
minimal plaintext response with the string value of HealthReport.Status.
 using Microsoft.AspNetCore.Diagnostics.HealthChecks;
using Microsoft.Extensions.Diagnostics.HealthChecks;

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
app.UseHealthChecks("/health", new HealthCheckOptions()
{
// WriteResponse is a delegate used to write the response.
ResponseWriter = WriteResponse
});
}

private static Task WriteResponse(HttpContext httpContext,

HealthReport result)
{
httpContext.Response.ContentType = "application/json";

var json = new JObject(

new JProperty("status", result.Status.ToString()),
new JProperty("results", new JObject(result.Entries.Select(pair =>
new JProperty(pair.Key, new JObject(
new JProperty("status", pair.Value.Status.ToString()),
new JProperty("description", pair.Value.Description),
new JProperty("data", new JObject(pair.Value.Data.Select(
p => new JProperty(p.Key, p.Value))))))))));
return httpContext.Response.WriteAsync(
json.ToString(Formatting.Indented));
}

Database probe
A health check can specify a database query to run as a boolean test to indicate if the database is responding
normally.
The sample app uses AspNetCore.Diagnostics.HealthChecks, a health check library for ASP.NET Core apps, to
perform a health check on a SQL Server database. AspNetCore.Diagnostics.HealthChecks executes a SELECT 1
query against the database to confirm the connection to the database is healthy.

WARNING
When checking a database connection with a query, choose a query that returns quickly. The query approach runs the risk
of overloading the database and degrading its performance. In most cases, running a test query isn't necessary. Merely
making a successful connection to the database is sufficient. If you find it necessary to run a query, choose a simple SELECT
query, such as SELECT 1 .

Include a package reference to AspNetCore.HealthChecks.SqlServer.

Supply a valid database connection string in the appsettings.json file of the sample app. The app uses a SQL
Server database named HealthCheckSample :
 {
"ConnectionStrings": {
"DefaultConnection": "Server=
(localdb)\\MSSQLLocalDB;Database=HealthCheckSample;Trusted_Connection=True;MultipleActiveResultSets=true;Conne
ctRetryCount=0"
},
"Logging": {
"LogLevel": {
"Default": "Debug"
},
"Console": {
"IncludeScopes": "true"
}
}
}

Register health check services with AddHealthChecks in Startup.ConfigureServices . The sample app calls the
AddSqlServer method with the database's connection string (DbHealthStartup.cs):

public void ConfigureServices(IServiceCollection services)

{
services.AddHealthChecks()
.AddSqlServer(Configuration["ConnectionStrings:DefaultConnection"]);
}

Call Health Check Middleware in the app processing pipeline in Startup.Configure :

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
app.UseHealthChecks("/health");

To run the database probe scenario using the sample app, execute the following command from the project's
folder in a command shell:

dotnet run --scenario db

NOTE
AspNetCore.Diagnostics.HealthChecks is a port of BeatPulse and isn't maintained or supported by Microsoft.

Entity Framework Core DbContext probe

The check confirms that the app can communicate with the database configured for an EF Core
DbContext
DbContext . The DbContext check is supported in apps that:

Use Entity Framework (EF ) Core.

Include a package reference to Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore.
AddDbContextCheck<TContext> registers a health check for a DbContext . The DbContext is supplied as the TContext
to the method. An overload is available to configure the failure status, tags, and a custom test query.
By default:
The DbContextHealthCheck calls EF Core's CanConnectAsync method. You can customize what operation is run
when checking health using AddDbContextCheck method overloads.
 The name of the health check is the name of the TContext type.

In the sample app, AppDbContext is provided to AddDbContextCheck and registered as a service in

Startup.ConfigureServices .
DbContextHealthStartup.cs:

public void ConfigureServices(IServiceCollection services)

{
services.AddHealthChecks()
.AddDbContextCheck<AppDbContext>();

services.AddDbContext<AppDbContext>(options =>
{
options.UseSqlServer(
Configuration["ConnectionStrings:DefaultConnection"]);
});
}

In the sample app, UseHealthChecks adds the Health Check Middleware in Startup.Configure .
DbContextHealthStartup.cs:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
app.UseHealthChecks("/health");

To run the DbContext probe scenario using the sample app, confirm that the database specified by the connection
string doesn't exist in the SQL Server instance. If the database exists, delete it.
Execute the following command from the project's folder in a command shell:

dotnet run --scenario dbcontext

After the app is running, check the health status by making a request to the /health endpoint in a browser. The
database and AppDbContext don't exist, so app provides the following response:

Unhealthy

Trigger the sample app to create the database. Make a request to /createdatabase . The app responds:

Creating the database...

Done!
Navigate to /health to see the health status.

Make a request to the /health endpoint. The database and context exist, so app responds:

Healthy

Trigger the sample app to delete the database. Make a request to /deletedatabase . The app responds:

Deleting the database...

Done!
Navigate to /health to see the health status.
Make a request to the /health endpoint. The app provides an unhealthy response:

Unhealthy

Separate readiness and liveness probes

In some hosting scenarios, a pair of health checks are used that distinguish two app states:
The app is functioning but not yet ready to receive requests. This state is the app's readiness.
The app is functioning and responding to requests. This state is the app's liveness.
The readiness check usually performs a more extensive and time-consuming set of checks to determine if all of the
app's subsystems and resources are available. A liveness check merely performs a quick check to determine if the
app is available to process requests. After the app passes its readiness check, there's no need to burden the app
further with the expensive set of readiness checks—further checks only require checking for liveness.
The sample app contains a health check to report the completion of long-running startup task in a Hosted Service.
The StartupHostedServiceHealthCheck exposes a property, StartupTaskCompleted , that the hosted service can set to
true when its long-running task is finished ( StartupHostedServiceHealthCheck.cs):

public class StartupHostedServiceHealthCheck : IHealthCheck

{
private volatile bool _startupTaskCompleted = false;

public string Name => "slow_dependency_check";

public bool StartupTaskCompleted

{
get => _startupTaskCompleted;
set => _startupTaskCompleted = value;
}

public Task<HealthCheckResult> CheckHealthAsync(

HealthCheckContext context,
CancellationToken cancellationToken = default(CancellationToken))
{
if (StartupTaskCompleted)
{
return Task.FromResult(
HealthCheckResult.Healthy("The startup task is finished."));
}

return Task.FromResult(
HealthCheckResult.Unhealthy("The startup task is still running."));
}
}

The long-running background task is started by a Hosted Service (Services/StartupHostedService). At the

conclusion of the task, StartupHostedServiceHealthCheck.StartupTaskCompleted is set to true :
 public class StartupHostedService : IHostedService, IDisposable
{
private readonly int _delaySeconds = 15;
private readonly ILogger _logger;
private readonly StartupHostedServiceHealthCheck _startupHostedServiceHealthCheck;

public StartupHostedService(ILogger<StartupHostedService> logger,

StartupHostedServiceHealthCheck startupHostedServiceHealthCheck)
{
_logger = logger;
_startupHostedServiceHealthCheck = startupHostedServiceHealthCheck;
}

public Task StartAsync(CancellationToken cancellationToken)

{
_logger.LogInformation($"Startup Background Service is starting.");

// Simulate the effect of a long-running startup task.

Task.Run(async () =>
{
await Task.Delay(_delaySeconds * 1000);

_startupHostedServiceHealthCheck.StartupTaskCompleted = true;

_logger.LogInformation($"Startup Background Service has started.");

});

return Task.CompletedTask;
}

public Task StopAsync(CancellationToken cancellationToken)

{
_logger.LogInformation("Startup Background Service is stopping.");

return Task.CompletedTask;
}

public void Dispose()

{
}
}

The health check is registered with AddCheck in Startup.ConfigureServices along with the hosted service.
Because the hosted service must set the property on the health check, the health check is also registered in the
service container (LivenessProbeStartup.cs):
 public void ConfigureServices(IServiceCollection services)
{
services.AddHostedService<StartupHostedService>();
services.AddSingleton<StartupHostedServiceHealthCheck>();

services.AddHealthChecks()
.AddCheck<StartupHostedServiceHealthCheck>(
"hosted_service_startup",
failureStatus: HealthStatus.Degraded,
tags: new[] { "ready" });

services.Configure<HealthCheckPublisherOptions>(options =>
{
options.Delay = TimeSpan.FromSeconds(2);
options.Predicate = (check) => check.Tags.Contains("ready");
});

// The following workaround permits adding an IHealthCheckPublisher

// instance to the service container when one or more other hosted
// services have already been added to the app. This workaround
// won't be required with the release of ASP.NET Core 3.0. For more
// information, see: https://github.com/aspnet/Extensions/issues/639.
services.TryAddEnumerable(
ServiceDescriptor.Singleton(typeof(IHostedService),
typeof(HealthCheckPublisherOptions).Assembly
.GetType(HealthCheckServiceAssembly)));

services.AddSingleton<IHealthCheckPublisher, ReadinessPublisher>();
}

Call Health Check Middleware in the app processing pipeline in Startup.Configure . In the sample app, the health
check endpoints are created at /health/ready for the readiness check and /health/live for the liveness check.
The readiness check filters health checks to the health check with the ready tag. The liveness check filters out the
StartupHostedServiceHealthCheck by returning false in the HealthCheckOptions.Predicate (for more information,
see Filter health checks):

public void Configure(IApplicationBuilder app)

{
// The readiness check uses all registered checks with the 'ready' tag.
app.UseHealthChecks("/health/ready", new HealthCheckOptions()
{
Predicate = (check) => check.Tags.Contains("ready"),
});

app.UseHealthChecks("/health/live", new HealthCheckOptions()

{
// Exclude all checks and return a 200-Ok.
Predicate = (_) => false
});

To run the readiness/liveness configuration scenario using the sample app, execute the following command from
the project's folder in a command shell:

dotnet run --scenario liveness

In a browser, visit /health/ready several times until 15 seconds have passed. The health check reports Unhealthy
for the first 15 seconds. After 15 seconds, the endpoint reports Healthy, which reflects the completion of the long-
running task by the hosted service.
This example also creates a Health Check Publisher (IHealthCheckPublisher implementation) that runs the first
readiness check with a two second delay. For more information, see the Health Check Publisher section.
Kubernetes example
Using separate readiness and liveness checks is useful in an environment such as Kubernetes. In Kubernetes, an
app might be required to perform time-consuming startup work before accepting requests, such as a test of the
underlying database availability. Using separate checks allows the orchestrator to distinguish whether the app is
functioning but not yet ready or if the app has failed to start. For more information on readiness and liveness
probes in Kubernetes, see Configure Liveness and Readiness Probes in the Kubernetes documentation.
The following example demonstrates a Kubernetes readiness probe configuration:

spec:
template:
spec:
readinessProbe:
# an http probe
httpGet:
path: /health/ready
port: 80
# length of time to wait for a pod to initialize
# after pod startup, before applying health checking
initialDelaySeconds: 30
timeoutSeconds: 1
ports:
- containerPort: 80

Metric-based probe with a custom response writer

The sample app demonstrates a memory health check with a custom response writer.
MemoryHealthCheck reports a degraded status if the app uses more than a given threshold of memory (1 GB in the
sample app). The HealthCheckResult includes Garbage Collector (GC ) information for the app
(MemoryHealthCheck.cs):
 public class MemoryHealthCheck : IHealthCheck
{
private readonly IOptionsMonitor<MemoryCheckOptions> _options;

public MemoryHealthCheck(IOptionsMonitor<MemoryCheckOptions> options)

{
_options = options;
}

public string Name => "memory_check";

public Task<HealthCheckResult> CheckHealthAsync(

HealthCheckContext context,
CancellationToken cancellationToken = default(CancellationToken))
{
var options = _options.Get(context.Registration.Name);

// Include GC information in the reported diagnostics.

var allocated = GC.GetTotalMemory(forceFullCollection: false);
var data = new Dictionary<string, object>()
{
{ "AllocatedBytes", allocated },
{ "Gen0Collections", GC.CollectionCount(0) },
{ "Gen1Collections", GC.CollectionCount(1) },
{ "Gen2Collections", GC.CollectionCount(2) },
};

var status = (allocated < options.Threshold) ?

HealthStatus.Healthy : HealthStatus.Unhealthy;

return Task.FromResult(new HealthCheckResult(

status,
description: "Reports degraded status if allocated bytes " +
$">= {options.Threshold} bytes.",
exception: null,
data: data));
}
}

Register health check services with AddHealthChecks in Startup.ConfigureServices . Instead of enabling the health
check by passing it to AddCheck, the MemoryHealthCheck is registered as a service. All IHealthCheck registered
services are available to the health check services and middleware. We recommend registering health check
services as Singleton services.
CustomWriterStartup.cs:

public void ConfigureServices(IServiceCollection services)

{
services.AddHealthChecks()
.AddMemoryHealthCheck("memory");
}

Call Health Check Middleware in the app processing pipeline in Startup.Configure . A WriteResponse delegate is
provided to the ResponseWriter property to output a custom JSON response when the health check executes:
 public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseHealthChecks("/health", new HealthCheckOptions()
{
// This custom writer formats the detailed status as JSON.
ResponseWriter = WriteResponse
});

The WriteResponse method formats the CompositeHealthCheckResult into a JSON object and yields JSON output
for the health check response:

private static Task WriteResponse(HttpContext httpContext,

HealthReport result)
{
httpContext.Response.ContentType = "application/json";

var json = new JObject(

new JProperty("status", result.Status.ToString()),
new JProperty("results", new JObject(result.Entries.Select(pair =>
new JProperty(pair.Key, new JObject(
new JProperty("status", pair.Value.Status.ToString()),
new JProperty("description", pair.Value.Description),
new JProperty("data", new JObject(pair.Value.Data.Select(
p => new JProperty(p.Key, p.Value))))))))));
return httpContext.Response.WriteAsync(
json.ToString(Formatting.Indented));
}

To run the metric-based probe with custom response writer output using the sample app, execute the following
command from the project's folder in a command shell:

dotnet run --scenario writer

NOTE
AspNetCore.Diagnostics.HealthChecks includes metric-based health check scenarios, including disk storage and maximum
value liveness checks.
AspNetCore.Diagnostics.HealthChecks is a port of BeatPulse and isn't maintained or supported by Microsoft.

Filter by port
Calling UseHealthChecks with a port restricts health check requests to the port specified. This is typically used in a
container environment to expose a port for monitoring services.
The sample app configures the port using the Environment Variable Configuration Provider. The port is set in the
launchSettings.json file and passed to the configuration provider via an environment variable. You must also
configure the server to listen to requests on the management port.
To use the sample app to demonstrate management port configuration, create the launchSettings.json file in a
Properties folder.
The following launchSettings.json file isn't included in the sample app's project files and must be created manually.
Properties/launchSettings.json:
 {
"profiles": {
"SampleApp": {
"commandName": "Project",
"commandLineArgs": "",
"launchBrowser": true,
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development",
"ASPNETCORE_URLS": "http://localhost:5000/;http://localhost:5001/",
"ASPNETCORE_MANAGEMENTPORT": "5001"
},
"applicationUrl": "http://localhost:5000/"
}
}
}

Register health check services with AddHealthChecks in Startup.ConfigureServices . The call to UseHealthChecks
specifies the management port (ManagementPortStartup.cs):

public class ManagementPortStartup

{
public ManagementPortStartup(IConfiguration configuration)
{
Configuration = configuration;
}

public IConfiguration Configuration { get; }

public void ConfigureServices(IServiceCollection services)

{
services.AddHealthChecks();
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{

app.UseHealthChecks("/health", port: Configuration["ManagementPort"]);

app.Run(async (context) =>

{
await context.Response.WriteAsync(
"Navigate to " +
$"http://localhost:{Configuration["ManagementPort"]}/health " +
"to see the health status.");
});
}
}
 NOTE
You can avoid creating the launchSettings.json file in the sample app by setting the URLs and management port explicitly in
code. In Program.cs where the WebHostBuilder is created, add a call to UseUrls and provide the app's normal response
endpoint and the management port endpoint. In ManagementPortStartup.cs where UseHealthChecks is called, specify the
management port explicitly.
Program.cs:

return new WebHostBuilder()

.UseConfiguration(config)
.UseUrls("http://localhost:5000/;http://localhost:5001/")
.ConfigureLogging(builder =>
{
builder.SetMinimumLevel(LogLevel.Trace);
builder.AddConfiguration(config);
builder.AddConsole();
})
.UseKestrel()
.UseStartup(startupType)
.Build();

ManagementPortStartup.cs:

app.UseHealthChecks("/health", port: 5001);

To run the management port configuration scenario using the sample app, execute the following command from
the project's folder in a command shell:

dotnet run --scenario port

Distribute a health check library

To distribute a health check as a library:
1. Write a health check that implements the IHealthCheck interface as a standalone class. The class can rely on
dependency injection (DI), type activation, and named options to access configuration data.
 using System;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Diagnostics.HealthChecks;

namespace SampleApp
{
public class ExampleHealthCheck : IHealthCheck
{
private readonly string _data1;
private readonly int? _data2;

public ExampleHealthCheck(string data1, int? data2)

{
_data1 = data1 ?? throw new ArgumentNullException(nameof(data1));
_data2 = data2 ?? throw new ArgumentNullException(nameof(data2));
}

public async Task<HealthCheckResult> CheckHealthAsync(

HealthCheckContext context, CancellationToken cancellationToken)
{
try
{
// Health check logic
//
// data1 and data2 are used in the method to
// run the probe's health check logic.

// Assume that it's possible for this health check

// to throw an AccessViolationException.

return HealthCheckResult.Healthy();
}
catch (AccessViolationException ex)
{
return new HealthCheckResult(
context.Registration.FailureStatus,
description: "An access violation occurred during the check.",
exception: ex,
data: null);
}
}
}
}

2. Write an extension method with parameters that the consuming app calls in its Startup.Configure method.
In the following example, assume the following health check method signature:

ExampleHealthCheck(string, string, int )

The preceding signature indicates that the ExampleHealthCheck requires additional data to process the
health check probe logic. The data is provided to the delegate used to create the health check instance when
the health check is registered with an extension method. In the following example, the caller specifies
optional:
health check name ( name ). If null , example_health_check is used.
string data point for the health check ( data1 ).
integer data point for the health check ( data2 ). If null , 1 is used.
failure status (HealthStatus). The default is null . If null , HealthStatus.Unhealthy is reported for a
failure status.
tags ( IEnumerable<string> ).
 using System.Collections.Generic;
using Microsoft.Extensions.Diagnostics.HealthChecks;

public static class ExampleHealthCheckBuilderExtensions

{
const string NAME = "example_health_check";

public static IHealthChecksBuilder AddExampleHealthCheck(

this IHealthChecksBuilder builder,
string name = default,
string data1,
int data2 = 1,
HealthStatus? failureStatus = default,
IEnumerable<string> tags = default)
{
return builder.Add(new HealthCheckRegistration(
name ?? NAME,
sp => new ExampleHealthCheck(data1, data2),
failureStatus,
tags));
}
}

Health Check Publisher

When an IHealthCheckPublisher is added to the service container, the health check system periodically executes
your health checks and calls PublishAsync with the result. This is useful in a push-based health monitoring system
scenario that expects each process to call the monitoring system periodically in order to determine health.
The IHealthCheckPublisher interface has a single method:

Task PublishAsync(HealthReport report, CancellationToken cancellationToken);

HealthCheckPublisherOptions allow you to set:

Delay – The initial delay applied after the app starts before executing IHealthCheckPublisher instances. The
delay is applied once at startup and doesn't apply to subsequent iterations. The default value is five seconds.
Period – The period of IHealthCheckPublisher execution. The default value is 30 seconds.
Predicate – If Predicate is null (default), the health check publisher service runs all registered health checks.
To run a subset of health checks, provide a function that filters the set of checks. The predicate is evaluated each
period.
Timeout – The timeout for executing the health checks for all IHealthCheckPublisher instances. Use
InfiniteTimeSpan to execute without a timeout. The default value is 30 seconds.

WARNING
In the ASP.NET Core 2.2 release, setting Period isn't honored by the IHealthCheckPublisher implementation; it sets the value
of Delay. This issue will be fixed in ASP.NET Core 3.0. For more information, see HealthCheckPublisherOptions.Period sets the
value of .Delay.

In the sample app, ReadinessPublisher is an IHealthCheckPublisher implementation. The health check status is
recorded in Entries and logged for each check:
 public class ReadinessPublisher : IHealthCheckPublisher
{
private readonly ILogger _logger;

public ReadinessPublisher(ILogger<ReadinessPublisher> logger)

{
_logger = logger;
}

public List<(HealthReport report, CancellationToken cancellationToken)>

Entries { get; } =
new List<(HealthReport report,
CancellationToken cancellationToken)>();

public Exception Exception { get; set; }

public Task PublishAsync(HealthReport report,

CancellationToken cancellationToken)
{
Entries.Add((report, cancellationToken));

_logger.LogInformation("{TIMESTAMP} Readiness Probe Status: {RESULT}",

DateTime.UtcNow, report.Status);

if (Exception != null)
{
throw Exception;
}

cancellationToken.ThrowIfCancellationRequested();

return Task.CompletedTask;
}
}

In the sample app's LivenessProbeStartup example, the StartupHostedService readiness check has a two second
startup delay and runs the check every 30 seconds. To activate the IHealthCheckPublisher implementation, the
sample registers ReadinessPublisher as a singleton service in the dependency injection (DI) container:
 public void ConfigureServices(IServiceCollection services)
{
services.AddHostedService<StartupHostedService>();
services.AddSingleton<StartupHostedServiceHealthCheck>();

services.AddHealthChecks()
.AddCheck<StartupHostedServiceHealthCheck>(
"hosted_service_startup",
failureStatus: HealthStatus.Degraded,
tags: new[] { "ready" });

services.Configure<HealthCheckPublisherOptions>(options =>
{
options.Delay = TimeSpan.FromSeconds(2);
options.Predicate = (check) => check.Tags.Contains("ready");
});

// The following workaround permits adding an IHealthCheckPublisher

// instance to the service container when one or more other hosted
// services have already been added to the app. This workaround
// won't be required with the release of ASP.NET Core 3.0. For more
// information, see: https://github.com/aspnet/Extensions/issues/639.
services.TryAddEnumerable(
ServiceDescriptor.Singleton(typeof(IHostedService),
typeof(HealthCheckPublisherOptions).Assembly
.GetType(HealthCheckServiceAssembly)));

services.AddSingleton<IHealthCheckPublisher, ReadinessPublisher>();
}

NOTE
The following workaround permits adding an IHealthCheckPublisher instance to the service container when one or more
other hosted services have already been added to the app. This workaround won't be required with the release of ASP.NET
Core 3.0. For more information, see: https://github.com/aspnet/Extensions/issues/639.

private const string HealthCheckServiceAssembly =

"Microsoft.Extensions.Diagnostics.HealthChecks.HealthCheckPublisherHostedService";

services.TryAddEnumerable(
ServiceDescriptor.Singleton(typeof(IHostedService),
typeof(HealthCheckPublisherOptions).Assembly
.GetType(HealthCheckServiceAssembly)));

NOTE
AspNetCore.Diagnostics.HealthChecks includes publishers for several systems, including Application Insights.
AspNetCore.Diagnostics.HealthChecks is a port of BeatPulse and isn't maintained or supported by Microsoft.

Restrict health checks with MapWhen

Use MapWhen to conditionally branch the request pipeline for health check endpoints.
In the following example, MapWhen branches the request pipeline to activate Health Check Middleware if a GET
request is received for the api/HealthCheck endpoint:
 app.MapWhen(
context => context.Request.Method == HttpMethod.Get.Method &&
context.Request.Path.StartsWith("/api/HealthCheck"),
builder => builder.UseHealthChecks());

app.UseMvc();

For more information, see ASP.NET Core Middleware.

 Host and deploy ASP.NET Core Blazor
8/9/2019 • 2 minutes to read • Edit Online

By Luke Latham, Rainer Stropek, and Daniel Roth

Publish the app

Apps are published for deployment in Release configuration.
Visual Studio
.NET Core CLI
1. Select Build > Publish {APPLICATION } from the navigation bar.
2. Select the publish target. To publish locally, select Folder.
3. Accept the default location in the Choose a folder field or specify a different location. Select the Publish
button.
Publishing the app triggers a restore of the project's dependencies and builds the project before creating the assets
for deployment. As part of the build process, unused methods and assemblies are removed to reduce app
download size and load times.
A Blazor client-side app is published to the /bin/Release/{TARGET FRAMEWORK }/publish/{ASSEMBLY
NAME }/dist folder. A Blazor server-side app is published to the /bin/Release/{TARGET FRAMEWORK }/publish
folder.
The assets in the folder are deployed to the web server. Deployment might be a manual or automated process
depending on the development tools in use.

Deployment
For deployment guidance, see the following topics:
Host and deploy ASP.NET Core Blazor client-side
Host and deploy ASP.NET Core Blazor server-side

Blazor serverless hosting with Azure Storage

Blazor client-side apps can be served from Azure Storage as static content directly from a storage container.
For more information, see Host and deploy ASP.NET Core Blazor client-side (Standalone deployment): Azure
Storage.
 Host and deploy ASP.NET Core Blazor client-side
8/13/2019 • 11 minutes to read • Edit Online

By Luke Latham, Rainer Stropek, and Daniel Roth

Host configuration values

Blazor apps that use the client-side hosting model can accept the following host configuration values as
command-line arguments at runtime in the development environment.
Content Root
The --contentroot argument sets the absolute path to the directory that contains the app's content files. In the
following examples, /content-root-path is the app's content root path.
Pass the argument when running the app locally at a command prompt. From the app's directory, execute:

dotnet run --contentroot=/content-root-path

Add an entry to the app's launchSettings.json file in the IIS Express profile. This setting is used when the
app is run with the Visual Studio Debugger and from a command prompt with dotnet run .

"commandLineArgs": "--contentroot=/content-root-path"

In Visual Studio, specify the argument in Properties > Debug > Application arguments. Setting the
argument in the Visual Studio property page adds the argument to the launchSettings.json file.

--contentroot=/content-root-path

Path base
The --pathbase argument sets the app base path for an app run locally with a non-root virtual path (the <base>
tag href is set to a path other than / for staging and production). In the following examples, /virtual-path is
the app's path base. For more information, see the App base path section.

IMPORTANT
Unlike the path provided to href of the <base> tag, don't include a trailing slash ( / ) when passing the --pathbase
argument value. If the app base path is provided in the <base> tag as <base href="/CoolApp/"> (includes a trailing
slash), pass the command-line argument value as --pathbase=/CoolApp (no trailing slash).

Pass the argument when running the app locally at a command prompt. From the app's directory, execute:

dotnet run --pathbase=/virtual-path

Add an entry to the app's launchSettings.json file in the IIS Express profile. This setting is used when
running the app with the Visual Studio Debugger and from a command prompt with dotnet run .
 "commandLineArgs": "--pathbase=/virtual-path"

In Visual Studio, specify the argument in Properties > Debug > Application arguments. Setting the
argument in the Visual Studio property page adds the argument to the launchSettings.json file.

--pathbase=/virtual-path

URLs
The --urls argument sets the IP addresses or host addresses with ports and protocols to listen on for requests.
Pass the argument when running the app locally at a command prompt. From the app's directory, execute:

dotnet run --urls=http://127.0.0.1:0

Add an entry to the app's launchSettings.json file in the IIS Express profile. This setting is used when
running the app with the Visual Studio Debugger and from a command prompt with dotnet run .

"commandLineArgs": "--urls=http://127.0.0.1:0"

In Visual Studio, specify the argument in Properties > Debug > Application arguments. Setting the
argument in the Visual Studio property page adds the argument to the launchSettings.json file.

--urls=http://127.0.0.1:0

Deployment
With the client-side hosting model:
The Blazor app, its dependencies, and the .NET runtime are downloaded to the browser.
The app is executed directly on the browser UI thread. Either of the following strategies is supported:
The Blazor app is served by an ASP.NET Core app. This strategy is covered in the Hosted deployment
with ASP.NET Core section.
The Blazor app is placed on a static hosting web server or service, where .NET isn't used to serve the
Blazor app. This strategy is covered in the Standalone deployment section.

Configure the Linker

Blazor performs Intermediate Language (IL ) linking on each build to remove unnecessary IL from the output
assemblies. Assembly linking can be controlled on build. For more information, see Configure the Linker for
ASP.NET Core Blazor.

Rewrite URLs for correct routing

Routing requests for page components in a client-side app isn't as simple as routing requests to a server-side,
hosted app. Consider a client-side app with two components:
Main.razor – Loads at the root of the app and contains a link to the About component ( href="About" ).
About.razor – About component.

When the app's default document is requested using the browser's address bar (for example,
https://www.contoso.com/ ):
1. The browser makes a request.
2. The default page is returned, which is usually index.html.
3. index.html bootstraps the app.
4. Blazor's router loads, and the Razor Main component is rendered.

In the Main page, selecting the link to the About component works on the client because the Blazor router stops
the browser from making a request on the Internet to www.contoso.com for About and serves the rendered About
component itself. All of the requests for internal endpoints within the client-side app work the same way: Requests
don't trigger browser-based requests to server-hosted resources on the Internet. The router handles the requests
internally.
If a request is made using the browser's address bar for www.contoso.com/About , the request fails. No such
resource exists on the app's Internet host, so a 404 - Not Found response is returned.
Because browsers make requests to Internet-based hosts for client-side pages, web servers and hosting services
must rewrite all requests for resources not physically on the server to the index.html page. When index.html is
returned, the app's client-side router takes over and responds with the correct resource.

App base path

The app base path is the virtual app root path on the server. For example, an app that resides on the Contoso
server in a virtual folder at /CoolApp/ is reached at https://www.contoso.com/CoolApp and has a virtual base path
of /CoolApp/ . By setting the app base path to the virtual path ( <base href="/CoolApp/"> ), the app is made aware
of where it virtually resides on the server. The app can use the app base path to construct URLs relative to the app
root from a component that isn't in the root directory. This allows components that exist at different levels of the
directory structure to build links to other resources at locations throughout the app. The app base path is also
used to intercept hyperlink clicks where the href target of the link is within the app base path URI space—the
Blazor router handles the internal navigation.
In many hosting scenarios, the server's virtual path to the app is the root of the app. In these cases, the app base
path is a forward slash ( <base href="/" /> ), which is the default configuration for an app. In other hosting
scenarios, such as GitHub Pages and IIS virtual directories or sub-applications, the app base path must be set to
the server's virtual path to the app. To set the app's base path, update the <base> tag within the <head> tag
elements of the wwwroot/index.html file. Set the href attribute value to /virtual-path/ (the trailing slash is
required), where /virtual-path/ is the full virtual app root path on the server for the app. In the preceding
example, the virtual path is set to /CoolApp/ : <base href="/CoolApp/"> .
For an app with a non-root virtual path configured (for example, <base href="/CoolApp/"> ), the app fails to find its
resources when run locally. To overcome this problem during local development and testing, you can supply a
path base argument that matches the href value of the <base> tag at runtime.
To pass the path base argument with the root path ( / ) when running the app locally, execute the dotnet run
command from the app's directory with the --pathbase option:

dotnet run --pathbase=/{Virtual Path (no trailing slash)}

For an app with a virtual base path of /CoolApp/ ( <base href="/CoolApp/"> ), the command is:

dotnet run --pathbase=/CoolApp

The app responds locally at http://localhost:port/CoolApp .

For more information, see the section on the path base host configuration value.
If an app uses the client-side hosting model (based on the Blazor WebAssembly App project template, the
blazorwasm template when using the dotnet new command) and is hosted as an IIS sub-app in an ASP.NET Core
app, it's important to disable the inherited ASP.NET Core Module handler or make sure the root (parent) app's
<handlers> section in the web.config file isn't inherited by the sub-app.

Remove the handler in the app's published web.config file by adding a <handlers> section to the file:

<handlers>
<remove name="aspNetCore" />
</handlers>

Alternatively, disable inheritance of the root (parent) app's <system.webServer> section using a <location>
element with inheritInChildApplications set to false :

<?xml version="1.0" encoding="utf-8"?>

<configuration>
<location path="." inheritInChildApplications="false">
<system.webServer>
<handlers>
<add name="aspNetCore" ... />
</handlers>
<aspNetCore ... />
</system.webServer>
</location>
</configuration>

Removing the handler or disabling inheritance is performed in addition to configuring the app's base path as
described in this section. Set the app base path in the app's index.html file to the IIS alias used when configuring
the sub-app in IIS.

Hosted deployment with ASP.NET Core

A hosted deployment serves the Blazor client-side app to browsers from an ASP.NET Core app that runs on a web
server.
The Blazor app is included with the ASP.NET Core app in the published output so that the two apps are deployed
together. A web server that is capable of hosting an ASP.NET Core app is required. For a hosted deployment,
Visual Studio includes the Blazor WebAssembly App project template ( blazorwasm template when using the
dotnet new command) with the Hosted option selected.
For more information on ASP.NET Core app hosting and deployment, see Host and deploy ASP.NET Core.
For information on deploying to Azure App Service, see Publish an ASP.NET Core app to Azure with Visual
Studio.

Standalone deployment
A standalone deployment serves the Blazor client-side app as a set of static files that are requested directly by
clients. Any static file server is able to serve the Blazor app.
Standalone deployment assets are published to the bin/Release/{TARGET FRAMEWORK }/publish/{ASSEMBLY
NAME }/dist folder.
IIS
IIS is a capable static file server for Blazor apps. To configure IIS to host Blazor, see Build a Static Website on IIS.
Published assets are created in the /bin/Release/{TARGET FRAMEWORK }/publish folder. Host the contents of the
publish folder on the web server or hosting service.
web.config
When a Blazor project is published, a web.config file is created with the following IIS configuration:
MIME types are set for the following file extensions:
.dll – application/octet-stream
.json – application/json
.wasm – application/wasm
.woff – application/font-woff
.woff2 – application/font-woff
HTTP compression is enabled for the following MIME types:
application/octet-stream
application/wasm
URL Rewrite Module rules are established:
Serve the sub-directory where the app's static assets reside ({ASSEMBLY NAME }/dist/{PATH
REQUESTED }).
Create SPA fallback routing so that requests for non-file assets are redirected to the app's default
document in its static assets folder ({ASSEMBLY NAME }/dist/index.html).
Install the URL Rewrite Module
The URL Rewrite Module is required to rewrite URLs. The module isn't installed by default, and it isn't available
for install as a Web Server (IIS ) role service feature. The module must be downloaded from the IIS website. Use
the Web Platform Installer to install the module:
1. Locally, navigate to the URL Rewrite Module downloads page. For the English version, select WebPI to
download the WebPI installer. For other languages, select the appropriate architecture for the server (x86/x64)
to download the installer.
2. Copy the installer to the server. Run the installer. Select the Install button and accept the license terms. A
server restart isn't required after the install completes.
Configure the website
Set the website's Physical path to the app's folder. The folder contains:
The web.config file that IIS uses to configure the website, including the required redirect rules and file content
types.
The app's static asset folder.
Troubleshooting
If a 500 - Internal Server Error is received and IIS Manager throws errors when attempting to access the website's
configuration, confirm that the URL Rewrite Module is installed. When the module isn't installed, the web.config
file can't be parsed by IIS. This prevents the IIS Manager from loading the website's configuration and the website
from serving Blazor's static files.
For more information on troubleshooting deployments to IIS, see Troubleshoot ASP.NET Core on Azure App
Service and IIS.
Azure Storage
Azure Storage static file hosting allows serverless Blazor app hosting. Custom domain names, the Azure Content
Delivery Network (CDN ), and HTTPS are supported.
When the blob service is enabled for static website hosting on a storage account:
Set the Index document name to index.html .
 Set the Error document path to index.html . Razor components and other non-file endpoints don't reside at
physical paths in the static content stored by the blob service. When a request for one of these resources is
received that the Blazor router should handle, the 404 - Not Found error generated by the blob service routes
the request to the Error document path. The index.html blob is returned, and the Blazor router loads and
processes the path.
For more information, see Static website hosting in Azure Storage.
Nginx
The following nginx.conf file is simplified to show how to configure Nginx to send the index.html file whenever it
can't find a corresponding file on disk.

events { }
http {
server {
listen 80;

location / {
root /usr/share/nginx/html;
try_files $uri $uri/ /index.html =404;
}
}
}

For more information on production Nginx web server configuration, see Creating NGINX Plus and NGINX
Configuration Files.
Nginx in Docker
To host Blazor in Docker using Nginx, setup the Dockerfile to use the Alpine-based Nginx image. Update the
Dockerfile to copy the nginx.config file into the container.
Add one line to the Dockerfile, as shown in the following example:

FROM nginx:alpine
COPY ./bin/Release/netstandard2.0/publish /usr/share/nginx/html/
COPY nginx.conf /etc/nginx/nginx.conf

GitHub Pages
To handle URL rewrites, add a 404.html file with a script that handles redirecting the request to the index.html
page. For an example implementation provided by the community, see Single Page Apps for GitHub Pages
(rafrex/spa-github-pages on GitHub). An example using the community approach can be seen at blazor-
demo/blazor-demo.github.io on GitHub (live site).
When using a project site instead of an organization site, add or update the <base> tag in index.html. Set the
href attribute value to the GitHub repository name with a trailing slash (for example, my-repository/ .
 Host and deploy Blazor server-side
7/15/2019 • 2 minutes to read • Edit Online

By Luke Latham, Rainer Stropek, and Daniel Roth

Host configuration values

Server-side apps that use the server-side hosting model can accept Generic Host configuration values.

Deployment
With the server-side hosting model, Blazor is executed on the server from within an ASP.NET Core app. UI
updates, event handling, and JavaScript calls are handled over a SignalR connection.
A web server capable of hosting an ASP.NET Core app is required. Visual Studio includes the Blazor Server App
project template ( blazorserverside template when using the dotnet new command).

Connection scale out

Blazor server-side apps require one active SignalR connection for each user. A production Blazor server-side
deployment requires a solution for supporting as many concurrent connections as required by the app. The Azure
SignalR Service handles the scaling of connections and is recommended as a scaling solution for Blazor server-
side apps. For more information, see Publish an ASP.NET Core SignalR app to Azure App Service.

SignalR configuration
SignalR is configured by ASP.NET Core for the most common Blazor server-side scenarios. For custom and
advanced scenarios, consult the SignalR articles in the Additional resources section.

Additional resources
Introduction to ASP.NET Core SignalR
Azure SignalR Service Documentation
Quickstart: Create a chat room by using SignalR Service
Host and deploy ASP.NET Core
Publish an ASP.NET Core app to Azure with Visual Studio
Deploy ASP.NET Core preview release to Azure App Service
 Configure the Linker for ASP.NET Core Blazor
7/3/2019 • 2 minutes to read • Edit Online

By Luke Latham
Blazor performs Intermediate Language (IL ) linking during a Release build to remove unnecessary IL from the
app's output assemblies.
Control assembly linking using either of the following approaches:
Disable linking globally with a MSBuild property.
Control linking on a per-assembly basis with a configuration file.

Disable linking with a MSBuild property

Linking is enabled by default in Release mode when an app is built, which includes publishing. To disable linking
for all assemblies, set the BlazorLinkOnBuild MSBuild property to false in the project file:

<PropertyGroup>
<BlazorLinkOnBuild>false</BlazorLinkOnBuild>
</PropertyGroup>

Control linking with a configuration file

Control linking on a per-assembly basis by providing an XML configuration file and specifying the file as a
MSBuild item in the project file:

<ItemGroup>
<BlazorLinkerDescriptor Include="Linker.xml" />
</ItemGroup>

Linker.xml:
 <?xml version="1.0" encoding="UTF-8" ?>
<!--
This file specifies which parts of the BCL or Blazor packages must not be
stripped by the IL Linker even if they aren't referenced by user code.
-->
<linker>
<assembly fullname="mscorlib">
<!--
Preserve the methods in WasmRuntime because its methods are called by
JavaScript client-side code to implement timers.
Fixes: https://github.com/aspnet/Blazor/issues/239
-->
<type fullname="System.Threading.WasmRuntime" />
</assembly>
<assembly fullname="System.Core">
<!--
System.Linq.Expressions* is required by Json.NET and any
expression.Compile caller. The assembly isn't stripped.
-->
<type fullname="System.Linq.Expressions*" />
</assembly>
<!--
In this example, the app's entry point assembly is listed. The assembly
isn't stripped by the IL Linker.
-->
<assembly fullname="MyCoolBlazorApp" />
</linker>

For more information, see IL Linker: Syntax of xml descriptor.

 Overview of ASP.NET Core Security
4/26/2019 • 2 minutes to read • Edit Online

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, HTTPS 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 other articles in the
Security and Identity section of the table of contents.
 Introduction to Identity on ASP.NET Core
4/26/2019 • 10 minutes to read • Edit Online

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.NET 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, then select Change Authentication.
Select Individual User Accounts and click OK.
The generated project provides ASP.NET Core Identity as a Razor Class Library. The Identity Razor Class
Library exposes endpoints with the Identity area. For example:
/Identity/Account/Login
/Identity/Account/Logout
/Identity/Account/Manage
Apply migrations
Apply the migrations to initialise the database.
Visual Studio
 .NET Core CLI
Run the following command in the Package Manager Console (PMC ):
PM> Update-Database

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.
 public void ConfigureServices(IServiceCollection services)
{
services.Configure<CookiePolicyOptions>(options =>
{
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddDbContext<ApplicationDbContext>(options =>
options.UseSqlServer(
Configuration.GetConnectionString("DefaultConnection")));
services.AddDefaultIdentity<IdentityUser>()
.AddDefaultUI(UIFramework.Bootstrap4)
.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.Cookie.HttpOnly = true;
options.ExpireTimeSpan = TimeSpan.FromMinutes(5);

options.LoginPath = "/Identity/Account/Login";
options.AccessDeniedPath = "/Identity/Account/AccessDenied";
options.SlidingExpiration = true;
});

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}

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.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseDatabaseErrorPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}

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

app.UseAuthentication();

app.UseMvc();
}
 // This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
services.AddDbContext<ApplicationDbContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")));

services.AddIdentity<ApplicationUser, IdentityRole>()
.AddEntityFrameworkStores<ApplicationDbContext>()
.AddDefaultTokenProviders();

services.Configure<IdentityOptions>(options =>
{
// Password settings
options.Password.RequireDigit = true;
options.Password.RequiredLength = 8;
options.Password.RequireNonAlphanumeric = false;
options.Password.RequireUppercase = true;
options.Password.RequireLowercase = false;
options.Password.RequiredUniqueChars = 6;

// Lockout settings
options.Lockout.DefaultLockoutTimeSpan = TimeSpan.FromMinutes(30);
options.Lockout.MaxFailedAccessAttempts = 10;
options.Lockout.AllowedForNewUsers = true;

// User settings
options.User.RequireUniqueEmail = true;
});

services.ConfigureApplicationCookie(options =>
{
// Cookie settings
options.Cookie.HttpOnly = true;
options.ExpireTimeSpan = TimeSpan.FromMinutes(30);
// 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";
options.SlidingExpiration = true;
});

// Add application services.

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.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseBrowserLink();
app.UseDatabaseErrorPage();
}
else
{
app.UseExceptionHandler("/Home/Error");
}

app.UseStaticFiles();

app.UseAuthentication();

app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});
}

public void ConfigureServices(IServiceCollection services)

{
// Add framework services.
services.AddDbContext<ApplicationDbContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")));

services.AddIdentity<ApplicationUser, IdentityRole>()
.AddEntityFrameworkStores<ApplicationDbContext>()
.AddDefaultTokenProviders();

services.AddMvc();

// Configure Identity
services.Configure<IdentityOptions>(options =>
{
// Password settings
options.Password.RequireDigit = true;
options.Password.RequiredLength = 8;
options.Password.RequireNonAlphanumeric = false;
options.Password.RequireUppercase = true;
options.Password.RequireLowercase = false;

// Lockout settings
options.Lockout.DefaultLockoutTimeSpan = TimeSpan.FromMinutes(30);
options.Lockout.MaxFailedAccessAttempts = 10;

// Cookie settings
options.Cookies.ApplicationCookie.ExpireTimeSpan = TimeSpan.FromDays(150);
options.Cookies.ApplicationCookie.LoginPath = "/Account/Login";

// User settings
options.User.RequireUniqueEmail = true;
});

// Add application services.

services.AddTransient<IEmailSender, AuthMessageSender>();
services.AddTransient<ISmsSender, AuthMessageSender>();
}
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.

public void Configure(IApplicationBuilder app,

IHostingEnvironment env,
ILoggerFactory loggerFactory)
{
loggerFactory.AddConsole(Configuration.GetSection("Logging"));
loggerFactory.AddDebug();

if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseDatabaseErrorPage();
app.UseBrowserLink();
}
else
{
app.UseExceptionHandler("/Home/Error");
}

app.UseStaticFiles();

app.UseIdentity();

// Add external authentication middleware below. To configure them please see

https://go.microsoft.com/fwlink/?LinkID=532715

app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});
}

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 to generate the code shown
in this section.
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("~/");
if (ModelState.IsValid)
{
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);

return LocalRedirect(returnUrl);
}
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]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Register(RegisterViewModel model)
{
if (ModelState.IsValid)
{
var user = new ApplicationUser { UserName = model.Email, Email = model.Email };
var result = await _userManager.CreateAsync(user, model.Password);
if (result.Succeeded)
{
// 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>");
await _signInManager.SignInAsync(user, isPersistent: false);
_logger.LogInformation(3, "User created a new account with password.");
return RedirectToAction(nameof(HomeController.Index), "Home");
}
AddErrors(result);
}

// If we got this far, something failed, redisplay form

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.
A user attempts to access a restricted page that they aren't authorized to access or when they haven't been
authenticated by the system.
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).
 public async Task<IActionResult> OnPostAsync(string returnUrl = null)
{
returnUrl = returnUrl ?? Url.Content("~/");

if (ModelState.IsValid)
{
// 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);
if (result.Succeeded)
{
_logger.LogInformation("User logged in.");
return LocalRedirect(returnUrl);
}
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();
}
}

// If we got this far, something failed, redisplay form

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
Introduction to authorization in ASP.NET Core.
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]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Login(LoginViewModel model, string returnUrl = null)
{
ViewData["ReturnUrl"] = returnUrl;
if (ModelState.IsValid)
{
// 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);
if (result.Succeeded)
{
_logger.LogInformation(1, "User logged in.");
return RedirectToLocal(returnUrl);
}
if (result.RequiresTwoFactor)
{
return RedirectToAction(nameof(SendCode), new { ReturnUrl = returnUrl, RememberMe =
model.RememberMe });
}
if (result.IsLockedOut)
{
_logger.LogWarning(2, "User account locked out.");
return View("Lockout");
}
else
{
ModelState.AddModelError(string.Empty, "Invalid login attempt.");
return View(model);
}
}

// If we got this far, something failed, redisplay form

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 Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.Extensions.Logging;
using System.Threading.Tasks;

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)
{
return LocalRedirect(returnUrl);
}
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:
 @using Microsoft.AspNetCore.Identity
@inject SignInManager<IdentityUser> SignInManager
@inject UserManager<IdentityUser> UserManager

<ul class="navbar-nav">
@if (SignInManager.IsSignedIn(User))
{
<li class="nav-item">
<a class="nav-link text-dark" asp-area="Identity"
asp-page="/Account/Manage/Index"
title="Manage">[email protected]!</a>
</li>
<li class="nav-item">
<form class="form-inline" asp-area="Identity" asp-page="/Account/Logout"
asp-route-returnUrl="@Url.Page("/", new { area = "" })"
method="post">
<button type="submit" class="nav-link btn btn-link text-dark">Logout</button>
</form>
</li>
}
else
{
<li class="nav-item">
<a class="nav-link text-dark" asp-area="Identity" asp-page="/Account/Register">Register</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="Identity" asp-page="/Account/Login">Login</a>
</li>
}
</ul>

Clicking the Log out link calls the LogOut action.

//
// POST: /Account/LogOut
[HttpPost]
[ValidateAntiForgeryToken]
public async Task<IActionResult> LogOut()
{
await _signInManager.SignOutAsync();
_logger.LogInformation(4, "User logged out.");
return RedirectToAction(nameof(HomeController.Index), "Home");
}

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 Privacy page.
 using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc.RazorPages;

namespace WebApp1.Pages
{
[Authorize]
public class PrivacyModel : PageModel
{
public void OnGet()
{
}
}
}

If you are signed in, sign out. Run the app and select the Privacy 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 user data to Identity in an ASP.NET Core project
Enable QR Code generation for TOTP authenticator apps in ASP.NET Core
Migrate Authentication and Identity to ASP.NET Core
Account confirmation and password recovery in ASP.NET Core
Two-factor authentication with SMS in ASP.NET Core
Host ASP.NET Core in a web farm
 Authentication and authorization for SPAs
8/6/2019 • 10 minutes to read • Edit Online

ASP.NET Core 3.0 or later offers authentication in Single Page Apps (SPAs) using the support for API
authorization. ASP.NET Core Identity for authenticating and storing users is combined with IdentityServer for
implementing Open ID Connect.
An authentication parameter was added to the Angular and React project templates that is similar to the
authentication parameter in the Web Application (Model-View-Controller) (MVC ) and Web Application
(Razor Pages) project templates. The allowed parameter values are None and Individual. The React.js and
Redux project template doesn't support the authentication parameter at this time.

Create an app with API authorization support

User authentication and authorization can be used with both Angular and React SPAs. Open a command shell, and
run the following command:
Angular:

dotnet new angular -o <output_directory_name> -au Individual

React:

dotnet new react -o <output_directory_name> -au Individual

The preceding command creates an ASP.NET Core app with a ClientApp directory containing the SPA.

General description of the ASP.NET Core components of the app

The following sections describe additions to the project when authentication support is included:
Startup class
The Startup class has the following additions:
Inside the Startup.ConfigureServices method:
Identity with the default UI:

services.AddDbContext<ApplicationDbContext>(options =>
options.UseSqlite(Configuration.GetConnectionString("DefaultConnection")));

services.AddDefaultIdentity<ApplicationUser>()
.AddDefaultUI(UIFramework.Bootstrap4)
.AddEntityFrameworkStores<ApplicationDbContext>();

IdentityServer with an additional AddApiAuthorization helper method that setups some default
ASP.NET Core conventions on top of IdentityServer:

services.AddIdentityServer()
.AddApiAuthorization<ApplicationUser, ApplicationDbContext>();
 Authentication with an additional AddIdentityServerJwt helper method that configures the app to
validate JWT tokens produced by IdentityServer:

services.AddAuthentication()
.AddIdentityServerJwt();

Inside the Startup.Configure method:

The authentication middleware that is responsible for validating the request credentials and setting
the user on the request context:

app.UseAuthentication();

The IdentityServer middleware that exposes the Open ID Connect endpoints:

app.UseIdentityServer();

AddApiAuthorization
This helper method configures IdentityServer to use our supported configuration. IdentityServer is a powerful and
extensible framework for handling app security concerns. At the same time, that exposes unnecessary complexity
for the most common scenarios. Consequently, a set of conventions and configuration options is provided to you
that are considered a good starting point. Once your authentication needs change, the full power of IdentityServer
is still available to customize authentication to suit your needs.
AddIdentityServerJwt
This helper method configures a policy scheme for the app as the default authentication handler. The policy is
configured to let Identity handle all requests routed to any subpath in the Identity URL space "/Identity". The
JwtBearerHandler handles all other requests. Additionally, this method registers an <<ApplicationName>>API API
resource with IdentityServer with a default scope of <<ApplicationName>>API and configures the JWT Bearer token
middleware to validate tokens issued by IdentityServer for the app.
SampleDataController
In the Controllers\SampleDataController.cs file, notice the [Authorize] attribute applied to the class that indicates
that the user needs to be authorized based on the default policy to access the resource. The default authorization
policy happens to be configured to use the default authentication scheme, which is set up by AddIdentityServerJwt
to the policy scheme that was mentioned above, making the JwtBearerHandler configured by such helper method
the default handler for requests to the app.
ApplicationDbContext
In the Data\ApplicationDbContext.cs file, notice the same DbContext is used in Identity with the exception that it
extends ApiAuthorizationDbContext (a more derived class from IdentityDbContext ) to include the schema for
IdentityServer.
To gain full control of the database schema, inherit from one of the available Identity DbContext classes and
configure the context to include the Identity schema by calling
builder.ConfigurePersistedGrantContext(_operationalStoreOptions.Value) on the OnModelCreating method.

OidcConfigurationController
In the Controllers\OidcConfigurationController.cs file, notice the endpoint that's provisioned to serve the OIDC
parameters that the client needs to use.
appsettings.json
In the appsettings.json file of the project root, there's a new IdentityServer section that describes the list of
configured clients. In the following example, there's a single client. The client name corresponds to the app name
and is mapped by convention to the OAuth ClientId parameter. The profile indicates the app type being
configured. It's used internally to drive conventions that simplify the configuration process for the server. There are
several profiles available, as explained in the Application profiles section.

"IdentityServer": {
"Clients": {
"angularindividualpreview3final": {
"Profile": "IdentityServerSPA"
}
}
}

appsettings.Development.json
In the appsettings.Development.json file of the project root, there's an IdentityServer section that describes the
key used to sign tokens. When deploying to production, a key needs to be provisioned and deployed alongside the
app, as explained in the Deploy to production section.

"IdentityServer": {
"Key": {
"Type": "Development"
}
}

General description of the Angular app

The authentication and API authorization support in the Angular template resides in its own Angular module in
the ClientApp\src\api-authorization directory. The module is composed of the following elements:
3 components:
login.component.ts: Handles the app's login flow.
logout.component.ts: Handles the app's logout flow.
login-menu.component.ts: A widget that displays one of the following sets of links:
User profile management and log out links when the user is authenticated.
Registration and log in links when the user isn't authenticated.
A route guard AuthorizeGuard that can be added to routes and requires a user to be authenticated before
visiting the route.
An HTTP interceptor AuthorizeInterceptor that attaches the access token to outgoing HTTP requests targeting
the API when the user is authenticated.
A service AuthorizeService that handles the lower-level details of the authentication process and exposes
information about the authenticated user to the rest of the app for consumption.
An Angular module that defines routes associated with the authentication parts of the app. It exposes the login
menu component, the interceptor, the guard, and the service for consumption from the rest of the app.

General description of the React app

The support for authentication and API authorization in the React template resides in the
ClientApp\src\components\api-authorization directory. It's composed of the following elements:
4 components:
Login.js: Handles the app's login flow.
 Logout.js: Handles the app's logout flow.
LoginMenu.js: A widget that displays one of the following sets of links:
User profile management and log out links when the user is authenticated.
Registration and log in links when the user isn't authenticated.
AuthorizeRoute.js: A route component that requires a user to be authenticated before rendering the
component indicated in the Component parameter.
An exported authService instance of class AuthorizeService that handles the lower-level details of the
authentication process and exposes information about the authenticated user to the rest of the app for
consumption.
Now that you've seen the main components of the solution, you can take a deeper look at individual scenarios for
the app.

Require authorization on a new API

By default, the system is configured to easily require authorization for new APIs. To do so, create a new controller
and add the [Authorize] attribute to the controller class or to any action within the controller.

Protect a client-side route (Angular)

Protecting a client-side route is done by adding the authorize guard to the list of guards to run when configuring a
route. As an example, you can see how the fetch-data route is configured within the main app Angular module:

RouterModule.forRoot([
// ...
{ path: 'fetch-data', component: FetchDataComponent, canActivate: [AuthorizeGuard] },
])

It's important to mention that protecting a route doesn't protect the actual endpoint (which still requires an
[Authorize] attribute applied to it) but that it only prevents the user from navigating to the given client-side route
when it isn't authenticated.

Authenticate API requests (Angular)

Authenticating requests to APIs hosted alongside the app is done automatically through the use of the HTTP client
interceptor defined by the app.

Protect a client-side route (React)

Protect a client-side route by using the AuthorizeRoute component instead of the plain Route component. For
example, notice how the fetch-data route is configured within the App component:

<AuthorizeRoute path='/fetch-data' component={FetchData} />

Protecting a route:
Doesn't protect the actual endpoint (which still requires an [Authorize] attribute applied to it).
Only prevents the user from navigating to the given client-side route when it isn't authenticated.

Authenticate API requests (React)

Authenticating requests with React is done by first importing the authService instance from the AuthorizeService
. The access token is retrieved from the authService and is attached to the request as shown below. In React
components, this work is typically done in the componentDidMount lifecycle method or as the result from some user
interaction.
Import the authService into your component

import authService from './api-authorization/AuthorizeService'

Retrieve and attach the access token to the response

async populateWeatherData() {
const token = await authService.getAccessToken();
const response = await fetch('api/SampleData/WeatherForecasts', {
headers: !token ? {} : { 'Authorization': `Bearer ${token}` }
});
const data = await response.json();
this.setState({ forecasts: data, loading: false });
}

Deploy to production
To deploy the app to production, the following resources need to be provisioned:
A database to store the Identity user accounts and the IdentityServer grants.
A production certificate to use for signing tokens.
There are no specific requirements for this certificate; it can be a self-signed certificate or a certificate
provisioned through a CA authority.
It can be generated through standard tools like PowerShell or OpenSSL.
It can be installed into the certificate store on the target machines or deployed as a .pfx file with a strong
password.
Example: Deploy to Azure Websites
This section describes deploying the app to Azure websites using a certificate stored in the certificate store. To
modify the app to load a certificate from the certificate store, the App Service plan needs to be on at least the
Standard tier when you configure in a later step. In the app's appsettings.json file, modify the IdentityServer
section to include the key details:

"IdentityServer": {
"Key": {
"Type": "Store",
"StoreName": "My",
"StoreLocation": "CurrentUser",
"Name": "CN=MyApplication"
}
}

The name property on certificate corresponds with the distinguished subject for the certificate.
The store location represents where to load the certificate from ( CurrentUser or LocalMachine ).
The store name represents the name of the certificate store where the certificate is stored. In this case, it points
to the personal user store.
To deploy to Azure Websites, deploy the app following the steps in Deploy the app to Azure to create the
necessary Azure resources and deploy the app to production.
After following the preceding instructions, the app is deployed to Azure but isn't yet functional. The certificate used
by the app still needs to be set up. Locate the thumbprint for the certificate to be used, and follow the steps
described in Load your certificates.
While these steps mention SSL, there's a Private certificates section on the portal where you can upload the
provisioned certificate to use with the app.
After this step, restart the app and it should be functional.

Other configuration options

The support for API authorization builds on top of IdentityServer with a set of conventions, default values, and
enhancements to simplify the experience for SPAs. Needless to say, the full power of IdentityServer is available
behind the scenes if the ASP.NET Core integrations don't cover your scenario. The ASP.NET Core support is
focused on "first-party" apps, where all the apps are created and deployed by our organization. As such, support
isn't offered for things like consent or federation. For those scenarios, use IdentityServer and follow their
documentation.
Application profiles
Application profiles are predefined configurations for apps that further define their parameters. At this time, the
following profiles are supported:
IdentityServerSPA : Represents a SPA hosted alongside IdentityServer as a single unit.
The redirect_uri defaults to /authentication/login-callback .
The post_logout_redirect_uri defaults to /authentication/logout-callback .
The set of scopes includes the openid , profile , and every scope defined for the APIs in the app.
The set of allowed OIDC response types is id_token token or each of them individually ( id_token ,
token ).
The allowed response mode is fragment .
SPA : Represents a SPA that isn't hosted with IdentityServer.
The set of scopes includes the openid , profile , and every scope defined for the APIs in the app.
The set of allowed OIDC response types is id_token token or each of them individually ( id_token ,
token ).
The allowed response mode is fragment .
IdentityServerJwt : Represents an API that is hosted alongside with IdentityServer.
The app is configured to have a single scope that defaults to the app name.
API : Represents an API that isn't hosted with IdentityServer.
The app is configured to have a single scope that defaults to the app name.
Configuration through AppSettings
Configure the apps through the configuration system by adding them to the list of Clients or Resources .
Configure each client's redirect_uri and post_logout_redirect_uri property, as shown in the following example:

"IdentityServer": {
"Clients": {
"MySPA": {
"Profile": "SPA",
"RedirectUri": "https://www.example.com/authentication/login-callback",
"LogoutUri": "https://www.example.com/authentication/logout-callback"
}
}
}

When configuring resources, you can configure the scopes for the resource as shown below:
 "IdentityServer": {
"Resources": {
"MyExternalApi": {
"Profile": "API",
"Scopes": "a b c"
}
}
}

Configuration through code

You can also configure the clients and resources through code using an overload of AddApiAuthorization that
takes an action to configure options.

AddApiAuthorization<ApplicationUser, ApplicationDbContext>(options =>

{
options.Clients.AddSPA(
"My SPA", spa =>
spa.WithRedirectUri("http://www.example.com/authentication/login-callback")
.WithLogoutRedirectUri(
"http://www.example.com/authentication/logout-callback"));

options.ApiResources.AddApiResource("MyExternalApi", resource =>

resource.WithScopes("a", "b", "c"));
});

Additional resources
Use the Angular project template with ASP.NET Core
Use the React project template with ASP.NET Core
Scaffold Identity in ASP.NET Core projects
 Scaffold Identity in ASP.NET Core projects
7/8/2019 • 12 minutes to read • Edit Online

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:
 public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
}

// 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.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseAuthentication();
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

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.
Identity is configured in Areas/Identity/IdentityHostingStartup.cs. for more information, see IHostingStartup.
Migrations, UseAuthentication, and layout
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.

Enable authentication
In the Configure method of the Startup class, call UseAuthentication after UseStaticFiles :

public class Startup

{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}

public IConfiguration Configuration { get; }

public void ConfigureServices(IServiceCollection services)

{
services.AddMvc();
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}

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

app.UseMvc();
}
}

UseHsts is recommended but not required. See HTTP Strict Transport Security Protocol for more information.
Layout changes
Optional: Add the login partial ( _LoginPartial ) to the layout file:

<!DOCTYPE html>
<html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@ViewData["Title"] - RazorNoAuth8</title>

<environment include="Development">
<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
<link rel="stylesheet" href="~/css/site.css" />
</environment>
<environment exclude="Development">
<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>
</head>
<body>
<nav class="navbar navbar-inverse navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-
collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a asp-page="/Index" class="navbar-brand">RazorNoAuth8</a>
</div>
<div class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li><a asp-page="/Index">Home</a></li>
<li><a asp-page="/About">About</a></li>
<li><a asp-page="/Contact">Contact</a></li>
</ul>
<partial name="_LoginPartial" />
</div>
</div>
</nav>

<partial name="_CookieConsentPartial" />

<div class="container body-content">

@RenderBody()
<hr />
<footer>
<p>&copy; 2018 - RazorNoAuth8</p>
</footer>
</div>

<environment include="Development">
<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>
<environment exclude="Development">
<script src="https://ajax.aspnetcdn.com/ajax/jquery/jquery-3.3.1.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"
crossorigin="anonymous"
integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa">
</script>
 </script>
<script src="~/js/site.min.js" asp-append-version="true"></script>
</environment>

@RenderSection("Scripts", required: false)

</body>
</html>

Scaffold identity into a Razor project with authorization

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. 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 the + button to create a new Data context class.
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

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.
Optional: Add the login partial ( _LoginPartial ) to the Views/Shared/_Layout.cshtml file:

<!DOCTYPE html>
<html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@ViewData["Title"] - MvcNoAuth3</title>

<environment include="Development">
<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
<link rel="stylesheet" href="~/css/site.css" />
</environment>
<environment exclude="Development">
<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>
</head>
<body>
<nav class="navbar navbar-inverse navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-
collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a asp-area="" asp-controller="Home" asp-action="Index" class="navbar-brand">MvcNoAuth3</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>
<partial name="_LoginPartial" />
</div>
</div>
</nav>

<partial name="_CookieConsentPartial" />

<div class="container body-content">

@RenderBody()
<hr />
<footer>
<p>&copy; 2018 - MvcNoAuth3</p>
</footer>
</div>

<environment include="Development">
<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>
<environment exclude="Development">
<script src="https://ajax.aspnetcdn.com/ajax/jquery/jquery-3.3.1.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"
crossorigin="anonymous"
integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa">
</script>
 </script>
<script src="~/js/site.min.js" asp-append-version="true"></script>
</environment>

@RenderSection("Scripts", required: false)

</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.
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.

Call UseAuthentication after UseStaticFiles :

public class Startup

{

public void ConfigureServices(IServiceCollection services)

{
services.AddMvc();
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Home/Error");
app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseAuthentication();
app.UseMvcWithDefaultRoute();
}
}

UseHsts is recommended but not required. See HTTP Strict Transport Security Protocol for more information.

Scaffold identity into an MVC project with authorization

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. 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 the + button to create a new Data context class.
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.
 public void ConfigureServices(IServiceCollection services)
{
services.Configure<CookiePolicyOptions>(options =>
{
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});

services.AddDbContext<ApplicationDbContext>(options =>
options.UseSqlServer(
Configuration.GetConnectionString("DefaultConnection")));

services.AddIdentity<IdentityUser, IdentityRole>()
// services.AddDefaultIdentity<IdentityUser>()
.AddEntityFrameworkStores<ApplicationDbContext>()
.AddDefaultTokenProviders();

services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1)
.AddRazorPagesOptions(options =>
{
options.AllowAreas = true;
options.Conventions.AuthorizeAreaFolder("Identity", "/Account/Manage");
options.Conventions.AuthorizeAreaPage("Identity", "/Account/Logout");
});

services.ConfigureApplicationCookie(options =>
{
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>()
.AddEntityFrameworkStores<ApplicationDbContext>()
.AddDefaultTokenProviders();

The following code sets the LoginPath, LogoutPath, and AccessDeniedPath:

services.ConfigureApplicationCookie(options =>
{
options.LoginPath = $"/Identity/Account/Login";
options.LogoutPath = $"/Identity/Account/Logout";
options.AccessDeniedPath = $"/Identity/Account/AccessDenied";
});

Register an IEmailSender implementation, for example:

// using Microsoft.AspNetCore.Identity.UI.Services;
services.AddSingleton<IEmailSender, EmailSender>();
 public class EmailSender : IEmailSender
{
public Task SendEmailAsync(string email, string subject, string message)
{
return Task.CompletedTask;
}
}

Additional resources
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
6/18/2019 • 7 minutes to read • Edit Online

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 PersonalDataAttribute 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.
View or download sample code (how to download)

Prerequisites
.NET Core 2.2 SDK or later

Create a Razor web app

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.2 in the dropdown
Select Web Application > OK
Build and run the 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, 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 Microsoft.AspNetCore.Identity;
using System;

namespace WebApp1.Areas.Identity.Data
{
public class WebApp1User : IdentityUser
{
[PersonalData]
public string Name { get; set; }
[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;
 _userManager = userManager;
_signInManager = signInManager;
_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")]
public string Name { get; set; }

[Required]
[Display(Name = "Birth Date")]
[DataType(DataType.Date)]
public DateTime DOB { get; set; }

[Required]
[EmailAddress]
public string Email { get; set; }

[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();
}

public async Task<IActionResult> OnPostAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

var user = await _userManager.GetUserAsync(User);

 var user = await _userManager.GetUserAsync(User);
if (user == null)
{
return NotFound($"Unable to load user with ID '{_userManager.GetUserId(User)}'.");
}

var email = await _userManager.GetEmailAsync(user);

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}'.");
}
}

if (Input.Name != user.Name)
{
user.Name = Input.Name;
}

if (Input.DOB != user.DOB)
{
user.DOB = Input.DOB;
}

var phoneNumber = await _userManager.GetPhoneNumberAsync(user);

if (Input.PhoneNumber != phoneNumber)
{
var setPhoneResult = await _userManager.SetPhoneNumberAsync(user, Input.PhoneNumber);
if (!setPhoneResult.Succeeded)
{
var userId = await _userManager.GetUserIdAsync(user);
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";
return RedirectToPage();
}

public async Task<IActionResult> OnPostSendVerificationEmailAsync()

{
if (!ModelState.IsValid)
{
return Page();
}

var user = await _userManager.GetUserAsync(User);

if (user == null)
{
return NotFound($"Unable to load user with ID '{_userManager.GetUserId(User)}'.");
}

var userId = await _userManager.GetUserIdAsync(user);

var email = await _userManager.GetEmailAsync(user);
var code = await _userManager.GenerateEmailConfirmationTokenAsync(user);
var callbackUrl = Url.Page(
"/Account/ConfirmEmail",
pageHandler: null,
values: new { userId = userId, code = code },
protocol: Request.Scheme);
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.";

return RedirectToPage();
}
}

Update the Areas/Identity/Pages/Account/Manage/Index.cshtml with the following highlighted markup:

 @page
@model IndexModel
@{
ViewData["Title"] = "Profile";
ViewData["ActivePage"] = ManageNavPages.Index;
}

<h4>@ViewData["Title"]</h4>
<partial name="_StatusMessage" for="StatusMessage" />
<div class="row">
<div class="col-md-6">
<form id="profile-form" method="post">
<div asp-validation-summary="All" class="text-danger"></div>
<div class="form-group">
<label asp-for="Username"></label>
<input asp-for="Username" class="form-control" disabled />
</div>
<div class="form-group">
<label asp-for="Input.Email"></label>
@if (Model.IsEmailConfirmed)