ASP.NET Core fundamentals

An ASP.NET Core app is a console app that creates a web server in its Main method:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

The Main method invokes WebHost.CreateDefaultBuilder, which follows the builder pattern to create a web host. The builder has methods that define the web server (for example, UseKestrel) and the startup class (UseStartup). In the preceding example, the Kestrel web server is automatically allocated. ASP.NET Core's web host attempts to run on IIS, if available. Other web servers, such as HTTP.sys, can be used by invoking the appropriate extension method. UseStartup is explained further in the next section.

IWebHostBuilder, the return type of the WebHost.CreateDefaultBuilder invocation, provides many optional methods. Some of these methods include UseHttpSys for hosting the app in HTTP.sys and UseContentRoot for specifying the root content directory. The Build and Run methods build the IWebHost object that hosts the app and begins listening for HTTP requests.

public class Program
{
    public static void Main(string[] args)
    {
        var host = new WebHostBuilder()
            .UseKestrel()
            .UseStartup<Startup>()
            .Build();

        host.Run();
    }
}

The Main method uses WebHostBuilder, which follows the builder pattern to create a web app host. The builder has methods that define the web server (for example, UseKestrel) and the startup class (UseStartup). In the preceding example, the Kestrel web server is used. Other web servers, such as WebListener, can be used by invoking the appropriate extension method. UseStartup is explained further in the next section.

WebHostBuilder provides many optional methods, including UseIISIntegration for hosting in IIS and IIS Express and UseContentRoot for specifying the root content directory. The Build and Run methods build the IWebHost object that hosts the app and begins listening for HTTP requests.

Startup

The UseStartup method on WebHostBuilder specifies the Startup class for your app:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}
public class Program
{
    public static void Main(string[] args)
    {
        var host = new WebHostBuilder()
            .UseKestrel()
            .UseStartup<Startup>()
            .Build();

        host.Run();
    }
}

The Startup class is where you define the request handling pipeline and where any services needed by the app are configured. The Startup class must be public and contain the following methods:

public class Startup
{
    // This method gets called by the runtime. Use this method
    // to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
    }

    // This method gets called by the runtime. Use this method
    // to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app)
    {
    }
}
public class Startup
{
    // This method gets called by the runtime. Use this method
    // to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
    }

    // This method gets called by the runtime. Use this method
    // to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app)
    {
    }
}

ConfigureServices defines the Services used by your app (for example, ASP.NET Core MVC, Entity Framework Core, Identity). Configure defines the middleware called in the request pipeline.

For more information, see Application startup in ASP.NET Core.

Content root

The content root is the base path to any content used by the app, such as Razor Pages, MVC views, and static assets. By default, the content root is the same location as the app base path for the executable hosting the app.

Web root

The web root of an app is the directory in the project containing public, static resources, such as CSS, JavaScript, and image files.

Dependency injection (services)

A service is a component that's intended for common consumption in an app. Services are made available through dependency injection (DI). ASP.NET Core includes a native Inversion of Control (IoC) container that supports constructor injection by default. You can replace the default container if you wish. In addition to its loose coupling benefit, DI makes services, such as logging, available throughout your app.

For more information, see Dependency injection in ASP.NET Core.

Middleware

In ASP.NET Core, you compose your request pipeline using middleware. ASP.NET Core middleware performs asynchronous operations on an HttpContext and then either invokes the next middleware in the pipeline or terminates the request.

By convention, a middleware component called "XYZ" is added to the pipeline by invoking a UseXYZ extension method in the Configure method.

ASP.NET Core includes a rich set of built-in middleware, and you can write your own custom middleware. Open Web Interface for .NET (OWIN), which allows web apps to be decoupled from web servers, is supported in ASP.NET Core apps.

For more information, see ASP.NET Core Middleware and Open Web Interface for .NET (OWIN) with ASP.NET Core.

Initiate HTTP requests

IHttpClientFactory is available to access HttpClient instances to make HTTP requests.

For more information, see Initiate HTTP requests.

Environments

Environments, such as Development and Production, are a first-class notion in ASP.NET Core and can be set using an environment variable, settings file, and command-line argument.

For more information, see Use multiple environments in ASP.NET Core.

Hosting

ASP.NET Core apps configure and launch a host, which is responsible for app startup and lifetime management.

For more information, see Host in ASP.NET Core.

Servers

The ASP.NET Core hosting model doesn't directly listen for requests. The hosting model relies on an HTTP server implementation to forward the request to the app. The forwarded request is wrapped as a set of feature objects that can be accessed through interfaces. ASP.NET Core includes a managed, cross-platform web server, called Kestrel. Kestrel is commonly run behind a production web server, such as IIS or Nginx in a reverse proxy configuration. Kestrel can also be run as a public-facing edge server exposed directly to the Internet in ASP.NET Core 2.0 or later.

For more information, see Web server implementations in ASP.NET Core.

Configuration

ASP.NET Core uses a configuration model based on name-value pairs. The configuration model isn't based on System.Configuration or web.config. Configuration obtains settings from an ordered set of configuration providers. The built-in configuration providers support a variety of file formats (XML, JSON, INI), environment variables, and command-line arguments. You can also write your own custom configuration providers.

For more information, see Configuration in ASP.NET Core.

Logging

ASP.NET Core supports a Logging API that works with a variety of logging providers. Built-in providers support sending logs to one or more destinations. Third-party logging frameworks can be used.

For more information, see Logging in ASP.NET Core.

Error handling

ASP.NET Core has built-in scenarios for handling errors in apps, including a developer exception page, custom error pages, static status code pages, and startup exception handling.

For more information, see Handle errors in ASP.NET Core.

Routing

ASP.NET Core offers scenarios for routing of app requests to route handlers.

For more information, see Routing in ASP.NET Core.

File Providers

ASP.NET Core abstracts file system access through the use of File Providers, which offers a common interface for working with files across platforms.

For more information, see File Providers in ASP.NET Core.

Static files

Static Files Middleware serves static files, such as HTML, CSS, image, and JavaScript files.

For more information, see Static files in ASP.NET Core.

Session and app state

ASP.NET Core offers several approaches to preserve session and app state while a user browses a web app.

For more information, see Session and app state in ASP.NET Core.

Globalization and localization

Creating a multilingual website with ASP.NET Core allows your site to reach a wider audience. ASP.NET Core provides services and middleware for localizing content into different languages and cultures.

For more information, see Globalization and localization in ASP.NET Core.

Request features

Web server implementation details related to HTTP requests and responses are defined in interfaces. These interfaces are used by server implementations and middleware to create and modify the app's hosting pipeline.

For more information, see Request Features in ASP.NET Core.

Background tasks

Background tasks are implemented as hosted services. A hosted service is a class with background task logic that implements the IHostedService interface.

For more information, see Background tasks with hosted services in ASP.NET Core.

Access HttpContext

HttpContext is automatically available when processing requests with Razor Pages and MVC. In circumstances where HttpContext isn't readily available, you can access the HttpContext through the IHttpContextAccessor interface and its default implementation, HttpContextAccessor.

For more information, see Access HttpContext in ASP.NET Core.

WebSockets

WebSocket is a protocol that enables two-way persistent communication channels over TCP connections. It's used for apps such as chat, stock tickers, games, and anywhere you desire real-time functionality in a web app. ASP.NET Core supports web socket scenarios.

For more information, see WebSockets support in ASP.NET Core.

Microsoft.AspNetCore.App metapackage

The Microsoft.AspNetCore.App metapackage simplifies package management.

For more information, see Microsoft.AspNetCore.App metapackage for ASP.NET Core 2.1 and later.

Microsoft.AspNetCore.All metapackage

The Microsoft.AspNetCore.All metapackage for ASP.NET Core includes:

  • All supported packages by the ASP.NET Core team.
  • All supported packages by Entity Framework Core.
  • Internal and 3rd-party dependencies used by ASP.NET Core and Entity Framework Core.

For more information, see Microsoft.AspNetCore.All metapackage for ASP.NET Core 2.0.

.NET Core vs. .NET Framework runtime

An ASP.NET Core app can target the .NET Core or .NET Framework runtime.

For more information, see Choosing between .NET Core and .NET Framework.

Choose between ASP.NET Core and ASP.NET

For more information on choosing between ASP.NET Core and ASP.NET, see Choose between ASP.NET 4.x and ASP.NET Core.