100% found this document useful (1 vote)

208 views5,326 pages

Web API Apps Nguyen Thanh Bao Long

Uploaded by

thanhhaiit99

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

100% found this document useful (1 vote)

208 views5,326 pages

Web API Apps Nguyen Thanh Bao Long

Uploaded by

thanhhaiit99

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 5326

ASP.NET Core documentation

What's new in ASP.NET Core docs
Overview
About ASP.NET Core
Compare ASP.NET Core and ASP.NET
Compare .NET Core and .NET Framework
Get started
Release notes
What's new in 3.1
What's new in 3.0
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 Details and Delete
Blazor
Web API apps
Create a web API
Web API with MongoDB
Web API with JavaScript
Backend for mobile
Real-time web apps
SignalR with JavaScript
SignalR with TypeScript
SignalR with Blazor WebAssembly
Remote Procedure Call apps
Get started with a 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
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
Microsoft Learn modules
Web apps >>
Web API apps >>
Cloud-native microservices >>
Data access >>
Web app security >>
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
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
Dependency injection - controllers
Dependency injection - views
Unit test
Blazor
Overview
Supported platforms
Tooling
Hosting models
Tutorials
Build a Blazor todo list app
SignalR with Blazor WebAssembly
Templates
Fundamentals
Routing
Configuration
Dependency injection
Environments
Logging
Handle errors
Additional scenarios
Components
Overview
Built-in components
App
Authentication
AuthorizeView
InputCheckbox
InputDate
InputNumber
InputSelect
InputText
InputTextArea
MainLayout
NavLink
NavMenu
Router
Cascading values and parameters
Data binding
Event handling
Lifecycle
Templated components
Integrate components
Component libraries
Globalization and localization
Layouts
Forms and validation
Call JavaScript from .NET
Call .NET from JavaScript
Call a web API from WebAssembly
Security and Identity
Overview
Blazor WebAssembly
Overview
Standalone with Authentication library
Standalone with Microsoft Accounts
Standalone with AAD
Standalone with AAD B2C
Hosted with AAD
Hosted with AAD B2C
Hosted with Identity Server
Additional scenarios
AAD groups and roles
Blazor Server
Overview
Threat mitigation
Additional scenarios
Content Security Policy
State management
Debug WebAssembly
WebAssembly performance
Progressive Web Applications
Host and deploy
Overview
Blazor WebAssembly
Blazor Server
Configure the Linker
Advanced scenarios
Client-side development
Single Page Apps
Angular
React
React with Redux
JavaScript Services
LibMan
Overview
CLI
Visual Studio
Grunt
Bundle and minify
Browser Link
Session and state management
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
Component
Distributed Cache
Environment
Form
Form Action
Image
Input
Label
Link
Partial
Script
Select
Textarea
Validation Message
Validation Summary
Advanced
Application parts
Application model
Areas
Filters
Razor SDK
View components
View compilation
Upload files
Web SDK
aspnet-codegenerator (Scaffolding)
Web API apps
Overview
Tutorials
Create a web API
Web API with MongoDB
Swagger / OpenAPI
Overview
Get started with Swashbuckle
Get started with NSwag
OpenAPI tools
Action return types
Handle JSON Patch requests
Format response data
Custom formatters
Analyzers
Conventions
Handle errors
Test APIs with HTTP REPL
Real-time apps
SignalR overview
Supported platforms
Tutorials
SignalR with JavaScript
SignalR with TypeScript
SignalR with Blazor WebAssembly
Samples
Server concepts
Hubs
Send from outside a hub
Users and groups
API design considerations
Hub filters
Clients
Overview
.NET client
.NET API reference
Java client
Java API reference
JavaScript client
JavaScript API reference
Host and scale
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
Specifications
Hub protocol
Transport protocols
Remote Procedure Call apps
Introduction to gRPC services
Tutorials
Get started with a gRPC service
gRPC services with C#
gRPC services with ASP.NET Core
Call gRPC services with .NET client
gRPC client factory integration
Use gRPC in browser apps
Configuration
Authentication and authorization
Logging and diagnostics
Security considerations
Versioning gRPC services
Manage Protobuf references with dotnet-grpc
Migrate gRPC services from C-core
Compare gRPC services with HTTP APIs
Samples
Troubleshoot
Test, debug, and troubleshoot
Razor Pages unit tests
Test controllers
Test middleware
Remote debugging
Snapshot debugging
Snapshot debugging in Visual Studio
Integration tests
Load and stress testing
Troubleshoot and debug
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
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
Host and deploy
Overview
Azure App Service
Overview
Publish with Visual Studio
Publish with Visual Studio for Mac
Publish with the CLI
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
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
Windows service
Linux with Nginx
Linux with Apache
Docker
Overview
Build Docker images
Visual Studio Tools
Publish to a Docker image
Sample Docker images
Proxy and load balancer configuration
Web farm
Visual Studio publish profiles
Visual Studio for Mac publish to folder
Directory structure
Health checks
Security and Identity
Overview
Authentication
Overview
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
Scenarios
Web app that signs in users
Web app that calls web APIs
Protected web API
Web API that calls other web APIs
Integrate Azure AD B2C into a web app
Samples
Sign-in users and call web APIs using Azure AD V2
Calling an ASP.NET Core 2.0 Web API from a WPF application using Azure AD
V2
Web API with Azure AD B2C
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
Multi-factor 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
Host Docker with HTTPS
Docker Compose with 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
SameSite cookies
SameSite samples
Razor Pages 2.1 SameSite cookie sample
Razor Pages 3.1 SameSite cookie sample
MVC SameSite cookie sample
IP safelist
Application security - OWASP
Performance
Overview
Memory and GC
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
ASP.NET Core in class libraries
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
3.1 to 5.0
3.0 to 3.1
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
7/10/2020 • 8 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-
enabled, Internet-connected apps. With ASP.NET Core, you can:
Build web apps and services, Internet of Things (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.

Why choose ASP.NET Core?

Millions of developers use or have used ASP.NET 4.x to create web apps. ASP.NET Core is a redesign of ASP.NET
4.x, including 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.
Support for hosting Remote Procedure Call (RPC) services using gRPC.
A cloud-ready, environment-based configuration system.
Built-in dependency injection.
A lightweight, high-performance, and modular HTTP request pipeline.
Ability to host on the following:
Kestrel
IIS
HTTP.sys
Nginx
Apache
Docker
Side-by-side versioning.
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 ASP.NET Core Blazor and related topics under
Client-side development.

ASP.NET Core target frameworks

ASP.NET Core 3.x and later can only target .NET Core. Generally, ASP.NET Core is composed of .NET Standard
libraries. Libraries written with .NET Standard 2.0 run on any .NET platform that implements .NET Standard 2.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 Windows, macOS, and Linux.
Improved performance
Side-by-side versioning
New APIs
Open source

Recommended learning path

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

APP TYPE SC EN A RIO T UTO RIA L

Web app New server-side web UI Get started with Razor Pages
development

Web app Maintaining an MVC app Get started with MVC

Web app Client-side web UI development Get started with Blazor

Web API RESTful HTTP services Create a web API†

Remote Procedure Call app Contract-first services using Protocol Get started with a gRPC service
Buffers

Real-time app Bidirectional communication Get started with SignalR

between servers and connected
clients

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

SC EN A RIO T UTO RIA L

New development Razor Pages with Entity Framework Core

Maintaining an MVC app MVC with Entity Framework Core

3. Read an overview of ASP.NET Core fundamentals that apply to all app types.
4. Browse the table of contents for other topics of interest.
†There's also an interactive web API tutorial. No local installation of development tools is required. The code runs
in an Azure Cloud Shell in your browser, and curl is used for testing.

Migrate from .NET Framework

For a reference guide to migrating ASP.NET 4.x apps to ASP.NET Core, see Migrate from ASP.NET to ASP.NET Core.
ASP.NET Core is a cross-platform, high-performance, open-source framework for building modern, cloud-
enabled, Internet-connected apps. With ASP.NET Core, you can:
Build web apps and services, Internet of Things (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 use or have used 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.
Support for hosting Remote Procedure Call (RPC) services using gRPC.
A cloud-ready, environment-based configuration system.
Built-in dependency injection.
A lightweight, high-performance, and modular HTTP request pipeline.
Ability to host on the following:
Kestrel
IIS
HTTP.sys
Nginx
Apache
Docker
Side-by-side versioning.
Tooling that simplifies modern web development.

Build web APIs and web UI using ASP.NET Core MVC

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 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
To help 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 SC EN A RIO T UTO RIA L

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.

SC EN A RIO T UTO RIA L

For new development Razor Pages with Entity Framework Core

For maintaining an MVC app MVC with Entity Framework Core

3. Read an overview of ASP.NET Core fundamentals that apply to all app types.
4. Browse the Table of Contents for other topics of interest.
†There's also a 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.

Migrate from .NET Framework

For a reference guide to migrating ASP.NET apps to ASP.NET Core, see Migrate from ASP.NET to ASP.NET Core.

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 preprocessor
directives to selectively compile and run different sections of sample code. For those samples that make use of
this approach, set the #define directive at the top of the C# files to define the symbol associated with the
scenario that you want to run. Some samples require defining 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# directives. 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_WebHostDefaults :

#region snippet_WebHostDefaults
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
#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_WebHostDefaults)]

You may safely ignore (or remove) the #region and #endregion directives that surround the code. Don't alter the
code within these directives 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/10/2020 • 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.
Support for hosting Remote Procedure Call (RPC) services using gRPC.
A cloud-ready, environment-based configuration system.
Built-in dependency injection.
A lightweight, high-performance, and modular HTTP request pipeline.
Ability to host on the following:
Kestrel
IIS
HTTP.sys
Nginx
Apache
Docker
Side-by-side versioning.
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.

A SP. N ET C O RE A SP. N ET 4. X

Build for Windows, macOS, or Linux Build for Windows

A SP. N ET C O RE A SP. N ET 4. X

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

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

This tutorial shows how to create and run an ASP.NET Core web app using the .NET Core CLI.
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 3.1 SDK or later

Create a web app project

Open a command shell, and enter the following command:

dotnet new webapp -o aspnetcoreapp

The preceding command:

Creates a new web app.
The -o aspnetcoreapp parameter creates a directory named aspnetcoreapp with the source files for the app.
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 watch run

After the command shell indicates that the app has started, browse to https://localhost:5001 .

Edit a Razor page

Open Pages/Index.cshtml and modify and save 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 , refresh the page, 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 3.1
7/10/2020 • 2 minutes to read • Edit Online

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

Partial class support for Razor components

Razor components are now generated as partial classes. Code for a Razor component can be written using a code-
behind file defined as a partial class rather than defining all the code for the component in a single file. For more
information, see Partial class support.

Blazor Component Tag Helper and pass parameters to top-level

components
In Blazor with ASP.NET Core 3.0, components were rendered into pages and views using an HTML Helper (
Html.RenderComponentAsync ). In ASP.NET Core 3.1, render a component from a page or view with the new
Component Tag Helper:

<component type="typeof(Counter)" render-mode="ServerPrerendered" />

The HTML Helper remains supported in ASP.NET Core 3.1, but the Component Tag Helper is recommended.
Blazor Server apps can now pass parameters to top-level components during the initial render. Previously you
could only pass parameters to a top-level component with RenderMode.Static. With this release, both
RenderMode.Server and RenderMode.ServerPrerendered are supported. Any specified parameter values are
serialized as JSON and included in the initial response.
For example, prerender a Counter component with an increment amount ( IncrementAmount ):

<component type="typeof(Counter)" render-mode="ServerPrerendered"

param-IncrementAmount="10" />

For more information, see Integrate components into Razor Pages and MVC apps.

Support for shared queues in HTTP.sys

HTTP.sys supports creating anonymous request queues. In ASP.NET Core 3.1, we've added to ability to create or
attach to an existing named HTTP.sys request queue. Creating or attaching to an existing named HTTP.sys request
queue enables scenarios where the HTTP.sys controller process that owns the queue is independent of the listener
process. This independence makes it possible to preserve existing connections and enqueued requests between
listener process restarts:
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
// ...
webBuilder.UseHttpSys(options =>
{
options.RequestQueueName = "MyExistingQueue";
options.RequestQueueMode = RequestQueueMode.CreateOrAttach;
});
});

Breaking changes for SameSite cookies

The behavior of SameSite cookies has changed to reflect upcoming browser changes. This may affect
authentication scenarios like AzureAd, OpenIdConnect, or WsFederation. For more information, see Work with
SameSite cookies in ASP.NET Core.

Prevent default actions for events in Blazor apps

Use the @on{EVENT}:preventDefault directive attribute to prevent the default action for an event. In the following
example, the default action of displaying the key's character in the text box is prevented:

<input value="@_count" @onkeypress="KeyHandler" @onkeypress:preventDefault />

For more information, see Prevent default actions.

Stop event propagation in Blazor apps

Use the @on{EVENT}:stopPropagation directive attribute to stop event propagation. In the following example,
selecting the check box prevents click events from the child <div> from propagating to the parent <div> :

<input @bind="_stopPropagation" type="checkbox" />

@code {
private bool _stopPropagation = false;
}

For more information, see Stop event propagation.

Detailed errors during Blazor app development

When a Blazor app isn't functioning properly during development, receiving detailed error information from the
app assists in troubleshooting and fixing the issue. When an error occurs, Blazor apps display a gold bar at the
bottom of the screen:
During development, the gold bar directs you to the browser console, where you can see the exception.
In production, the gold bar notifies the user that an error has occurred and recommends refreshing the browser.
For more information, see Detailed errors during development.
What's new in ASP.NET Core 3.0
7/10/2020 • 14 minutes to read • Edit Online

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

Blazor
Blazor is a new framework in ASP.NET Core 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.
Blazor framework supported scenarios:
Reusable UI components (Razor components)
Client-side routing
Component layouts
Support for dependency injection
Forms and validation
Build component libraries with Razor class libraries
JavaScript interop
For more information, see Introduction to ASP.NET Core Blazor.
Blazor Server
Blazor decouples component rendering logic from how UI updates are applied. Blazor Server provides support for
hosting Razor components on the server in an ASP.NET Core app. UI updates are handled over a SignalR
connection. Blazor Server is supported in ASP.NET Core 3.0.
Blazor WebAssembly (Preview)
Blazor apps can also be run directly in the browser using a WebAssembly-based .NET runtime. Blazor
WebAssembly is in preview and not supported in ASP.NET Core 3.0. Blazor WebAssembly will be supported in a
future release of ASP.NET Core.
Razor components
Blazor apps are built from components. Components are self-contained chunks of user interface (UI), such as a
page, dialog, or form. Components are normal .NET classes that define UI rendering logic and client-side event
handlers. You can create rich interactive web apps without JavaScript.
Components in Blazor are typically authored using Razor syntax, a natural blend of HTML and C#. Razor
components are similar to Razor Pages and MVC views in that they both use Razor. Unlike pages and views, which
are based on a request-response model, components are used specifically for handling UI composition.

gRPC
gRPC:
Is a popular, high-performance RPC (remote procedure call) framework.
Offers an opinionated contract-first approach to API development.
Uses modern technologies such as:
HTTP/2 for transport.
Protocol Buffers as the interface description language.
Binary serialization format.
Provides features such as:
Authentication
Bidirectional streaming and flow control.
Cancellation and timeouts.
gRPC functionality in ASP.NET Core 3.0 includes:
Grpc.AspNetCore: An ASP.NET Core framework for hosting gRPC services. gRPC on ASP.NET Core integrates
with standard ASP.NET Core features like logging, dependency injection (DI), authentication, and authorization.
Grpc.Net.Client: A gRPC client for .NET Core that builds upon the familiar HttpClient .
Grpc.Net.ClientFactory: gRPC client integration with HttpClientFactory .

For more information, see Introduction to gRPC on .NET Core.

SignalR
See Update SignalR code for migration instructions. SignalR now uses System.Text.Json to serialize/deserialize
JSON messages. See Switch to Newtonsoft.Json for instructions to restore the Newtonsoft.Json -based serializer.
In the JavaScript and .NET Clients for SignalR, support was added for automatic reconnection. By default, the client
tries to reconnect immediately and retry after 2, 10, and 30 seconds if necessary. If the client successfully
reconnects, it receives a new connection ID. Automatic reconnect is opt-in:

const connection = new signalR.HubConnectionBuilder()

.withUrl("/chathub")
.withAutomaticReconnect()
.build();

The reconnection intervals can be specified by passing an array of millisecond-based durations:

.withAutomaticReconnect([0, 3000, 5000, 10000, 15000, 30000])

//.withAutomaticReconnect([0, 2000, 10000, 30000]) The default intervals.

A custom implementation can be passed in for full control of the reconnection intervals.
If the reconnection fails after the last reconnect interval:
The client considers the connection is offline.
The client stops trying to reconnect.
During reconnection attempts, update the app UI to notify the user that the reconnection is being attempted.
To provide UI feedback when the connection is interrupted, the SignalR client API has been expanded to include the
following event handlers:
onreconnecting : Gives developers an opportunity to disable UI or to let users know the app is offline.
onreconnected : Gives developers an opportunity to update the UI once the connection is reestablished.

The following code uses onreconnecting to update the UI while trying to connect:
connection.onreconnecting((error) => {
const status = `Connection lost due to error "${error}". Reconnecting.`;
document.getElementById("messageInput").disabled = true;
document.getElementById("sendButton").disabled = true;
document.getElementById("connectionStatus").innerText = status;
});

The following code uses onreconnected to update the UI on connection:

connection.onreconnected((connectionId) => {
const status = `Connection reestablished. Connected.`;
document.getElementById("messageInput").disabled = false;
document.getElementById("sendButton").disabled = false;
document.getElementById("connectionStatus").innerText = status;
});

SignalR 3.0 and later 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
Name of the hub method being invoked.
Arguments to the hub method.
Consider the following example of a chat room app 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 can
ban users or view users' chat histories. The app could restrict certain functionality from specific users.

public class DomainRestrictedRequirement :

AuthorizationHandler<DomainRestrictedRequirement, HubInvocationContext>,
IAuthorizationRequirement
{
protected override Task HandleRequirementAsync(AuthorizationHandlerContext context,
DomainRestrictedRequirement requirement,
HubInvocationContext resource)
{
if (context.User?.Identity?.Name == null)
{
return Task.CompletedTask;
}

if (IsUserAllowedToDoThis(resource.HubMethodName, context.User.Identity.Name))
{
context.Succeed(requirement);
}

return Task.CompletedTask;
}

private bool IsUserAllowedToDoThis(string hubMethodName, string currentUsername)

{
if (hubMethodName.Equals("banUser", StringComparison.OrdinalIgnoreCase))
{
return currentUsername.Equals("[email protected]", StringComparison.OrdinalIgnoreCase);
}

return currentUsername.EndsWith("@jabbr.net", StringComparison.OrdinalIgnoreCase));

}
}

In the preceding code, DomainRestrictedRequirement serves as a custom IAuthorizationRequirement . Because the

HubInvocationContext resource parameter is being passed in, the internal logic can:
Inspect the context in which the Hub is being called.
Make decisions on allowing the user to execute individual Hub methods.
Individual Hub methods can be marked with the name of the policy the code checks at run-time. As clients attempt
to call individual Hub methods, the DomainRestrictedRequirement handler runs and controls access to the methods.
Based on the way the DomainRestrictedRequirement controls access:
All logged-in users can call the SendMessage method.
Only users who have logged in with a @jabbr.net email address can view users' histories.
Only [email protected] can ban users from the chat room.

[Authorize]
public class ChatHub : Hub
{
public void SendMessage(string message)
{
}

[Authorize("DomainRestricted")]
public void BanUser(string username)
{
}

[Authorize("DomainRestricted")]
public void ViewUserHistory(string username)
{
}
}

Creating the DomainRestricted policy might involve:

In Startup.cs, adding the new policy.
Provide the custom DomainRestrictedRequirement requirement as a parameter.
Registering DomainRestricted with the authorization middleware.

services
.AddAuthorization(options =>
{
options.AddPolicy("DomainRestricted", policy =>
{
policy.Requirements.Add(new DomainRestrictedRequirement());
});
});

SignalR hubs use Endpoint Routing. SignalR hub connection was previously done explicitly:

app.UseSignalR(routes =>
{
routes.MapHub<ChatHub>("hubs/chat");
});

In the previous version, developers needed to wire up controllers, Razor pages, and hubs in a variety of places.
Explicit connection results in a series of nearly-identical routing segments:
app.UseSignalR(routes =>
{
routes.MapHub<ChatHub>("hubs/chat");
});

app.UseRouting(routes =>
{
routes.MapRazorPages();
});

SignalR 3.0 hubs can be routed via endpoint routing. With endpoint routing, typically all routing can be configured
in UseRouting :

app.UseRouting(routes =>
{
routes.MapRazorPages();
routes.MapHub<ChatHub>("hubs/chat");
});

ASP.NET Core 3.0 SignalR added:

Client-to-server streaming. With client-to-server streaming, server-side methods can take instances of either an
IAsyncEnumerable<T> or ChannelReader<T> . In the following C# sample, the UploadStream method on the Hub will
receive a stream of strings from the client:

public async Task UploadStream(IAsyncEnumerable<string> stream)

{
await foreach (var item in stream)
{
// process content
}
}

.NET client apps can pass either an IAsyncEnumerable<T> or ChannelReader<T> instance as the stream argument of
the UploadStream Hub method above.
After the for loop has completed and the local function exits, the stream completion is sent:

async IAsyncEnumerable<string> clientStreamData()

{
for (var i = 0; i < 5; i++)
{
var data = await FetchSomeData();
yield return data;
}
}

await connection.SendAsync("UploadStream", clientStreamData());

JavaScript client apps use the SignalR Subject (or an RxJS Subject) for the stream argument of the UploadStream
Hub method above.

let subject = new signalR.Subject();

await connection.send("StartStream", "MyAsciiArtStream", subject);

The JavaScript code could use the subject.next method to handle strings as they are captured and ready to be
sent to the server.
subject.next("example");
subject.complete();

Using code like the two preceding snippets, real-time streaming experiences can be created.

New JSON serialization

ASP.NET Core 3.0 now uses System.Text.Json by default for JSON serialization:
Reads and writes JSON asynchronously.
Is optimized for UTF-8 text.
Typically higher performance than Newtonsoft.Json .

To add Json.NET to ASP.NET Core 3.0, see Add Newtonsoft.Json-based JSON format support.

New Razor directives

The following list contains new Razor directives:
@attribute : The directive applies the given attribute to the class of the generated page or view. For
@attribute
example, @attribute [Authorize] .
@implements : The @implements directive implements an interface for the generated class. For example,
@implements IDisposable .

IdentityServer4 supports authentication and authorization for web APIs

and SPAs
ASP.NET Core 3.0 offers authentication in Single Page Apps (SPAs) using the support for web API authorization.
ASP.NET Core Identity for authenticating and storing users is combined with IdentityServer4 for implementing
Open ID Connect.
IdentityServer4 is an OpenID Connect and OAuth 2.0 framework for ASP.NET Core 3.0. It enables the following
security features:
Authentication as a Service (AaaS)
Single sign-on/off (SSO) over multiple application types
Access control for APIs
Federation Gateway
For more information, see the IdentityServer4 documentation or Authentication and authorization for SPAs.

Certificate and Kerberos authentication

Certificate authentication requires:
Configuring the server to accept certificates.
Adding the authentication middleware in Startup.Configure .
Adding the certificate authentication service in Startup.ConfigureServices .
public void ConfigureServices(IServiceCollection services)
{
services.AddAuthentication(
CertificateAuthenticationDefaults.AuthenticationScheme)
.AddCertificate();
// Other service configuration removed.
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
app.UseAuthentication();
// Other app configuration removed.
}

Options for certificate authentication include the ability to:

Accept self-signed certificates.
Check for certificate revocation.
Check that the proffered certificate has the right usage flags in it.
A default user principal is constructed from the certificate properties. The user principal contains an event that
enables supplementing or replacing the principal. For more information, see Configure certificate authentication in
ASP.NET Core.
Windows Authentication has been extended onto Linux and macOS. In previous versions, Windows Authentication
was limited to IIS and HttpSys. In ASP.NET Core 3.0, Kestrel has the ability to use Negotiate, Kerberos, and NTLM on
Windows, Linux, and macOS for Windows domain-joined hosts. Kestrel support of these authentication schemes is
provided by the Microsoft.AspNetCore.Authentication.Negotiate NuGet package. As with the other authentication
services, configure authentication app wide, then configure the service:

public void ConfigureServices(IServiceCollection services)

{
services.AddAuthentication(NegotiateDefaults.AuthenticationScheme)
.AddNegotiate();
// Other service configuration removed.
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)

{
app.UseAuthentication();
// Other app configuration removed.
}

Host requirements:
Windows hosts must have Service Principal Names (SPNs) added to the user account hosting the app.
Linux and macOS machines must be joined to the domain.
SPNs must be created for the web process.
Keytab files must be generated and configured on the host machine.
For more information, see Configure Windows Authentication in ASP.NET Core.

Template changes
The web UI templates (Razor Pages, MVC with controller and views) have the following removed:
The cookie consent UI is no longer included. To enable the cookie consent feature in an ASP.NET Core 3.0
template-generated app, see General Data Protection Regulation (GDPR) support in ASP.NET Core.
Scripts and related static assets are now referenced as local files instead of using CDNs. For more information,
see Scripts and related static assets are now referenced as local files instead of using CDNs based on the current
environment (aspnet/AspNetCore.Docs #14350).
The Angular template updated to use Angular 8.
The Razor class library (RCL) template defaults to Razor component development by default. A new template
option in Visual Studio provides template support for pages and views. When creating an RCL from the template in
a command shell, pass the --support-pages-and-views option ( dotnet new razorclasslib --support-pages-and-views
).

Generic Host
The ASP.NET Core 3.0 templates use .NET Generic Host. Previous versions used WebHostBuilder. Using the .NET
Core Generic Host (HostBuilder) provides better integration of ASP.NET Core apps with other server scenarios that
aren't web-specific. For more information, see HostBuilder replaces WebHostBuilder.
Host configuration
Prior to the release of ASP.NET Core 3.0, environment variables prefixed with ASPNETCORE_ were loaded for host
configuration of the Web Host. In 3.0, AddEnvironmentVariables is used to load environment variables prefixed with
DOTNET_ for host configuration with CreateDefaultBuilder .

Changes to Startup constructor injection

The Generic Host only supports the following types for Startup constructor injection:
IHostEnvironment
IWebHostEnvironment
IConfiguration
All services can still be injected directly as arguments to the Startup.Configure method. For more information, see
Generic Host restricts Startup constructor injection (aspnet/Announcements #353).

Kestrel
Kestrel configuration has been updated for the migration to the Generic Host. In 3.0, Kestrel is configured on the
web host builder provided by ConfigureWebHostDefaults .
Connection Adapters have been removed from Kestrel and replaced with Connection Middleware, which is
similar to HTTP Middleware in the ASP.NET Core pipeline but for lower-level connections.
The Kestrel transport layer has been exposed as a public interface in Connections.Abstractions .
Ambiguity between headers and trailers has been resolved by moving trailing headers to a new collection.
Synchronous I/O APIs, such as HttpRequest.Body.Read , are a common source of thread starvation leading to app
crashes. In 3.0, AllowSynchronousIO is disabled by default.

For more information, see Migrate from ASP.NET Core 2.2 to 3.0.

HTTP/2 enabled by default

HTTP/2 is enabled by default in Kestrel for HTTPS endpoints. HTTP/2 support for IIS or HTTP.sys is enabled when
supported by the operating system.

EventCounters on request
The Hosting EventSource, Microsoft.AspNetCore.Hosting , emits the following new EventCounter types related to
incoming requests:
requests-per-second
total-requests
current-requests
failed-requests

Endpoint routing
Endpoint Routing, which allows frameworks (for example, MVC) to work well with middleware, is enhanced:
The order of middleware and endpoints is configurable in the request processing pipeline of Startup.Configure .
Endpoints and middleware compose well with other ASP.NET Core-based technologies, such as Health Checks.
Endpoints can implement a policy, such as CORS or authorization, in both middleware and MVC.
Filters and attributes can be placed on methods in controllers.
For more information, see Routing in ASP.NET Core.

Health Checks
Health Checks use endpoint routing with the Generic Host. In Startup.Configure , call MapHealthChecks on the
endpoint builder with the endpoint URL or relative path:

app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health");
});

Health Checks endpoints can:

Specify one or more permitted hosts/ports.
Require authorization.
Require CORS.
For more information, see the following articles:
Migrate from ASP.NET Core 2.2 to 3.0
Health checks in ASP.NET Core

Pipes on HttpContext
It's now possible to read the request body and write the response body using the System.IO.Pipelines API. The
HttpRequest.BodyReader property provides a PipeReader that can be used to read the request body. The
HttpResponse.BodyWriter property provides a PipeWriter that can be used to write the response body.
HttpRequest.BodyReader is an analogue of the HttpRequest.Body stream. HttpResponse.BodyWriter is an analogue of
the HttpResponse.Body stream.

Improved error reporting in IIS

Startup errors when hosting ASP.NET Core apps in IIS now produce richer diagnostic data. These errors are
reported to the Windows Event Log with stack traces wherever applicable. In addition, all warnings, errors, and
unhandled exceptions are logged to the Windows Event Log.

Worker Service and Worker SDK

.NET Core 3.0 introduces the new Worker Service app template. This template provides a starting point for writing
long running services in .NET Core.
For more information, see:
.NET Core Workers as Windows Services
Background tasks with hosted services in ASP.NET Core
Host ASP.NET Core in a Windows Service

Forwarded Headers Middleware improvements

In previous versions of ASP.NET Core, calling UseHsts and UseHttpsRedirection were problematic when deployed to
an Azure Linux or behind any reverse proxy other than IIS. The fix for previous versions is documented in Forward
the scheme for Linux and non-IIS reverse proxies.
This scenario is fixed in ASP.NET Core 3.0. The host enables the Forwarded Headers Middleware when the
ASPNETCORE_FORWARDEDHEADERS_ENABLED environment variable is set to true . ASPNETCORE_FORWARDEDHEADERS_ENABLED is
set to true in our container images.

Performance improvements
ASP.NET Core 3.0 includes many improvements that reduce memory usage and improve throughput:
Reduction in memory usage when using the built-in dependency injection container for scoped services.
Reduction in allocations across the framework, including middleware scenarios and routing.
Reduction in memory usage for WebSocket connections.
Memory reduction and throughput improvements for HTTPS connections.
New optimized and fully asynchronous JSON serializer.
Reduction in memory usage and throughput improvements in form parsing.

ASP.NET Core 3.0 only runs on .NET Core 3.0

As of ASP.NET Core 3.0, .NET Framework is no longer a supported target framework. Projects targeting .NET
Framework can continue in a fully supported fashion using the .NET Core 2.1 LTS release. Most ASP.NET Core 2.1.x
related packages will be supported indefinitely, beyond the three-year LTS period for .NET Core 2.1.
For migration information, see Port your code from .NET Framework to .NET Core.

Use the ASP.NET Core shared framework

The ASP.NET Core 3.0 shared framework, contained in the Microsoft.AspNetCore.App metapackage, no longer
requires an explicit <PackageReference /> element in the project file. The shared framework is automatically
referenced when using the Microsoft.NET.Sdk.Web SDK in the project file:

Assemblies removed from the ASP.NET Core shared framework

The most notable assemblies removed from the ASP.NET Core 3.0 shared framework are:
Newtonsoft.Json (Json.NET). To add Json.NET to ASP.NET Core 3.0, see Add Newtonsoft.Json-based JSON format
support. ASP.NET Core 3.0 introduces System.Text.Json for reading and writing JSON. For more information,
see New JSON serialization in this document.
Entity Framework Core
For a complete list of assemblies removed from the shared framework, see Assemblies being removed from
Microsoft.AspNetCore.App 3.0. For more information on the motivation for this change, see Breaking changes to
Microsoft.AspNetCore.App in 3.0 and A first look at changes coming in ASP.NET Core 3.0.
What's new in ASP.NET Core 2.2
7/10/2020 • 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. Notable features of HTTP/2 include:
Support for header compression.
Fully multiplexed streams over a single connection.
While HTTP/2 preserves HTTP's semantics (for example, HTTP headers and methods), it's a breaking change from
HTTP/1.x on how data is framed and sent between the client and server.
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
7/10/2020 • 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
7/10/2020 • 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 has 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.

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 ASP.NET Core 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
7/10/2020 • 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 developers who are familiar with controllers and views, 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.
Tutorial: Get started with Razor Pages in ASP.NET
Core
7/10/2020 • 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 developers who are familiar with controllers and views, 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 16.4 or later with the ASP.NET and web development workload
.NET Core 3.1 SDK or later
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.1 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.

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
MODEL

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 developers who are familiar with controllers and views, 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.
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
MODEL
Part 2, add a model to a Razor Pages app in ASP.NET
Core
7/10/2020 • 22 minutes to read • Edit Online

By Rick Anderson
In this section, classes are added for managing movies. The app's model classes use Entity Framework Core (EF
Core) to work with the database. EF Core is an object-relational mapper (O/RM) 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 for Mac
Visual Studio Code
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 migrations command generates code to create the initial database schema. The schema is based on the model
specified in DbContext . 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 update command runs the Up method in migrations that have not been applied. In this case, update runs the
Up method in Migrations/<time-stamp>_InitialCreate.cs file, which 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.
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

PR EVIO U S: G ET N E XT: S C A F F O LD E D R A ZO R
S TA R T E D PA G E S

In this section, classes are added for managing movies in a cross-platform SQLite database. Apps created from an
ASP.NET Core template use a SQLite database. The app's model classes are used with Entity Framework Core (EF
Core) (SQLite EF Core Database Provider) to work with the 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

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:

Scaffold the movie model

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.

Add-Migration Initial
Update-Database

The Add-Migration command generates code to create the initial database schema. The schema is based on the
model specified in the DbContext (In the RazorPagesMovieContext.cs file). The InitialCreate argument is used to
name the migration. 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. The Up
method creates the database.

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

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

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

}
}

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

PR EVIO U S: G ET N E XT: S C A F F O LD E D R A ZO R
S TA R T E D PA G E S
Part 3, scaffolded Razor Pages in ASP.NET Core
7/10/2020 • 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 programming 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 to initialize the state of the page. In this case, OnGetAsync gets a list of movies and
displays them.
When OnGetreturns void or OnGetAsync returns Task , no return statement 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 directive
The @page Razor directive makes the file 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] is 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 pass data 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";
}

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>

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

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

PR EVIO U S: AD D ING A N E XT:

MODEL D A TA B A S E
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 programming 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>

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

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.

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>

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

Additional resources
YouTube version of this tutorial
PR EVIO U S: AD D ING A N E XT:
MODEL D A TA B A S E
Part 4, with a database and ASP.NET Core
7/10/2020 • 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 Ser ver 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.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
{
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>();
});
}
}

The following exception occurs when Update-Database has not been run:

SqlException: Cannot open database "RazorPagesMovieContext-" 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

PR EVIO U S: SCAF F O LD ED R AZO R N E X T: U P D ATI N G TH E

PA G E S PA G E S

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

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 Ser ver 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;

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

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

PR EVIO U S: SCAF F O LD ED R AZO R N E X T: U P D ATI N G TH E

PA G E S PA G E S
Part 5, update the generated pages in an ASP.NET
Core app
7/10/2020 • 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 ).

Add route template

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 KIN G W ITH A N E XT: A D D

D A TA B A S E SEARCH

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

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

<td>
<a href="/Movies/Edit/1">Edit</a> |
<a href="/Movies/Details/1">Details</a> |
<a href="/Movies/Delete/1">Delete</a>
</td>

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

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

[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 KIN G W ITH A N E XT: A D D

D A TA B A S E SEARCH
Part 6, add search to ASP.NET Core Razor Pages
7/10/2020 • 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 has 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 into GET binding is useful when addressing scenarios that 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)]

For more information, see ASP.NET Core Community Standup: Bind on GET discussion (YouTube).

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

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 I O U S : U P D ATI N G TH E N E XT: A D D IN G A N E W
PA G E S F IELD

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

For more information, see ASP.NET Core Community Standup: Bind on GET discussion (YouTube).

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>

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

Test the app by searching by genre, by movie title, and by both. The preceding code uses the Select Tag Helper and
Option Tag Helper.

Additional resources
YouTube version of this tutorial

P R E V I O U S : U P D ATI N G TH E N E XT: A D D IN G A N E W
PA G E S F IELD
Part 7, add a new field to a Razor Page in ASP.NET
Core
7/10/2020 • 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 an __EFMigrationsHistory 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>

<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. Running the app without updating the database
throws a SqlException :
SqlException: Invalid column name 'Rating'.

The SqlException exception 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 and to preserve
existing data.
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

PR EVIO U S: AD D ING N E XT: A D D IN G

SEARCH VA L I D ATI O 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>

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

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

PR EVIO U S: AD D ING N E XT: A D D IN G

SEARCH VA L I D ATI O N
Part 8, add validation to an ASP.NET Core Razor Page
7/10/2020 • 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 ("D on't R epeat Y ourself"). 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]*$")]
[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. See 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();
}

Alternatively, you can Disable client-side validation on the server.

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.

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 emit 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]*$"), 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 changes 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
PR EVIO U S: AD D ING A NEW
F IELD
Create a web app with ASP.NET Core MVC
7/10/2020 • 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
7/10/2020 • 10 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 16.4 or later with the ASP.NET and web development workload
.NET Core 3.1 SDK or later

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

NE XT

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

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.

NE XT
Part 2, add a controller to an ASP.NET Core MVC app
7/10/2020 • 12 minutes to read • Edit Online

By Rick Anderson
The Model-View-Controller (MVC) architectural pattern separates an app into three main components: M odel, V iew,
and C ontroller. The MVC pattern helps you create apps that are more testable and easier to update than traditional
monolithic apps. MVC-based apps contain:
M odels: 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.
V iews: Views are the components that display the app's user interface (UI). Generally, this UI displays the
model data.
C ontrollers: 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?}");
});

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
HelloWorld Controller 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 in
the query string. The ? (question mark) in the above URL is a separator, and the query string follows. The &
character separates field-value pairs.
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?}");
});

In these examples the controller has been doing the "VC" portion of MVC - that is, the V iew and the C ontroller
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.

PR EVIO U S NE XT

The Model-View-Controller (MVC) architectural pattern separates an app into three main components: M odel, V iew,
and C ontroller. The MVC pattern helps you create apps that are more testable and easier to update than traditional
monolithic apps. MVC-based apps contain:
M odels: 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.
V iews: Views are the components that display the app's user interface (UI). Generally, this UI displays the
model data.
C ontrollers: 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

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

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.

The preceding code:

Run the app and browse to:

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

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.

PR EVIO U S NE XT
Part 3, add a view to an ASP.NET Core MVC app
7/10/2020 • 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 the view template in
/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.min.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">
© 2020 - Movie App - <a asp-area="" asp-controller="Home" asp-action="Privacy">Privacy</a>
</div>
</footer>
<script src="~/lib/jquery/dist/jquery.min.js"></script>
<script src="~/lib/bootstrap/dist/js/bootstrap.bundle.min.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.

PR EVIO U S NE XT

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

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"
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">
<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">
© 2019 - Movie App - <a asp-area="" asp-controller="Home" asp-action="Privacy">Privacy</a>
</div>
</footer>

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

@{
Layout = "_Layout";
}

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

<h2>My Movie List</h2>

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

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.

Passing Data from the Controller to the View

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

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

PR EVIO U S NE XT
Part 4, add a model to an ASP.NET Core MVC app
7/10/2020 • 28 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 "M odel" part of the
M VC 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 P lain O ld C LR O bjects) 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.

Add a data model class

Visual Studio
Visual Studio Code
Visual Studio for Mac
Right-click the Models folder > Add > Class . Name the file Movie.cs.
Update the Movie.cs file with the following code:

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 an Id field, which is required by the database for the primary key.
The DataType attribute on ReleaseDate 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.

Add NuGet packages

Visual Studio
Visual Studio Code
Visual Studio for Mac
From the Tools menu, select NuGet Package Manager > Package Manager Console (PMC).

In the PMC, run the following command:

Install-Package Microsoft.EntityFrameworkCore.SqlServer

The preceding command adds the EF Core SQL Server provider. The provider package installs the EF Core package
as a dependency. Additional packages are installed automatically in the scaffolding step later in the tutorial.

Create a database context class

A database context class is needed to coordinate EF Core functionality (Create, Read, Update, Delete) for the Movie
model. The database context is derived from Microsoft.EntityFrameworkCore.DbContext and specifies the entities to
include in the data model.
Create a Data folder.
Add a Data/MvcMovieContext.cs file with the following code:

using Microsoft.EntityFrameworkCore;
using MvcMovie.Models;

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

public DbSet<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.
Register the database context
ASP.NET Core is built with dependency injection (DI). Services (such as the EF Core DB context) must be 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. In this section, you register the database context with the DI container.
Add the following using statements at the top of Startup.cs:

using MvcMovie.Data;
using Microsoft.EntityFrameworkCore;

Add the following highlighted code in Startup.ConfigureServices :

Visual Studio
Visual Studio Code / Visual Studio for Mac

public void ConfigureServices(IServiceCollection services)

{
services.AddControllersWithViews();

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

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.

Add a database connection string

Add a connection string to the appsettings.json file:
Visual Studio
Visual Studio Code / Visual Studio for Mac

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

Build the project as a check for compiler errors.

Scaffold movie pages

Use the scaffolding tool to produce Create, Read, Update, and Delete (CRUD) pages 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: MvcMovieContext (MvcMovie.Data)
Views: Keep the default of each option checked
Controller name: Keep the default MoviesController
Select Add
Visual Studio creates:
A movies controller (Controllers/MoviesController.cs)
Razor view files for Create, Delete, Details, Edit, and Index pages (Views/Movies/*.cshtml)
The automatic creation of these files is known as scaffolding.
You can't use the scaffolded pages yet because the database doesn't exist. If you run the app and click on the Movie
App link, you get a Cannot open database or no such table: Movie error message.

Initial migration
Use the EF Core Migrations feature to create the database. Migrations is a set of tools that let you create and update
a database to match your data model.
Visual Studio
Visual Studio Code / Visual Studio for Mac
From the Tools menu, select NuGet Package Manager > Package Manager Console (PMC).
In the PMC, enter the following commands:

Add-Migration InitialCreate
Update-Database

Add-Migration InitialCreate : Generates a Migrations/{timestamp}_InitialCreate.cs migration file. The

InitialCreate argument is the migration name. Any name can be used, but by convention, a name is
selected that describes the migration. Because this is the first migration, the generated class contains code to
create the database schema. The database schema is based on the model specified in the MvcMovieContext
class.
: Updates the database to the latest migration, which the previous command created. This
Update-Database
command runs the Up method in the Migrations/{time-stamp}_InitialCreate.cs file, which creates the
database.
The database update command generates 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.

For more information on the PMC tools for EF Core, see EF Core tools reference - PMC in Visual Studio.
The InitialCreate class
Examine the Migrations/{timestamp}_InitialCreate.cs migration file:

public partial class Initial : Migration

{
protected override void Up(MigrationBuilder migrationBuilder)
{
migrationBuilder.CreateTable(
name: "Movie",
columns: table => new
{
Id = table.Column<int>(nullable: false)
.Annotation("SqlServer:ValueGenerationStrategy",
SqlServerValueGenerationStrategy.IdentityColumn),
Title = table.Column<string>(nullable: true),
ReleaseDate = table.Column<DateTime>(nullable: false),
Genre = table.Column<string>(nullable: true),
Price = table.Column<decimal>(nullable: false)
},
constraints: table =>
{
table.PrimaryKey("PK_Movie", x => x.Id);
});
}

protected override void Down(MigrationBuilder migrationBuilder)

{
migrationBuilder.DropTable(
name: "Movie");
}
}

The Up method creates the Movie table and configures Id as the primary key. The Down method reverts the
schema changes made by the Up migration.

Test the app

Run the app and click the Movie App link.
If you get an exception similar to one of the following:
Visual Studio
Visual Studio Code / Visual Studio for Mac

SqlException: Cannot open database "MvcMovieContext-1" requested by the login. The login failed.
You probably missed the migrations step.
Test the Create page. Enter and submit data.

Test the Edit , Details , and Delete pages.

Dependency injection in the controller

Visual Studio
Visual Studio Code / Visual Studio for Mac
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
compile time code checking. The scaffolding mechanism used this approach (that is, passing a strongly typed
model) with the MoviesController class 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>

The @model statement at the top of the view file specifies the type of object that the view expects. When the movie
controller was created, the following @model statement was included:

@model MvcMovie.Models.Movie

This @model directive allows access to the movie that the controller passed to the view. The Model object is
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 the movies controller was created, scaffolding 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

PR EVIO U S AD D ING A N E XT W O R KIN G W ITH

VIEW SQL

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

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:

// Unused usings removed.

using Microsoft.EntityFrameworkCore;
using MvcMovie.Models; // Enables public DbSet<Movie> Movie

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

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

}
}

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

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>

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>

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

<h1>Index</h1>

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
PR EVIO U S AD D ING A N E XT W O R KIN G W ITH A
VIEW D A TA B A S E
Part 5, work with a database in an ASP.NET Core
MVC app
7/10/2020 • 9 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.AddControllersWithViews();

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 the app is deployed to a test or production server, an environment variable can be used to set the connection
string to a production 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 Ser ver 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 MvcMovie.Data;
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.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using MvcMovie.Data;
using MvcMovie.Models;
using System;

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

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.

PR EVIO U S NE XT

Visual Studio
Visual Studio Code / Visual Studio for Mac

public void ConfigureServices(IServiceCollection services)

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

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

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.

PR EVIO U S NE XT
Part 6, controller methods and views in ASP.NET Core
7/10/2020 • 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.UseEndpoints(endpoints =>
{
endpoints.MapControllerRoute(
name: "default",
pattern: "{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();
}

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

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.

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

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

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

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

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

PR EVIO U S NE XT
Part 7, add search to an ASP.NET Core MVC app
7/10/2020 • 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>

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

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

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

PR EVIO U S NE XT
Part 8, add a new field to an ASP.NET Core MVC app
7/10/2020 • 4 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 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, and display movies with a Rating field.

PR EVIO U S NE XT
Part 9, add validation to an ASP.NET Core MVC app
7/10/2020 • 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

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]*$")]
[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.

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. See 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]*$"), 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

PR EVIO U S NE XT
Part 10, examine the Details and Delete methods of
an ASP.NET Core app
7/10/2020 • 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.UseEndpoints(endpoints =>
{
endpoints.MapControllerRoute(
name: "default",
pattern: "{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.

PR EVIO U S
Build a Blazor todo list app
7/10/2020 • 4 minutes to read • Edit Online

By Daniel Roth and Luke Latham

This tutorial shows you how to build and modify a Blazor app. You learn how to:
Create a todo list Blazor app project
Modify Razor components
Use event handling and data binding in components
Use dependency injection (DI) and routing in a Blazor app
At the end of this tutorial, you'll have a working todo list app.
1. Create a new Blazor app named TodoList in a command shell:

dotnet new blazorserver -o TodoList

The preceding command creates a folder named TodoList to hold the app. Change directories to the
TodoList folder with the following command:

cd TodoList

2. Add a new Todo Razor component to the app in the Pages folder using the following command:

dotnet new razorcomponent -n Todo -o Pages

IMPORTANT
Razor component file names require a capitalized first letter, so confirm that the Todo component file name starts
with a capital letter T .

3. In Pages/Todo.razor provide the initial markup for the component:

@page "/todo"

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

5. Rebuild and run the app. Visit the new Todo page to confirm that the link to the Todo component works.
6. 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; }
}

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

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

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

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

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

<input placeholder="Something todo" />

@code {
private IList<TodoItem> todos = new List<TodoItem>();
}
9. 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.
10. 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" />

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

private void AddTodo()

{
// Todo: Add the todo
}
}

11. 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" />

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

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

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

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

13. Rebuild and run the app. Add some todo items to the todo list to test the new code.
14. 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>

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

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

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

@page "/todo"

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

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

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

17. Rebuild and run the app. Add todo items to test the new code.

Next steps
In this tutorial, you learned how to:
Create a todo list Blazor app project
Modify Razor components
Use event handling and data binding in components
Use dependency injection (DI) and routing in a Blazor app
Learn about tooling for ASP.NET Core Blazor:
Tooling for ASP.NET Core Blazor
Tutorial: Create a web API with ASP.NET Core
7/10/2020 • 31 minutes to read • Edit Online

By Rick Anderson, Kirk Larkin, 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 DESC RIP T IO N REQ UEST B O DY RESP O N SE B O DY

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 Delete an item None None

/api/TodoItems/{id}

The following diagram shows the design of the app.

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

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.1
are selected. Select the API template and click Create .

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:

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 Browse tab, and then enter Microsoft.EntityFrameworkCore.SqlSer ver in the search box.
Select Microsoft.EntityFrameworkCore.SqlSer ver 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:
Marks 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.
The ASP.NET Core templates for:
Controllers with views include [action] in the route template.
API controllers don't include [action] in the route template.

When the [action] token isn't in the route template, the action name is excluded from the route. That is, the
action's associated method name isn't used in the matching route.

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 cer tificate verification
From File > Settings (General tab), disable SSL cer tificate 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 TodoItems Controller, 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 initialized 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;
}

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 .

Prevent over-posting
Currently the sample app exposes the entire TodoItem object. Production apps typically limit the data that's input
and returned using a subset of the model. There are multiple reasons behind this and security is a major one. The
subset of a model is usually referred to as a Data Transfer Object (DTO), input model, or view model. DTO is used in
this article.
A DTO may be used to:
Prevent over-posting.
Hide properties that clients are not supposed to view.
Omit some properties in order to reduce payload size.
Flatten object graphs that contain nested objects. Flattened object graphs can be more convenient for clients.
To demonstrate the DTO approach, update the TodoItem class to include a secret field:

public class TodoItem

{
public long Id { get; set; }
public string Name { get; set; }
public bool IsComplete { get; set; }
public string Secret { get; set; }
}

The secret field needs to be hidden from this app, but an administrative app could choose to expose it.
Verify you can post and get the secret field.
Create a DTO model:

public class TodoItemDTO

{
public long Id { get; set; }
public string Name { get; set; }
public bool IsComplete { get; set; }
}

Update the TodoItemsController to use TodoItemDTO :

[HttpGet]
public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
{
return await _context.TodoItems
.Select(x => ItemToDTO(x))
.ToListAsync();
}

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
var todoItem = await _context.TodoItems.FindAsync(id);

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

return ItemToDTO(todoItem);
}

[HttpPut("{id}")]
public async Task<IActionResult> UpdateTodoItem(long id, TodoItemDTO todoItemDTO)
{
if (id != todoItemDTO.Id)
{
return BadRequest();
}

var todoItem = await _context.TodoItems.FindAsync(id);

var todoItem = await _context.TodoItems.FindAsync(id);
if (todoItem == null)
{
return NotFound();
}

todoItem.Name = todoItemDTO.Name;
todoItem.IsComplete = todoItemDTO.IsComplete;

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

return NoContent();
}

[HttpPost]
public async Task<ActionResult<TodoItemDTO>> CreateTodoItem(TodoItemDTO todoItemDTO)
{
var todoItem = new TodoItem
{
IsComplete = todoItemDTO.IsComplete,
Name = todoItemDTO.Name
};

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

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

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

private bool TodoItemExists(long id) =>

_context.TodoItems.Any(e => e.Id == id);

private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>

new TodoItemDTO
{
Id = todoItem.Id,
Name = todoItem.Name,
IsComplete = todoItem.IsComplete
};
}

Verify you can't post or get the secret field.

Call the web API with JavaScript
See Tutorial: Call an ASP.NET Core web API with JavaScript.
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 JavaScript.
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 DESC RIP T IO N REQ UEST B O DY RESP O N SE B O DY

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 Suppor t .

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.

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

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.
Marks 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 Todo Controller, 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;
}

Test the GetTodoItems method

This tutorial uses Postman to test the web API.
Install Postman.
Start the web app.
Start Postman.
Disable SSL cer tificate verification .
Visual Studio
Visual Studio Code / Visual Studio for Mac
From File > Settings (General tab), disable SSL cer tificate 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();
}

{
"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 web API with JavaScript

In this section, an HTML page is added that uses JavaScript to call the web API. jQuery initiates the request.
JavaScript updates the page with the details from the web 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>

<table>
<tr>
<th>Is Complete</th>
<th>Name</th>
<th></th>
<th></th>
</tr>
<tbody id="todos"></tbody>
</table>

Add a JavaScript file named site.js to the wwwroot directory. Replace its contents with the following code:

const uri = "api/todo";

$(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) {

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

$(".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.
This sample calls all of the CRUD methods of the web API. Following are explanations of the calls to the API.
Get a list of to -do items
jQuery sends an HTTP GET request to the web 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) {

tr.appendTo(tBody);
});

todos = data;
}
});
}

Add a to -do item

jQuery sends an HTTP 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
};

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

Add authentication support to a web API

ASP.NET Core Identity adds user interface (UI) login functionality to ASP.NET Core web apps. To secure web APIs and
SPAs, use one of the following:
Azure Active Directory
Azure Active Directory B2C (Azure AD B2C)
IdentityServer4
IdentityServer4 is an OpenID Connect and OAuth 2.0 framework for ASP.NET Core. IdentityServer4 enables the
following security features:
Authentication as a Service (AaaS)
Single sign-on/off (SSO) over multiple application types
Access control for APIs
Federation Gateway
For more information, see Welcome to IdentityServer4.

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
Razor Pages with Entity Framework Core in ASP.NET Core - Tutorial 1 of 8
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/10/2020 • 21 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 3.0 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.

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

{
// requires using Microsoft.Extensions.Options
services.Configure<BookstoreDatabaseSettings>(
Configuration.GetSection(nameof(BookstoreDatabaseSettings)));

services.AddSingleton<IBookstoreDatabaseSettings>(sp =>
sp.GetRequiredService<IOptions<BookstoreDatabaseSettings>>().Value);

services.AddControllers();
}

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

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;
}
[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. JSON.NET has been removed from ASP.NET shared framework. Add a package reference to
Microsoft.AspNetCore.Mvc.NewtonsoftJson .

2. In Startup.ConfigureServices , chain the following highlighted code on to the AddControllers 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.AddControllers()
.AddNewtonsoftJson(options => options.UseMemberCasing());
}

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 .
3. 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.
4. Add the following code to the top of Models/Book.cs to resolve the [JsonProperty] attribute reference:

using Newtonsoft.Json;

5. Repeat the steps defined in the Test the web API section. Notice the difference in JSON property names.
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
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.

7. View the documents in the database using the following command:

db.Books.find({}).pretty()

The following result is displayed:

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:

Add a configuration model

1. Add the following database configuration values to appsettings.json:

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:

using BooksApi.Models;

Add a CRUD operations service

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

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

using BooksApi.Services;

public BookService(IBookstoreDatabaseSettings settings)

{
var client = new MongoClient(settings.ConnectionString);
var database = client.GetDatabase(settings.DatabaseName);

_books = database.GetCollection<Book>(settings.BooksCollectionName);
}

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,

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:

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:

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

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.

Add authentication support to a web API

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
JavaScript
7/10/2020 • 5 minutes to read • Edit Online

By Rick Anderson
This tutorial shows how to call an ASP.NET Core web API with JavaScript, using the Fetch API.
For ASP.NET Core 2.2, see the 2.2 version of Call the web API with JavaScript.

Prerequisites
Complete Tutorial: Create a web API
Familiarity with CSS, HTML, and JavaScript

Call the web API with JavaScript

In this section, you'll add an HTML page containing forms for creating and managing to-do items. Event handlers
are attached to elements on the page. The event handlers result in HTTP requests to the web API's action methods.
The Fetch API's fetch function initiates each HTTP request.
The fetch function returns a Promise object, which contains an HTTP response represented as a Response object.
A common pattern is to extract the JSON response body by invoking the json function on the Response object.
JavaScript updates the page with the details from the web API's response.
The simplest fetch call accepts a single parameter representing the route. A second parameter, known as the
init object, is optional. init is used to configure the HTTP request.

1. Configure the app to serve static files and enable default file mapping. The following highlighted code is
needed in the Configure method of Startup.cs:

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

2. Create a wwwroot folder in the project root.

3. Create a js folder inside of the wwwroot folder.
4. Add an HTML file named index.html to the wwwroot folder. Replace the contents of index.html with the
following markup:

<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>To-do CRUD</title>
<link rel="stylesheet" href="css/site.css" />
</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>

<table>
<tr>
<th>Is Complete?</th>
<th>Name</th>
<th></th>
<th></th>
</tr>
<tbody id="todos"></tbody>
</table>

<script src="js/site.js" asp-append-version="true"></script>

5. Add a JavaScript file named site.js to the wwwroot/js folder. Replace the contents of site.js with the following
code:

const uri = 'api/TodoItems';

let todos = [];

function getItems() {
fetch(uri)
.then(response => response.json())
.then(data => _displayItems(data))
.catch(error => console.error('Unable to get items.', error));
}

function addItem() {
const addNameTextbox = document.getElementById('add-name');
const item = {
isComplete: false,
name: addNameTextbox.value.trim()
};

fetch(uri, {
method: 'POST',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: JSON.stringify(item)
})
.then(response => response.json())
.then(() => {
getItems();
addNameTextbox.value = '';
})
.catch(error => console.error('Unable to add item.', error));
}

function deleteItem(id) {
fetch(`${uri}/${id}`, {
method: 'DELETE'
})
.then(() => getItems())
.catch(error => console.error('Unable to delete item.', error));
}

function displayEditForm(id) {
const item = todos.find(item => item.id === id);

document.getElementById('edit-name').value = item.name;
document.getElementById('edit-id').value = item.id;
document.getElementById('edit-isComplete').checked = item.isComplete;
document.getElementById('editForm').style.display = 'block';
}

function updateItem() {
const itemId = document.getElementById('edit-id').value;
const item = {
id: parseInt(itemId, 10),
isComplete: document.getElementById('edit-isComplete').checked,
name: document.getElementById('edit-name').value.trim()
};

fetch(`${uri}/${itemId}`, {
method: 'PUT',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: JSON.stringify(item)
})
.then(() => getItems())
.catch(error => console.error('Unable to update item.', error));

closeInput();

return false;
}

function closeInput() {
document.getElementById('editForm').style.display = 'none';
}

function _displayCount(itemCount) {
const name = (itemCount === 1) ? 'to-do' : 'to-dos';
document.getElementById('counter').innerText = `${itemCount} ${name}`;
}

function _displayItems(data) {
const tBody = document.getElementById('todos');
tBody.innerHTML = '';

_displayCount(data.length);

const button = document.createElement('button');

data.forEach(item => {
let isCompleteCheckbox = document.createElement('input');
isCompleteCheckbox.type = 'checkbox';
isCompleteCheckbox.disabled = true;
isCompleteCheckbox.checked = item.isComplete;

let editButton = button.cloneNode(false);

editButton.innerText = 'Edit';
editButton.setAttribute('onclick', `displayEditForm(${item.id})`);

let deleteButton = button.cloneNode(false);

deleteButton.innerText = 'Delete';
deleteButton.setAttribute('onclick', `deleteItem(${item.id})`);

let tr = tBody.insertRow();

let td1 = tr.insertCell(0);

td1.appendChild(isCompleteCheckbox);

let td2 = tr.insertCell(1);

let textNode = document.createTextNode(item.name);
td2.appendChild(textNode);

let td3 = tr.insertCell(2);

td3.appendChild(editButton);

let td4 = tr.insertCell(3);

td4.appendChild(deleteButton);
});

todos = data;
}

A change to the ASP.NET Core project's launch settings may be required to test the HTML page locally:
1. Open Properties\launchSettings.json.
2. Remove the launchUrl property to force the app to open at index.html—the project's default file.

This sample calls all of the CRUD methods of the web API. Following are explanations of the web API requests.
Get a list of to -do items
In the following code, an HTTP GET request is sent to the api/TodoItems route:

fetch(uri)
.then(response => response.json())
.then(data => _displayItems(data))
.catch(error => console.error('Unable to get items.', error));

When the web API returns a successful status code, the _displayItems function is invoked. Each to-do item in the
array parameter accepted by _displayItems is added to a table with Edit and Delete buttons. If the web API
request fails, an error is logged to the browser's console.
Add a to -do item
In the following code:
An item variable is declared to construct an object literal representation of the to-do item.
A Fetch request is configured with the following options:
method —specifies the POST HTTP action verb.
body —specifies the JSON representation of the request body. The JSON is produced by passing the
object literal stored in item to the JSON.stringify function.
headers —specifies the Accept and Content-Type HTTP request headers. Both headers are set to
application/json to specify the media type being received and sent, respectively.
An HTTP POST request is sent to the api/TodoItems route.

function addItem() {
const addNameTextbox = document.getElementById('add-name');

const item = {
isComplete: false,
name: addNameTextbox.value.trim()
};

When the web API returns a successful status code, the getItems function is invoked to update the HTML table. If
the web API request fails, an error is logged to the browser's console.
Update a to -do item
Updating a to-do item is similar to adding one; however, there are two significant differences:
The route is suffixed with the unique identifier of the item to update. For example, api/TodoItems/1.
The HTTP action verb is PUT, as indicated by the method option.

Delete a to -do item

To delete a to-do item, set the request's method option to DELETE and specify the item's unique identifier in the
URL.

fetch(`${uri}/${id}`, {
method: 'DELETE'
})
.then(() => getItems())
.catch(error => console.error('Unable to delete item.', error));

Advance to the next tutorial to learn how to generate web API help pages:
Get started with Swashbuckle and ASP.NET Core
Create backend services for native mobile apps with
ASP.NET Core
7/10/2020 • 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 with 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 is passed in the body of the
POST, this parameter specifies 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/10/2020 • 13 minutes to read • Edit Online

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

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 Librar y .
In the Add Client-Side Librar y dialog, for Provider select unpkg .
For Librar y , enter @microsoft/signalr@latest .
Select Choose specific files , expand the dist/browser folder, and select signalr.js and signalr.min.js.
Set Target Location to wwwroot/js/signalr/, and select Install .
LibMan creates a wwwroot/js/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 System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.HttpsPolicy;
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.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.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"> </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"> </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>
<script src="~/js/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, "&").replace(/</g, "<").replace(/>/g, ">");
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, run these commands to update your
development certificate:

dotnet dev-certs https --clean

dotnet dev-certs https --trust

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 Librar y .
In the Add Client-Side Librar y dialog, for Provider select unpkg .
For Librar y , enter @microsoft/signalr@3 , 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);
}
}
}

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"> </div>
<div class="row">
<div class="col-6"> </div>
<div class="col-6">
User..........<input type="text" id="userInput" />
<br />
Message...<input type="text" id="messageInput" />
<input type="button" id="sendButton" value="Send Message" />
</div>
</div>
<div class="row">
<div class="col-12">
<hr />
</div>
</div>
<div class="row">
<div class="col-6"> </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:

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

connection.start().then(function(){
document.getElementById("sendButton").disabled = false;
}).catch(function (err) {
return console.error(err.toString());
});

document.getElementById("sendButton").addEventListener("click", function (event) {

The preceding code:

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.

Additional resources
Youtube version of this tutorial
Use ASP.NET Core SignalR with TypeScript and
Webpack
7/10/2020 • 21 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 3.0 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. Launch Visual Studio. At the start window, select Continue without code .
2. Navigate to Tools > Options > Projects and Solutions > Web Package Management > External Web
Tools .
3. Select the $(PATH) entry from the list. Click the up arrow to move the entry to the second position in the list,
and select OK .
Visual Studio configuration is complete.
1. Use the File > New > Project menu option and choose the ASP.NET Core Web Application template. Select
Next .
2. Name the project SignalRWebPack, and select Create .
3. Select .NET Core from the target framework drop-down, and select ASP.NET Core 3.1 from the framework
selector drop-down. Select the Empty template, and select Create .
Add the Microsoft.TypeScript.MSBuild package to the project:
1. In Solution Explorer (right pane), right-click the project node and select Manage NuGet Packages . In the
Browse tab, search for Microsoft.TypeScript.MSBuild , and then click Install on the right to install the package.
Visual Studio adds the NuGet package under the Dependencies node in Solution Explorer , enabling TypeScript
compilation in the project.

Configure Webpack and TypeScript

The following steps configure the conversion of TypeScript to JavaScript and the bundling of client-side resources.
1. Run 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 and save the file changes:
{
"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. Run the following command from the project root:

npm i -D -E [email protected] [email protected] [email protected] mini-css-extract-

[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.41.5" is used instead of "webpack": "^4.41.5" . This option
prevents unintended upgrades to newer package versions.
See the npm-install docs for more detail.
4. Replace the scripts property of the package.json file with the following code:

"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 the 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 the 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 code:
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(),
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 to store the project's client-side assets.
7. Create src/index.html with the following markup.

<!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 CSS:

*, *::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 JSON:

{
"compilerOptions": {
"target": "es5"
}
}

The preceding code configures the TypeScript compiler to produce ECMAScript 5-compatible JavaScript.
11. Create src/index.ts with the following code:
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.key === "Enter") {
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 in the tbMessage textbox. 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 app

1. In Startup.Configure , add calls to UseDefaultFiles and UseStaticFiles.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)

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

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

app.UseEndpoints(endpoints =>
{
endpoints.MapHub<ChatHub>("/hub");
});

The preceding code allows the server to locate and serve the index.html file. The file is served whether the
user enters its full URL or the root URL of the web app.
2. At the end of Startup.Configure , map a /hub route to the ChatHub hub. Replace the code that displays Hello
World! with the following line:

app.UseEndpoints(endpoints =>
{
endpoints.MapHub<ChatHub>("/hub");
});

3. In Startup.ConfigureServices , call AddSignalR.

services.AddSignalR();

4. Create a new directory named Hubs in the project root SignalRWebPack/ to store the SignalR hub.
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 using statement 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 basic form to send messages, but is not yet functional. The server is listening to a
specific route but does nothing with sent messages.
1. Run the following command at the project root:

npm i @microsoft/signalr @types/node

The preceding command installs:

The SignalR TypeScript client, which allows the client to send messages to the server.
The TypeScript type definitions for Node.js, which enables compile-time checking of Node.js types.
2. Add the highlighted code to the src/index.ts file:
import "./css/main.css";
import * as signalR from "@microsoft/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.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;
});

connection.start().catch(err => document.write(err));

tbMessage.addEventListener("keyup", (e: KeyboardEvent) => {

if (e.key === "Enter") {
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, messages with the name messageReceived can run the logic responsible for displaying the new
message in the messages zone. Listening to a specific message can be done via the on function. Any
number of message names can be listened to. 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 "@microsoft/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.on("messageReceived", (username: string, message: string) => {

let messages = document.createElement("div");

messages.innerHTML =
`<div class="message-author">${username}</div><div>${message}</div>`;

divMessages.appendChild(messages);
divMessages.scrollTop = divMessages.scrollHeight;
});

connection.start().catch(err => document.write(err));

tbMessage.addEventListener("keyup", (e: KeyboardEvent) => {

if (e.key === "Enter") {
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 NewMessage 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 SendAsync 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, run 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 generates 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 in a process known as transpilation.
Mangled the generated JavaScript to reduce file size in 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 > Star t 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> .
If you get compile errors, try closing and reopening the solution.
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.
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 Create .
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 Create .

Configure Webpack and TypeScript

The following steps configure the conversion of TypeScript to JavaScript and the bundling of client-side resources.
1. Run 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. Run 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 npm-install docs for more detail.
4. Replace the scripts property of the package.json file with the following code:

"scripts": {
"build": "webpack --mode=development --watch",
"release": "webpack --mode=production",
"publish": "npm run release && dotnet publish -c Release"
},

Some explanation of the scripts:

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

*, *::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 JSON:

{
"compilerOptions": {
"target": "es5"
}
}

The preceding code configures the TypeScript compiler to produce ECMAScript 5-compatible JavaScript.
11. Create src/index.ts with the following code:
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() {
}

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 Startup.ConfigureServices . It adds the SignalR services to the project.

services.AddSignalR();

3. Map a /hub route to the ChatHub hub. Add the following lines at the end of Startup.Configure :

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. Run 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.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;
});

connection.start().catch(err => document.write(err));

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, messages with the name messageReceived can run 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. The new
message is 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.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;
});

connection.start().catch(err => document.write(err));

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

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

Test the app

npm run release

This command generates 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 in a process known as transpilation.
Mangled the generated JavaScript to reduce file size in 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 > Star t 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 ASP.NET Core SignalR with Blazor WebAssembly
7/10/2020 • 7 minutes to read • Edit Online

By Daniel Roth and Luke Latham

This tutorial teaches the basics of building a real-time app using SignalR with Blazor WebAssembly. You learn how
to:
Create a Blazor WebAssembly Hosted app project
Add the SignalR client library
Add a SignalR hub
Add SignalR services and an endpoint for the SignalR hub
Add Razor component code for chat
At the end of this tutorial, you'll have a working chat app.
View or download sample code (how to download)

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

Create a hosted Blazor WebAssembly app project

Follow the guidance for your choice of tooling:
Visual Studio
Visual Studio Code
Visual Studio for Mac
.NET Core CLI

NOTE
Visual Studio 16.6 or later and .NET Core SDK 3.1.300 or later are required.

1. Create a new project.

2. Select Blazor App and select Next .
3. Type BlazorSignalRApp in the Project name field. Confirm the Location entry is correct or provide a
location for the project. Select Create .
4. Choose the Blazor WebAssembly App template.
5. Under Advanced , select the ASP.NET Core hosted check box.
6. Select Create .

Add the SignalR client library

Visual Studio
Visual Studio Code
Visual Studio for Mac
.NET Core CLI
1. In Solution Explorer , right-click the BlazorSignalRApp.Client project and select Manage NuGet
Packages .
2. In the Manage NuGet Packages dialog, confirm that the Package source is set to nuget.org .
3. With Browse selected, type Microsoft.AspNetCore.SignalR.Client in the search box.
4. In the search results, select the Microsoft.AspNetCore.SignalR.Client package and select Install .
5. If the Preview Changes dialog appears, select OK .
6. If the License Acceptance dialog appears, select I Accept if you agree with the license terms.

Add a SignalR hub

In the BlazorSignalRApp.Server project, create a Hubs (plural) folder and add the following ChatHub class (
Hubs/ChatHub.cs ):

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.SignalR;

namespace BlazorSignalRApp.Server.Hubs
{
public class ChatHub : Hub
{
public async Task SendMessage(string user, string message)
{
await Clients.All.SendAsync("ReceiveMessage", user, message);
}
}
}

Add services and an endpoint for the SignalR hub

1. In the BlazorSignalRApp.Server project, open the Startup.cs file.
2. Add the namespace for the ChatHub class to the top of the file:

using BlazorSignalRApp.Server.Hubs;

3. Add SignalR and Response Compression Middleware services to Startup.ConfigureServices :

public void ConfigureServices(IServiceCollection services)
{
services.AddSignalR();
services.AddControllersWithViews();
services.AddResponseCompression(opts =>
{
opts.MimeTypes = ResponseCompressionDefaults.MimeTypes.Concat(
new[] { "application/octet-stream" });
});
}

4. In Startup.Configure :
Use Response Compression Middleware at the top of the processing pipeline's configuration.
Between the endpoints for controllers and the client-side fallback, add an endpoint for the hub.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)

{
app.UseResponseCompression();

if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseWebAssemblyDebugging();
}
else
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}

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

app.UseRouting();

app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
endpoints.MapHub<ChatHub>("/chathub");
endpoints.MapFallbackToFile("index.html");
});
}

Add Razor component code for chat

1. In the BlazorSignalRApp.Client project, open the Pages/Index.razor file.
2. Replace the markup with the following code:
@page "/"
@using Microsoft.AspNetCore.SignalR.Client
@inject NavigationManager NavigationManager
@implements IDisposable

<div class="form-group">
<label>
User:
<input @bind="userInput" />
</label>
</div>
<div class="form-group">
<label>
Message:
<input @bind="messageInput" size="50" />
</label>
</div>
<button @onclick="Send" disabled="@(!IsConnected)">Send</button>

<hr>

<ul id="messagesList">
@foreach (var message in messages)
{
<li>@message</li>
}
</ul>

@code {
private HubConnection hubConnection;
private List<string> messages = new List<string>();
private string userInput;
private string messageInput;

protected override async Task OnInitializedAsync()

{
hubConnection = new HubConnectionBuilder()
.WithUrl(NavigationManager.ToAbsoluteUri("/chathub"))
.Build();

hubConnection.On<string, string>("ReceiveMessage", (user, message) =>

{
var encodedMsg = $"{user}: {message}";
messages.Add(encodedMsg);
StateHasChanged();
});

await hubConnection.StartAsync();
}

Task Send() =>

hubConnection.SendAsync("SendMessage", userInput, messageInput);

public bool IsConnected =>

hubConnection.State == HubConnectionState.Connected;

public void Dispose()

{
_ = hubConnection.DisposeAsync();
}
}

Run the app

1. Follow the guidance for your tooling:
Visual Studio
Visual Studio Code
Visual Studio for Mac
.NET Core CLI
1. In Solution Explorer , select the BlazorSignalRApp.Server project. Press F5 to run the app with debugging
or Ctrl+F5 to run the app without debugging.
2. Copy the URL from the address bar, open another browser instance or tab, and paste the URL in the address
bar.
3. Choose either browser, enter a name and message, and select the button to send the message. The name and
message are displayed on both pages instantly:

Quotes: Star Trek VI: The Undiscovered Country ©1991 Paramount

Next steps
In this tutorial, you learned how to:
Create a Blazor WebAssembly Hosted app project
Add the SignalR client library
Add a SignalR hub
Add SignalR services and an endpoint for the SignalR hub
Add Razor component code for chat
To learn more about building Blazor apps, see the Blazor documentation:
Introduction to ASP.NET Core Blazor

Additional resources
Introduction to ASP.NET Core SignalR
SignalR cross-origin negotiation for authentication
Tutorial: Create a gRPC client and server in ASP.NET
Core
7/10/2020 • 9 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 16.4 or later with the ASP.NET and web development workload
.NET Core 3.1 SDK or later

Create a gRPC service

Visual Studio
Visual Studio Code
Visual Studio for Mac
Start Visual Studio and select Create a new project . Alternatively, from the Visual Studio File menu, select
New > Project .
In the Create a new project dialog, select gRPC Ser vice and 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 gRPC ser vice dialog:
The gRPC Ser vice template is selected.
Select Create .
Run the service
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.

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

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 Unable to start ASP.NET Core gRPC app 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 and select Create a new project .
In the Create a new project dialog, select Console App (.NET Core) and select Next .
In the Project name text box, enter GrpcGreeterClient and 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, run cd GrpcGreeterClient to change directories to the
folder containing the GrpcGreeterClient.csproj files.
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:

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)
{
// The port number(5001) must match the port of the gRPC server.
using var channel = GrpcChannel.ForAddress("https://localhost:5001");
var client = new Greeter.GreeterClient(channel);
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 a GrpcChannel containing the information for creating the connection to the gRPC service.
Using the GrpcChannel to construct the Greeter client:

static async Task Main(string[] args)

{
// The port number(5001) must match the port of the gRPC server.
using var channel = GrpcChannel.ForAddress("https://localhost:5001");
var client = new Greeter.GreeterClient(channel);
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)

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

NOTE
The code in this article requires the ASP.NET Core HTTPS development certificate to secure the gRPC service. If the .NET gRPC
client fails with the message The remote certificate is invalid according to the validation procedure. or
The SSL connection could not be established. , the development certificate isn't trusted. To fix this issue, see Call a gRPC
service with an untrusted/invalid certificate.

WARNING
ASP.NET Core gRPC is not currently supported on Azure App Service or IIS. The HTTP/2 implementation of Http.Sys does not
support HTTP response trailing headers which gRPC relies on. For more information, see this GitHub issue.

Next steps
Introduction to gRPC on .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
7/10/2020 • 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. The tutorial uses the code first approach. For
information on following this tutorial using the database first approach, see this Github issue.
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 3.0 SDK or later

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:
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 updating Pages/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 Depar tments .
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">
© 2019 - Contoso University - <a asp-area="" asp-page="/Privacy">Privacy</a>
</div>
</footer>

@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/dotnet/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 . For more information, see EF Core - Keys.
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=SchoolContext6;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")}
};

context.Students.AddRange(students);
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=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}
};

context.Courses.AddRange(courses);
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},
};

context.Enrollments.AddRange(enrollments);
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
Stop the app if it's running, and run the following command in the Package Manager Console (PMC):

Drop-Database

Restart the app.

Select the Students page to see the seeded data.

View the database

Visual Studio
Visual Studio Code
Open SQL Ser ver 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
NE XT
T U TO R I A 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

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 Depar tments , 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>© 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 »
</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/dotnet/AspNetCore.Docs/tree/master/aspnetcore/data/ef-
rp/intro/samples/">
See project source code »
</a>
</p>
</div>
</div>

Create the data model

Create entity classes for the Contoso University app. Start with the following three entities:

There's a one-to-many relationship between Student and Enrollment entities. There's a one-to-many relationship
between Course and Enrollment entities. A student can enroll in any number of courses. A course can have any
number of students enrolled in it.
In the following sections, a class for each one of these entities is created.
The Student entity
Create a Models folder. In the Models folder, create a class file named Student.cs with the following code:

using System;
using System.Collections.Generic;

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;

public ICollection<Enrollment> Enrollments { get; set; }

}
}

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

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;

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[]

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

Visual Studio
Visual Studio Code
Stop the app if it's running, and run the following command in the Package Manager Console (PMC):

Drop-Database

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 Ser ver 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

NE XT
Part 2, Razor Pages with EF Core in ASP.NET Core -
CRUD
7/10/2020 • 22 minutes to read • Edit Online

By Tom Dykstra, Jon P Smith, and Rick Anderson

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>

Run the app and delete a student to test the Delete page.

Next steps

PR EVIO U S NE XT
T U TO R I A L T U TO R I A 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;

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

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

PR EVIO U S NE XT
Part 3, Razor Pages with EF Core in ASP.NET Core -
Sort, Filter, Paging
7/10/2020 • 29 minutes to read • Edit Online

By Tom Dykstra, Rick Anderson, and Jon P Smith

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:

C URREN T SO RT O RDER L A ST N A M E H Y P ERL IN K DAT E H Y P ERL IN K

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;

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

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

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

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

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.

PR EVIO U S NE XT
T U TO R I A L T U TO R I A 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;

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:

C URREN T SO RT O RDER L A ST N A M E H Y P ERL IN K DAT E H Y P ERL IN K

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;

Student = await studentIQ.AsNoTracking().ToListAsync();

}

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

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

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(

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,

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

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

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.
PR EVIO U S NE XT
Part 4, Razor Pages with EF Core migrations in
ASP.NET Core
7/10/2020 • 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 Ser ver 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.

PR EVIO U S NE XT
T U TO R I A L T U TO R I A 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 Ser ver 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 Ser ver 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)

PR EVIO U S NE XT
Part 5, Razor Pages with EF Core in ASP.NET Core -
Data Model
7/10/2020 • 57 minutes to read • Edit Online

By Tom Dykstra and Rick Anderson

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]*$")]

Visual Studio
Visual Studio Code
In SQL Ser ver 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 must be used with MinimumLength for the MinimumLength to be enforced.
[Display(Name = "Last Name")]
[Required]
[StringLength(50, MinimumLength=2)]
public string LastName { get; set; }

MinimumLength and Required allow whitespace to satisfy the validation. Use the RegularExpression attribute for full
control over the string.
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; }

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

context.Students.AddRange(students);
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") }
};

context.Instructors.AddRange(instructors);
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 }
};

context.Departments.AddRange(departments);
context.SaveChanges();

var courses = new Course[]

{
new Course {CourseID = 1050, Title = "Chemistry", Credits = 3,
DepartmentID = departments.Single( s => s.Name == "Engineering").DepartmentID
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
},
};

context.Courses.AddRange(courses);
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" },
};

context.OfficeAssignments.AddRange(officeAssignments);
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
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
},
};

context.CourseAssignments.AddRange(courseInstructors);
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)

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:

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:

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.

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.

PR EVIO U S NE XT
T U TO R I A L T U TO R I A 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]*$")]

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 Ser ver 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;

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;

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.

[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

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

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

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

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[]

foreach (Instructor i in instructors)

{
context.Instructors.Add(i);
}
context.SaveChanges();

var departments = new Department[]

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[]

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

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.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)
PR EVIO U S NE XT
Part 6, Razor Pages with EF Core in ASP.NET Core -
Read Related Data
7/10/2020 • 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 Depar tment 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 preceding code doesn't return any entity types, therefore no tracking is done. For more information about the
EF tracking, see Tracking vs. No-Tracking Queries.
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 ).

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>

@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 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)
{
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.Single(
i => i.ID == id.Value);
InstructorData.Courses = instructor.CourseAssignments.Select(
s => s.Course);
}

if (courseID != null)
{
CourseID = courseID.Value;
InstructorData.Enrollments = InstructorData.Courses.Single(
x => x.CourseID == courseID).Enrollments;
}
}

Use of Singlewith 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

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

PR EVIO U S NE XT
T U TO R I A L T U TO R I A 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 Depar tment 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;

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

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

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

PR EVIO U S NE XT
Part 7, Razor Pages with EF Core in ASP.NET Core -
Update Related Data
7/10/2020 • 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();
}
}
}

If you would like to see code comments translated to languages other than English, let us know in this GitHub
discussion issue.
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 Depar tmentID to Depar tment .
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";
}

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

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

The preceding code makes the following changes:

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

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>

Make the same changes to the Details page.

@page
@model ContosoUniversity.Pages.Courses.DetailsModel

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

<h2>Details</h2>

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

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>

@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

PR EVIO U S NE XT
T U TO R I A L T U TO R I A 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);
}
}
}

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

// 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 Depar tmentID to Depar tment .
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);

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

@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 Depar tmentID to Depar tment .
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>

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

}
}

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>

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

namespace ContosoUniversity.Pages.Instructors
{
public class InstructorCoursesPageModel : PageModel
{

public List<AssignedCourseData> AssignedCourseDataList;

public void PopulateAssignedCourseData(SchoolContext context,

public void UpdateInstructorCourses(SchoolContext context,

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

var selectedCoursesHS = new HashSet<string>(selectedCourses);

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

@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)

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

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>

@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)

PR EVIO U S NE XT
Part 8, Razor Pages with EF Core in ASP.NET Core -
Concurrency
7/10/2020 • 36 minutes to read • Edit Online

By Rick Anderson, Tom Dykstra, and Jon P Smith

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 ConcurrencyCheckAttribute 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 TimestampAttribute 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 Pages\Departments\Index.cshtml 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}");
}

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

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 Edit 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 postback 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 model

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

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

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.

PR EVIO U S
T U TO R I A 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;

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

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

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

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

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:

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

public async Task<IActionResult> OnPostAsync(int 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>

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

PR EVIO U S
ASP.NET Core MVC with EF Core - tutorial series
7/10/2020 • 2 minutes to read • Edit Online

This tutorial has not been updated to ASP.NET Core 3.0. The Razor Pages version has been updated. For information
on when this might be updated, see this GitHub issue.
This tutorial teaches ASP.NET Core MVC and Entity Framework Core with controllers and views. Razor Pages is an
alternative programming model that was introduced in ASP.NET Core 2.0. For new development, we recommend
Razor Pages over MVC with controllers and views. There is a Razor Pages version of this tutorial. Each tutorial
covers some material the other doesn't:
Some things this MVC tutorial has that the Razor Pages tutorial doesn't:
Implement inheritance in the data model
Perform raw SQL queries
Use dynamic LINQ to simplify code
Some things the Razor Pages tutorial has that this one doesn't:
Use Select method to load related data
A version available for ASP.NET Core 3.0
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
7/10/2020 • 21 minutes to read • Edit Online

This tutorial has not been updated to ASP.NET Core 3.0. The Razor Pages version has been updated. Most of the
code changes for the ASP.NET Core 3.0 and later version of this tutorial:
Are in the Startup.cs and Program.cs files.
Can be found in the Razor Pages version.
For information on when this might be updated, see this GitHub issue.
This tutorial teaches ASP.NET Core MVC and Entity Framework Core with controllers and views. Razor Pages is an
alternative programming model that was introduced in ASP.NET Core 2.0. For new development, we recommend
Razor Pages over MVC with controllers and views. There is a Razor Pages version of this tutorial. Each tutorial
covers some material the other doesn't:
Some things this MVC tutorial has that the Razor Pages tutorial doesn't:
Implement inheritance in the data model
Perform raw SQL queries
Use dynamic LINQ to simplify code
Some things the Razor Pages tutorial has that this one doesn't:
Use Select method to load related data
A version available for ASP.NET Core 3.0
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 Depar tments , 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>
</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-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">
© 2019 - Contoso University - <a asp-area="" asp-controller="Home" asp-
action="Privacy">Privacy</a>
</div>
</footer>

@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 »</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/dotnet/AspNetCore.Docs/tree/master/aspnetcore/data/ef-mvc/intro/samples/cu-final">See
project source code »</a></p>
</div>
</div>

Press CTRL+F5 to run the project or choose Debug > Star t 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;

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;

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[]

var courses = new Course[]

var enrollments = new Enrollment[]

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 > Star t 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 Ser ver 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
7/10/2020 • 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 Index 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:

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:

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 declared 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
7/10/2020 • 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:

C URREN T SO RT O RDER L A ST N A M E H Y P ERL IN K DAT E H Y P ERL IN K

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

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

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

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

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

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/10/2020 • 7 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 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 Ser ver 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 tool install --global dotnet-ef

dotnet ef migrations add InitialCreate
dotnet tool install --global dotnet-ef installs dotnet ef as a global tool.
In the preceding commands, output similar to the following is displayed:

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.
Use the dotnet ef migrations remove command to remove a migration. dotnet ef migrations remove deletes the
migration and ensures the snapshot is correctly reset. If dotnet ef migrations remove fails, use
dotnet ef migrations remove -v to get more information on the failure.

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 Ser ver 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 .
Impor tant: 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/10/2020 • 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;

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 attribute won't prevent a user from entering white space for a name. You can use the
StringLength
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]*$")]

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 Ser ver 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.
The Required attribute must be used with MinimumLength for the MinimumLength to be enforced.

[Display(Name = "Last Name")]

[Required]
[StringLength(50, MinimumLength=2)]
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;

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;

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

protected override void OnModelCreating(ModelBuilder modelBuilder)

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[]

foreach (Student s in students)

{
context.Students.Add(s);
}
context.SaveChanges();

var instructors = new Instructor[]

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[]

foreach (Course c in courses)

{
context.Courses.Add(c);
}
context.SaveChanges();

var officeAssignments = new OfficeAssignment[]

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[]

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 Ser ver 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
7/10/2020 • 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 Depar tment 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;

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

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.

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 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 (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. It also drops AsNoTracking . 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
7/10/2020 • 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 Depar tment drop-down list, change the
caption from Depar tmentID to Depar tment , 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>

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

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

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 overload that requires explicit approval 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);

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

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

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)

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

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
7/10/2020 • 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";
}

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

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

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>

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>

@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
7/10/2020 • 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