WebApplication и WebApplicationBuilder в приложениях ASP.NET Core

WebApplication

Шаблон ASP.NET Core создает следующий код:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

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

app.Run();

Приведенный выше код можно создать, набрав dotnet new web в командной строке или выбрав в Visual Studio шаблон пустого веб-проекта.

Следующий код создает WebApplication (app) без явного создания WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.CreateBuilder инициализирует новый экземпляр WebApplicationBuilder класса с предварительно настроенными значениями по умолчанию:

if (isDevelopment)
{
    app.UseDeveloperExceptionPage();
}

app.UseRouting();

if (isAuthenticationConfigured)
{
    app.UseAuthentication();
}

if (isAuthorizationConfigured)
{
    app.UseAuthorization();
}

// user middleware/endpoints
app.CustomMiddleware(...);
app.MapGet("/", () => "hello world");
// end user middleware/endpoints

app.UseEndpoints(e => {});

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

app.Use((context, next) =>
{
    return next(context);
});

app.UseRouting();

// other middleware and endpoints

app.UseRouting();

app.MapGet("/", () => "hello world");

app.UseEndpoints(e => {});

app.Run(context =>
{
    context.Response.StatusCode = 404;
    return Task.CompletedTask;
});

Работа с портами

Если вы создаете веб-приложение с помощью Visual Studio или dotnet new, автоматически создается файл Properties/launchSettings.json с указанием портов, на которых отвечает это приложение. Запуск приложения из Visual Studio с параметрами портов, представленными в следующих примерах, возвращает диалоговое окно с сообщением об ошибке Unable to connect to web server 'AppName'. Visual Studio возвращает ошибку, так как ожидается порт, указанный в Properties/launchSettings.json, но приложение использует порт, указанный в app.Run("http://localhost:3000"). Выполните в командной строке следующий пример кода для изменения портов.

В следующих разделах задан порт приложения.

var app = WebApplication.Create(args);

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

app.Run("http://localhost:3000");

В приведенном выше коде приложение использует порт 3000.

Несколько портов

В следующем коде приложение отвечает на порт 3000 и 4000:

var app = WebApplication.Create(args);

app.Urls.Add("http://localhost:3000");
app.Urls.Add("http://localhost:4000");

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

app.Run();

Настройка порта из командной строки

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

dotnet run --urls="https://localhost:7777"

Если конечная точка Kestrel также настроена в файле appsettings.json, используется URL-адрес, указанный в файле appsettings.json. Дополнительные сведения см. в разделе Конфигурация конечной точки Kestrel.

Получение порта из среды

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

var app = WebApplication.Create(args);

var port = Environment.GetEnvironmentVariable("PORT") ?? "3000";

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

app.Run($"http://localhost:{port}");

Для настройки порта из среды лучше всего использовать переменную среды ASPNETCORE_URLS, как показано в следующем разделе.

Настройка портов с помощью переменной ASPNETCORE_URLS среды

Для настройки порта существует переменная среды ASPNETCORE_URLS:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS поддерживает несколько URL-адресов:

ASPNETCORE_URLS=http://localhost:3000;https://localhost:5000

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

Прослушивать все интерфейсы

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

http://*:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://*:3000");

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

app.Run();

http://+:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://+:3000");

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

app.Run();

http://0.0.0.0:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://0.0.0.0:3000");

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

app.Run();

Прослушивание всех интерфейсов с помощью ASPNETCORE_URLS

Приведенные выше примеры могут использовать ASPNETCORE_URLS:

ASPNETCORE_URLS=http://*:3000;https://+:5000;http://0.0.0.0:5005

Выбор протокола HTTPS с сертификатом разработки

var app = WebApplication.Create(args);

app.Urls.Add("https://localhost:3000");

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

app.Run();

Дополнительные сведения о сертификате разработки см. в разделе Доверие к сертификату разработки HTTPS в среде ASP.NET Core на ОС Windows и macOS.

Указать HTTPS с пользовательским сертификатом

В следующих разделах показано, как указать пользовательский сертификат с помощью appsettings.json файла и конфигурации.

Укажите пользовательский сертификат с помощью appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Kestrel": {
    "Certificates": {
      "Default": {
        "Path": "cert.pem",
        "KeyPath": "key.pem"
      }
    }
  }
}

Настройка пользовательского сертификата в конфигурации

var builder = WebApplication.CreateBuilder(args);

// Configure the cert and the key
builder.Configuration["Kestrel:Certificates:Default:Path"] = "cert.pem";
builder.Configuration["Kestrel:Certificates:Default:KeyPath"] = "key.pem";

var app = builder.Build();

app.Urls.Add("https://localhost:3000");

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

app.Run();

Использование API сертификатов

using System.Security.Cryptography.X509Certificates;

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.ConfigureHttpsDefaults(httpsOptions =>
    {
        var certPath = Path.Combine(builder.Environment.ContentRootPath, "cert.pem");
        var keyPath = Path.Combine(builder.Environment.ContentRootPath, "key.pem");

        httpsOptions.ServerCertificate = X509Certificate2.CreateFromPemFile(certPath, 
                                         keyPath);
    });
});

var app = builder.Build();

app.Urls.Add("https://localhost:3000");

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

app.Run();

Configuration

Следующий код считывает данные из системы конфигурации:

var app = WebApplication.Create(args);

var message = app.Configuration["HelloKey"] ?? "Config failed!";

app.MapGet("/", () => message);

app.Run();

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

Logging

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

var app = WebApplication.Create(args);

app.Logger.LogInformation("The app started");

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

app.Run();

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

Откройте контейнер внедрения зависимостей (DI)

В следующем коде показано, как получить службы из контейнера DI во время запуска приложения.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddScoped<SampleService>();

var app = builder.Build();

app.MapControllers();

using (var scope = app.Services.CreateScope())
{
    var sampleService = scope.ServiceProvider.GetRequiredService<SampleService>();
    sampleService.DoSomething();
}

app.Run();

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

WebApplicationBuilder

В этом разделе содержится пример кода с использованием WebApplicationBuilder.

Изменение корневой папки содержимого, имени приложения и среды

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

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    ApplicationName = typeof(Program).Assembly.FullName,
    ContentRootPath = Directory.GetCurrentDirectory(),
    EnvironmentName = Environments.Staging,
    WebRootPath = "customwwwroot"
});

Console.WriteLine($"Application Name: {builder.Environment.ApplicationName}");
Console.WriteLine($"Environment Name: {builder.Environment.EnvironmentName}");
Console.WriteLine($"ContentRoot Path: {builder.Environment.ContentRootPath}");
Console.WriteLine($"WebRootPath: {builder.Environment.WebRootPath}");

var app = builder.Build();

WebApplication.Create инициализирует новый экземпляр класса WebApplication с предварительно настроенными значениями по умолчанию.

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

Изменение корневой папки содержимого, имени приложения и среды через переменные среды или командную строку

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

Добавить поставщиков конфигурации

В следующем примере добавляется поставщик конфигурации INI:

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddIniFile("appsettings.ini");

var app = builder.Build();

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

Конфигурация чтения

По умолчанию WebApplicationBuilder считывает конфигурацию из нескольких источников, в том числе:

• appSettings.json и appSettings.{environment}.json.
• Переменные среды
• Командная строка

Следующий код считывает из конфигурации значение HelloKey и отображает его в конечной точке /. Если значение конфигурации равно null, message присваивается значение "Hello":

var builder = WebApplication.CreateBuilder(args);

var message = builder.Configuration["HelloKey"] ?? "Hello";

var app = builder.Build();

app.MapGet("/", () => message);

app.Run();

Полный список источников конфигурации см. в разделе "Конфигурация по умолчанию" в ASP.NET Core.

Добавить поставщиков журналирования

var builder = WebApplication.CreateBuilder(args);

// Configure JSON logging to the console.
builder.Logging.AddJsonConsole();

var app = builder.Build();

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

app.Run();

Добавление служб

var builder = WebApplication.CreateBuilder(args);

// Add the memory cache services.
builder.Services.AddMemoryCache();

// Add a custom scoped service.
builder.Services.AddScoped<ITodoRepository, TodoRepository>();
var app = builder.Build();

Настройте IHostBuilder

К существующим методам расширения IHostBuilder можно обращаться через свойство Host.

var builder = WebApplication.CreateBuilder(args);

// Wait 30 seconds for graceful shutdown.
builder.Host.ConfigureHostOptions(o => o.ShutdownTimeout = TimeSpan.FromSeconds(30));

var app = builder.Build();

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

app.Run();

Настройте IWebHostBuilder

Доступ к методам расширения для IWebHostBuilder можно получить с помощью свойства WebApplicationBuilder.WebHost.

var builder = WebApplication.CreateBuilder(args);

// Change the HTTP server implemenation to be HTTP.sys based
builder.WebHost.UseHttpSys();

var app = builder.Build();

app.MapGet("/", () => "Hello HTTP.sys");

app.Run();

Изменение корневой папки веб-сайта

По умолчанию корневой каталог веб-приложения задается относительно корневого каталога содержимого в папке wwwroot. Корневой каталог веб-приложения — это место, где middleware статических файлов ищет статические файлы. Корневой веб-сайт можно изменить с помощью WebHostOptions, командной строки или метода UseWebRoot:

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    // Look for static files in webroot
    WebRootPath = "webroot"
});

var app = builder.Build();

app.Run();

Настраиваемый контейнер внедрения зависимостей (DI)

В следующем примере используется Autofac:

var builder = WebApplication.CreateBuilder(args);

builder.Host.UseServiceProviderFactory(new AutofacServiceProviderFactory());

// Register services directly with Autofac here. Don't
// call builder.Populate(), that happens in AutofacServiceProviderFactory.
builder.Host.ConfigureContainer<ContainerBuilder>(builder => builder.RegisterModule(new MyApplicationModule()));

var app = builder.Build();

Добавить промежуточное ПО

Любое существующее ПО промежуточного слоя для ASP.NET Core можно настроить в WebApplication:

var app = WebApplication.Create(args);

// Setup the file server to serve static files.
app.UseFileServer();

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

app.Run();

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

Страница исключения для разработчиков

WebApplication.CreateBuilder инициализирует новый экземпляр класса WebApplicationBuilder с предварительно настроенными значениями по умолчанию. Страница исключений для разработчиков включена в предварительно настроенных параметрах по умолчанию. При выполнении следующего кода в среде разработки переход к адресу / отображает страницу с удобным представлением информации об исключении.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapGet("/", () =>
{
    throw new InvalidOperationException("Oops, the '/' route has thrown an exception.");
});

app.Run();

WebApplication

Шаблон ASP.NET Core создает следующий код:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

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

app.Run();

Приведенный выше код можно создать, набрав dotnet new web в командной строке или выбрав в Visual Studio шаблон пустого веб-проекта.

Следующий код создает WebApplication (app) без явного создания WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.CreateBuilder инициализирует новый экземпляр WebApplicationBuilder класса с предварительно настроенными значениями по умолчанию:

if (isDevelopment)
{
    app.UseDeveloperExceptionPage();
}

app.UseRouting();

if (isAuthenticationConfigured)
{
    app.UseAuthentication();
}

if (isAuthorizationConfigured)
{
    app.UseAuthorization();
}

// User middleware/endpoints
app.CustomMiddleware(...);
app.MapGet("/", () => "hello world");
// End user middleware/endpoints

app.UseEndpoints(e => {});

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

app.Use((context, next) =>
{
    return next(context);
});

app.UseRouting();

// Other middleware and endpoints

app.UseRouting();

app.MapGet("/", () => "hello world");

app.UseEndpoints(e => {});

app.Run(context =>
{
    context.Response.StatusCode = 404;
    return Task.CompletedTask;
});

Работа с портами

Если вы создаете веб-приложение с помощью Visual Studio или dotnet new, автоматически создается файл Properties/launchSettings.json с указанием портов, на которых отвечает это приложение. Запуск приложения из Visual Studio с параметрами портов, представленными в следующих примерах, возвращает диалоговое окно с сообщением об ошибке Unable to connect to web server 'AppName'. Visual Studio возвращает ошибку, так как ожидается порт, указанный в Properties/launchSettings.json, но приложение использует порт, указанный в app.Run("http://localhost:3000"). Выполните в командной строке следующий пример кода для изменения портов.

В следующих разделах задан порт приложения.

var app = WebApplication.Create(args);

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

app.Run("http://localhost:3000");

В приведенном выше коде приложение использует порт 3000.

Несколько портов

В следующем коде приложение отвечает на порт 3000 и 4000:

var app = WebApplication.Create(args);

app.Urls.Add("http://localhost:3000");
app.Urls.Add("http://localhost:4000");

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

app.Run();

Настройка порта из командной строки

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

dotnet run --urls="https://localhost:7777"

Если конечная точка Kestrel также настроена в файле appsettings.json, используется URL-адрес, указанный в файле appsettings.json. Дополнительные сведения см. в разделе Конфигурация конечной точки Kestrel.

Получение порта из среды

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

var app = WebApplication.Create(args);

var port = Environment.GetEnvironmentVariable("PORT") ?? "3000";

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

app.Run($"http://localhost:{port}");

Для настройки порта из среды лучше всего использовать переменную среды ASPNETCORE_URLS, как показано в следующем разделе.

Настройка портов с помощью переменной ASPNETCORE_URLS среды

Для настройки порта существует переменная среды ASPNETCORE_URLS:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS поддерживает несколько URL-адресов:

ASPNETCORE_URLS=http://localhost:3000;https://localhost:5000

Прослушивать все интерфейсы

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

http://*:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://*:3000");

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

app.Run();

http://+:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://+:3000");

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

app.Run();

http://0.0.0.0:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://0.0.0.0:3000");

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

app.Run();

Прослушивание всех интерфейсов с помощью ASPNETCORE_URLS

Приведенные выше примеры могут использовать ASPNETCORE_URLS:

ASPNETCORE_URLS=http://*:3000;https://+:5000;http://0.0.0.0:5005

Прослушивание всех интерфейсов с помощью ASPNETCORE_HTTP_PORTS и ASPNETCORE_HTTPS_PORTS

Приведенные выше примеры также могут использовать ASPNETCORE_HTTP_PORTS и ASPNETCORE_HTTPS_PORTS,но ASPNETCORE_URLS (при установке) переопределяет следующие параметры:

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Дополнительные сведения см. в разделе "Настройка конечных точек для Kestrel веб-сервера".

Выбор протокола HTTPS с сертификатом разработки

var app = WebApplication.Create(args);

app.Urls.Add("https://localhost:3000");

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

app.Run();

Дополнительные сведения о сертификате разработки см. в разделе Доверие к сертификату разработки HTTPS в среде ASP.NET Core на ОС Windows и macOS.

Указать HTTPS с пользовательским сертификатом

В следующих разделах показано, как указать пользовательский сертификат с помощью appsettings.json файла и конфигурации.

Укажите пользовательский сертификат с помощью appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Kestrel": {
    "Certificates": {
      "Default": {
        "Path": "cert.pem",
        "KeyPath": "key.pem"
      }
    }
  }
}

Настройка пользовательского сертификата в конфигурации

var builder = WebApplication.CreateBuilder(args);

// Configure the cert and the key
builder.Configuration["Kestrel:Certificates:Default:Path"] = "cert.pem";
builder.Configuration["Kestrel:Certificates:Default:KeyPath"] = "key.pem";

var app = builder.Build();

app.Urls.Add("https://localhost:3000");

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

app.Run();

Использование API сертификатов

using System.Security.Cryptography.X509Certificates;

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.ConfigureHttpsDefaults(httpsOptions =>
    {
        var certPath = Path.Combine(builder.Environment.ContentRootPath, "cert.pem");
        var keyPath = Path.Combine(builder.Environment.ContentRootPath, "key.pem");

        httpsOptions.ServerCertificate = X509Certificate2.CreateFromPemFile(certPath, 
                                         keyPath);
    });
});

var app = builder.Build();

app.Urls.Add("https://localhost:3000");

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

app.Run();

Чтение данных из среды

var app = WebApplication.Create(args);

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

app.MapGet("/", () => "Hello World");
app.MapGet("/oops", () => "Oops! An error happened.");

app.Run();

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

Configuration

Следующий код считывает данные из системы конфигурации:

var app = WebApplication.Create(args);

var message = app.Configuration["HelloKey"] ?? "Config failed!";

app.MapGet("/", () => message);

app.Run();

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

Logging

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

var app = WebApplication.Create(args);

app.Logger.LogInformation("The app started");

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

app.Run();

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

Откройте контейнер внедрения зависимостей (DI)

В следующем коде показано, как получить службы из контейнера DI во время запуска приложения.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddScoped<SampleService>();

var app = builder.Build();

app.MapControllers();

using (var scope = app.Services.CreateScope())
{
    var sampleService = scope.ServiceProvider.GetRequiredService<SampleService>();
    sampleService.DoSomething();
}

app.Run();

В следующем коде показано, как получить доступ к ключам из контейнера DI с помощью атрибута[FromKeyedServices]:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddKeyedSingleton<ICache, BigCache>("big");
builder.Services.AddKeyedSingleton<ICache, SmallCache>("small");

var app = builder.Build();

app.MapGet("/big", ([FromKeyedServices("big")] ICache bigCache) => bigCache.Get("date"));

app.MapGet("/small", ([FromKeyedServices("small")] ICache smallCache) => smallCache.Get("date"));

app.Run();

public interface ICache
{
    object Get(string key);
}
public class BigCache : ICache
{
    public object Get(string key) => $"Resolving {key} from big cache.";
}

public class SmallCache : ICache
{
    public object Get(string key) => $"Resolving {key} from small cache.";
}

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

WebApplicationBuilder

В этом разделе содержится пример кода с использованием WebApplicationBuilder.

Изменение корневой папки содержимого, имени приложения и среды

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

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    ApplicationName = typeof(Program).Assembly.FullName,
    ContentRootPath = Directory.GetCurrentDirectory(),
    EnvironmentName = Environments.Staging,
    WebRootPath = "customwwwroot"
});

Console.WriteLine($"Application Name: {builder.Environment.ApplicationName}");
Console.WriteLine($"Environment Name: {builder.Environment.EnvironmentName}");
Console.WriteLine($"ContentRoot Path: {builder.Environment.ContentRootPath}");
Console.WriteLine($"WebRootPath: {builder.Environment.WebRootPath}");

var app = builder.Build();

WebApplication.Create инициализирует новый экземпляр класса WebApplication с предварительно настроенными значениями по умолчанию.

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

Изменение корневого каталога содержимого, имени приложения и среды с помощью переменных среды или командной строки

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

Добавить поставщиков конфигурации

В следующем примере добавляется поставщик конфигурации INI:

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddIniFile("appsettings.ini");

var app = builder.Build();

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

Конфигурация чтения

По умолчанию WebApplicationBuilder считывает конфигурацию из нескольких источников, в том числе:

• appSettings.json и appSettings.{environment}.json.
• Переменные среды
• Командная строка

Полный список источников конфигурации см. в разделе "Конфигурация по умолчанию" в ASP.NET Core.

Следующий код считывает из конфигурации значение HelloKey и отображает его в конечной точке /. Если значение конфигурации равно null, message присваивается значение "Hello":

var builder = WebApplication.CreateBuilder(args);

var message = builder.Configuration["HelloKey"] ?? "Hello";

var app = builder.Build();

app.MapGet("/", () => message);

app.Run();

Чтение данных из среды

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsDevelopment())
{
    Console.WriteLine($"Running in development.");
}

var app = builder.Build();

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

app.Run();

Добавить поставщиков журналирования

var builder = WebApplication.CreateBuilder(args);

// Configure JSON logging to the console.
builder.Logging.AddJsonConsole();

var app = builder.Build();

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

app.Run();

Добавление служб

var builder = WebApplication.CreateBuilder(args);

// Add the memory cache services.
builder.Services.AddMemoryCache();

// Add a custom scoped service.
builder.Services.AddScoped<ITodoRepository, TodoRepository>();
var app = builder.Build();

Настройте IHostBuilder

К существующим методам расширения IHostBuilder можно обращаться через свойство Host.

var builder = WebApplication.CreateBuilder(args);

// Wait 30 seconds for graceful shutdown.
builder.Host.ConfigureHostOptions(o => o.ShutdownTimeout = TimeSpan.FromSeconds(30));

var app = builder.Build();

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

app.Run();

Настройте IWebHostBuilder

Доступ к методам расширения для IWebHostBuilder можно получить с помощью свойства WebApplicationBuilder.WebHost.

var builder = WebApplication.CreateBuilder(args);

// Change the HTTP server implemenation to be HTTP.sys based
builder.WebHost.UseHttpSys();

var app = builder.Build();

app.MapGet("/", () => "Hello HTTP.sys");

app.Run();

Изменение корневой папки веб-сайта

По умолчанию корневой каталог веб-приложения задается относительно корневого каталога содержимого в папке wwwroot. Корневой каталог веб-приложения — это место, где middleware статических файлов ищет статические файлы. Корневой веб-сайт можно изменить с помощью WebHostOptions, командной строки или метода UseWebRoot:

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    // Look for static files in webroot
    WebRootPath = "webroot"
});

var app = builder.Build();

app.Run();

Настраиваемый контейнер внедрения зависимостей (DI)

В следующем примере используется Autofac:

var builder = WebApplication.CreateBuilder(args);

builder.Host.UseServiceProviderFactory(new AutofacServiceProviderFactory());

// Register services directly with Autofac here. Don't
// call builder.Populate(), that happens in AutofacServiceProviderFactory.
builder.Host.ConfigureContainer<ContainerBuilder>(builder => builder.RegisterModule(new MyApplicationModule()));

var app = builder.Build();

Добавить промежуточное ПО

Любое существующее ПО промежуточного слоя для ASP.NET Core можно настроить в WebApplication:

var app = WebApplication.Create(args);

// Setup the file server to serve static files.
app.UseFileServer();

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

app.Run();

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

Страница исключения для разработчиков

WebApplication.CreateBuilder инициализирует новый экземпляр класса WebApplicationBuilder с предварительно настроенными значениями по умолчанию. Страница исключений для разработчиков включена в предварительно настроенных параметрах по умолчанию. При выполнении следующего кода в среде разработки переход к адресу / отображает страницу с удобным представлением информации об исключении.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapGet("/", () =>
{
    throw new InvalidOperationException("Oops, the '/' route has thrown an exception.");
});

app.Run();

WebApplication

Шаблон ASP.NET Core создает следующий код:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

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

app.Run();

Приведенный выше код можно создать, набрав dotnet new web в командной строке или выбрав в Visual Studio шаблон пустого веб-проекта.

Следующий код создает WebApplication (app) без явного создания WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.CreateBuilder инициализирует новый экземпляр WebApplicationBuilder класса с предварительно настроенными значениями по умолчанию:

if (isDevelopment)
{
    app.UseDeveloperExceptionPage();
}

app.UseRouting();

if (isAuthenticationConfigured)
{
    app.UseAuthentication();
}

if (isAuthorizationConfigured)
{
    app.UseAuthorization();
}

// User middleware/endpoints
app.CustomMiddleware(...);
app.MapGet("/", () => "hello world");
// End user middleware/endpoints

app.UseEndpoints(e => {});

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

app.Use((context, next) =>
{
    return next(context);
});

app.UseRouting();

// Other middleware and endpoints

app.UseRouting();

app.MapGet("/", () => "hello world");

app.UseEndpoints(e => {});

app.Run(context =>
{
    context.Response.StatusCode = 404;
    return Task.CompletedTask;
});

Работа с портами

Если вы создаете веб-приложение с помощью Visual Studio или dotnet new, автоматически создается файл Properties/launchSettings.json с указанием портов, на которых отвечает это приложение. Запуск приложения из Visual Studio с параметрами портов, представленными в следующих примерах, возвращает диалоговое окно с сообщением об ошибке Unable to connect to web server 'AppName'. Visual Studio возвращает ошибку, так как ожидается порт, указанный в Properties/launchSettings.json, но приложение использует порт, указанный в app.Run("http://localhost:3000"). Выполните в командной строке следующий пример кода для изменения портов.

В следующих разделах задан порт приложения.

var app = WebApplication.Create(args);

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

app.Run("http://localhost:3000");

В приведенном выше коде приложение использует порт 3000.

Несколько портов

В следующем коде приложение отвечает на порт 3000 и 4000:

var app = WebApplication.Create(args);

app.Urls.Add("http://localhost:3000");
app.Urls.Add("http://localhost:4000");

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

app.Run();

Настройка порта из командной строки

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

dotnet run --urls="https://localhost:7777"

Если конечная точка Kestrel также настроена в файле appsettings.json, используется URL-адрес, указанный в файле appsettings.json. Дополнительные сведения см. в разделе Конфигурация конечной точки Kestrel.

Получение порта из среды

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

var app = WebApplication.Create(args);

var port = Environment.GetEnvironmentVariable("PORT") ?? "3000";

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

app.Run($"http://localhost:{port}");

Для настройки порта из среды лучше всего использовать переменную среды ASPNETCORE_URLS, как показано в следующем разделе.

Настройка портов с помощью переменной ASPNETCORE_URLS среды

Для настройки порта существует переменная среды ASPNETCORE_URLS:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS поддерживает несколько URL-адресов:

ASPNETCORE_URLS=http://localhost:3000;https://localhost:5000

Прослушивать все интерфейсы

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

http://*:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://*:3000");

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

app.Run();

http://+:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://+:3000");

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

app.Run();

http://0.0.0.0:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://0.0.0.0:3000");

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

app.Run();

Прослушивание всех интерфейсов с помощью ASPNETCORE_URLS

Приведенные выше примеры могут использовать ASPNETCORE_URLS:

ASPNETCORE_URLS=http://*:3000;https://+:5000;http://0.0.0.0:5005

Прослушивайте все интерфейсы с помощью ASPNETCORE_HTTP_PORTS и ASPNETCORE_HTTPS_PORTS

Приведенные выше примеры также могут использовать ASPNETCORE_HTTP_PORTS и ASPNETCORE_HTTPS_PORTS,но ASPNETCORE_URLS (при установке) переопределяет следующие параметры:

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Дополнительные сведения см. в разделе "Настройка конечных точек для Kestrel веб-сервера".

Выбор протокола HTTPS с сертификатом разработки

var app = WebApplication.Create(args);

app.Urls.Add("https://localhost:3000");

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

app.Run();

Дополнительные сведения о сертификате разработки см. в разделе Доверие к сертификату разработки HTTPS в среде ASP.NET Core на ОС Windows и macOS.

Указать HTTPS с пользовательским сертификатом

В следующих разделах показано, как указать пользовательский сертификат с помощью appsettings.json файла и конфигурации.

Укажите пользовательский сертификат с помощью appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Kestrel": {
    "Certificates": {
      "Default": {
        "Path": "cert.pem",
        "KeyPath": "key.pem"
      }
    }
  }
}

Настройка пользовательского сертификата в конфигурации

var builder = WebApplication.CreateBuilder(args);

// Configure the cert and the key
builder.Configuration["Kestrel:Certificates:Default:Path"] = "cert.pem";
builder.Configuration["Kestrel:Certificates:Default:KeyPath"] = "key.pem";

var app = builder.Build();

app.Urls.Add("https://localhost:3000");

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

app.Run();

Использование API сертификатов

using System.Security.Cryptography.X509Certificates;

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.ConfigureHttpsDefaults(httpsOptions =>
    {
        var certPath = Path.Combine(builder.Environment.ContentRootPath, "cert.pem");
        var keyPath = Path.Combine(builder.Environment.ContentRootPath, "key.pem");

        httpsOptions.ServerCertificate = X509Certificate2.CreateFromPemFile(certPath, 
                                         keyPath);
    });
});

var app = builder.Build();

app.Urls.Add("https://localhost:3000");

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

app.Run();

Чтение данных из среды

var app = WebApplication.Create(args);

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

app.MapGet("/", () => "Hello World");
app.MapGet("/oops", () => "Oops! An error happened.");

app.Run();

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

Configuration

Следующий код считывает данные из системы конфигурации:

var app = WebApplication.Create(args);

var message = app.Configuration["HelloKey"] ?? "Config failed!";

app.MapGet("/", () => message);

app.Run();

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

Logging

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

var app = WebApplication.Create(args);

app.Logger.LogInformation("The app started");

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

app.Run();

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

Откройте контейнер внедрения зависимостей (DI)

В следующем коде показано, как получить службы из контейнера DI во время запуска приложения.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddScoped<SampleService>();

var app = builder.Build();

app.MapControllers();

using (var scope = app.Services.CreateScope())
{
    var sampleService = scope.ServiceProvider.GetRequiredService<SampleService>();
    sampleService.DoSomething();
}

app.Run();

В следующем коде показано, как получить доступ к ключам из контейнера DI с помощью атрибута[FromKeyedServices]:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddKeyedSingleton<ICache, BigCache>("big");
builder.Services.AddKeyedSingleton<ICache, SmallCache>("small");

var app = builder.Build();

app.MapGet("/big", ([FromKeyedServices("big")] ICache bigCache) => bigCache.Get("date"));

app.MapGet("/small", ([FromKeyedServices("small")] ICache smallCache) => smallCache.Get("date"));

app.Run();

public interface ICache
{
    object Get(string key);
}
public class BigCache : ICache
{
    public object Get(string key) => $"Resolving {key} from big cache.";
}

public class SmallCache : ICache
{
    public object Get(string key) => $"Resolving {key} from small cache.";
}

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

WebApplicationBuilder

В этом разделе содержится пример кода с использованием WebApplicationBuilder.

Изменение корневой папки содержимого, имени приложения и среды

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

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    ApplicationName = typeof(Program).Assembly.FullName,
    ContentRootPath = Directory.GetCurrentDirectory(),
    EnvironmentName = Environments.Staging,
    WebRootPath = "customwwwroot"
});

Console.WriteLine($"Application Name: {builder.Environment.ApplicationName}");
Console.WriteLine($"Environment Name: {builder.Environment.EnvironmentName}");
Console.WriteLine($"ContentRoot Path: {builder.Environment.ContentRootPath}");
Console.WriteLine($"WebRootPath: {builder.Environment.WebRootPath}");

var app = builder.Build();

WebApplication.Create инициализирует новый экземпляр класса WebApplication с предварительно настроенными значениями по умолчанию.

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

Изменение корневого каталога содержимого, имени приложения и среды с помощью переменных среды или командной строки

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

Добавить поставщиков конфигурации

В следующем примере добавляется поставщик конфигурации INI:

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddIniFile("appsettings.ini");

var app = builder.Build();

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

Конфигурация чтения

По умолчанию WebApplicationBuilder считывает конфигурацию из нескольких источников, в том числе:

• appSettings.json и appSettings.{environment}.json.
• Переменные среды
• Командная строка

Полный список источников конфигурации см. в разделе "Конфигурация по умолчанию" в ASP.NET Core.

Следующий код считывает из конфигурации значение HelloKey и отображает его в конечной точке /. Если значение конфигурации равно null, message присваивается значение "Hello":

var builder = WebApplication.CreateBuilder(args);

var message = builder.Configuration["HelloKey"] ?? "Hello";

var app = builder.Build();

app.MapGet("/", () => message);

app.Run();

Чтение данных из среды

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsDevelopment())
{
    Console.WriteLine($"Running in development.");
}

var app = builder.Build();

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

app.Run();

Добавить поставщиков журналирования

var builder = WebApplication.CreateBuilder(args);

// Configure JSON logging to the console.
builder.Logging.AddJsonConsole();

var app = builder.Build();

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

app.Run();

Добавление служб

var builder = WebApplication.CreateBuilder(args);

// Add the memory cache services.
builder.Services.AddMemoryCache();

// Add a custom scoped service.
builder.Services.AddScoped<ITodoRepository, TodoRepository>();
var app = builder.Build();

Настройте IHostBuilder

К существующим методам расширения IHostBuilder можно обращаться через свойство Host.

var builder = WebApplication.CreateBuilder(args);

// Wait 30 seconds for graceful shutdown.
builder.Host.ConfigureHostOptions(o => o.ShutdownTimeout = TimeSpan.FromSeconds(30));

var app = builder.Build();

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

app.Run();

Настройте IWebHostBuilder

Доступ к методам расширения для IWebHostBuilder можно получить с помощью свойства WebApplicationBuilder.WebHost.

var builder = WebApplication.CreateBuilder(args);

// Change the HTTP server implemenation to be HTTP.sys based
builder.WebHost.UseHttpSys();

var app = builder.Build();

app.MapGet("/", () => "Hello HTTP.sys");

app.Run();

Изменение корневой папки веб-сайта

По умолчанию корневой каталог веб-приложения задается относительно корневого каталога содержимого в папке wwwroot. Корневой каталог веб-приложения — это место, где middleware статических файлов ищет статические файлы. Корневой веб-сайт можно изменить с помощью WebHostOptions, командной строки или метода UseWebRoot:

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    // Look for static files in webroot
    WebRootPath = "webroot"
});

var app = builder.Build();

app.Run();

Настраиваемый контейнер внедрения зависимостей (DI)

В следующем примере используется Autofac:

var builder = WebApplication.CreateBuilder(args);

builder.Host.UseServiceProviderFactory(new AutofacServiceProviderFactory());

// Register services directly with Autofac here. Don't
// call builder.Populate(), that happens in AutofacServiceProviderFactory.
builder.Host.ConfigureContainer<ContainerBuilder>(builder => builder.RegisterModule(new MyApplicationModule()));

var app = builder.Build();

Добавить промежуточное ПО

Любое существующее ПО промежуточного слоя для ASP.NET Core можно настроить в WebApplication:

var app = WebApplication.Create(args);

// Setup the file server to serve static files.
app.UseFileServer();

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

app.Run();

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

Страница исключения для разработчиков

WebApplication.CreateBuilder инициализирует новый экземпляр класса WebApplicationBuilder с предварительно настроенными значениями по умолчанию. Страница исключений для разработчиков включена в предварительно настроенных параметрах по умолчанию. При выполнении следующего кода в среде разработки переход к адресу / отображает страницу с удобным представлением информации об исключении.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapGet("/", () =>
{
    throw new InvalidOperationException("Oops, the '/' route has thrown an exception.");
});

app.Run();

WebApplication

Шаблон ASP.NET Core создает следующий код:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

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

app.Run();

Приведенный выше код можно создать, набрав dotnet new web в командной строке или выбрав в Visual Studio шаблон пустого веб-проекта.

Следующий код создает WebApplication (app) без явного создания WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.CreateBuilder инициализирует новый экземпляр WebApplicationBuilder класса с предварительно настроенными значениями по умолчанию:

if (isDevelopment)
{
    app.UseDeveloperExceptionPage();
}

app.UseRouting();

if (isAuthenticationConfigured)
{
    app.UseAuthentication();
}

if (isAuthorizationConfigured)
{
    app.UseAuthorization();
}

// User middleware/endpoints
app.CustomMiddleware(...);
app.MapGet("/", () => "hello world");
// End user middleware/endpoints

app.UseEndpoints(e => {});

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

app.Use((context, next) =>
{
    return next(context);
});

app.UseRouting();

// Other middleware and endpoints

app.UseRouting();

app.MapGet("/", () => "hello world");

app.UseEndpoints(e => {});

app.Run(context =>
{
    context.Response.StatusCode = 404;
    return Task.CompletedTask;
});

Работа с портами

Если вы создаете веб-приложение с помощью Visual Studio или dotnet new, автоматически создается файл Properties/launchSettings.json с указанием портов, на которых отвечает это приложение. Запуск приложения из Visual Studio с параметрами портов, представленными в следующих примерах, возвращает диалоговое окно с сообщением об ошибке Unable to connect to web server 'AppName'. Visual Studio возвращает ошибку, так как ожидается порт, указанный в Properties/launchSettings.json, но приложение использует порт, указанный в app.Run("http://localhost:3000"). Выполните в командной строке следующий пример кода для изменения портов.

В следующих разделах задан порт приложения.

var app = WebApplication.Create(args);

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

app.Run("http://localhost:3000");

В приведенном выше коде приложение использует порт 3000.

Несколько портов

В следующем коде приложение отвечает на порт 3000 и 4000:

var app = WebApplication.Create(args);

app.Urls.Add("http://localhost:3000");
app.Urls.Add("http://localhost:4000");

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

app.Run();

Настройка порта из командной строки

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

dotnet run --urls="https://localhost:7777"

Если конечная точка Kestrel также настроена в файле appsettings.json, используется URL-адрес, указанный в файле appsettings.json. Дополнительные сведения см. в разделе Конфигурация конечной точки Kestrel.

Получение порта из среды

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

var app = WebApplication.Create(args);

var port = Environment.GetEnvironmentVariable("PORT") ?? "3000";

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

app.Run($"http://localhost:{port}");

Для настройки порта из среды лучше всего использовать переменную среды ASPNETCORE_URLS, как показано в следующем разделе.

Настройка портов с помощью переменной ASPNETCORE_URLS среды

Для настройки порта существует переменная среды ASPNETCORE_URLS:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS поддерживает несколько URL-адресов:

ASPNETCORE_URLS=http://localhost:3000;https://localhost:5000

Прослушивать все интерфейсы

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

http://*:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://*:3000");

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

app.Run();

http://+:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://+:3000");

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

app.Run();

http://0.0.0.0:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://0.0.0.0:3000");

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

app.Run();

Прослушивание всех интерфейсов с помощью ASPNETCORE_URLS

Приведенные выше примеры могут использовать ASPNETCORE_URLS:

ASPNETCORE_URLS=http://*:3000;https://+:5000;http://0.0.0.0:5005

Прослушивание всех интерфейсов с помощью ASPNETCORE_HTTP_PORTS и ASPNETCORE_HTTPS_PORTS

Приведенные выше примеры также могут использовать ASPNETCORE_HTTP_PORTS и ASPNETCORE_HTTPS_PORTS,но ASPNETCORE_URLS (при установке) переопределяет следующие параметры:

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Дополнительные сведения см. в разделе "Настройка конечных точек для Kestrel веб-сервера".

Выбор протокола HTTPS с сертификатом разработки

var app = WebApplication.Create(args);

app.Urls.Add("https://localhost:3000");

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

app.Run();

Дополнительные сведения о сертификате разработки см. в разделе Доверие к сертификату разработки HTTPS в среде ASP.NET Core на ОС Windows и macOS.

Указать HTTPS с пользовательским сертификатом

В следующих разделах показано, как указать пользовательский сертификат с помощью appsettings.json файла и конфигурации.

Укажите пользовательский сертификат с помощью appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Kestrel": {
    "Certificates": {
      "Default": {
        "Path": "cert.pem",
        "KeyPath": "key.pem"
      }
    }
  }
}

Настройка пользовательского сертификата в конфигурации

var builder = WebApplication.CreateBuilder(args);

// Configure the cert and the key
builder.Configuration["Kestrel:Certificates:Default:Path"] = "cert.pem";
builder.Configuration["Kestrel:Certificates:Default:KeyPath"] = "key.pem";

var app = builder.Build();

app.Urls.Add("https://localhost:3000");

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

app.Run();

Использование API сертификатов

using System.Security.Cryptography.X509Certificates;

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.ConfigureHttpsDefaults(httpsOptions =>
    {
        var certPath = Path.Combine(builder.Environment.ContentRootPath, "cert.pem");
        var keyPath = Path.Combine(builder.Environment.ContentRootPath, "key.pem");

        httpsOptions.ServerCertificate = X509Certificate2.CreateFromPemFile(certPath, 
                                         keyPath);
    });
});

var app = builder.Build();

app.Urls.Add("https://localhost:3000");

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

app.Run();

Чтение данных из среды

var app = WebApplication.Create(args);

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

app.MapGet("/", () => "Hello World");
app.MapGet("/oops", () => "Oops! An error happened.");

app.Run();

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

Configuration

Следующий код считывает данные из системы конфигурации:

var app = WebApplication.Create(args);

var message = app.Configuration["HelloKey"] ?? "Config failed!";

app.MapGet("/", () => message);

app.Run();

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

Logging

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

var app = WebApplication.Create(args);

app.Logger.LogInformation("The app started");

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

app.Run();

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

Откройте контейнер внедрения зависимостей (DI)

В следующем коде показано, как получить службы из контейнера DI во время запуска приложения.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddScoped<SampleService>();

var app = builder.Build();

app.MapControllers();

using (var scope = app.Services.CreateScope())
{
    var sampleService = scope.ServiceProvider.GetRequiredService<SampleService>();
    sampleService.DoSomething();
}

app.Run();

В следующем коде показано, как получить доступ к ключам из контейнера DI с помощью атрибута[FromKeyedServices]:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddKeyedSingleton<ICache, BigCache>("big");
builder.Services.AddKeyedSingleton<ICache, SmallCache>("small");

var app = builder.Build();

app.MapGet("/big", ([FromKeyedServices("big")] ICache bigCache) => bigCache.Get("date"));

app.MapGet("/small", ([FromKeyedServices("small")] ICache smallCache) => smallCache.Get("date"));

app.Run();

public interface ICache
{
    object Get(string key);
}
public class BigCache : ICache
{
    public object Get(string key) => $"Resolving {key} from big cache.";
}

public class SmallCache : ICache
{
    public object Get(string key) => $"Resolving {key} from small cache.";
}

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

WebApplicationBuilder

В этом разделе содержится пример кода с использованием WebApplicationBuilder.

Изменение корневой папки содержимого, имени приложения и среды

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

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    ApplicationName = typeof(Program).Assembly.FullName,
    ContentRootPath = Directory.GetCurrentDirectory(),
    EnvironmentName = Environments.Staging,
    WebRootPath = "customwwwroot"
});

Console.WriteLine($"Application Name: {builder.Environment.ApplicationName}");
Console.WriteLine($"Environment Name: {builder.Environment.EnvironmentName}");
Console.WriteLine($"ContentRoot Path: {builder.Environment.ContentRootPath}");
Console.WriteLine($"WebRootPath: {builder.Environment.WebRootPath}");

var app = builder.Build();

WebApplication.Create инициализирует новый экземпляр класса WebApplication с предварительно настроенными значениями по умолчанию.

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

Изменение корневого каталога содержимого, имени приложения и среды с помощью переменных среды или командной строки

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

Добавить поставщиков конфигурации

В следующем примере добавляется поставщик конфигурации INI:

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddIniFile("appsettings.ini");

var app = builder.Build();

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

Конфигурация чтения

По умолчанию WebApplicationBuilder считывает конфигурацию из нескольких источников, в том числе:

• appSettings.json и appSettings.{environment}.json.
• Переменные среды
• Командная строка

Полный список источников конфигурации см. в разделе "Конфигурация по умолчанию" в ASP.NET Core.

Следующий код считывает из конфигурации значение HelloKey и отображает его в конечной точке /. Если значение конфигурации равно null, message присваивается значение "Hello":

var builder = WebApplication.CreateBuilder(args);

var message = builder.Configuration["HelloKey"] ?? "Hello";

var app = builder.Build();

app.MapGet("/", () => message);

app.Run();

Чтение данных из среды

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsDevelopment())
{
    Console.WriteLine($"Running in development.");
}

var app = builder.Build();

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

app.Run();

Добавить поставщиков журналирования

var builder = WebApplication.CreateBuilder(args);

// Configure JSON logging to the console.
builder.Logging.AddJsonConsole();

var app = builder.Build();

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

app.Run();

Добавление служб

var builder = WebApplication.CreateBuilder(args);

// Add the memory cache services.
builder.Services.AddMemoryCache();

// Add a custom scoped service.
builder.Services.AddScoped<ITodoRepository, TodoRepository>();
var app = builder.Build();

Настройте IHostBuilder

К существующим методам расширения IHostBuilder можно обращаться через свойство Host.

var builder = WebApplication.CreateBuilder(args);

// Wait 30 seconds for graceful shutdown.
builder.Host.ConfigureHostOptions(o => o.ShutdownTimeout = TimeSpan.FromSeconds(30));

var app = builder.Build();

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

app.Run();

Настройте IWebHostBuilder

К методам расширения для IWebHostBuilder можно получить доступ с помощью свойства WebApplicationBuilder.WebHost.

var builder = WebApplication.CreateBuilder(args);

// Change the HTTP server implemenation to be HTTP.sys based
builder.WebHost.UseHttpSys();

var app = builder.Build();

app.MapGet("/", () => "Hello HTTP.sys");

app.Run();

Изменение корневой папки веб-сайта

По умолчанию корневой каталог веб-приложения задается относительно корневого каталога содержимого в папке wwwroot. Корневой каталог веб-приложения — это место, где middleware статических файлов ищет статические файлы. Корневой веб-сайт можно изменить с помощью WebHostOptions, командной строки или метода UseWebRoot:

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    // Look for static files in webroot
    WebRootPath = "webroot"
});

var app = builder.Build();

app.Run();

Настраиваемый контейнер внедрения зависимостей (DI)

В следующем примере используется Autofac:

var builder = WebApplication.CreateBuilder(args);

builder.Host.UseServiceProviderFactory(new AutofacServiceProviderFactory());

// Register services directly with Autofac here. Don't
// call builder.Populate(), that happens in AutofacServiceProviderFactory.
builder.Host.ConfigureContainer<ContainerBuilder>(builder => builder.RegisterModule(new MyApplicationModule()));

var app = builder.Build();

Добавить промежуточное ПО

Любое существующее ПО промежуточного слоя для ASP.NET Core можно настроить в WebApplication:

var app = WebApplication.Create(args);

// Setup the file server to serve static files.
app.UseFileServer();

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

app.Run();

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

Страница исключения для разработчиков

WebApplication.CreateBuilder инициализирует новый экземпляр класса WebApplicationBuilder с предварительно настроенными значениями по умолчанию. Страница исключений для разработчиков включена в предварительно настроенных параметрах по умолчанию. При выполнении следующего кода в среде разработки переход к адресу / отображает страницу с удобным представлением информации об исключении.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapGet("/", () =>
{
    throw new InvalidOperationException("Oops, the '/' route has thrown an exception.");
});

app.Run();