WebApplication i WebApplicationBuilder w aplikacjach ASP.NET Core

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

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

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 przedstawionych poniżej przykładach konfiguracji portów uruchomienie aplikacji z programu Visual Studio powoduje wyświetlenie okna dialogowego błędu Unable to connect to web server 'AppName'. Program Visual Studio zwraca błąd, ponieważ oczekuje portu określonego w elemencie Properties/launchSettings.json, ale aplikacja używa portu określonego w app.Run("http://localhost:3000"). Uruchom poniższe przykłady zmiany portu z poziomu wiersza polecenia.

W poniższych sekcjach ustawiono port aplikacji.

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"

Jeśli punkt końcowy Kestrel jest również skonfigurowany w pliku appsettings.json, używany jest adres URL określony w pliku appsettings.json. 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 pośrednictwem 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

Aby uzyskać więcej informacji na temat korzystania ze środowiska, zobacz ASP.NET Core środowiska uruchomieniowe.

Nasłuchuj na 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łuchuj na wszystkich interfejsach, używając ASPNETCORE_URLS

W powyższych przykładach można użyć ASPNETCORE_URLS:

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

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

Używaj 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();

Configuration

Poniższy kod odczytuje dane 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 Konfiguracja na platformie ASP.NET Core.

Logging

Poniższy kod zapisuje komunikat w dzienniku podczas uruchamiania aplikacji:

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 i ASP.NET Core.

Uzyskaj dostęp do kontenera iniekcji 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();

Aby uzyskać więcej informacji, zobacz Wstrzykiwanie zależności na platformie 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.Create Inicjuje nowe wystąpienie WebApplication klasy 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 według 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.

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 opartych na plikach w artykule Konfiguracja w ASP.NET Core.

Odczytaj konfigurację

Domyślnie element WebApplicationBuilder odczytuje konfigurację z wielu źródeł, w tym:

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

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

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

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

Dostosuj IHostBuilder

Dostęp do istniejących metod rozszerzających dla IHostBuilder można uzyskać za pomocą 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();

Dostosuj IWebHostBuilder

Dostęp do metod rozszerzających w elemencie IWebHostBuilder można uzyskać za pomocą 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 aplikacji internetowej to katalog, w którym middleware obsługujące pliki statyczne szuka plików statycznych. Katalog główny witryny sieci Web można zmienić za pomocą WebHostOptions, z poziomu wiersza polecenia lub za pomocą metody UseWebRoot:

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 oprogramowanie pośredniczące.

Strona wyjątku dla deweloperów

WebApplication.CreateBuilder Inicjuje nowe wystąpienie WebApplicationBuilder klasy ze wstępnie skonfigurowanymi wartościami domyślnymi. Strona wyjątków dla deweloperów jest włączona w prekonfigurowanych ustawieniach domyślnych. Po uruchomieniu następującego kodu w środowisku deweloperskim przejście do / powoduje wyświetlenie przyjaznej strony, która wyświetla 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();

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

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

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 przedstawionych poniżej przykładach konfiguracji portów uruchomienie aplikacji z programu Visual Studio powoduje wyświetlenie okna dialogowego błędu Unable to connect to web server 'AppName'. Program Visual Studio zwraca błąd, ponieważ oczekuje portu określonego w elemencie Properties/launchSettings.json, ale aplikacja używa portu określonego w app.Run("http://localhost:3000"). Uruchom poniższe przykłady zmiany portu z poziomu wiersza polecenia.

W poniższych sekcjach ustawiono port aplikacji.

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"

Jeśli punkt końcowy Kestrel jest również skonfigurowany w pliku appsettings.json, używany jest adres URL określony w pliku appsettings.json. 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 pośrednictwem 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łuchuj na 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łuchuj na wszystkich interfejsach, używając ASPNETCORE_URLS

W powyższych przykładach można użyć ASPNETCORE_URLS:

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

Nasłuchuj na wszystkich interfejsach, używając ASPNETCORE_HTTP_PORTS i ASPNETCORE_HTTPS_PORTS

Powyższe przykłady mogą również używać parametrów ASPNETCORE_HTTP_PORTS i ASPNETCORE_HTTPS_PORTS, ale ASPNETCORE_URLS (po ustawieniu) zastępuje następujące ustawienia:

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

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

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

Używaj 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();

Odczytaj środowisko

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 ASP.NET Core środowiska uruchomieniowe.

Configuration

Poniższy kod odczytuje dane 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 Konfiguracja na platformie ASP.NET Core.

Logging

Poniższy kod zapisuje komunikat w dzienniku podczas uruchamiania aplikacji:

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 i ASP.NET Core.

Uzyskaj dostęp do kontenera iniekcji 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.Create Inicjuje nowe wystąpienie WebApplication klasy 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.

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 opartych na plikach w artykule Konfiguracja w ASP.NET Core.

Odczytaj konfigurację

Domyślnie element WebApplicationBuilder odczytuje konfigurację z wielu źródeł, w tym:

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

Aby uzyskać pełną listę odczytywanych źródeł konfiguracji, przeczytaj temat Konfiguracja domyślna w artykule Konfiguracja 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();

Odczytaj środowisko

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

Dostosuj IHostBuilder

Dostęp do istniejących metod rozszerzających dla IHostBuilder można uzyskać za pomocą 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();

Dostosuj IWebHostBuilder

Dostęp do metod rozszerzających w elemencie IWebHostBuilder można uzyskać za pomocą 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 aplikacji internetowej to katalog, w którym middleware obsługujące pliki statyczne szuka plików statycznych. Katalog główny witryny sieci Web można zmienić za pomocą WebHostOptions, z poziomu wiersza polecenia lub za pomocą metody UseWebRoot:

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 oprogramowanie pośredniczące.

Strona wyjątku dla deweloperów

WebApplication.CreateBuilder Inicjuje nowe wystąpienie WebApplicationBuilder klasy ze wstępnie skonfigurowanymi wartościami domyślnymi. Strona wyjątków dla deweloperów jest włączona w prekonfigurowanych ustawieniach domyślnych. Po uruchomieniu następującego kodu w środowisku deweloperskim przejście do / powoduje wyświetlenie przyjaznej strony, która wyświetla 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();

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

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

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 przedstawionych poniżej przykładach konfiguracji portów uruchomienie aplikacji z programu Visual Studio powoduje wyświetlenie okna dialogowego błędu Unable to connect to web server 'AppName'. Program Visual Studio zwraca błąd, ponieważ oczekuje portu określonego w elemencie Properties/launchSettings.json, ale aplikacja używa portu określonego w app.Run("http://localhost:3000"). Uruchom poniższe przykłady zmiany portu z poziomu wiersza polecenia.

W poniższych sekcjach ustawiono port aplikacji.

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"

Jeśli punkt końcowy Kestrel jest również skonfigurowany w pliku appsettings.json, używany jest adres URL określony w pliku appsettings.json. 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 pośrednictwem 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łuchuj na 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łuchuj na wszystkich interfejsach, używając ASPNETCORE_URLS

W powyższych przykładach można użyć ASPNETCORE_URLS:

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

Nasłuchuj na wszystkich interfejsach, używając ASPNETCORE_HTTP_PORTS i ASPNETCORE_HTTPS_PORTS

Powyższe przykłady mogą również używać parametrów ASPNETCORE_HTTP_PORTS i ASPNETCORE_HTTPS_PORTS, ale ASPNETCORE_URLS (po ustawieniu) zastępuje następujące ustawienia:

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

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

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

Używaj 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();

Odczytaj środowisko

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 ASP.NET Core środowiska uruchomieniowe.

Configuration

Poniższy kod odczytuje dane 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 Konfiguracja na platformie ASP.NET Core.

Logging

Poniższy kod zapisuje komunikat w dzienniku podczas uruchamiania aplikacji:

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 i ASP.NET Core.

Uzyskaj dostęp do kontenera iniekcji 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.Create Inicjuje nowe wystąpienie WebApplication klasy 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.

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 opartych na plikach w artykule Konfiguracja w ASP.NET Core.

Odczytaj konfigurację

Domyślnie element WebApplicationBuilder odczytuje konfigurację z wielu źródeł, w tym:

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

Aby uzyskać pełną listę odczytywanych źródeł konfiguracji, przeczytaj temat Konfiguracja domyślna w artykule Konfiguracja 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();

Odczytaj środowisko

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

Dostosuj IHostBuilder

Dostęp do istniejących metod rozszerzających dla IHostBuilder można uzyskać za pomocą 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();

Dostosuj IWebHostBuilder

Dostęp do metod rozszerzających w elemencie IWebHostBuilder można uzyskać za pomocą 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 aplikacji internetowej to katalog, w którym middleware obsługujące pliki statyczne szuka plików statycznych. Katalog główny witryny sieci Web można zmienić za pomocą WebHostOptions, z poziomu wiersza polecenia lub za pomocą metody UseWebRoot:

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 oprogramowanie pośredniczące.

Strona wyjątku dla deweloperów

WebApplication.CreateBuilder Inicjuje nowe wystąpienie WebApplicationBuilder klasy ze wstępnie skonfigurowanymi wartościami domyślnymi. Strona wyjątków dla deweloperów jest włączona w prekonfigurowanych ustawieniach domyślnych. Po uruchomieniu następującego kodu w środowisku deweloperskim przejście do / powoduje wyświetlenie przyjaznej strony, która wyświetla 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();

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

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

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 przedstawionych poniżej przykładach konfiguracji portów uruchomienie aplikacji z programu Visual Studio powoduje wyświetlenie okna dialogowego błędu Unable to connect to web server 'AppName'. Program Visual Studio zwraca błąd, ponieważ oczekuje portu określonego w elemencie Properties/launchSettings.json, ale aplikacja używa portu określonego w app.Run("http://localhost:3000"). Uruchom poniższe przykłady zmiany portu z poziomu wiersza polecenia.

W poniższych sekcjach ustawiono port aplikacji.

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"

Jeśli punkt końcowy Kestrel jest również skonfigurowany w pliku appsettings.json, używany jest adres URL określony w pliku appsettings.json. 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 pośrednictwem 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łuchuj na 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łuchuj na wszystkich interfejsach, używając ASPNETCORE_URLS

W powyższych przykładach można użyć ASPNETCORE_URLS:

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

Nasłuchuj na wszystkich interfejsach, używając ASPNETCORE_HTTP_PORTS i ASPNETCORE_HTTPS_PORTS

Powyższe przykłady mogą również używać parametrów ASPNETCORE_HTTP_PORTS i ASPNETCORE_HTTPS_PORTS, ale ASPNETCORE_URLS (po ustawieniu) zastępuje następujące ustawienia:

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

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

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

Używaj 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();

Odczytaj środowisko

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 ASP.NET Core środowiska uruchomieniowe.

Configuration

Poniższy kod odczytuje dane 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 Konfiguracja na platformie ASP.NET Core.

Logging

Poniższy kod zapisuje komunikat w dzienniku podczas uruchamiania aplikacji:

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 i ASP.NET Core.

Uzyskaj dostęp do kontenera iniekcji 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.Create Inicjuje nowe wystąpienie WebApplication klasy 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.

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 opartych na plikach w artykule Konfiguracja w ASP.NET Core.

Odczytaj konfigurację

Domyślnie element WebApplicationBuilder odczytuje konfigurację z wielu źródeł, w tym:

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

Aby uzyskać pełną listę odczytywanych źródeł konfiguracji, przeczytaj temat Konfiguracja domyślna w artykule Konfiguracja 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();

Odczytaj środowisko

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

Dostosuj IHostBuilder

Dostęp do istniejących metod rozszerzających dla IHostBuilder można uzyskać za pomocą 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();

Dostosuj IWebHostBuilder

Dostęp do metod rozszerzających w elemencie IWebHostBuilder można uzyskać za pomocą 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 aplikacji internetowej to katalog, w którym middleware obsługujące pliki statyczne szuka plików statycznych. Katalog główny witryny sieci Web można zmienić za pomocą WebHostOptions, z poziomu wiersza polecenia lub za pomocą metody UseWebRoot:

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 oprogramowanie pośredniczące.

Strona wyjątku dla deweloperów

WebApplication.CreateBuilder Inicjuje nowe wystąpienie WebApplicationBuilder klasy ze wstępnie skonfigurowanymi wartościami domyślnymi. Strona wyjątków dla deweloperów jest włączona w prekonfigurowanych ustawieniach domyślnych. Po uruchomieniu następującego kodu w środowisku deweloperskim przejście do / powoduje wyświetlenie przyjaznej strony, która wyświetla 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();