Introduction to ASP.NET Core

By Daniel Roth, Rick Anderson, and Shaun Luttin

ASP.NET Core is a cross-platform, high-performance, open-source framework for building modern, cloud-based, Internet-connected applications. With ASP.NET Core, you can:

  • Build web apps and services, IoT apps, and mobile backends.
  • Use your favorite development tools on Windows, macOS, and Linux.
  • Deploy to the cloud or on-premises.
  • Run on .NET Core or .NET Framework.

Why choose ASP.NET Core?

Millions of developers have used (and continue to use) ASP.NET 4.x to create web apps. ASP.NET Core is a redesign of ASP.NET 4.x, with architectural changes that result in a leaner, more modular framework.

ASP.NET Core provides the following benefits:

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

ASP.NET Core MVC provides features to build web APIs and web apps:

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 targeting .NET Framework

ASP.NET Core 2.x can target .NET Core or .NET Framework. ASP.NET Core apps targeting .NET Framework aren't cross-platform—they run on Windows only. Generally, ASP.NET Core 2.x is made up of .NET Standard libraries. Libraries written with .NET Standard 2.0 run on any .NET platform that implements .NET Standard 2.0.

ASP.NET Core 2.x is supported on .NET Framework versions that implement .NET Standard 2.0:

  • .NET Framework latest version is strongly recommended.
  • .NET Framework 4.6.1 and later.

ASP.NET Core 3.0 and later will only run on .NET Core. For more details regarding this change, see A first look at changes coming in ASP.NET Core 3.0.

There are several advantages to targeting .NET Core, and these advantages increase with each release. Some advantages of .NET Core over .NET Framework include:

  • Cross-platform. Runs on macOS, Linux, and Windows.
  • Improved performance
  • Side-by-side versioning
  • New APIs
  • Open source

We're working hard to close the API gap from .NET Framework to .NET Core. The Windows Compatibility Pack made thousands of Windows-only APIs available in .NET Core. These APIs weren't available in .NET Core 1.x.

We recommend the following sequence of tutorials and articles for an introduction to developing ASP.NET Core apps:

  1. Follow a tutorial for the type of app you want to develop or maintain:

    App type Scenario Tutorial
    Web app For new development Get started with Razor Pages
    Web app For maintaining an MVC app Get started with MVC
    Web API Create a web API*
    Real-time app Get started with SignalR
    Blazor app Get started with Blazor
    Remote Procedure Call app Get started with a gRPC service
  2. Follow a tutorial that shows how to do basic data access:

    Scenario Tutorial
    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 features that apply to all app types:

  4. Browse the Table of Contents for other topics of interest.

* There is a new web API tutorial that you follow entirely in the browser, no local IDE installation required. The code runs in an Azure Cloud Shell, and curl is used for testing.

Migration from the .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 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
    .ConfigureWebHostDefaults(webBuilder =>

The preceding C# code snippet is referenced in the topic's markdown file with the following line:


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: