Поделиться через

ASP.NET Core, основы, обзор

Note

Это не последняя версия этой статьи. В текущем выпуске см . версию .NET 9 этой статьи.

Warning

Эта версия ASP.NET Core больше не поддерживается. Дополнительные сведения см. в политике поддержки .NET и .NET Core. В текущем выпуске см . версию .NET 9 этой статьи.

Important

Эта информация относится к предварительному выпуску продукта, который может быть существенно изменен до его коммерческого выпуска. Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых, относительно приведенных здесь сведений.

В текущем выпуске см . версию .NET 9 этой статьи.

В этой статье представлены основные этапы создания приложений ASP.NET Core, включая внедрение зависимостей (DI), конфигурацию, ПО промежуточного слоя и многое другое.

Рекомендации по основам Blazor, которые дополняют или заменяют инструкции, приведенные в этой статье, см. в разделе ASP.NET Core Blazor основы.

Program.cs

Приложения ASP.NET Core, созданные на основе веб-шаблонов, содержат код запуска приложения в файле Program.cs. В файле Program.cs:

  • Настраиваются службы, необходимые приложению.
  • The app's request handling pipeline is defined as a series of middleware components.

Следующий код запуска приложения поддерживает несколько типов приложений:

using WebAll.Components;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseAuthorization();

app.MapGet("/hi", () => "Hello!");

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.UseAntiforgery();

app.Run();

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

ASP.NET Core обладает встроенным внедрением зависимостей (DI), которое делает настроенные службы доступными во всем приложении. Services are added to the DI container with WebApplicationBuilder.Services, builder.Services in the preceding code. When the WebApplicationBuilder is instantiated, many framework-provided services are added automatically. builder — это WebApplicationBuilder в приведенном ниже коде:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

В приведенном выше коде CreateBuilder добавляет конфигурацию, ведение журнала и многие другие службы в контейнер DI. Платформа DI предоставляет экземпляр запрошенной службы во время выполнения.

Следующий код добавляет настраиваемые компоненты DbContext и Blazor в контейнер DI:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContextFactory<BlazorWebAppMoviesContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("MoviesContext") 
        ?? throw new InvalidOperationException("Connection string not found.")));

builder.Services.AddQuickGridEntityFrameworkAdapter();

builder.Services.AddDatabaseDeveloperPageExceptionFilter();

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

var app = builder.Build();

В Blazor Web Appуслуги часто разрешаются из DI во время выполнения с помощью директивы @inject в компоненте Razor, как показано в следующем примере:

@page "/movies"
@rendermode InteractiveServer
@using Microsoft.EntityFrameworkCore
@using Microsoft.AspNetCore.Components.QuickGrid
@using BlazorWebAppMovies.Models
@using BlazorWebAppMovies.Data
@implements IAsyncDisposable
@inject IDbContextFactory<BlazorWebAppMovies.Data.BlazorWebAppMoviesContext> DbFactory

<PageTitle>Index</PageTitle>

<h1>Index</h1>

<div>
    <input type="search" @bind="titleFilter" @bind:event="oninput" />
</div>

<p>
    <a href="movies/create">Create New</a>
</p>

<QuickGrid Class="table" Items="FilteredMovies" Pagination="pagination">
    <PropertyColumn Property="movie => movie.Title" Sortable="true" />
    <PropertyColumn Property="movie => movie.ReleaseDate" Title="Release Date" />
    <PropertyColumn Property="movie => movie.Genre" />
    <PropertyColumn Property="movie => movie.Price" />
    <PropertyColumn Property="movie => movie.Rating" />

    <TemplateColumn Context="movie">
        <a href="@($"movies/edit?id={movie.Id}")">Edit</a> |
        <a href="@($"movies/details?id={movie.Id}")">Details</a> |
        <a href="@($"movies/delete?id={movie.Id}")">Delete</a>
    </TemplateColumn>
</QuickGrid>

<Paginator State="pagination" />

@code {
    private BlazorWebAppMoviesContext context = default!;
    private PaginationState pagination = new PaginationState { ItemsPerPage = 10 };
    private string titleFilter = string.Empty;

    private IQueryable<Movie> FilteredMovies =>
        context.Movie.Where(m => m.Title!.Contains(titleFilter));

    protected override void OnInitialized()
    {
        context = DbFactory.CreateDbContext();
    }

    public async ValueTask DisposeAsync() => await context.DisposeAsync();
}

В приведенном выше коде:

  • Используется директива @inject.
  • Служба обрабатывается методом OnInitialized и назначается переменной context.
  • Служба context создает список FilteredMovie.

Другой способ разрешения службы из DI — это конструкторная инъекция. Следующий код Razor Pages использует внедрение конструктора для разрешения контекста базы данных и логгера из DI.

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;
    private readonly ILogger<IndexModel> _logger;

    public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
    {
        _context = context;
        _logger = logger;
    }

    public IList<Movie> Movie { get;set; }

    public async Task OnGetAsync()
    {
        _logger.LogInformation("IndexModel OnGetAsync.");
        Movie = await _context.Movie.ToListAsync();
    }
}

В приведенном выше коде конструктор IndexModel принимает параметр типа RazorPagesMovieContext, который преобразуется во время выполнения в переменную _context. Объект контекста используется для создания списка фильмов в методе OnGetAsync.

Дополнительные сведения см. в статье ASP.NET Внедрение Blazor зависимостей core и внедрение зависимостей в ASP.NET Core.

Middleware

Конвейер обработки запросов состоит из ряда компонентов ПО промежуточного слоя. Каждый компонент выполняет операции в HttpContext, а затем либо вызывает следующий компонент в конвейере, либо завершает запрос.

По принятому соглашению компонент ПО промежуточного слоя добавляется в конвейер вызовом метода расширения Use{Feature}. Использование методов с именем Use{Feature} для добавления ПО промежуточного слоя в приложение показано в следующем коде:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContextFactory<BlazorWebAppMoviesContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("MoviesContext") 
        ?? throw new InvalidOperationException("Connection string not found.")));

builder.Services.AddQuickGridEntityFrameworkAdapter();

builder.Services.AddDatabaseDeveloperPageExceptionFilter();

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

var app = builder.Build();

using (var scope = app.Services.CreateScope())
{
    var services = scope.ServiceProvider;

    SeedData.Initialize(services);
}

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    app.UseHsts();
    app.UseMigrationsEndPoint();
}
app.UseHttpsRedirection();

app.UseAntiforgery();

app.MapStaticAssets();
app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.Run();

Дополнительные сведения см. в статье ПО промежуточного слоя ASP.NET Core.

Host

On startup, an ASP.NET Core app builds a host. Узел инкапсулирует все ресурсы приложения:

  • Реализация HTTP-сервера
  • Middleware components
  • Logging
  • Службы внедрения зависимостей
  • Configuration

Существует три разных узла, способных запускать приложение ASP.NET Core:

Рекомендуется использовать типы WebApplication и WebApplicationBuilder ASP.NET Core, поскольку они применяются во всех шаблонах ASP.NET Core. WebApplication работает аналогично универсальному узлу .NET и предоставляет множество одинаковых интерфейсов, но требует меньше обратных вызовов для настройки. Ядро ASP.NET WebHost доступно только для обратной совместимости.

В следующем примере создается экземпляр WebApplication и присваивается переменной с именем app.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContextFactory<BlazorWebAppMoviesContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("MoviesContext") 
        ?? throw new InvalidOperationException("Connection string not found.")));

builder.Services.AddQuickGridEntityFrameworkAdapter();

builder.Services.AddDatabaseDeveloperPageExceptionFilter();

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

var app = builder.Build();

The WebApplicationBuilder.Build method configures a host with a set of default options, such as:

  • Используйте Kestrel в качестве веб-сервера и включите интеграцию IIS.
  • Load configuration from appsettings.json, environment variables, command line arguments, and other configuration sources.
  • Отправка выходных данных журнала в поставщики служб консоли и отладки.

Non-web scenarios

Универсальный узел позволяет другим типам приложений использовать универсальные расширения платформы, такие как логирование, внедрение зависимостей (DI), настройка и управление временем существования приложений. Дополнительные сведения см. в статье Универсальный узел .NET в ASP.NET Core и Фоновые задачи с размещенными службами в ASP.NET Core.

Servers

Приложение ASP.NET Core использует реализацию HTTP-сервера для приема HTTP-запросов. The server surfaces requests to the app as a set of request features composed into an HttpContext.

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

  • Kestrel представляет собой кроссплатформенный веб-сервер. Kestrel is often run in a reverse proxy configuration using IIS. В ASP.NET Core 2.0 или более поздних версиях Kestrel может быть запущен как общедоступный пограничный сервер, напрямую подключенный к Интернету.
  • HTTP-сервер IIS — это сервер для Windows, который использует службы IIS. Он позволяет запускать приложение ASP.NET Core и службы IIS в одном процессе.
  • HTTP.sys is a server for Windows that isn't used with IIS.

Дополнительные сведения см. в статье Реализация веб-сервера в ASP.NET Core.

Configuration

ASP.NET Core provides a configuration framework that gets settings as name-value pairs from an ordered set of configuration providers. Встроенные поставщики конфигурации доступны для различных источников, таких как .json файлы, файлы, .xml переменные среды и аргументы командной строки. Для поддержки других источников можно создать настраиваемые поставщики конфигурации.

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

For managing confidential configuration data such as passwords in the development environment, .NET Core provides the Secret Manager. Для секретов в рабочей среде рекомендуется использовать Azure Key Vault.

Дополнительные сведения см. в разделе Конфигурация в ASP.NET Core.

Environments

Среды выполнения, такие как Development, Staging и Production, доступны в ASP.NET Core. Указать среду, в которой запускается приложение, можно с помощью переменной среды ASPNETCORE_ENVIRONMENT. ASP.NET Core считывает переменную среды при запуске приложения и сохраняет ее значение в реализации IWebHostEnvironment. Эта реализация доступна в любом месте приложения посредством внедрения зависимостей.

В следующем примере выполняется настройка обработчика исключений и ПО промежуточного слоя протокола HTTP Strict Transport Security Protocol (HSTS) при выполнении НЕ в среде Development:

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    app.UseHsts();
    app.UseMigrationsEndPoint();
}

Дополнительные сведения см. в статье Использование нескольких сред в ASP.NET Core.

Logging

ASP.NET Core поддерживает API ведения журнала, который совместим со множеством встроенных и сторонних соответствующих решений. Доступные следующие поставщики:

  • Console
  • Debug
  • Трассировка событий Windows
  • Журнал событий Windows
  • TraceSource
  • Служба приложений Azure
  • Azure Application Insights

Для создания журналов необходимо разрешить службу ILogger<TCategoryName> из системы внедрения зависимостей (DI) и вызвать методы ведения журналов, такие как LogInformation. В следующем примере показано, как получить и использовать средство ведения журнала в файле .razor для страницы в Blazor Web App. Объект средства ведения журнала и поставщик консоли для него хранятся в контейнере DI автоматически при вызове метода CreateBuilder в Program.cs.

@page "/weather"
@attribute [StreamRendering]
@inject ILogger<Weather> Logger

<PageTitle>Weather</PageTitle>

<h1>Weather</h1>

<p>This component demonstrates showing data and logging.</p>

@if (forecasts == null)
{
    <p><em>Loading...</em></p>
}
else
{
    <table class="table">
        <thead>
            <tr>
                <th>Date</th>
                <th aria-label="Temperature in Celsius">Temp. (C)</th>
                <th aria-label="Temperature in Fahrenheit">Temp. (F)</th>
                <th>Summary</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var forecast in forecasts)
            {
                <tr>
                    <td>@forecast.Date.ToShortDateString()</td>
                    <td>@forecast.TemperatureC</td>
                    <td>@forecast.TemperatureF</td>
                    <td>@forecast.Summary</td>
                </tr>
            }
        </tbody>
    </table>
}

@code {
    private WeatherForecast[]? forecasts;

    protected override async Task OnInitializedAsync()
    {
        // Simulate asynchronous loading to demonstrate streaming rendering
       
        await Task.Delay(500);

        Logger.LogInformation("This is an information log message.");
        Logger.LogWarning("This is a warning log message.");
        Logger.LogError("This is an error log message.");

        var startDate = DateOnly.FromDateTime(DateTime.Now);
        var summaries = new[] { "Freezing", "Bracing", "Chilly",
            "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" };
        forecasts = Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = startDate.AddDays(index),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = summaries[Random.Shared.Next(summaries.Length)]
        }).ToArray();
    }

    private class WeatherForecast
    {
        public DateOnly Date { get; set; }
        public int TemperatureC { get; set; }
        public string? Summary { get; set; }
        public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
    }
}

Дополнительные сведения см. в разделе Ведение журнала в .NET Core и ASP.NET Core.

Routing

Маршрутизация в ASP.NET Core — это механизм, который сопоставляет входящие запросы с определенными конечными точками в приложении. Он позволяет определять шаблоны URL-адресов, соответствующие различным компонентам, таким как компоненты Blazor, Razor страницы, действия контроллера MVC или ПО промежуточного слоя.

Метод UseRouting(IApplicationBuilder) добавляет промежуточное программное обеспечение маршрутизации в конвейер запросов. Это ПО промежуточного слоя обрабатывает сведения о маршрутизации и определяет соответствующую конечную точку для каждого запроса. Вам не нужно явно вызывать UseRouting, если только вы не хотите изменить порядок обработки промежуточного ПО.

Дополнительные сведения см. в статье Маршрутизация в ASP.NET Core и Маршрутизация и навигация в ASP.NET Core Blazor.

Error handling

ASP.NET Core содержит встроенные функции обработки ошибок, такие как:

  • Страница исключений для разработчика
  • Пользовательские страницы ошибок
  • Статические страницы с кодами состояния
  • Обработка исключений при запуске

Дополнительные сведения см. в статье Обработка ошибок в ASP.NET Core.

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

ASP.NET Core включает реализацию интерфейса IHttpClientFactory для создания экземпляров HttpClient. The factory:

  • Центральное расположение для именования и настройки логических экземпляров HttpClient. For example, register and configure a github client for accessing GitHub. Можно зарегистрировать и настроить клиент по умолчанию для других целей.
  • Поддержка регистрации и связывания в цепочки множества делегирующих обработчиков для создания конвейера ПО промежуточного слоя под исходящие запросы. Этот шаблон похож на входящий конвейер ПО промежуточного слоя для ASP.NET Core. Шаблон предоставляет механизм управления сквозной функциональностью HTTP-запросов, включая кэширование, обработку ошибок, сериализацию и ведение журнала.
  • Integrates with Polly, a popular third-party library for transient fault handling.
  • Управление созданием пулов и временем существования базовых экземпляров HttpClientHandler с целью избежать обычных проблем с DNS, которые возникают при управлении временем существования HttpClient вручную.
  • Настройка параметров ведения журнала (через ILogger) для всех запросов, отправленных через клиентов, созданных фабрикой.

Дополнительные сведения см. в статье Выполнение HTTP-запросов с помощью IHttpClientFactory в ASP.NET Core.

Content root

Корневой каталог содержимого — это базовый путь к следующим элементам:

  • The executable hosting the app (.exe).
  • Compiled assemblies that make up the app (.dll).
  • Файлы содержимого, используемые приложением, например:
    • Файлы Razor (.cshtml, .razor)
    • Файлы конфигурации (.json, .xml)
    • Файлы данных (.db)
  • The Web root, typically the wwwroot folder.

Во время развертывания корень содержимого по умолчанию сбрасывается до корневого каталога проекта. This directory is also the base path for both the app's content files and the web root. Альтернативный корневой путь к содержимому может быть указан при создании узла. For more information, see Content root.

Web root

Корневой веб-каталог — это базовый путь к общедоступным файлам статических ресурсов, например:

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

По умолчанию статические файлы обслуживаются только в корневом веб-каталоге и его подкаталогах. Корневой путь веб-сайта по умолчанию имеет {CONTENT ROOT}/wwwrootзначение , где {CONTENT ROOT} заполнитель является корнем содержимого. Альтернативное расположение корневого веб-каталога можно указать при создании узла. For more information, see Web root.

Запретить публикацию <Content> файлов в wwwroot элементе проекта в файле проекта. Следующий пример запрещает публикацию содержимого в wwwroot/local и его вложенных каталогах:

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

В файлах Razor.cshtml~/ указывает на корневой каталог. A path beginning with ~/ is referred to as a virtual path.

Подробные сведения см. в статье Статические файлы в ASP.NET Core.

Additional resources

В этой статье представлены основные этапы создания приложений ASP.NET Core, включая внедрение зависимостей (DI), конфигурацию, ПО промежуточного слоя и многое другое.

Program.cs

Приложения ASP.NET Core, созданные на основе веб-шаблонов, содержат код запуска приложения в файле Program.cs. В файле Program.cs:

  • Настраиваются службы, необходимые приложению.
  • The app's request handling pipeline is defined as a series of middleware components.

Следующий код запуска приложения поддерживает:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseAuthorization();

app.MapGet("/hi", () => "Hello!");

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

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

ASP.NET Core включает внедрение зависимостей, позволяющее обращаться к настроенным службам в рамках приложения. Services are added to the DI container with WebApplicationBuilder.Services, builder.Services in the preceding code. When the WebApplicationBuilder is instantiated, many framework-provided services are added. builder — это WebApplicationBuilder в приведенном ниже коде:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

В приведенном выше код builder добавляет в контейнер внедрения зависимостей конфигурацию, ведение журнала и множество других служб.

Следующий код добавляет в контейнер внедрения зависимостей Razor Pages, контроллеры MVC с представлениями и настраиваемый DbContext:

using Microsoft.EntityFrameworkCore;
using RazorPagesMovie.Data;
var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

builder.Services.AddDbContext<RazorPagesMovieContext>(options =>
   options.UseSqlServer(builder.Configuration.GetConnectionString("RPMovieContext")));

var app = builder.Build();

Как правило, службы разрешаются из системы внедрения зависимостей с помощью внедрения конструктора. Платформа внедрения зависимостей предоставляет экземпляр этой службы во время выполнения.

В следующем коде используется внедрение конструктора для решения контекста базы данных и средство ведения журнала из внедрения зависимостей:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;
    private readonly ILogger<IndexModel> _logger;

    public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
    {
        _context = context;
        _logger = logger;
    }

    public IList<Movie> Movie { get;set; }

    public async Task OnGetAsync()
    {
        _logger.LogInformation("IndexModel OnGetAsync.");
        Movie = await _context.Movie.ToListAsync();
    }
}

Middleware

Конвейер обработки запросов состоит из ряда компонентов ПО промежуточного слоя. Каждый компонент выполняет операции в HttpContext, а затем либо вызывает следующий компонент в конвейере, либо завершает запрос.

По принятому соглашению компонент ПО промежуточного слоя добавляется в конвейер вызовом метода расширения Use{Feature}. ПО промежуточного слоя, добавленное в приложение, выделено в следующем коде:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseAuthorization();

app.MapGet("/hi", () => "Hello!");

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

Дополнительные сведения см. в статье ПО промежуточного слоя ASP.NET Core.

Host

On startup, an ASP.NET Core app builds a host. Узел инкапсулирует все ресурсы приложения:

  • Реализация HTTP-сервера
  • Middleware components
  • Logging
  • Службы внедрения зависимостей
  • Configuration

Существует три разных узла, способных запускать приложение ASP.NET Core:

Рекомендуется использовать ASP.NET Core WebApplication и WebApplicationBuilder типы во всех шаблонах ASP.NET Core. WebApplication выполняется аналогично универсальному узлу .NET и предоставляет множество одинаковых интерфейсов, но требует меньше обратных вызовов для настройки. Ядро ASP.NET WebHost доступно только для обратной совместимости.

В следующем примере создается экземпляр :WebApplication

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

The WebApplicationBuilder.Build method configures a host with a set of default options, such as:

  • Используйте Kestrel в качестве веб-сервера и включите интеграцию IIS.
  • Load configuration from appsettings.json, environment variables, command line arguments, and other configuration sources.
  • Отправка выходных данных журнала в поставщики служб консоли и отладки.

Non-web scenarios

Универсальный узел позволяет приложениям других типов использовать перекрестные расширения платформ, такие как средства ведения журналов, внедрения зависимостей, настройки и управления жизненным циклом. Дополнительные сведения см. в статье Универсальный узел .NET в ASP.NET Core и Фоновые задачи с размещенными службами в ASP.NET Core.

Servers

Приложение ASP.NET Core использует реализацию HTTP-сервера для приема HTTP-запросов. The server surfaces requests to the app as a set of request features composed into an HttpContext.

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

  • Kestrel представляет собой кроссплатформенный веб-сервер. Kestrel is often run in a reverse proxy configuration using IIS. В ASP.NET Core 2.0 или более поздних версиях Kestrel может быть запущен как общедоступный пограничный сервер, напрямую подключенный к Интернету.
  • HTTP-сервер IIS — это сервер для Windows, который использует службы IIS. Он позволяет запускать приложение ASP.NET Core и службы IIS в одном процессе.
  • HTTP.sys is a server for Windows that isn't used with IIS.

Дополнительные сведения см. в статье Реализация веб-сервера в ASP.NET Core.

Configuration

ASP.NET Core provides a configuration framework that gets settings as name-value pairs from an ordered set of configuration providers. Встроенные поставщики конфигурации доступны для различных источников, таких как .json файлы, файлы, .xml переменные среды и аргументы командной строки. Для поддержки других источников можно создать настраиваемые поставщики конфигурации.

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

For managing confidential configuration data such as passwords, .NET Core provides the Secret Manager. Для секретов в рабочей среде рекомендуется использовать Azure Key Vault.

Дополнительные сведения см. в разделе Конфигурация в ASP.NET Core.

Environments

Среды выполнения, такие как Development, Staging и Production, доступны в ASP.NET Core. Указать среду, в которой запускается приложение, можно с помощью переменной среды ASPNETCORE_ENVIRONMENT. ASP.NET Core считывает переменную среды при запуске приложения и сохраняет ее значение в реализации IWebHostEnvironment. Эта реализация доступна в любом месте приложения посредством внедрения зависимостей.

В следующем примере выполняется настройка обработчика исключений и ПО промежуточного слоя протокола HTTP Strict Transport Security Protocol (HSTS) при выполнении НЕ в среде Development:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseAuthorization();

app.MapGet("/hi", () => "Hello!");

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

Дополнительные сведения см. в статье Использование нескольких сред в ASP.NET Core.

Logging

ASP.NET Core поддерживает API ведения журнала, который совместим со множеством встроенных и сторонних соответствующих решений. Доступные следующие поставщики:

  • Console
  • Debug
  • Трассировка событий Windows
  • Журнал событий Windows
  • TraceSource
  • Служба приложений Azure
  • Azure Application Insights

Для создания журналов необходимо разрешить службу ILogger<TCategoryName> из системы внедрения зависимостей (DI) и вызвать методы ведения журналов, такие как LogInformation. For example:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;
    private readonly ILogger<IndexModel> _logger;

    public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
    {
        _context = context;
        _logger = logger;
    }

    public IList<Movie> Movie { get;set; }

    public async Task OnGetAsync()
    {
        _logger.LogInformation("IndexModel OnGetAsync.");
        Movie = await _context.Movie.ToListAsync();
    }
}

Дополнительные сведения см. в разделе Ведение журнала в .NET Core и ASP.NET Core.

Routing

A route is a URL pattern that is mapped to a handler. Обычно обработчик представляет собой страницу Razor, метод действия в контроллере MVC или ПО промежуточного слоя. Маршрутизация ASP.NET Core позволяет контролировать URL-адреса, используемые приложением.

Следующий код, созданный шаблоном веб-приложения ASP.NET Core, вызывает UseRouting:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Подробные сведения см. в статье Маршрутизация в ASP.NET Core.

Error handling

ASP.NET Core содержит встроенные функции обработки ошибок, такие как:

  • Страница исключений для разработчика
  • Пользовательские страницы ошибок
  • Статические страницы с кодами состояния
  • Обработка исключений при запуске

Дополнительные сведения см. в статье Обработка ошибок в ASP.NET Core.

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

ASP.NET Core включает реализацию интерфейса IHttpClientFactory для создания экземпляров HttpClient. The factory:

  • Центральное расположение для именования и настройки логических экземпляров HttpClient. For example, register and configure a github client for accessing GitHub. Можно зарегистрировать и настроить клиент по умолчанию для других целей.
  • Поддержка регистрации и связывания в цепочки множества делегирующих обработчиков для создания конвейера ПО промежуточного слоя под исходящие запросы. Этот шаблон похож на входящий конвейер ПО промежуточного слоя для ASP.NET Core. Шаблон предоставляет механизм управления сквозной функциональностью HTTP-запросов, включая кэширование, обработку ошибок, сериализацию и ведение журнала.
  • Integrates with Polly, a popular third-party library for transient fault handling.
  • Управление созданием пулов и временем существования базовых экземпляров HttpClientHandler с целью избежать обычных проблем с DNS, которые возникают при управлении временем существования HttpClient вручную.
  • Настройка параметров ведения журнала (через ILogger) для всех запросов, отправленных через клиентов, созданных фабрикой.

Дополнительные сведения см. в статье Выполнение HTTP-запросов с помощью IHttpClientFactory в ASP.NET Core.

Content root

Корневой каталог содержимого — это базовый путь к следующим элементам:

  • The executable hosting the app (.exe).
  • Compiled assemblies that make up the app (.dll).
  • Файлы содержимого, используемые приложением, например:
    • Файлы Razor (.cshtml, .razor)
    • Файлы конфигурации (.json, .xml)
    • Файлы данных (.db)
  • The Web root, typically the wwwroot folder.

Во время развертывания корень содержимого по умолчанию сбрасывается до корневого каталога проекта. This directory is also the base path for both the app's content files and the Web root. Альтернативный корневой путь к содержимому может быть указан при создании узла. For more information, see Content root.

Web root

Корневой веб-каталог — это базовый путь к общедоступным файлам статических ресурсов, например:

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

По умолчанию статические файлы обслуживаются только в корневом веб-каталоге и его подкаталогах. The web root path defaults to {content root}/wwwroot. Альтернативное расположение корневого веб-каталога можно указать при создании узла. For more information, see Web root.

Prevent publishing files in wwwroot with the <Content> project item in the project file. The following example prevents publishing content in wwwroot/local and its sub-directories:

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

В файлах Razor.cshtml~/ указывает на корневой каталог. A path beginning with ~/ is referred to as a virtual path.

Подробные сведения см. в статье Статические файлы в ASP.NET Core.

Additional resources

В этой статье представлены основные этапы создания приложений ASP.NET Core, включая внедрение зависимостей (DI), конфигурацию, ПО промежуточного слоя и многое другое.

Класс Startup

В классе Startup делается следующее.

  • Настраиваются службы, необходимые приложению.
  • Конвейер обработки запросов приложения определен как ряд компонентов ПО промежуточного слоя.

Пример класса Startup:

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.

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

ASP.NET Core включает встроенную платформу внедрения зависимостей, позволяющую обращаться к настроенным службам в рамках приложения. Например, службой является компонент ведения журнала.

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();
}

Как правило, службы разрешаются из системы внедрения зависимостей с помощью внедрения конструктора. При внедрении конструктора класс объявляет параметр конструктора, который может быть требуемым типом или интерфейсом. Платформа внедрения зависимостей предоставляет экземпляр этой службы во время выполнения.

В следующем примере показано использование внедрения конструктора для разрешения RazorPagesMovieContext из системы внедрения зависимостей.

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.

Дополнительные сведения см. в статье Внедрение зависимостей в ASP.NET Core.

Middleware

Конвейер обработки запросов состоит из ряда компонентов ПО промежуточного слоя. Каждый компонент выполняет операции в HttpContext, а затем либо вызывает следующий компонент в конвейере, либо завершает запрос.

По принятому соглашению компонент ПО промежуточного слоя добавляется в конвейер вызовом метода расширения Use... в методе Startup.Configure. Например, чтобы включить отрисовку статических файлов, вызовите UseStaticFiles.

В следующем примере показана настройка конвейера обработки запросов.

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

    app.UseRouting();

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

ASP.NET Core содержит большой набор встроенного ПО промежуточного слоя. Кроме того, можно создать пользовательские компоненты ПО промежуточного слоя.

Дополнительные сведения см. в статье ПО промежуточного слоя ASP.NET Core.

Host

On startup, an ASP.NET Core app builds a host. Узел инкапсулирует все ресурсы приложения:

  • Реализация HTTP-сервера
  • Middleware components
  • Logging
  • Службы внедрения зависимостей
  • Configuration

Существует два различных узла:

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

Рекомендуется использовать универсальный узел .NET. Веб-узел ASP.NET Core доступен только для обеспечения обратной совместимости.

В следующем примере показано создание универсального узла .NET.

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 применяются для настройки узла с набором параметров по умолчанию, например:

  • Используйте Kestrel в качестве веб-сервера и включите интеграцию IIS.
  • Загрузка конфигурации из appsettings.json, appsettings.{Environment}.json, переменных среды, аргументов командной строки и других источников конфигураций.
  • Отправка выходных данных журнала в поставщики служб консоли и отладки.

Дополнительные сведения см. в статье Универсальный узел .NET в ASP.NET Core.

Non-web scenarios

Универсальный узел позволяет приложениям других типов использовать перекрестные расширения платформ, такие как средства ведения журналов, внедрения зависимостей, настройки и управления жизненным циклом. Дополнительные сведения см. в статье Универсальный узел .NET в ASP.NET Core и Фоновые задачи с размещенными службами в ASP.NET Core.

Servers

Приложение ASP.NET Core использует реализацию HTTP-сервера для приема HTTP-запросов. The server surfaces requests to the app as a set of request features composed into an HttpContext.

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

  • Kestrel представляет собой кроссплатформенный веб-сервер. Kestrel is often run in a reverse proxy configuration using IIS. В ASP.NET Core 2.0 или более поздних версиях Kestrel может быть запущен как общедоступный пограничный сервер, напрямую подключенный к Интернету.
  • HTTP-сервер IIS — это сервер для Windows, который использует службы IIS. Он позволяет запускать приложение ASP.NET Core и службы IIS в одном процессе.
  • HTTP.sys is a server for Windows that isn't used with IIS.

Дополнительные сведения см. в статье Реализация веб-сервера в ASP.NET Core.

Configuration

ASP.NET Core предоставляет платформу конфигурации, которая получает параметры в виде пар "имя-значение" от упорядоченного набора поставщиков конфигурации. Встроенные поставщики конфигурации доступны для различных источников, таких как .json файлы, файлы, .xml переменные среды и аргументы командной строки. Для поддержки других источников можно создать настраиваемые поставщики конфигурации.

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

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

For managing confidential configuration data such as passwords, .NET Core provides the Secret Manager. Для секретов в рабочей среде рекомендуется использовать Azure Key Vault.

Дополнительные сведения см. в разделе Конфигурация в ASP.NET Core.

Environments

Среды выполнения, такие как Development, Staging и Production, являются ключевыми компонентами ASP.NET Core. Указать среду, в которой запускается приложение, можно с помощью переменной среды ASPNETCORE_ENVIRONMENT. ASP.NET Core считывает переменную среды при запуске приложения и сохраняет ее значение в реализации IWebHostEnvironment. Эта реализация доступна в любом месте приложения посредством внедрения зависимостей.

В следующем примере показана настройка приложения для предоставления подробных сведений об ошибке при выполнении в среде Development.

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.

Logging

ASP.NET Core поддерживает API ведения журнала, который совместим со множеством встроенных и сторонних соответствующих решений. Доступные следующие поставщики:

  • Console
  • Debug
  • Трассировка событий Windows
  • Журнал событий Windows
  • TraceSource
  • Служба приложений Azure
  • Azure Application Insights

Для создания журналов необходимо разрешить службу ILogger<TCategoryName> из системы внедрения зависимостей (DI) и вызвать методы ведения журналов, такие как 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, поддерживают любое количество полей. Как правило, эти поля используются для создания сообщения string, но некоторые поставщики ведения журналов отправляют их в хранилище данных в виде отдельных полей. Благодаря этому поставщики могут реализовывать семантическое (структурированное) ведение журналов.

Дополнительные сведения см. в разделе Ведение журнала в .NET Core и ASP.NET Core.

Routing

A route is a URL pattern that is mapped to a handler. Обычно обработчик представляет собой страницу Razor, метод действия в контроллере MVC или ПО промежуточного слоя. Маршрутизация ASP.NET Core позволяет контролировать URL-адреса, используемые приложением.

Подробные сведения см. в статье Маршрутизация в ASP.NET Core.

Error handling

ASP.NET Core содержит встроенные функции обработки ошибок, такие как:

  • Страница исключений для разработчика
  • Пользовательские страницы ошибок
  • Статические страницы с кодами состояния
  • Обработка исключений при запуске

Дополнительные сведения см. в статье Обработка ошибок в ASP.NET Core.

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

ASP.NET Core включает реализацию интерфейса IHttpClientFactory для создания экземпляров HttpClient. The factory:

  • Центральное расположение для именования и настройки логических экземпляров HttpClient. For example, register and configure a github client for accessing GitHub. Можно зарегистрировать и настроить клиент по умолчанию для других целей.
  • Поддержка регистрации и связывания в цепочки множества делегирующих обработчиков для создания конвейера ПО промежуточного слоя под исходящие запросы. Этот шаблон похож на входящий конвейер ПО промежуточного слоя для ASP.NET Core. Шаблон предоставляет механизм управления сквозной функциональностью HTTP-запросов, включая кэширование, обработку ошибок, сериализацию и ведение журнала.
  • Integrates with Polly, a popular third-party library for transient fault handling.
  • Управление созданием пулов и временем существования базовых экземпляров HttpClientHandler с целью избежать обычных проблем с DNS, которые возникают при управлении временем существования HttpClient вручную.
  • Настройка параметров ведения журнала (через ILogger) для всех запросов, отправленных через клиентов, созданных фабрикой.

Дополнительные сведения см. в статье Выполнение HTTP-запросов с помощью IHttpClientFactory в ASP.NET Core.

Content root

Корневой каталог содержимого — это базовый путь к следующим элементам:

  • The executable hosting the app (.exe).
  • Compiled assemblies that make up the app (.dll).
  • Файлы содержимого, используемые приложением, например:
    • Файлы Razor (.cshtml, .razor)
    • Файлы конфигурации (.json, .xml)
    • Файлы данных (.db)
  • The Web root, typically the wwwroot folder.

Во время развертывания корень содержимого по умолчанию сбрасывается до корневого каталога проекта. This directory is also the base path for both the app's content files and the Web root. Альтернативный корневой путь к содержимому может быть указан при создании узла. For more information, see Content root.

Web root

Корневой веб-каталог — это базовый путь к общедоступным файлам статических ресурсов, например:

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

По умолчанию статические файлы обслуживаются только в корневом веб-каталоге и его подкаталогах. The web root path defaults to {content root}/wwwroot. Альтернативное расположение корневого веб-каталога можно указать при создании узла. For more information, see Web root.

Prevent publishing files in wwwroot with the <Content> project item in the project file. The following example prevents publishing content in wwwroot/local and its sub-directories:

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

Для указания на корневой каталог файлов Razor.cshtml используется символ тильды и косой черты ~/. A path beginning with ~/ is referred to as a virtual path.

Подробные сведения см. в статье Статические файлы в ASP.NET Core.

В этой статье представлены основные этапы создания приложений ASP.NET Core, включая внедрение зависимостей (DI), конфигурацию, ПО промежуточного слоя и многое другое.

Рекомендации Blazor по основам, добавляющие в этот узел или заменяющие инструкции, см . в разделе ASP.NET Основные Blazor основы.

Program.cs

Приложения ASP.NET Core, созданные на основе веб-шаблонов, содержат код запуска приложения в файле Program.cs. В файле Program.cs:

  • Настраиваются службы, необходимые приложению.
  • The app's request handling pipeline is defined as a series of middleware components.

Следующий код запуска приложения поддерживает:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseAuthorization();

app.MapGet("/hi", () => "Hello!");

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

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

ASP.NET Core включает внедрение зависимостей, позволяющее обращаться к настроенным службам в рамках приложения. Services are added to the DI container with WebApplicationBuilder.Services, builder.Services in the preceding code. When the WebApplicationBuilder is instantiated, many framework-provided services are added. builder — это WebApplicationBuilder в приведенном ниже коде:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

В приведенном выше код builder добавляет в контейнер внедрения зависимостей конфигурацию, ведение журнала и множество других служб.

Следующий код добавляет в контейнер внедрения зависимостей Razor Pages, контроллеры MVC с представлениями и настраиваемый DbContext:

using Microsoft.EntityFrameworkCore;
using RazorPagesMovie.Data;
var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

builder.Services.AddDbContext<RazorPagesMovieContext>(options =>
   options.UseSqlServer(builder.Configuration.GetConnectionString("RPMovieContext")));

var app = builder.Build();

Как правило, службы разрешаются из системы внедрения зависимостей с помощью внедрения конструктора. Платформа внедрения зависимостей предоставляет экземпляр этой службы во время выполнения.

В следующем коде используется внедрение конструктора для решения контекста базы данных и средство ведения журнала из внедрения зависимостей:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;
    private readonly ILogger<IndexModel> _logger;

    public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
    {
        _context = context;
        _logger = logger;
    }

    public IList<Movie> Movie { get;set; }

    public async Task OnGetAsync()
    {
        _logger.LogInformation("IndexModel OnGetAsync.");
        Movie = await _context.Movie.ToListAsync();
    }
}

Middleware

Конвейер обработки запросов состоит из ряда компонентов ПО промежуточного слоя. Каждый компонент выполняет операции в HttpContext, а затем либо вызывает следующий компонент в конвейере, либо завершает запрос.

По принятому соглашению компонент ПО промежуточного слоя добавляется в конвейер вызовом метода расширения Use{Feature}. ПО промежуточного слоя, добавленное в приложение, выделено в следующем коде:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseAuthorization();

app.MapGet("/hi", () => "Hello!");

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

Дополнительные сведения см. в статье ПО промежуточного слоя ASP.NET Core.

Host

On startup, an ASP.NET Core app builds a host. Узел инкапсулирует все ресурсы приложения:

  • Реализация HTTP-сервера
  • Middleware components
  • Logging
  • Службы внедрения зависимостей
  • Configuration

Существует три разных узла, способных запускать приложение ASP.NET Core:

Рекомендуется использовать ASP.NET Core WebApplication и WebApplicationBuilder типы во всех шаблонах ASP.NET Core. WebApplication выполняется аналогично универсальному узлу .NET и предоставляет множество одинаковых интерфейсов, но требует меньше обратных вызовов для настройки. Ядро ASP.NET WebHost доступно только для обратной совместимости.

В следующем примере создается экземпляр :WebApplication

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

The WebApplicationBuilder.Build method configures a host with a set of default options, such as:

  • Используйте Kestrel в качестве веб-сервера и включите интеграцию IIS.
  • Load configuration from appsettings.json, environment variables, command line arguments, and other configuration sources.
  • Отправка выходных данных журнала в поставщики служб консоли и отладки.

Non-web scenarios

Универсальный узел позволяет приложениям других типов использовать перекрестные расширения платформ, такие как средства ведения журналов, внедрения зависимостей, настройки и управления жизненным циклом. Дополнительные сведения см. в статье Универсальный узел .NET в ASP.NET Core и Фоновые задачи с размещенными службами в ASP.NET Core.

Servers

Приложение ASP.NET Core использует реализацию HTTP-сервера для приема HTTP-запросов. The server surfaces requests to the app as a set of request features composed into an HttpContext.

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

  • Kestrel представляет собой кроссплатформенный веб-сервер. Kestrel is often run in a reverse proxy configuration using IIS. В ASP.NET Core 2.0 или более поздних версиях Kestrel может быть запущен как общедоступный пограничный сервер, напрямую подключенный к Интернету.
  • HTTP-сервер IIS — это сервер для Windows, который использует службы IIS. Он позволяет запускать приложение ASP.NET Core и службы IIS в одном процессе.
  • HTTP.sys is a server for Windows that isn't used with IIS.

Дополнительные сведения см. в статье Реализация веб-сервера в ASP.NET Core.

Configuration

ASP.NET Core provides a configuration framework that gets settings as name-value pairs from an ordered set of configuration providers. Встроенные поставщики конфигурации доступны для различных источников, таких как .json файлы, файлы, .xml переменные среды и аргументы командной строки. Для поддержки других источников можно создать настраиваемые поставщики конфигурации.

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

For managing confidential configuration data such as passwords, .NET Core provides the Secret Manager. Для секретов в рабочей среде рекомендуется использовать Azure Key Vault.

Дополнительные сведения см. в разделе Конфигурация в ASP.NET Core.

Environments

Среды выполнения, такие как Development, Staging и Production, доступны в ASP.NET Core. Указать среду, в которой запускается приложение, можно с помощью переменной среды ASPNETCORE_ENVIRONMENT. ASP.NET Core считывает переменную среды при запуске приложения и сохраняет ее значение в реализации IWebHostEnvironment. Эта реализация доступна в любом месте приложения посредством внедрения зависимостей.

В следующем примере выполняется настройка обработчика исключений и ПО промежуточного слоя протокола HTTP Strict Transport Security Protocol (HSTS) при выполнении НЕ в среде Development:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseAuthorization();

app.MapGet("/hi", () => "Hello!");

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

Дополнительные сведения см. в статье Использование нескольких сред в ASP.NET Core.

Logging

ASP.NET Core поддерживает API ведения журнала, который совместим со множеством встроенных и сторонних соответствующих решений. Доступные следующие поставщики:

  • Console
  • Debug
  • Трассировка событий Windows
  • Журнал событий Windows
  • TraceSource
  • Служба приложений Azure
  • Azure Application Insights

Для создания журналов необходимо разрешить службу ILogger<TCategoryName> из системы внедрения зависимостей (DI) и вызвать методы ведения журналов, такие как LogInformation. For example:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;
    private readonly ILogger<IndexModel> _logger;

    public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
    {
        _context = context;
        _logger = logger;
    }

    public IList<Movie> Movie { get;set; }

    public async Task OnGetAsync()
    {
        _logger.LogInformation("IndexModel OnGetAsync.");
        Movie = await _context.Movie.ToListAsync();
    }
}

Дополнительные сведения см. в разделе Ведение журнала в .NET Core и ASP.NET Core.

Routing

A route is a URL pattern that is mapped to a handler. Обычно обработчик представляет собой страницу Razor, метод действия в контроллере MVC или ПО промежуточного слоя. Маршрутизация ASP.NET Core позволяет контролировать URL-адреса, используемые приложением.

Следующий код, созданный шаблоном веб-приложения ASP.NET Core, вызывает UseRouting:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Подробные сведения см. в статье Маршрутизация в ASP.NET Core.

Error handling

ASP.NET Core содержит встроенные функции обработки ошибок, такие как:

  • Страница исключений для разработчика
  • Пользовательские страницы ошибок
  • Статические страницы с кодами состояния
  • Обработка исключений при запуске

Дополнительные сведения см. в статье Обработка ошибок в ASP.NET Core.

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

ASP.NET Core включает реализацию интерфейса IHttpClientFactory для создания экземпляров HttpClient. The factory:

  • Центральное расположение для именования и настройки логических экземпляров HttpClient. For example, register and configure a github client for accessing GitHub. Можно зарегистрировать и настроить клиент по умолчанию для других целей.
  • Поддержка регистрации и связывания в цепочки множества делегирующих обработчиков для создания конвейера ПО промежуточного слоя под исходящие запросы. Этот шаблон похож на входящий конвейер ПО промежуточного слоя для ASP.NET Core. Шаблон предоставляет механизм управления сквозной функциональностью HTTP-запросов, включая кэширование, обработку ошибок, сериализацию и ведение журнала.
  • Integrates with Polly, a popular third-party library for transient fault handling.
  • Управление созданием пулов и временем существования базовых экземпляров HttpClientHandler с целью избежать обычных проблем с DNS, которые возникают при управлении временем существования HttpClient вручную.
  • Настройка параметров ведения журнала (через ILogger) для всех запросов, отправленных через клиентов, созданных фабрикой.

Дополнительные сведения см. в статье Выполнение HTTP-запросов с помощью IHttpClientFactory в ASP.NET Core.

Content root

Корневой каталог содержимого — это базовый путь к следующим элементам:

  • The executable hosting the app (.exe).
  • Compiled assemblies that make up the app (.dll).
  • Файлы содержимого, используемые приложением, например:
    • Файлы Razor (.cshtml, .razor)
    • Файлы конфигурации (.json, .xml)
    • Файлы данных (.db)
  • The Web root, typically the wwwroot folder.

Во время развертывания корень содержимого по умолчанию сбрасывается до корневого каталога проекта. This directory is also the base path for both the app's content files and the Web root. Альтернативный корневой путь к содержимому может быть указан при создании узла. For more information, see Content root.

Web root

Корневой веб-каталог — это базовый путь к общедоступным файлам статических ресурсов, например:

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

По умолчанию статические файлы обслуживаются только в корневом веб-каталоге и его подкаталогах. The web root path defaults to {content root}/wwwroot. Альтернативное расположение корневого веб-каталога можно указать при создании узла. For more information, see Web root.

Prevent publishing files in wwwroot with the <Content> project item in the project file. The following example prevents publishing content in wwwroot/local and its sub-directories:

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

В файлах Razor.cshtml~/ указывает на корневой каталог. A path beginning with ~/ is referred to as a virtual path.

Подробные сведения см. в статье Статические файлы в ASP.NET Core.

Additional resources