WebApplication и WebApplicationBuilder в минимальных приложениях API

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.Create инициализирует новый экземпляр класса WebApplication с предварительно настроенными значениями по умолчанию.

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

Если вы создаете веб-приложение с помощью 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"

Если в файле appsettings.json настроена еще и конечная точка Kestrel, то используется файл с 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_HTTPS_PORTS

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

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Дополнительные сведения см. в разделе "Настройка конечных точек" для веб-сервера ASP.NET Core 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.

Настройка

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

var app = WebApplication.Create(args);

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

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

app.Run();

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

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

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

var app = WebApplication.Create(args);

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

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

app.Run();

Дополнительные сведения см. в статье Ведение журнала в .NET Core и 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.CreateBuilder инициализирует новый экземпляр класса WebApplicationBuilder с предварительно настроенными значениями по умолчанию.

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

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

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

функция	Переменная среды	Аргумент командной строки
Имя приложения	ASPNETCORE_APPLICATIONNAME	--applicationName
Имя среды	ASPNETCORE_ENVIRONMENT	--environment
Корневой каталог содержимого	ASPNETCORE_CONTENTROOT	--contentRoot

Все поставщики конфигурации

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