Запуск приложения в ASP.NET Core

  • Статья

Примечание.

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

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

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

Внимание

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

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

Автор: Рик Андерсон (Rick Anderson)

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

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

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

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

Приложения, использующие EventSource, могут измерять время запуска, чтобы определить и оптимизировать его производительность. Событие ServerReady в Microsoft.AspNetCore.Hosting представляет точку, в которой сервер готов отвечать на запросы.

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

Расширение класса Startup с использованием фильтров запуска

Используйте IStartupFilter в следующих случаях:

  • Чтобы настроить ПО промежуточного слоя в начале или конце конвейера по промежуточному слоя приложения без явного вызова Use{Middleware}. Используется IStartupFilter для добавления по умолчанию в начало конвейера без явной регистрации ПО промежуточного слоя по умолчанию. IStartupFilter разрешает другим компонентам вызывать Use{Middleware} от имени автора приложения.
  • Для создания конвейера методов Configure. IStartupFilter.Configure может обеспечивать запуск ПО промежуточного слоя до или после ПО промежуточного слоя, добавляемого библиотеками.

IStartupFilter реализует метод Configure, который принимает и возвращает Action<IApplicationBuilder>. IApplicationBuilder определяет класс для настройки конвейера запросов приложения. Дополнительные сведения см. в разделе Создание конвейера ПО промежуточного слоя с помощью IApplicationBuilder.

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

В следующем примере показана регистрация ПО промежуточного слоя с помощью IStartupFilter. ПО промежуточного слоя RequestSetOptionsMiddleware задает значения параметров из параметра строки запроса:

public class RequestSetOptionsMiddleware
{
    private readonly RequestDelegate _next;

    public RequestSetOptionsMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    // Test with https://localhost:5001/Privacy/?option=Hello
    public async Task Invoke(HttpContext httpContext)
    {
        var option = httpContext.Request.Query["option"];

        if (!string.IsNullOrWhiteSpace(option))
        {
            httpContext.Items["option"] = WebUtility.HtmlEncode(option);
        }

        await _next(httpContext);
    }
}

RequestSetOptionsMiddleware настраивается в классе RequestSetOptionsStartupFilter:

namespace WebStartup.Middleware;
// <snippet1>
public class RequestSetOptionsStartupFilter : IStartupFilter
{
    public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
    {
        return builder =>
        {
            builder.UseMiddleware<RequestSetOptionsMiddleware>();
            next(builder);
        };
    }
}
// </snippet1>

Зарегистрировано IStartupFilter в Program.cs:

using WebStartup.Middleware;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddTransient<IStartupFilter,
                      RequestSetOptionsStartupFilter>();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

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

@page
@model PrivacyModel
@{
    ViewData["Title"] = "Privacy Policy";
}
<h1>@ViewData["Title"]</h1>

<p> Append query string ?option=hello</p>
Option String: @HttpContext.Items["option"];

Порядок выполнения ПО промежуточного слоя определяется порядком регистраций IStartupFilter:

  • Несколько реализаций IStartupFilter могут взаимодействовать с одними и теми же объектами. Если важен порядок, упорядочите регистрации службы IStartupFilter в соответствии с требуемым порядком выполнения ПО промежуточного слоя.

  • Библиотеки могут добавлять ПО промежуточного слоя с одной или несколькими реализациями IStartupFilter, которые выполняются до или после другого ПО промежуточного слоя приложения, зарегистрированного с помощью IStartupFilter. Чтобы вызвать ПО промежуточного слоя IStartupFilter до ПО промежуточного слоя, добавляемого библиотекой IStartupFilter, сделайте следующее:

    • расположите регистрацию службы до добавления библиотеки в контейнер службы.
    • Чтобы вызвать его после этого момента, расположите регистрацию службы после добавления библиотеки.

Примечание. Вы не можете расширить приложение ASP.NET Core при переопределении Configure. Дополнительные сведения см . в этой проблеме с GitHub.

Добавление конфигурации из внешней сборки при запуске

Реализация IHostingStartup позволяет добавлять улучшения в приложение при запуске из внешней сборки за пределами файла приложения Program.cs . Дополнительные сведения см. в статье Использование начальных сборок размещения в ASP.NET Core.

Запуск, настройка служб и настройка

Сведения об использовании ConfigureServices и Configure методах с минимальной моделью размещения см. в следующих статье:

Приложения ASP.NET Core, созданные на основе веб-шаблонов, содержат код запуска приложения в файле 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.

Расширение класса Startup с использованием фильтров запуска

Используйте IStartupFilter в следующих случаях:

  • Чтобы настроить ПО промежуточного слоя в начале или конце конвейера по промежуточному слоя приложения без явного вызова Use{Middleware}. Используется IStartupFilter для добавления по умолчанию в начало конвейера без явной регистрации ПО промежуточного слоя по умолчанию. IStartupFilter разрешает другим компонентам вызывать Use{Middleware} от имени автора приложения.
  • Для создания конвейера методов Configure. IStartupFilter.Configure может обеспечивать запуск ПО промежуточного слоя до или после ПО промежуточного слоя, добавляемого библиотеками.

IStartupFilter реализует метод Configure, который принимает и возвращает Action<IApplicationBuilder>. IApplicationBuilder определяет класс для настройки конвейера запросов приложения. Дополнительные сведения см. в разделе Создание конвейера ПО промежуточного слоя с помощью IApplicationBuilder.

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

В следующем примере показана регистрация ПО промежуточного слоя с помощью IStartupFilter. ПО промежуточного слоя RequestSetOptionsMiddleware задает значения параметров из параметра строки запроса:

public class RequestSetOptionsMiddleware
{
    private readonly RequestDelegate _next;

    public RequestSetOptionsMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    // Test with https://localhost:5001/Privacy/?option=Hello
    public async Task Invoke(HttpContext httpContext)
    {
        var option = httpContext.Request.Query["option"];

        if (!string.IsNullOrWhiteSpace(option))
        {
            httpContext.Items["option"] = WebUtility.HtmlEncode(option);
        }

        await _next(httpContext);
    }
}

RequestSetOptionsMiddleware настраивается в классе RequestSetOptionsStartupFilter:

namespace WebStartup.Middleware;
// <snippet1>
public class RequestSetOptionsStartupFilter : IStartupFilter
{
    public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
    {
        return builder =>
        {
            builder.UseMiddleware<RequestSetOptionsMiddleware>();
            next(builder);
        };
    }
}
// </snippet1>

Зарегистрировано IStartupFilter в Program.cs:

using WebStartup.Middleware;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddTransient<IStartupFilter,
                      RequestSetOptionsStartupFilter>();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

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

@page
@model PrivacyModel
@{
    ViewData["Title"] = "Privacy Policy";
}
<h1>@ViewData["Title"]</h1>

<p> Append query string ?option=hello</p>
Option String: @HttpContext.Items["option"];

Порядок выполнения ПО промежуточного слоя определяется порядком регистраций IStartupFilter:

  • Несколько реализаций IStartupFilter могут взаимодействовать с одними и теми же объектами. Если важен порядок, упорядочите регистрации службы IStartupFilter в соответствии с требуемым порядком выполнения ПО промежуточного слоя.

  • Библиотеки могут добавлять ПО промежуточного слоя с одной или несколькими реализациями IStartupFilter, которые выполняются до или после другого ПО промежуточного слоя приложения, зарегистрированного с помощью IStartupFilter. Чтобы вызвать ПО промежуточного слоя IStartupFilter до ПО промежуточного слоя, добавляемого библиотекой IStartupFilter, сделайте следующее:

    • расположите регистрацию службы до добавления библиотеки в контейнер службы.
    • Чтобы вызвать его после этого момента, расположите регистрацию службы после добавления библиотеки.

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

Добавление конфигурации из внешней сборки при запуске

Реализация IHostingStartup позволяет добавлять улучшения в приложение при запуске из внешней сборки за пределами файла приложения Program.cs . Дополнительные сведения см. в статье Использование начальных сборок размещения в ASP.NET Core.

Класс Startup настраивает службы и конвейер запросов приложения.

Класс Startup

Приложения ASP.NET Core используют класс Startup, который называется Startup по соглашению . Класс Startup:

  • При необходимости содержит метод ConfigureServices для настройки служб приложения. Служба — многократно используемый компонент, обеспечивающий функциональность приложения. Службы регистрируются в ConfigureServices и используются в приложении с помощью внедрения зависимостей (DI) или ApplicationServices.
  • Содержит метод Configure для создания конвейера обработки запросов приложения.

ConfigureServices и Configure вызываются средой выполнения ASP.NET Core при запуске приложения:

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages();
    }

    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.UseAuthorization();

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

Предыдущий пример предназначен для Razor Pages; версия для MVC похожа.

Класс Startup указывается при создании узла приложения. Класс Startup обычно указывается путем вызова метода WebHostBuilderExtensions.UseStartup/<TStartup> в построителе узлов.

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

Узел предоставляет службы, которые доступны конструктору классов Startup. Приложение добавляет дополнительные службы через ConfigureServices. Как службы узла, так и службы приложения доступны в Configure и во всем приложении.

При использовании универсального узла (IHostBuilder) в конструктор Startup могут внедряться только следующие типы служб:

public class Startup
{
    private readonly IWebHostEnvironment _env;

    public Startup(IConfiguration configuration, IWebHostEnvironment env)
    {
        Configuration = configuration;
        _env = env;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
        }
        else
        {
        }
    }
}

Большинство служб недоступны, пока не будет вызван метод Configure.

Несколько запусков

Когда приложение определяет отдельные классы Startup для различных сред (например, StartupDevelopment), подходящий класс Startup выбирается во время выполнения. Класс, у которого суффикс имени соответствует текущей среде, получает приоритет. Если приложение выполняется в среде разработки и включает в себя оба класса — Startup и StartupDevelopment, используется класс StartupDevelopment. Дополнительные сведения см. в статье Использование нескольких сред.

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

Метод ConfigureServices

Метод ConfigureServices:

  • Необязательно.
  • Вызывается узлом перед методом Configure для настройки служб приложения.
  • По соглашению используется для задания параметров конфигурации.

Узел может настраивать некоторые службы перед вызовом методов Startup. Дополнительную информацию см. в разделе Узел.

Для функций, нуждающихся в значительной настройке, существуют методы расширения Add{Service} в IServiceCollection. Например, AddDbContext, AddDefaultIdentity, AddEntityFrameworkStores и AddRazorPages:

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {

        services.AddDbContext<ApplicationDbContext>(options =>
            options.UseSqlServer(
                Configuration.GetConnectionString("DefaultConnection")));
        services.AddDefaultIdentity<IdentityUser>(
            options => options.SignIn.RequireConfirmedAccount = true)
            .AddEntityFrameworkStores<ApplicationDbContext>();

        services.AddRazorPages();
    }

Добавление служб в контейнер службы делает их доступными в приложении и методе Configure. Службы разрешаются посредством внедрения зависимостей или из ApplicationServices.

Метод Configure

Метод Configure используется для указания того, как приложение реагирует на HTTP-запросы. Конвейер запросов настраивается путем добавления компонентов ПО промежуточного слоя в экземпляр IApplicationBuilder. IApplicationBuilder доступен для метода Configure, но он не зарегистрирован в контейнере службы. При размещении создается IApplicationBuilder и передается непосредственно в Configure.

Шаблоны ASP.NET Core настраивают конвейер с поддержкой следующих компонентов и функций:

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages();
    }

    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.UseAuthorization();

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

Предыдущий пример предназначен для Razor Pages; версия для MVC похожа.

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

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

В сигнатуре метода Configure могут быть указаны дополнительные службы, такие как IWebHostEnvironment, ILoggerFactory или любые службы, определенные в ConfigureServices. Эти службы внедряются, если доступны.

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

Настройка служб без запуска

Для настройки служб и конвейера обработки запросов в построителе узлов вместо класса Startup можно использовать удобные методы ConfigureServices и Configure. Несколько вызовов ConfigureServices добавляются друг к другу. При наличии нескольких вызовов метода Configure используется последний вызов Configure.

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.ConfigureServices(services =>
                {
                    services.AddControllersWithViews();
                })
                .Configure(app =>
                {
                    var loggerFactory = app.ApplicationServices
                        .GetRequiredService<ILoggerFactory>();
                    var logger = loggerFactory.CreateLogger<Program>();
                    var env = app.ApplicationServices.GetRequiredService<IWebHostEnvironment>();
                    var config = app.ApplicationServices.GetRequiredService<IConfiguration>();

                    logger.LogInformation("Logged in Configure");

                    if (env.IsDevelopment())
                    {
                        app.UseDeveloperExceptionPage();
                    }
                    else
                    {
                        app.UseExceptionHandler("/Home/Error");
                        app.UseHsts();
                    }

                    var configValue = config["MyConfigKey"];
                });
            });
        });
}

Расширение класса Startup с использованием фильтров запуска

Используйте IStartupFilter в следующих случаях:

  • Для настройки ПО промежуточного слоя в начале или конце конвейера ПО промежуточного слоя Configure приложения без явного вызова Use{Middleware}. ASP.NET Core использует IStartupFilter для добавления значений по умолчанию в начало конвейера, исключая необходимость явной регистрации ПО промежуточного слоя по умолчанию автором приложения. IStartupFilter разрешает другим компонентам вызывать Use{Middleware} от имени автора приложения.
  • Для создания конвейера методов Configure. IStartupFilter.Configure может обеспечивать запуск ПО промежуточного слоя до или после ПО промежуточного слоя, добавляемого библиотеками.

IStartupFilter реализует метод Configure, который принимает и возвращает Action<IApplicationBuilder>. IApplicationBuilder определяет класс для настройки конвейера запросов приложения. Дополнительные сведения см. в разделе Создание конвейера ПО промежуточного слоя с помощью IApplicationBuilder.

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

В следующем примере показана регистрация ПО промежуточного слоя с помощью IStartupFilter. ПО промежуточного слоя RequestSetOptionsMiddleware задает значения параметров из параметра строки запроса:

public class RequestSetOptionsMiddleware
{
    private readonly RequestDelegate _next;

    public RequestSetOptionsMiddleware( RequestDelegate next )
    {
        _next = next;
    }

    // Test with https://localhost:5001/Privacy/?option=Hello
    public async Task Invoke(HttpContext httpContext)
    {
        var option = httpContext.Request.Query["option"];

        if (!string.IsNullOrWhiteSpace(option))
        {
            httpContext.Items["option"] = WebUtility.HtmlEncode(option);
        }

        await _next(httpContext);
    }
}

RequestSetOptionsMiddleware настраивается в классе RequestSetOptionsStartupFilter:

public class RequestSetOptionsStartupFilter : IStartupFilter
{
    public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
    {
        return builder =>
        {
            builder.UseMiddleware<RequestSetOptionsMiddleware>();
            next(builder);
        };
    }
}

IStartupFilter регистрируется в контейнере службы в ConfigureServices.

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
           .ConfigureAppConfiguration((hostingContext, config) =>
           {
           })
         .ConfigureWebHostDefaults(webBuilder =>
         {
             webBuilder.UseStartup<Startup>();
         })
        .ConfigureServices(services =>
        {
            services.AddTransient<IStartupFilter,
                      RequestSetOptionsStartupFilter>();
        });
}

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

Порядок выполнения ПО промежуточного слоя определяется порядком регистраций IStartupFilter:

  • Несколько реализаций IStartupFilter могут взаимодействовать с одними и теми же объектами. Если важен порядок, упорядочите регистрации службы IStartupFilter в соответствии с требуемым порядком выполнения ПО промежуточного слоя.

  • Библиотеки могут добавлять ПО промежуточного слоя с одной или несколькими реализациями IStartupFilter, которые выполняются до или после другого ПО промежуточного слоя приложения, зарегистрированного с помощью IStartupFilter. Чтобы вызвать ПО промежуточного слоя IStartupFilter до ПО промежуточного слоя, добавляемого библиотекой IStartupFilter, сделайте следующее:

    • расположите регистрацию службы до добавления библиотеки в контейнер службы.
    • Чтобы вызвать его после этого момента, расположите регистрацию службы после добавления библиотеки.

Добавление конфигурации из внешней сборки при запуске

Реализация IHostingStartup позволяет при запуске добавлять в приложение улучшения из внешней сборки вне приложения класса Startup. Дополнительные сведения см. в статье Использование начальных сборок размещения в ASP.NET Core.

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