AspNetCore.Docs/aspnetcore/fundamentals/index.md

title	author	description	keywords	ms.author	manager	ms.date	ms.topic	ms.assetid	ms.technology	ms.prod	uid	ms.custom
ASP.NET Core fundamentals	rick-anderson	Discover the foundational concepts for building ASP.NET Core applications.	ASP.NET Core,fundamentals,overview	riande	wpickett	09/30/2017	get-started-article	a19b7836-63e4-44e8-8250-50d426dd1070	aspnet	asp.net-core	fundamentals/index	H1Hack27Feb2017

ASP.NET Core fundamentals

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

ASP.NET Core 2.x

[!code-csharpMain]

The Main method invokes WebHost.CreateDefaultBuilder, which follows the builder pattern to create a web application 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.

ASP.NET Core 1.x

[!code-csharpMain]

The Main method uses WebHostBuilder, which follows the builder pattern to create a web application 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:

ASP.NET Core 2.x

[!code-csharpMain]

ASP.NET Core 1.x

[!code-csharpMain]

---

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

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

For more information, see Application startup.

Content root

The content root is the base path to any content used by the app, such as views, Razor Pages, and static assets. By default, the content root is the same as application 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 native container if you wish. In addition to its loose coupling benefit, DI makes services available throughout your app (for example, logging).

For more information, see Dependency injection.

Middleware

In ASP.NET Core, you compose your request pipeline using middleware. ASP.NET Core middleware performs asynchronous logic on an HttpContext and then either invokes the next middleware in the sequence or terminates the request directly. A middleware component called "XYZ" is added by invoking an UseXYZ extension method in the Configure method.

ASP.NET Core comes with a rich set of built-in middleware:

• Static files
• Routing
• Authentication
• Response Compression Middleware
• URL Rewriting Middleware

OWIN-based middleware is available for ASP.NET Core apps, and you can write your own custom middleware.

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

Environments

Environments, such as "Development" and "Production", are a first-class notion in ASP.NET Core and can be set using environment variables.

For more information, see Working with Multiple Environments.

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) and environment variables to enable environment-based configuration. You can also write your own custom configuration providers.

For more information, see Configuration.

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.

Logging

Error handling

ASP.NET Core has built-in features 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 Error Handling.

Routing

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

For more information, see Routing.

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.

Static files

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

For more information, see Working with static files.

Hosting

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

For more information, see Hosting.

Session and application state

Session state is a feature in ASP.NET Core that you can use to save and store user data while the user browses your web app.

For more information, see Session and application state.

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 often run behind a production web server, such as IIS or nginx. Kestrel can be run as an edge server.

For more information, see Servers and the following topics:

• Kestrel
• ASP.NET Core Module
• HTTP.sys (formerly called WebListener)

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 into different languages and cultures.

For more information, see Globalization and localization.

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.

Open Web Interface for .NET (OWIN)

ASP.NET Core supports the Open Web Interface for .NET (OWIN). OWIN allows web apps to be decoupled from web servers.

For more information, see Open Web Interface for .NET (OWIN).

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

For more information, see WebSockets.

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

.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 Core and ASP.NET.