App WebApplication e WebApplicationBuilder nelle app per le API minime

WebApplication

Il codice seguente viene generato da un modello ASP.NET Core:

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

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

app.Run();

Il codice precedente può essere creato tramite dotnet new web la riga di comando o selezionando il modello Web vuoto in Visual Studio.

Il codice seguente crea un oggetto WebApplication (app) senza creare in modo esplicito un oggetto WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.Create inizializza una nuova istanza della WebApplication classe con impostazioni predefinite preconfigurate.

Uso delle porte

Quando viene creata un'app Web con Visual Studio o dotnet new, viene creato un Properties/launchSettings.json file che specifica le porte a cui risponde l'app. Negli esempi di impostazione della porta che seguono, l'esecuzione dell'app da Visual Studio restituisce una finestra di dialogo Unable to connect to web server 'AppName'di errore. Visual Studio restituisce un errore perché prevede la porta specificata in Properties/launchSettings.json, ma l'app usa la porta specificata da app.Run("http://localhost:3000"). Eseguire i seguenti esempi di modifica della porta dalla riga di comando.

Le sezioni seguenti impostano la porta a cui risponde l'app.

var app = WebApplication.Create(args);

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

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

Nel codice precedente l'app risponde alla porta 3000.

Più porte

Nel codice seguente l'app risponde alla porta 3000 e 4000a .

var app = WebApplication.Create(args);

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

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

app.Run();

Impostare la porta dalla riga di comando

Il comando seguente rende l'app risponde alla porta 7777:

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

Se l'endpoint Kestrel è configurato anche nel appsettings.json file, viene usato l'URL specificato dal appsettings.json file. Per altre informazioni, vedere Kestrel Configurazione dell'endpoint

Leggere la porta dall'ambiente

Il codice seguente legge la porta dall'ambiente:

var app = WebApplication.Create(args);

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

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

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

Il modo migliore per impostare la porta dall'ambiente consiste nell'usare la ASPNETCORE_URLS variabile di ambiente, illustrata nella sezione seguente.

Impostare le porte tramite la variabile di ambiente ASPNETCORE_URLS

La ASPNETCORE_URLS variabile di ambiente è disponibile per impostare la porta:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS supporta più URL:

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

Ascoltare tutte le interfacce

Gli esempi seguenti illustrano l'ascolto su tutte le interfacce

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

Ascoltare tutte le interfacce usando ASPNETCORE_URLS

Gli esempi precedenti possono usare ASPNETCORE_URLS

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

Ascoltare tutte le interfacce usando ASPNETCORE_HTTPS_PORTS

Gli esempi precedenti possono usare ASPNETCORE_HTTPS_PORTS e ASPNETCORE_HTTP_PORTS.

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Per altre informazioni, vedere Configurare gli endpoint per il server Web ASP.NET Core Kestrel

Specificare HTTPS con il certificato di sviluppo

var app = WebApplication.Create(args);

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

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

app.Run();

Per altre informazioni sul certificato di sviluppo, vedere Considerare attendibile il certificato di sviluppo HTTPS di ASP.NET Core in Windows e macOS.

Specificare HTTPS usando un certificato personalizzato

Le sezioni seguenti illustrano come specificare il certificato personalizzato usando il appsettings.json file e tramite la configurazione.

Specificare il certificato personalizzato con appsettings.json

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

Specificare il certificato personalizzato tramite la configurazione

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

Usare le API del certificato

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

Leggere l'ambiente

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

Per altre informazioni sull'uso dell'ambiente, vedere Usare più ambienti in ASP.NET Core

Impostazione

Il codice seguente legge dal sistema di configurazione:

var app = WebApplication.Create(args);

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

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

app.Run();

Per altre informazioni, vedere Configurazione in ASP.NET Core

Registrazione

Il codice seguente scrive un messaggio all'avvio dell'applicazione di accesso:

var app = WebApplication.Create(args);

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

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

app.Run();

Per altre informazioni, vedere Registrazione in .NET Core e ASP.NET Core

Accedere al contenitore di inserimento delle dipendenze

Il codice seguente illustra come ottenere servizi dal contenitore di inserimento delle dipendenze durante l'avvio dell'applicazione:

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

Il codice seguente illustra come accedere alle chiavi dal contenitore di inserimento delle dipendenze usando l'attributo [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.";
}

Per altre informazioni sull'inserimento delle dipendenze, vedere Inserimento delle dipendenze in ASP.NET Core.

WebApplicationBuilder

Questa sezione contiene codice di esempio che usa WebApplicationBuilder.

Modificare la radice del contenuto, il nome dell'applicazione e l'ambiente

Il codice seguente imposta la radice del contenuto, il nome dell'applicazione e l'ambiente:

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 inizializza una nuova istanza della classe WebApplicationBuilder con valori predefiniti preconfigurati.

Per altre informazioni, vedere ASP.NET Panoramica dei concetti fondamentali di base

Modificare la radice del contenuto, il nome dell'app e l'ambiente usando variabili di ambiente o riga di comando

La tabella seguente illustra la variabile di ambiente e l'argomento della riga di comando usati per modificare la radice del contenuto, il nome dell'app e l'ambiente:

funzionalità	Variabile di ambiente	Argomento della riga di comando
Nome applicazione	ASPNETCORE_APPLICATIONNAME	--applicationName
Nome ambiente	ASPNETCORE_ENVIRONMENT	--ambiente
Radice del contenuto	ASPNETCORE_CONTENTROOT	--contentRoot

Aggiungere provider di configurazione

L'esempio seguente aggiunge il provider di configurazione INI:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Per informazioni dettagliate, vedere Provider di configurazione file in Configurazione in ASP.NET Core.

Leggere la configurazione

Per impostazione predefinita, la WebApplicationBuilder configurazione legge da più origini, tra cui:

• appSettings.json e appSettings.{environment}.json
• Variabili di ambiente
• Riga di comando

Per un elenco completo delle origini di configurazione, vedere Configurazione predefinita in Configurazione in ASP.NET Core.

Il codice seguente legge HelloKey dalla configurazione e visualizza il valore nell'endpoint / . Se il valore di configurazione è Null, "Hello" viene assegnato a message:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Leggere l'ambiente

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Aggiungere provider di registrazione

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

Aggiungere servizi

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

Personalizzare IHostBuilder

È possibile accedere ai metodi di estensione esistenti in IHostBuilder usando la proprietà 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();

Personalizzare IWebHostBuilder

È possibile accedere ai metodi IWebHostBuilder di estensione in usando la proprietà 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();

Modificare la radice Web

Per impostazione predefinita, la radice Web è relativa alla radice del contenuto nella wwwroot cartella. La radice Web è la posizione in cui il middleware dei file statici cerca i file statici. La radice Web può essere modificata con WebHostOptions, la riga di comando o con il UseWebRoot metodo :

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

var app = builder.Build();

app.Run();

Contenitore di inserimento delle dipendenze personalizzato

L'esempio seguente usa 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();

Aggiungere middleware

Qualsiasi middleware core ASP.NET esistente può essere configurato in WebApplication:

var app = WebApplication.Create(args);

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

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

app.Run();

Per altre informazioni, vedere middleware ASP.NET Core

Pagina delle eccezioni per gli sviluppatori

WebApplication.CreateBuilder inizializza una nuova istanza della WebApplicationBuilder classe con impostazioni predefinite preconfigurate. La pagina delle eccezioni per sviluppatori è abilitata nelle impostazioni predefinite preconfigurate. Quando il codice seguente viene eseguito nell'ambiente di sviluppo, spostarsi per eseguire / il rendering di una pagina descrittiva che mostra l'eccezione.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();