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

  • Статья

Примечание.

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

Предупреждение

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

Внимание

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

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

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

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

Program.cs

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

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

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 включает внедрение зависимостей, позволяющее обращаться к настроенным службам в рамках приложения. Службы добавляются в контейнер внедрения зависимостей с помощью WebApplicationBuilder.Services, builder.Services в предыдущем коде. При создании экземпляра WebApplicationBuilder добавляется множество предоставляемых платформой служб. 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();
    }
}

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

Конвейер обработки запросов состоит из ряда компонентов ПО промежуточного слоя. Каждый компонент выполняет операции в 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.

Хост

При запуске приложение ASP.NET Core создает узел. Узел инкапсулирует все ресурсы приложения:

  • Реализация HTTP-сервера
  • Компоненты ПО промежуточного слоя
  • Ведение журнала
  • Службы внедрения зависимостей
  • Настройка

Существует три разных узла, способных запускать приложение 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();

Метод WebApplicationBuilder.Build настраивает узел с параметрами по умолчанию, например с такими:

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

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

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

Серверы

Приложение ASP.NET Core использует реализацию HTTP-сервера для приема HTTP-запросов. Сервер отправляет приложению запросы в виде набора функций запросов, объединенных в HttpContext.

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

  • Kestrel представляет собой кроссплатформенный веб-сервер. Kestrel зачастую запускается в конфигурации обратного прокси с использованием службы IIS. В ASP.NET Core 2.0 или более поздних версиях Kestrel может быть запущен как общедоступный пограничный сервер, напрямую подключенный к Интернету.
  • HTTP-сервер IIS — это сервер для Windows, который использует службы IIS. Он позволяет запускать приложение ASP.NET Core и службы IIS в одном процессе.
  • HTTP.sys — это сервер для Windows, который не используется со службами IIS.

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

Настройка

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

По умолчанию приложения ASP.NET Core настроены для чтения из файла appsettings.json, переменных среды, командной строки и т. д. При загрузке конфигурации приложения значения из переменных среды переопределяют значения из файла appsettings.json.

Для управления конфиденциальными данными конфигурации, например паролями, .NET Core предоставляет диспетчер секретов. Для секретов в рабочей среде рекомендуется использовать Azure Key Vault.

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

Среды

Среды выполнения, такие как 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.

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

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

  • Консоль
  • Отладка
  • Трассировка событий Windows
  • Журнал событий Windows
  • TraceSource
  • Azure App Service
  • Azure Application Insights

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

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.

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

Маршрут — это шаблон URL-адреса, сопоставляемый с обработчиком. Обычно обработчик представляет собой страницу 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.

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

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

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

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

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

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

  • Центральное расположение для именования и настройки логических экземпляров HttpClient. Например, можно зарегистрировать и использовать клиент github для доступа к сайту GitHub. Можно зарегистрировать и настроить клиент по умолчанию для других целей.
  • Поддержка регистрации и связывания в цепочки множества делегирующих обработчиков для создания конвейера ПО промежуточного слоя под исходящие запросы. Этот шаблон похож на входящий конвейер ПО промежуточного слоя для ASP.NET Core. Шаблон предоставляет механизм управления сквозной функциональностью HTTP-запросов, включая кэширование, обработку ошибок, сериализацию и ведение журнала.
  • Интеграция с Polly — популярной сторонней библиотекой для обработки временных сбоев.
  • Управление созданием пулов и временем существования базовых экземпляров HttpClientHandler с целью избежать обычных проблем с DNS, которые возникают при управлении временем существования HttpClient вручную.
  • Настройка параметров ведения журнала (через ILogger) для всех запросов, отправленных через клиентов, созданных фабрикой.

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

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

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

  • Исполняемый файл, в котором размещено приложение (EXE).
  • Скомпилированные сборки, составляющие приложение (DLL).
  • Файлы содержимого, используемые приложением, например:
    • Файлы Razor (.cshtml, .razor)
    • Файлы конфигурации (.json, .xml)
    • Файлы данных (.db)
  • Корневой веб-каталог, обычно это папка wwwroot.

Во время развертывания корень содержимого по умолчанию сбрасывается до корневого каталога проекта. Этот каталог является базовым путем к файлам содержимого приложения и корневому веб-каталогу. Альтернативный корневой путь к содержимому может быть указан при создании узла. Дополнительные сведения: Корень содержимого.

каталог документов

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

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

По умолчанию статические файлы обслуживаются только в корневом веб-каталоге и его подкаталогах. По умолчанию используется путь {корневой каталог содержимого}/wwwroot. Альтернативное расположение корневого веб-каталога можно указать при создании узла. Дополнительные сведения см. в разделе Корневой веб-каталог.

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

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

В файлах Razor.cshtml ~/ указывает на корневой каталог. Путь, начинающийся с ~/, называется виртуальным путем.

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

Дополнительные ресурсы

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

Program.cs

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

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

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 включает внедрение зависимостей, позволяющее обращаться к настроенным службам в рамках приложения. Службы добавляются в контейнер внедрения зависимостей с помощью WebApplicationBuilder.Services, builder.Services в предыдущем коде. При создании экземпляра WebApplicationBuilder добавляется множество предоставляемых платформой служб. 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();
    }
}

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

Конвейер обработки запросов состоит из ряда компонентов ПО промежуточного слоя. Каждый компонент выполняет операции в 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.

Хост

При запуске приложение ASP.NET Core создает узел. Узел инкапсулирует все ресурсы приложения:

  • Реализация HTTP-сервера
  • Компоненты ПО промежуточного слоя
  • Ведение журнала
  • Службы внедрения зависимостей
  • Настройка

Существует три разных узла, способных запускать приложение 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();

Метод WebApplicationBuilder.Build настраивает узел с параметрами по умолчанию, например с такими:

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

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

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

Серверы

Приложение ASP.NET Core использует реализацию HTTP-сервера для приема HTTP-запросов. Сервер отправляет приложению запросы в виде набора функций запросов, объединенных в HttpContext.

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

  • Kestrel представляет собой кроссплатформенный веб-сервер. Kestrel зачастую запускается в конфигурации обратного прокси с использованием службы IIS. В ASP.NET Core 2.0 или более поздних версиях Kestrel может быть запущен как общедоступный пограничный сервер, напрямую подключенный к Интернету.
  • HTTP-сервер IIS — это сервер для Windows, который использует службы IIS. Он позволяет запускать приложение ASP.NET Core и службы IIS в одном процессе.
  • HTTP.sys — это сервер для Windows, который не используется со службами IIS.

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

Настройка

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

По умолчанию приложения ASP.NET Core настроены для чтения из файла appsettings.json, переменных среды, командной строки и т. д. При загрузке конфигурации приложения значения из переменных среды переопределяют значения из файла appsettings.json.

Для управления конфиденциальными данными конфигурации, например паролями, .NET Core предоставляет диспетчер секретов. Для секретов в рабочей среде рекомендуется использовать Azure Key Vault.

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

Среды

Среды выполнения, такие как 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.

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

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

  • Консоль
  • Отладка
  • Трассировка событий Windows
  • Журнал событий Windows
  • TraceSource
  • Azure App Service
  • Azure Application Insights

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

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.

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

Маршрут — это шаблон URL-адреса, сопоставляемый с обработчиком. Обычно обработчик представляет собой страницу 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.

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

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

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

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

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

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

  • Центральное расположение для именования и настройки логических экземпляров HttpClient. Например, можно зарегистрировать и использовать клиент github для доступа к сайту GitHub. Можно зарегистрировать и настроить клиент по умолчанию для других целей.
  • Поддержка регистрации и связывания в цепочки множества делегирующих обработчиков для создания конвейера ПО промежуточного слоя под исходящие запросы. Этот шаблон похож на входящий конвейер ПО промежуточного слоя для ASP.NET Core. Шаблон предоставляет механизм управления сквозной функциональностью HTTP-запросов, включая кэширование, обработку ошибок, сериализацию и ведение журнала.
  • Интеграция с Polly — популярной сторонней библиотекой для обработки временных сбоев.
  • Управление созданием пулов и временем существования базовых экземпляров HttpClientHandler с целью избежать обычных проблем с DNS, которые возникают при управлении временем существования HttpClient вручную.
  • Настройка параметров ведения журнала (через ILogger) для всех запросов, отправленных через клиентов, созданных фабрикой.

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

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

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

  • Исполняемый файл, в котором размещено приложение (EXE).
  • Скомпилированные сборки, составляющие приложение (DLL).
  • Файлы содержимого, используемые приложением, например:
    • Файлы Razor (.cshtml, .razor)
    • Файлы конфигурации (.json, .xml)
    • Файлы данных (.db)
  • Корневой веб-каталог, обычно это папка wwwroot.

Во время развертывания корень содержимого по умолчанию сбрасывается до корневого каталога проекта. Этот каталог является базовым путем к файлам содержимого приложения и корневому веб-каталогу. Альтернативный корневой путь к содержимому может быть указан при создании узла. Дополнительные сведения: Корень содержимого.

каталог документов

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

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

По умолчанию статические файлы обслуживаются только в корневом веб-каталоге и его подкаталогах. По умолчанию используется путь {корневой каталог содержимого}/wwwroot. Альтернативное расположение корневого веб-каталога можно указать при создании узла. Дополнительные сведения см. в разделе Корневой веб-каталог.

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

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

В файлах Razor.cshtml ~/ указывает на корневой каталог. Путь, начинающийся с ~/, называется виртуальным путем.

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

Дополнительные ресурсы

В этой статье представлены основные этапы создания приложений 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 включает встроенную платформу внедрения зависимостей, позволяющую обращаться к настроенным службам в рамках приложения. Например, службой является компонент ведения журнала.

Код для настройки (или регистрации) служб добавляется в метод Startup.ConfigureServices. Например:

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.

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

Конвейер обработки запросов состоит из ряда компонентов ПО промежуточного слоя. Каждый компонент выполняет операции в 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.

Хост

При запуске приложение ASP.NET Core создает узел. Узел инкапсулирует все ресурсы приложения:

  • Реализация HTTP-сервера
  • Компоненты ПО промежуточного слоя
  • Ведение журнала
  • Службы внедрения зависимостей
  • Настройка

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

  • Универсальный узел .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.

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

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

Серверы

Приложение ASP.NET Core использует реализацию HTTP-сервера для приема HTTP-запросов. Сервер отправляет приложению запросы в виде набора функций запросов, объединенных в HttpContext.

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

  • Kestrel представляет собой кроссплатформенный веб-сервер. Kestrel зачастую запускается в конфигурации обратного прокси с использованием службы IIS. В ASP.NET Core 2.0 или более поздних версиях Kestrel может быть запущен как общедоступный пограничный сервер, напрямую подключенный к Интернету.
  • HTTP-сервер IIS — это сервер для Windows, который использует службы IIS. Он позволяет запускать приложение ASP.NET Core и службы IIS в одном процессе.
  • HTTP.sys — это сервер для Windows, который не используется со службами IIS.

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

Настройка

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

По умолчанию приложения ASP.NET Core настроены для чтения из файла appsettings.json, переменных среды, командной строки и т. д. При загрузке конфигурации приложения значения из переменных среды переопределяют значения из файла appsettings.json.

Предпочтительный способ чтения связанных значений конфигурации — использование шаблона параметров. Дополнительные сведения см. в статье Привязка иерархических данных конфигурации с помощью шаблона параметров.

Для управления конфиденциальными данными конфигурации, например паролями, .NET Core предоставляет диспетчер секретов. Для секретов в рабочей среде рекомендуется использовать Azure Key Vault.

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

Среды

Среды выполнения, такие как 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.

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

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

  • Консоль
  • Отладка
  • Трассировка событий Windows
  • Журнал событий Windows
  • TraceSource
  • Azure App Service
  • Azure Application Insights

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

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.

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

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

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

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

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

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

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

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

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

  • Центральное расположение для именования и настройки логических экземпляров HttpClient. Например, можно зарегистрировать и использовать клиент github для доступа к сайту GitHub. Можно зарегистрировать и настроить клиент по умолчанию для других целей.
  • Поддержка регистрации и связывания в цепочки множества делегирующих обработчиков для создания конвейера ПО промежуточного слоя под исходящие запросы. Этот шаблон похож на входящий конвейер ПО промежуточного слоя для ASP.NET Core. Шаблон предоставляет механизм управления сквозной функциональностью HTTP-запросов, включая кэширование, обработку ошибок, сериализацию и ведение журнала.
  • Интеграция с Polly — популярной сторонней библиотекой для обработки временных сбоев.
  • Управление созданием пулов и временем существования базовых экземпляров HttpClientHandler с целью избежать обычных проблем с DNS, которые возникают при управлении временем существования HttpClient вручную.
  • Настройка параметров ведения журнала (через ILogger) для всех запросов, отправленных через клиентов, созданных фабрикой.

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

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

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

  • Исполняемый файл, в котором размещено приложение (EXE).
  • Скомпилированные сборки, составляющие приложение (DLL).
  • Файлы содержимого, используемые приложением, например:
    • Файлы Razor (.cshtml, .razor)
    • Файлы конфигурации (.json, .xml)
    • Файлы данных (.db)
  • Корневой веб-каталог, обычно это папка wwwroot.

Во время развертывания корень содержимого по умолчанию сбрасывается до корневого каталога проекта. Этот каталог является базовым путем к файлам содержимого приложения и корневому веб-каталогу. Альтернативный корневой путь к содержимому может быть указан при создании узла. Дополнительные сведения: Корень содержимого.

каталог документов

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

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

По умолчанию статические файлы обслуживаются только в корневом веб-каталоге и его подкаталогах. По умолчанию используется путь {корневой каталог содержимого}/wwwroot. Альтернативное расположение корневого веб-каталога можно указать при создании узла. Дополнительные сведения см. в разделе Корневой веб-каталог.

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

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

Для указания на корневой каталог файлов Razor.cshtml используется символ тильды и косой черты ~/. Путь, начинающийся с ~/, называется виртуальным путем.

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