WebApplication i WebApplicationBuilder w minimalnych aplikacjach interfejsu API

WebApplication

Następujący kod jest generowany przez szablon ASP.NET Core:

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

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

app.Run();

Powyższy kod można utworzyć za pomocą wiersza dotnet new web polecenia lub wybrać pusty szablon sieci Web w programie Visual Studio.

Poniższy kod tworzy element WebApplication (app) bez jawnego utworzenia elementu WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.Create Inicjuje nowe wystąpienie WebApplication klasy ze wstępnie skonfigurowanymi wartościami domyślnymi.

Praca z portami

Po utworzeniu aplikacji internetowej za pomocą programu Visual Studio lub dotnet newProperties/launchSettings.json zostanie utworzony plik, który określa porty, na które odpowiada aplikacja. W poniższych przykładach ustawień portów uruchomienie aplikacji z programu Visual Studio zwraca okno dialogowe Unable to connect to web server 'AppName'błędu . Program Visual Studio zwraca błąd, ponieważ oczekuje portu określonego w Properties/launchSettings.jsonelemecie , ale aplikacja używa portu określonego przez app.Run("http://localhost:3000"). Uruchom następujący port, zmieniając przykłady z wiersza polecenia.

W poniższych sekcjach ustawiono port, na który odpowiada aplikacja.

var app = WebApplication.Create(args);

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

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

W poprzednim kodzie aplikacja odpowiada na port 3000.

Wiele portów

W poniższym kodzie aplikacja odpowiada na port 3000 i 4000.

var app = WebApplication.Create(args);

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

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

app.Run();

Ustawianie portu z wiersza polecenia

Następujące polecenie powoduje, że aplikacja odpowiada na port 7777:

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

Kestrel Jeśli punkt końcowy jest również skonfigurowany w appsettings.json pliku, appsettings.json używany jest określony adres URL. Aby uzyskać więcej informacji, zobacz Kestrel Konfiguracja punktu końcowego

Odczytywanie portu ze środowiska

Poniższy kod odczytuje port ze środowiska:

var app = WebApplication.Create(args);

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

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

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

Preferowanym sposobem ustawienia portu ze środowiska jest użycie ASPNETCORE_URLS zmiennej środowiskowej, która jest pokazana w poniższej sekcji.

Ustawianie portów za pomocą zmiennej środowiskowej ASPNETCORE_URLS

Zmienna ASPNETCORE_URLS środowiskowa jest dostępna do ustawienia portu:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS obsługuje wiele adresów URL:

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

Nasłuchiwanie we wszystkich interfejsach

W poniższych przykładach pokazano nasłuchiwanie we wszystkich interfejsach

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

Nasłuchiwanie we wszystkich interfejsach przy użyciu ASPNETCORE_URLS

Powyższe przykłady mogą być używane ASPNETCORE_URLS

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

Nasłuchiwanie we wszystkich interfejsach przy użyciu ASPNETCORE_HTTPS_PORTS

Powyższe przykłady mogą używać elementów ASPNETCORE_HTTPS_PORTS i ASPNETCORE_HTTP_PORTS.

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Aby uzyskać więcej informacji, zobacz Konfigurowanie punktów końcowych dla serwera internetowego platformy ASP.NET Core Kestrel

Określanie protokołu HTTPS przy użyciu certyfikatu programistycznego

var app = WebApplication.Create(args);

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

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

app.Run();

Aby uzyskać więcej informacji na temat certyfikatu programistycznego, zobacz Trust the ASP.NET Core HTTPS development certificate on Windows and macOS (Ufaj certyfikatowi programistycznemu ASP.NET Core HTTPS w systemach Windows i macOS).

Określanie protokołu HTTPS przy użyciu certyfikatu niestandardowego

W poniższych sekcjach pokazano, jak określić certyfikat niestandardowy przy użyciu appsettings.json pliku i za pośrednictwem konfiguracji.

Określanie certyfikatu niestandardowego za pomocą polecenia appsettings.json

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

Określanie certyfikatu niestandardowego za pomocą konfiguracji

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

Korzystanie z interfejsów API certyfikatów

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

Odczytywanie środowiska

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

Aby uzyskać więcej informacji na temat korzystania ze środowiska, zobacz Use multiple environments in ASP.NET Core (Używanie wielu środowisk w środowisku ASP.NET Core)

Konfigurowanie

Poniższy kod odczytuje z systemu konfiguracji:

var app = WebApplication.Create(args);

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

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

app.Run();

Aby uzyskać więcej informacji, zobacz Configuration in ASP.NET Core (Konfiguracja w programie ASP.NET Core)

Rejestrowanie

Poniższy kod zapisuje komunikat podczas uruchamiania aplikacji logowania:

var app = WebApplication.Create(args);

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

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

app.Run();

Aby uzyskać więcej informacji, zobacz Rejestrowanie na platformie .NET Core i ASP.NET Core

Uzyskiwanie dostępu do kontenera wstrzykiwania zależności (DI)

Poniższy kod pokazuje, jak pobrać usługi z kontenera DI podczas uruchamiania aplikacji:

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

Poniższy kod pokazuje, jak uzyskać dostęp do kluczy z kontenera DI przy użyciu atrybutu [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.";
}

Aby uzyskać więcej informacji na temat di, zobacz Wstrzykiwanie zależności w ASP.NET Core.

WebApplicationBuilder

Ta sekcja zawiera przykładowy kod przy użyciu polecenia WebApplicationBuilder.

Zmienianie katalogu głównego zawartości, nazwy aplikacji i środowiska

Poniższy kod ustawia katalog główny zawartości, nazwę aplikacji i środowisko:

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 inicjuje nowe wystąpienie klasy WebApplicationBuilder ze wstępnie skonfigurowanymi wartościami domyślnymi.

Aby uzyskać więcej informacji, zobacz omówienie podstaw platformy ASP.NET Core

Zmienianie katalogu głównego zawartości, nazwy aplikacji i środowiska przy użyciu zmiennych środowiskowych lub wiersza polecenia

W poniższej tabeli przedstawiono zmienną środowiskową i argument wiersza polecenia używany do zmiany katalogu głównego zawartości, nazwy aplikacji i środowiska:

funkcja	Zmienna środowiskowa	Argument wiersza polecenia
Nazwa aplikacji	ASPNETCORE_APPLICATIONNAME	--applicationName
Nazwa środowiska	ASPNETCORE_ENVIRONMENT	--środowisko
Katalog główny zawartości	ASPNETCORE_CONTENTROOT	--contentRoot

Dodawanie dostawców konfiguracji

Poniższy przykład dodaje dostawcę konfiguracji INI:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Aby uzyskać szczegółowe informacje, zobacz Dostawcy konfiguracji plików w konfiguracji w programie ASP.NET Core.

Konfiguracja odczytu

Domyślnie WebApplicationBuilder konfiguracja odczytu z wielu źródeł, w tym:

• appSettings.json i appSettings.{environment}.json
• Zmienne środowiskowe
• Wiersz polecenia

Aby uzyskać pełną listę źródeł konfiguracji, zobacz Konfiguracja domyślna w konfiguracji w programie ASP.NET Core.

Poniższy kod odczytuje HelloKey z konfiguracji i wyświetla wartość w punkcie / końcowym. Jeśli wartość konfiguracji ma wartość null, "Hello" zostanie przypisana do elementu message:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Odczytywanie środowiska

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Dodawanie dostawców rejestrowania

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

Dodawanie usług

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

Dostosowywanie elementu IHostBuilder

Dostęp do istniejących metod rozszerzeń IHostBuilder można uzyskać przy użyciu właściwości 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();

Dostosowywanie obiektu IWebHostBuilder

Dostęp do metod rozszerzeń IWebHostBuilder można uzyskać przy użyciu właściwości 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();

Zmienianie katalogu głównego sieci Web

Domyślnie katalog główny sieci Web jest powiązany z katalogem głównym zawartości w folderze wwwroot . Katalog główny sieci Web to miejsce, w którym oprogramowanie pośredniczące plików statycznych szuka plików statycznych. Katalog główny sieci Web można zmienić za pomocą WebHostOptionspolecenia , wiersza polecenia lub UseWebRoot metody :

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

var app = builder.Build();

app.Run();

Niestandardowy kontener wstrzykiwania zależności (DI)

W poniższym przykładzie użyto funkcji 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();

Dodawanie oprogramowania pośredniczącego

W programie WebApplicationmożna skonfigurować dowolne istniejące oprogramowanie pośredniczące ASP.NET Core:

var app = WebApplication.Create(args);

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

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

app.Run();

Aby uzyskać więcej informacji, zobacz ASP.NET Core Middleware

Strona wyjątku dla deweloperów

WebApplication.CreateBuilder Inicjuje nowe wystąpienie WebApplicationBuilder klasy ze wstępnie skonfigurowanymi wartościami domyślnymi. Strona wyjątku dewelopera jest włączona w wstępnie skonfigurowanych wartościach domyślnych. Po uruchomieniu następującego kodu w środowisku deweloperskim przejście do / strony renderuje przyjazną stronę, która pokazuje wyjątek.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();