Основы ASP.NET CoreASP.NET Core fundamentals

В этой статье приведен обзор основных тем, связанных с разработкой приложений ASP.NET Core.This article provides an overview of key topics for understanding how to develop ASP.NET Core apps.

Класс StartupThe Startup class

В классе Startup делается следующее.The Startup class is where:

  • Настраиваются службы, необходимые приложению.Services required by the app are configured.
  • Конвейер обработки запросов приложения определен как ряд компонентов ПО промежуточного слоя.The app's request handling pipeline is defined, as a series of middleware components.

Пример класса Startup:Here's a sample Startup class:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddDbContext<RazorPagesMovieContext>(options =>
            options.UseSqlServer(Configuration.GetConnectionString("RazorPagesMovieContext")));

        services.AddControllersWithViews();
        services.AddRazorPages();
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseHttpsRedirection();
        app.UseStaticFiles();

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapDefaultControllerRoute();
            endpoints.MapRazorPages();
        });
    }
}

Для получения дополнительной информации см. Запуск приложения в ASP.NET Core.For more information, see Запуск приложения в ASP.NET Core.

Введение зависимостей (службы)Dependency injection (services)

ASP.NET Core включает встроенную платформу внедрения зависимостей, позволяющую обращаться к настроенным службам в рамках приложения.ASP.NET Core includes a built-in dependency injection (DI) framework that makes configured services available throughout an app. Например, службой является компонент ведения журнала.For example, a logging component is a service.

Код для настройки (или регистрации) служб добавляется в метод Startup.ConfigureServices.Code to configure (or register) services is added to the Startup.ConfigureServices method. Пример:For example:

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<RazorPagesMovieContext>(options =>
        options.UseSqlServer(Configuration.GetConnectionString("RazorPagesMovieContext")));

    services.AddControllersWithViews();
    services.AddRazorPages();
}

Как правило, службы разрешаются из системы внедрения зависимостей с помощью внедрения конструктора.Services are typically resolved from DI using constructor injection. При внедрении конструктора класс объявляет параметр конструктора, который может быть требуемым типом или интерфейсом.With constructor injection, a class declares a constructor parameter of either the required type or an interface. Платформа внедрения зависимостей предоставляет экземпляр этой службы во время выполнения.The DI framework provides an instance of this service at runtime.

В следующем примере показано использование внедрения конструктора для разрешения RazorPagesMovieContext из системы внедрения зависимостей.The following example uses constructor injection to resolve a RazorPagesMovieContext from DI:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;

    public IndexModel(RazorPagesMovieContext context)
    {
        _context = context;
    }

    // ...

    public async Task OnGetAsync()
    {
        Movies = await _context.Movies.ToListAsync();
    }
}

Если встроенный контейнер с инверсией управления (IoC) не удовлетворяет всем потребностям приложения, вместо него можно использовать сторонний контейнер IoC.If the built-in Inversion of Control (IoC) container doesn't meet all of an app's needs, a third-party IoC container can be used instead.

Для получения дополнительной информации см. Внедрение зависимостей в ASP.NET Core.For more information, see Внедрение зависимостей в ASP.NET Core.

ПО промежуточного слояMiddleware

Конвейер обработки запросов состоит из ряда компонентов ПО промежуточного слоя.The request handling pipeline is composed as a series of middleware components. Каждый компонент выполняет операции в HttpContext, а затем либо вызывает следующий компонент в конвейере, либо завершает запрос.Each component performs operations on an HttpContext and either invokes the next middleware in the pipeline or terminates the request.

По принятому соглашению компонент ПО промежуточного слоя добавляется в конвейер вызовом метода расширения Use... в методе Startup.Configure.By convention, a middleware component is added to the pipeline by invoking a Use... extension method in the Startup.Configure method. Например, чтобы включить отрисовку статических файлов, вызовите UseStaticFiles.For example, to enable rendering of static files, call UseStaticFiles.

В следующем примере показана настройка конвейера обработки запросов.The following example configures a request handling pipeline:

public void Configure(IApplicationBuilder app)
{
    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute();
        endpoints.MapRazorPages();
    });
}

ASP.NET Core содержит большой набор встроенного ПО промежуточного слоя.ASP.NET Core includes a rich set of built-in middleware. Кроме того, можно создать пользовательские компоненты ПО промежуточного слоя.Custom middleware components can also be written.

Для получения дополнительной информации см. ПО промежуточного слоя ASP.NET Core.For more information, see ПО промежуточного слоя ASP.NET Core.

УзелHost

При запуске приложение ASP.NET Core создает узел.On startup, an ASP.NET Core app builds a host. Узел инкапсулирует все ресурсы приложения:The host encapsulates all of the app's resources, such as:

  • Реализация HTTP-сервераAn HTTP server implementation
  • Компоненты ПО промежуточного слояMiddleware components
  • Ведение журналаLogging
  • Службы внедрения зависимостейDependency injection (DI) services
  • Параметр ConfigurationConfiguration

Существует два различных узла:There are two different hosts:

  • Универсальный узел .NET.NET Generic Host
  • Веб-узел ASP.NET CoreASP.NET Core Web Host

Рекомендуется использовать универсальный узел .NET.The .NET Generic Host is recommended. Веб-узел ASP.NET Core доступен только для обеспечения обратной совместимости.The ASP.NET Core Web Host is available only for backwards compatibility.

В следующем примере показано создание универсального узла .NET.The following example creates a .NET Generic Host:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Методы CreateDefaultBuilder и ConfigureWebHostDefaults применяются для настройки узла с набором параметров по умолчанию, например:The CreateDefaultBuilder and ConfigureWebHostDefaults methods configure a host with a set of default options, such as:

  • Использование Kestrel в качестве веб-сервера и поддержка интеграции с IIS.Use Kestrel as the web server and enable IIS integration.
  • Загрузка конфигурации из файлов appsettings.json и appsettings.{имя среды}.json, переменных среды, аргументов командной строки и других источников.Load configuration from appsettings.json, appsettings.{Environment Name}.json, environment variables, command line arguments, and other configuration sources.
  • Отправка выходных данных журнала в поставщики служб консоли и отладки.Send logging output to the console and debug providers.

Для получения дополнительной информации см. Универсальный узел .NET.For more information, see Универсальный узел .NET.

Сценарии, не связанные с ИнтернетомNon-web scenarios

Универсальный узел позволяет приложениям других типов использовать перекрестные расширения платформ, такие как средства ведения журналов, внедрения зависимостей, настройки и управления жизненным циклом.The Generic Host allows other types of apps to use cross-cutting framework extensions, such as logging, dependency injection (DI), configuration, and app lifetime management. Дополнительные сведения см. в разделах Универсальный узел .NET и Фоновые задачи с размещенными службами в ASP.NET Core.For more information, see Универсальный узел .NET and Фоновые задачи с размещенными службами в ASP.NET Core.

СерверыServers

Приложение ASP.NET Core использует реализацию HTTP-сервера для приема HTTP-запросов.An ASP.NET Core app uses an HTTP server implementation to listen for HTTP requests. Сервер отправляет приложению запросы в виде набора функций запросов, объединенных в HttpContext.The server surfaces requests to the app as a set of request features composed into an HttpContext.

ASP.NET Core предоставляет следующие реализации серверов:ASP.NET Core provides the following server implementations:

  • Kestrel — это кроссплатформенный веб-сервер.Kestrel is a cross-platform web server. Он часто запускается в реконфигурации прокси-сервера с помощью IIS.Kestrel is often run in a reverse proxy configuration using IIS. В ASP.NET Core 2.0 и более поздних версиях можно использовать Kestrel в роли общедоступного пограничного сервера с прямым доступом через Интернет.In ASP.NET Core 2.0 or later, Kestrel can be run as a public-facing edge server exposed directly to the Internet.
  • HTTP-сервер IIS — это сервер для Windows, который использует службы IIS.IIS HTTP Server is a server for Windows that uses IIS. Он позволяет запускать приложение ASP.NET Core и службы IIS в одном процессе.With this server, the ASP.NET Core app and IIS run in the same process.
  • HTTP.sys — это сервер для Windows, который не используется со службами IIS.HTTP.sys is a server for Windows that isn't used with IIS.

Для получения дополнительной информации см. Реализации веб-сервера в ASP.NET Core.For more information, see Реализации веб-сервера в ASP.NET Core.

Параметр ConfigurationConfiguration

ASP.NET Core предоставляет платформу конфигурации, которая получает параметры в виде пар "имя-значение" от упорядоченного набора поставщиков конфигурации.ASP.NET Core provides a configuration framework that gets settings as name-value pairs from an ordered set of configuration providers. Доступны встроенные поставщики конфигурации для различных источников, таких как файлы JSON, XML, переменные среды и аргументы командной строки.Built-in configuration providers are available for a variety of sources, such as .json files, .xml files, environment variables, and command-line arguments. Для поддержки других источников можно создать настраиваемые поставщики конфигурации.Write custom configuration providers to support other sources.

По умолчанию приложения ASP.NET Core настроены для чтения из файла appsettings.json, переменных среды, командной строки и т. д.By default, ASP.NET Core apps are configured to read from appsettings.json, environment variables, the command line, and more. При загрузке конфигурации приложения значения из переменных среды переопределяют значения из файла appsettings.json.When the app's configuration is loaded, values from environment variables override values from appsettings.json.

Предпочтительный способ чтения связанных значений конфигурации — использование шаблона параметров.The preferred way to read related configuration values is using the options pattern. Дополнительные сведения см. в статье Привязка иерархических данных конфигурации с помощью шаблона параметров.For more information, see Bind hierarchical configuration data using the options pattern.

Для управления конфиденциальными данными конфигурации, например паролями, ASP.NET Core предоставляет Менеджер секретов.For managing confidential configuration data such as passwords, ASP.NET Core provides the Secret Manager. Для секретов в рабочей среде рекомендуется использовать Azure Key Vault.For production secrets, we recommend Azure Key Vault.

Для получения дополнительной информации см. Конфигурация в .NET Core.For more information, see Конфигурация в .NET Core.

СредыEnvironments

Среды выполнения, такие как Development, Staging и Production, являются ключевыми компонентами ASP.NET Core.Execution environments, such as Development, Staging, and Production, are a first-class notion in ASP.NET Core. Указать среду, в которой запускается приложение, можно с помощью переменной среды ASPNETCORE_ENVIRONMENT.Specify the environment an app is running in by setting the ASPNETCORE_ENVIRONMENT environment variable. ASP.NET Core считывает переменную среды при запуске приложения и сохраняет ее значение в реализации IWebHostEnvironment.ASP.NET Core reads that environment variable at app startup and stores the value in an IWebHostEnvironment implementation. Эта реализация доступна в любом месте приложения посредством внедрения зависимостей.This implementation is available anywhere in an app via dependency injection (DI).

В следующем примере показана настройка приложения для предоставления подробных сведений об ошибке при выполнении в среде Development.The following example configures the app to provide detailed error information when running in the Development environment:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

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

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute();
        endpoints.MapRazorPages();
    });
}

Для получения дополнительной информации см. Использование нескольких сред в ASP.NET Core.For more information, see Использование нескольких сред в ASP.NET Core.

Ведение журналаLogging

ASP.NET Core поддерживает API ведения журналов, который работает с разными встроенными и сторонними поставщиками.ASP.NET Core supports a logging API that works with a variety of built-in and third-party logging providers. Доступные следующие поставщики:Available providers include:

  • КонсольConsole
  • ОтладкаDebug
  • Трассировка событий WindowsEvent Tracing on Windows
  • Журнал событий WindowsWindows Event Log
  • TraceSourceTraceSource
  • Служба приложений AzureAzure App Service
  • Azure Application InsightsAzure Application Insights

Для создания журналов необходимо разрешить службу ILogger<TCategoryName> из системы внедрения зависимостей (DI) и вызвать методы ведения журналов, такие как LogInformation.To create logs, resolve an ILogger<TCategoryName> service from dependency injection (DI) and call logging methods such as LogInformation. Пример:For example:

public class TodoController : ControllerBase
{
    private readonly ILogger _logger;

    public TodoController(ILogger<TodoController> logger)
    {
        _logger = logger;
    }

    [HttpGet("{id}", Name = "GetTodo")]
    public ActionResult<TodoItem> GetById(string id)
    {
        _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
        
        // Item lookup code removed.
        
        if (item == null)
        {
            _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
            return NotFound();
        }
        
        return item;
    }
}

Методы ведения журналов, такие как LogInformation, поддерживают любое количество полей.Logging methods such as LogInformation support any number of fields. Как правило, эти поля используются для создания сообщения string, но некоторые поставщики ведения журналов отправляют их в хранилище данных в виде отдельных полей.These fields are commonly used to construct a message string, but some logging providers send these to a data store as separate fields. Благодаря этому поставщики могут реализовывать семантическое (структурированное) ведение журналов.This feature makes it possible for logging providers to implement semantic logging, also known as structured logging.

Для получения дополнительной информации см. Ведение журнала в .NET Core и ASP.NET Core.For more information, see Ведение журнала в .NET Core и ASP.NET Core.

МаршрутизацияRouting

Маршрут — это шаблон URL-адреса, сопоставляемый с обработчиком.A route is a URL pattern that is mapped to a handler. Обычно обработчик представляет собой страницу Razor, метод действия в контроллере MVC или ПО промежуточного слоя.The handler is typically a Razor page, an action method in an MVC controller, or a middleware. Маршрутизация ASP.NET Core позволяет контролировать URL-адреса, используемые приложением.ASP.NET Core routing gives you control over the URLs used by your app.

Для получения дополнительной информации см. Маршрутизация в ASP.NET Core.For more information, see Маршрутизация в ASP.NET Core.

Обработка ошибокError handling

ASP.NET Core содержит встроенные функции обработки ошибок, такие как:ASP.NET Core has built-in features for handling errors, such as:

  • Страница исключений для разработчикаA developer exception page
  • Настраиваемые страницы ошибокCustom error pages
  • Статические страницы с кодами состоянияStatic status code pages
  • Обработка исключений при запускеStartup exception handling

Для получения дополнительной информации см. Обработка ошибок в ASP.NET Core.For more information, see Обработка ошибок в ASP.NET Core.

Создание HTTP-запросовMake HTTP requests

ASP.NET Core включает реализацию интерфейса IHttpClientFactory для создания экземпляров HttpClient.An implementation of IHttpClientFactory is available for creating HttpClient instances. Фабрика:The factory:

  • Центральное расположение для именования и настройки логических экземпляров HttpClient.Provides a central location for naming and configuring logical HttpClient instances. Например, можно зарегистрировать и использовать клиент github для доступа к сайту GitHub.For example, register and configure a github client for accessing GitHub. Можно зарегистрировать и настроить клиент по умолчанию для других целей.Register and configure a default client for other purposes.
  • Поддержка регистрации и связывания в цепочки множества делегирующих обработчиков для создания конвейера ПО промежуточного слоя под исходящие запросы.Supports registration and chaining of multiple delegating handlers to build an outgoing request middleware pipeline. Этот шаблон похож на входящий конвейер ПО промежуточного слоя для ASP.NET Core.This pattern is similar to ASP.NET Core's inbound middleware pipeline. Шаблон предоставляет механизм управления сквозной функциональностью HTTP-запросов, включая кэширование, обработку ошибок, сериализацию и ведение журнала.The pattern provides a mechanism to manage cross-cutting concerns for HTTP requests, including caching, error handling, serialization, and logging.
  • Интеграция с Polly — популярной сторонней библиотекой для обработки временных сбоев.Integrates with Polly, a popular third-party library for transient fault handling.
  • Управление созданием пулов и временем существования базовых экземпляров HttpClientHandler с целью избежать обычных проблем с DNS, которые возникают при управлении временем существования HttpClient вручную.Manages the pooling and lifetime of underlying HttpClientHandler instances to avoid common DNS problems that occur when managing HttpClient lifetimes manually.
  • Настройка параметров ведения журнала (через ILogger) для всех запросов, отправленных через клиентов, созданных фабрикой.Adds a configurable logging experience via ILogger for all requests sent through clients created by the factory.

Для получения дополнительной информации см. Выполнения HTTP-запросов с помощью IHttpClientFactory в ASP.NET Core.For more information, see Выполнения HTTP-запросов с помощью IHttpClientFactory в ASP.NET Core.

Корневой каталог содержимогоContent root

Корневой каталог содержимого — это базовый путь к следующим элементам:The content root is the base path for:

  • Исполняемый файл, в котором размещено приложение (EXE).The executable hosting the app (.exe).
  • Скомпилированные сборки, составляющие приложение (DLL).Compiled assemblies that make up the app (.dll).
  • Файлы содержимого, используемые приложением, например:Content files used by the app, such as:
    • Файлы Razor (CSHTML, RAZOR).Razor files (.cshtml, .razor)
    • Файлы конфигурации (JSON, XML).Configuration files (.json, .xml)
    • Файлы данных (DB).Data files (.db)
  • Корневой веб-каталог, обычно это папка wwwroot.The Web root, typically the wwwroot folder.

Во время развертывания корень содержимого по умолчанию сбрасывается до корневого каталога проекта.During development, the content root defaults to the project's root directory. Этот каталог является базовым путем к файлам содержимого приложения и корневому веб-каталогу.This directory is also the base path for both the app's content files and the Web root. Альтернативный корневой путь к содержимому может быть указан при создании узла.Specify a different content root by setting its path when building the host. Дополнительные сведения: Корень содержимого.For more information, see Content root.

Корневой веб-узелWeb root

Корневой веб-каталог — это базовый путь к общедоступным файлам статических ресурсов, например:The web root is the base path for public, static resource files, such as:

  • Таблицы стилей (CSS).Stylesheets (.css)
  • JavaScript (JS).JavaScript (.js)
  • Изображения (PNG, JPG).Images (.png, .jpg)

По умолчанию статические файлы обслуживаются только в корневом веб-каталоге и его подкаталогах.By default, static files are served only from the web root directory and its sub-directories. По умолчанию используется путь {корневой каталог содержимого}/wwwroot.The web root path defaults to {content root}/wwwroot. Альтернативное расположение корневого веб-каталога можно указать при создании узла.Specify a different web root by setting its path when building the host. Дополнительные сведения см. в разделе Корневой веб-каталог.For more information, see Web root.

Запретите публикацию файлов в wwwroot с помощью элемента проекта <Content> в файле проекта.Prevent publishing files in wwwroot with the <Content> project item in the project file. В следующем примере запрещается публикация содержимого в каталоге wwwroot/local и его подкаталогах:The following example prevents publishing content in wwwroot/local and its sub-directories:

<ItemGroup>
  <Content Update="wwwroot\local\**\*.*" CopyToPublishDirectory="Never" />
</ItemGroup>

Для указания на корневой каталог файлов Razor (CSHTML) используется символ тильды и косой черты ~/.In Razor .cshtml files, tilde-slash (~/) points to the web root. Путь, начинающийся с ~/, называется виртуальным путем.A path beginning with ~/ is referred to as a virtual path.

Для получения дополнительной информации см. Статические файлы в ASP.NET Core.For more information, see Статические файлы в ASP.NET Core.

В этой статье приведен обзор основных тем, связанных с разработкой приложений ASP.NET Core.This article is an overview of key topics for understanding how to develop ASP.NET Core apps.

Класс StartupThe Startup class

В классе Startup делается следующее.The Startup class is where:

  • Настраиваются службы, необходимые приложению.Services required by the app are configured.
  • Определяется конвейер обработки запросов.The request handling pipeline is defined.

Службы — это компоненты, которые используются в приложении.Services are components that are used by the app. Например, службой является компонент ведения журнала.For example, a logging component is a service. Код для настройки (или регистрации) служб добавляется в метод Startup.ConfigureServices.Code to configure (or register) services is added to the Startup.ConfigureServices method.

Конвейер обработки запросов состоит из ряда компонентов ПО промежуточного слоя.The request handling pipeline is composed as a series of middleware components. Например, это ПО может обрабатывать запросы для статических файлов или перенаправлять HTTP-запросы в HTTPS.For example, a middleware might handle requests for static files or redirect HTTP requests to HTTPS. Каждый компонент ПО промежуточного слоя выполняет асинхронные операции в HttpContext, а затем либо вызывает следующий компонент в конвейере, либо завершает запрос.Each middleware performs asynchronous operations on an HttpContext and then either invokes the next middleware in the pipeline or terminates the request. Код для настройки конвейера обработки запросов добавляется в метод Startup.Configure.Code to configure the request handling pipeline is added to the Startup.Configure method.

Пример класса Startup:Here's a sample Startup class:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

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

    public void Configure(IApplicationBuilder app)
    {
        app.UseHttpsRedirection();
        app.UseStaticFiles();
        app.UseMvc();
    }
}

Для получения дополнительной информации см. Запуск приложения в ASP.NET Core.For more information, see Запуск приложения в ASP.NET Core.

Введение зависимостей (службы)Dependency injection (services)

ASP.NET Core включает встроенную платформу внедрения зависимостей, позволяющую классам приложения обращаться к настроенным службам.ASP.NET Core has a built-in dependency injection (DI) framework that makes configured services available to an app's classes. Одним из вариантов получения экземпляра службы в классе является создание конструктора с параметром требуемого типа.One way to get an instance of a service in a class is to create a constructor with a parameter of the required type. Параметр может быть типом службы или интерфейсом.The parameter can be the service type or an interface. Система внедрения зависимостей предоставляет службу во время выполнения.The DI system provides the service at runtime.

Ниже показан класс, который использует внедрение зависимостей для получения объекта контекста Entity Framework Core.Here's a class that uses DI to get an Entity Framework Core context object. Выделенная строка является примером внедрения через конструктор.The highlighted line is an example of constructor injection:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;

    public IndexModel(RazorPagesMovieContext context)
    {
        _context = context;
    }

    // ...

    public async Task OnGetAsync()
    {
        Movies = await _context.Movies.ToListAsync();
    }
}

Несмотря на то, что система внедрения зависимостей является встроенной, она позволяет вам при желании подключать сторонний контейнер с инверсией управления (IoC).While DI is built in, it's designed to let you plug in a third-party Inversion of Control (IoC) container if you prefer.

Для получения дополнительной информации см. Внедрение зависимостей в ASP.NET Core.For more information, see Внедрение зависимостей в ASP.NET Core.

ПО промежуточного слояMiddleware

Конвейер обработки запросов состоит из ряда компонентов ПО промежуточного слоя.The request handling pipeline is composed as a series of middleware components. Каждый компонент выполняет асинхронные операции в HttpContext, а затем либо вызывает следующий компонент в конвейере, либо завершает запрос.Each component performs asynchronous operations on an HttpContext and then either invokes the next middleware in the pipeline or terminates the request.

По принятому соглашению компонент ПО промежуточного слоя добавляется в конвейер вызовом метода расширения Use... в методе Startup.Configure.By convention, a middleware component is added to the pipeline by invoking its Use... extension method in the Startup.Configure method. Например, чтобы включить отрисовку статических файлов, вызовите UseStaticFiles.For example, to enable rendering of static files, call UseStaticFiles.

Код настройки конвейера обработки запросов выделен в следующем примере:The highlighted code in the following example configures the request handling pipeline:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

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

    public void Configure(IApplicationBuilder app)
    {
        app.UseHttpsRedirection();
        app.UseStaticFiles();
        app.UseMvc();
    }
}

ASP.NET Core включает обширный набор встроенного ПО промежуточного слоя и позволяет вам писать свое собственное.ASP.NET Core includes a rich set of built-in middleware, and you can write custom middleware.

Для получения дополнительной информации см. ПО промежуточного слоя ASP.NET Core.For more information, see ПО промежуточного слоя ASP.NET Core.

УзелHost

Приложение ASP.NET Core создает узел при запуске.An ASP.NET Core app builds a host on startup. Узел — это объект, который инкапсулирует все ресурсы приложения.The host is an object that encapsulates all of the app's resources, such as:

  • Реализация HTTP-сервераAn HTTP server implementation
  • Компоненты ПО промежуточного слояMiddleware components
  • Ведение журналаLogging
  • Внедрение зависимостейDI
  • Параметр ConfigurationConfiguration

Основной причиной включения всех взаимозависимых ресурсов приложения в один объект является управление жизненным циклом: контроль запуска и корректного завершения работы приложения.The main reason for including all of the app's interdependent resources in one object is lifetime management: control over app startup and graceful shutdown.

Доступны два узла: веб-узел и универсальный узел.Two hosts are available: the Web Host and the Generic Host. В ASP.NET Core 2.x универсальный узел используется в сценариях, не связанных с Интернетом.In ASP.NET Core 2.x, the Generic Host is only for non-web scenarios.

Код для создания узла находится в Program.Main:The code to create a host is in Program.Main:

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

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

Метод CreateDefaultBuilder применяется для настройки узла с часто используемыми параметрами, например:The CreateDefaultBuilder method configures a host with commonly used options, such as the following:

  • Использование Kestrel в качестве веб-сервера и поддержка интеграции с IIS.Use Kestrel as the web server and enable IIS integration.
  • Загрузка конфигурации из файлов appsettings.json и appsettings.{имя среды}.json, переменных среды, аргументов командной строки и других источников.Load configuration from appsettings.json, appsettings.{Environment Name}.json, environment variables, command line arguments, and other configuration sources.
  • Отправка выходных данных журнала в поставщики служб консоли и отладки.Send logging output to the console and debug providers.

Для получения дополнительной информации см. Веб-узел ASP.NET Core.For more information, see Веб-узел ASP.NET Core.

Сценарии, не связанные с ИнтернетомNon-web scenarios

Универсальный узел позволяет приложениям других типов использовать перекрестные расширения платформ, такие как средства ведения журналов, внедрения зависимостей, настройки и управления жизненным циклом.The Generic Host allows other types of apps to use cross-cutting framework extensions, such as logging, dependency injection (DI), configuration, and app lifetime management. Дополнительные сведения см. в разделах Универсальный узел .NET и Фоновые задачи с размещенными службами в ASP.NET Core.For more information, see Универсальный узел .NET and Фоновые задачи с размещенными службами в ASP.NET Core.

СерверыServers

Приложение ASP.NET Core использует реализацию HTTP-сервера для приема HTTP-запросов.An ASP.NET Core app uses an HTTP server implementation to listen for HTTP requests. Сервер отправляет приложению запросы в виде набора функций запросов, объединенных в HttpContext.The server surfaces requests to the app as a set of request features composed into an HttpContext.

ASP.NET Core предоставляет следующие реализации серверов:ASP.NET Core provides the following server implementations:

  • Kestrel — это кроссплатформенный веб-сервер.Kestrel is a cross-platform web server. Он часто запускается в реконфигурации прокси-сервера с помощью IIS.Kestrel is often run in a reverse proxy configuration using IIS. Kestrel можно использовать в роли общедоступного пограничного сервера с прямым доступом из Интернета.Kestrel can be run as a public-facing edge server exposed directly to the Internet.
  • HTTP-сервер IIS — это сервер для Windows, который использует службы IIS.IIS HTTP Server is a server for windows that uses IIS. Он позволяет запускать приложение ASP.NET Core и службы IIS в одном процессе.With this server, the ASP.NET Core app and IIS run in the same process.
  • HTTP.sys — это сервер для Windows, который не используется со службами IIS.HTTP.sys is a server for Windows that isn't used with IIS.

ASP.NET Core предоставляет следующие реализации серверов:ASP.NET Core provides the following server implementations:

  • Kestrel — это кроссплатформенный веб-сервер.Kestrel is a cross-platform web server. Он часто запускается в реконфигурации прокси-сервера с помощью IIS.Kestrel is often run in a reverse proxy configuration using IIS. Kestrel можно использовать в роли общедоступного пограничного сервера с прямым доступом из Интернета.Kestrel can be run as a public-facing edge server exposed directly to the Internet.
  • HTTP.sys — это сервер для Windows, который не используется со службами IIS.HTTP.sys is a server for Windows that isn't used with IIS.

Для получения дополнительной информации см. Реализации веб-сервера в ASP.NET Core.For more information, see Реализации веб-сервера в ASP.NET Core.

Параметр ConfigurationConfiguration

ASP.NET Core предоставляет платформу конфигурации, которая получает параметры в виде пар "имя-значение" от упорядоченного набора поставщиков конфигурации.ASP.NET Core provides a configuration framework that gets settings as name-value pairs from an ordered set of configuration providers. Доступны встроенные поставщики конфигурации для различных источников, таких как файлы JSON, XML, переменные среды и аргументы командной строки.There are built-in configuration providers for a variety of sources, such as .json files, .xml files, environment variables, and command-line arguments. Кроме того, вы можете писать поставщики конфигурации сами.You can also write custom configuration providers.

Например, можно указать, что источником конфигурации являются файл appsettings.json и переменные среды.For example, you could specify that configuration comes from appsettings.json and environment variables. В этом случае при запросе значения ConnectionString платформа сначала выполнит поиск в файле appsettings.json.Then when the value of ConnectionString is requested, the framework looks first in the appsettings.json file. Если значение будет найдено не только в нем, но и в переменной среды, приоритет получит значение из переменной среды.If the value is found there but also in an environment variable, the value from the environment variable would take precedence.

Для управления конфиденциальными данными конфигурации, например паролями, ASP.NET Core предоставляет специальный инструмент Менеджер секретов.For managing confidential configuration data such as passwords, ASP.NET Core provides a Secret Manager tool. Для секретов в рабочей среде рекомендуется использовать Azure Key Vault.For production secrets, we recommend Azure Key Vault.

Для получения дополнительной информации см. Конфигурация в .NET Core.For more information, see Конфигурация в .NET Core.

ПараметрыOptions

Когда это возможно, ASP.NET Core следует шаблону параметров для хранения и получения значений конфигурации.Where possible, ASP.NET Core follows the options pattern for storing and retrieving configuration values. Шаблон параметров использует классы для представления групп связанных настроек.The options pattern uses classes to represent groups of related settings.

Например, следующий код задает параметры WebSockets:For example, the following code sets WebSockets options:

var options = new WebSocketOptions  
{  
   KeepAliveInterval = TimeSpan.FromSeconds(120),  
   ReceiveBufferSize = 4096
};  

app.UseWebSockets(options);

Для получения дополнительной информации см. Шаблон параметров в ASP.NET Core.For more information, see Шаблон параметров в ASP.NET Core.

СредыEnvironments

Среды выполнения, включая среду разработки, промежуточную и рабочую среды, являются ключевыми компонентами ASP.NET Core.Execution environments, such as Development, Staging, and Production, are a first-class notion in ASP.NET Core. Указать среду, в которой запускается приложение, можно с помощью переменной среды ASPNETCORE_ENVIRONMENT.You can specify the environment an app is running in by setting the ASPNETCORE_ENVIRONMENT environment variable. ASP.NET Core считывает переменную среды при запуске приложения и сохраняет ее значение в реализации IHostingEnvironment.ASP.NET Core reads that environment variable at app startup and stores the value in an IHostingEnvironment implementation. Объект среды можно получить в любом месте приложения при помощи внедрения зависимостей.The environment object is available anywhere in the app via DI.

В следующем примере кода из класса Startup показана настройка приложения для вывода подробных сведений об ошибках исключительно при запуске в среде разработки:The following sample code from the Startup class configures the app to provide detailed error information only when it runs in development:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();
    app.UseMvc();
}

Для получения дополнительной информации см. Использование нескольких сред в ASP.NET Core.For more information, see Использование нескольких сред в ASP.NET Core.

Ведение журналаLogging

ASP.NET Core поддерживает API ведения журналов, который работает с разными встроенными и сторонними поставщиками.ASP.NET Core supports a logging API that works with a variety of built-in and third-party logging providers. Доступны следующие поставщики:Available providers include the following:

  • КонсольConsole
  • ОтладкаDebug
  • Трассировка событий WindowsEvent Tracing on Windows
  • Журнал событий WindowsWindows Event Log
  • TraceSourceTraceSource
  • Служба приложений AzureAzure App Service
  • Azure Application InsightsAzure Application Insights

Записи в журналы можно вносить в любом месте кода приложения. Для этого нужно получить объект ILogger из внедрения зависимостей и вызвать методы ведения журналов.Write logs from anywhere in an app's code by getting an ILogger object from DI and calling log methods.

Ниже приведен пример кода, где используется объект ILogger. В коде выделены строки внедрения конструктора и вызова методов ведения журналов.Here's sample code that uses an ILogger object, with constructor injection and the logging method calls highlighted.

public class TodoController : ControllerBase
{
    private readonly ILogger _logger;

    public TodoController(ILogger<TodoController> logger)
    {
        _logger = logger;
    }

    [HttpGet("{id}", Name = "GetTodo")]
    public ActionResult<TodoItem> GetById(string id)
    {
        _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
        // Item lookup code removed.
        if (item == null)
        {
            _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
            return NotFound();
        }
        return item;
    }
}

Интерфейс ILogger позволяет передавать в поставщик ведения журналов любое количество полей.The ILogger interface lets you pass any number of fields to the logging provider. Как правило, поля используются для создания строки сообщения, но поставщик также может отправлять их в хранилище данных в виде отдельных полей.The fields are commonly used to construct a message string, but the provider can also send them as separate fields to a data store. Благодаря этому поставщики могут реализовывать семантическое (структурированное) ведение журналов.This feature makes it possible for logging providers to implement semantic logging, also known as structured logging.

Для получения дополнительной информации см. Ведение журнала в .NET Core и ASP.NET Core.For more information, see Ведение журнала в .NET Core и ASP.NET Core.

МаршрутизацияRouting

Маршрут — это шаблон URL-адреса, сопоставляемый с обработчиком.A route is a URL pattern that is mapped to a handler. Обычно обработчик представляет собой страницу Razor, метод действия в контроллере MVC или ПО промежуточного слоя.The handler is typically a Razor page, an action method in an MVC controller, or a middleware. Маршрутизация ASP.NET Core позволяет контролировать URL-адреса, используемые приложением.ASP.NET Core routing gives you control over the URLs used by your app.

Для получения дополнительной информации см. Маршрутизация в ASP.NET Core.For more information, see Маршрутизация в ASP.NET Core.

Обработка ошибокError handling

ASP.NET Core содержит встроенные функции обработки ошибок, такие как:ASP.NET Core has built-in features for handling errors, such as:

  • Страница исключений для разработчикаA developer exception page
  • Настраиваемые страницы ошибокCustom error pages
  • Статические страницы с кодами состоянияStatic status code pages
  • Обработка исключений при запускеStartup exception handling

Для получения дополнительной информации см. Обработка ошибок в ASP.NET Core.For more information, see Обработка ошибок в ASP.NET Core.

Создание HTTP-запросовMake HTTP requests

ASP.NET Core включает реализацию интерфейса IHttpClientFactory для создания экземпляров HttpClient.An implementation of IHttpClientFactory is available for creating HttpClient instances. Фабрика:The factory:

  • Центральное расположение для именования и настройки логических экземпляров HttpClient.Provides a central location for naming and configuring logical HttpClient instances. Например, можно зарегистрировать и использовать клиент github для доступа к GitHub.For example, a github client can be registered and configured to access GitHub. Можно зарегистрировать клиент по умолчанию для других целей.A default client can be registered for other purposes.
  • Поддержка регистрации и связывания в цепочки множества делегирующих обработчиков для создания конвейера ПО промежуточного слоя под исходящие запросы.Supports registration and chaining of multiple delegating handlers to build an outgoing request middleware pipeline. Этот шаблон похож на входящий конвейер ПО промежуточного слоя в ASP.NET Core.This pattern is similar to the inbound middleware pipeline in ASP.NET Core. Шаблон предоставляет механизм управления сквозной функциональностью HTTP-запросов, включая кэширование, обработку ошибок, сериализацию и ведение журнала.The pattern provides a mechanism to manage cross-cutting concerns around HTTP requests, including caching, error handling, serialization, and logging.
  • Интеграция с Polly — популярной сторонней библиотекой для обработки временных сбоев.Integrates with Polly, a popular third-party library for transient fault handling.
  • Управление созданием пулов и временем существования базовых экземпляров HttpClientHandler с целью избежать обычных проблем с DNS, которые возникают при управлении временем существования HttpClient вручную.Manages the pooling and lifetime of underlying HttpClientHandler instances to avoid common DNS problems that occur when manually managing HttpClient lifetimes.
  • Настройка параметров ведения журнала (через ILogger) для всех запросов, отправленных через клиентов, созданных фабрикой.Adds a configurable logging experience (via ILogger) for all requests sent through clients created by the factory.

Для получения дополнительной информации см. Выполнения HTTP-запросов с помощью IHttpClientFactory в ASP.NET Core.For more information, see Выполнения HTTP-запросов с помощью IHttpClientFactory в ASP.NET Core.

Корневой каталог содержимогоContent root

Корневой каталог содержимого — это базовый путь к таким элементам:The content root is the base path to the:

  • Исполняемый файл, в котором размещено приложение (EXE).Executable hosting the app (.exe).
  • Скомпилированные сборки, составляющие приложение (DLL).Compiled assemblies that make up the app (.dll).
  • Файлы содержимого, не относящиеся к коду, используемые приложением, например:Non-code content files used by the app, such as:
    • Файлы Razor (CSHTML, RAZOR).Razor files (.cshtml, .razor)
    • Файлы конфигурации (JSON, XML).Configuration files (.json, .xml)
    • Файлы данных (DB).Data files (.db)
  • Корневой веб-каталог, обычно опубликованная папка wwwroot.Web root, typically the published wwwroot folder.

Во время разработки:During development:

  • Корень содержимого по умолчанию сбрасывается до корневого каталога проекта.The content root defaults to the project's root directory.
  • Корневой каталог проекта используется для создания:The project's root directory is used to create the:
    • пути к файлам содержимого, не являющихся кодом приложения, в корневом каталоге проекта;Path to the app's non-code content files in the project's root directory.
    • корневого веб-каталога, обычно папка wwwroot в корневом каталоге проекта.Web root, typically the wwwroot folder in the project's root directory.

Альтернативный корневой путь к содержимому может быть указан при создании узла.An alternative content root path can be specified when building the host. Для получения дополнительной информации см. Веб-узел ASP.NET Core.For more information, see Веб-узел ASP.NET Core.

Корневой веб-узелWeb root

Корневой веб-каталог — это базовый путь к общедоступным, не кодовым файлам статических ресурсов, например:The web root is the base path to public, non-code, static resource files, such as:

  • Таблицы стилей (CSS).Stylesheets (.css)
  • JavaScript (JS).JavaScript (.js)
  • Изображения (PNG, JPG).Images (.png, .jpg)

Статические файлы обслуживаются по умолчанию только в корневом веб-каталоге (и подкаталогах).Static files are only served by default from the web root directory (and sub-directories).

По умолчанию используется путь {корневой каталог содержимого}/wwwroot. Альтернативное расположение можно задать при создании узла.The web root path defaults to {content root}/wwwroot, but a different web root can be specified when building the host. Дополнительные сведения см. в разделе Корневой веб-каталог.For more information, see Web root.

Запретите публикацию файлов в wwwroot с помощью элемента проекта <Content> в файле проекта.Prevent publishing files in wwwroot with the <Content> project item in the project file. В следующем примере запрещается публикация содержимого в каталоге wwwroot/local и подкаталогах:The following example prevents publishing content in the wwwroot/local directory and sub-directories:

<ItemGroup>
  <Content Update="wwwroot\local\**\*.*" CopyToPublishDirectory="Never" />
</ItemGroup>

Для указания на корневой каталог файлов Razor (CSHTML) используется символ тильды и косой черты ~/.In Razor (.cshtml) files, the tilde-slash (~/) points to the web root. Путь, начинающийся с ~/, называется виртуальным путем.A path beginning with ~/ is referred to as a virtual path.

Для получения дополнительной информации см. Статические файлы в ASP.NET Core.For more information, see Статические файлы в ASP.NET Core.