ASP.NET Core fundamentals

An ASP.NET Core app is a console app that creates a web server in its Program.Main method. The Main method is the app's managed entry point:

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 .NET Core Host:

  • Loads the .NET Core runtime.
  • Uses the first command-line argument as the path to the managed binary that contains the entry point (Main) and begins code execution.

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 .NET Core Host:

  • Loads the .NET Core runtime.
  • Uses the first command-line argument as the path to the managed binary that contains the entry point (Main) and begins code execution.

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

The webroot of an app is the directory in the project containing public, static resources, such as CSS, JavaScript, and image files. By default, wwwroot is the webroot.

For Razor (.cshtml) files, the tilde-slash ~/ points to the webroot. Paths beginning with ~/ are referred to as virtual paths.

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.

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.