WebApplication en WebApplicationBuilder in ASP.NET Core-toepassingen

WebApplication

De volgende code wordt gegenereerd door een ASP.NET Core-sjabloon:

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

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

app.Run();

De voorgaande code kan worden gemaakt via dotnet new web de opdrachtregel of door de lege websjabloon in Visual Studio te selecteren.

Met de volgende code wordt een WebApplication (app) gemaakt zonder expliciet een WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.CreateBuilder initialiseert een nieuw exemplaar van de WebApplicationBuilder klasse met vooraf geconfigureerde standaardwaarden:

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

Werken met poorten

Wanneer een web-app wordt gemaakt met Visual Studio of dotnet new, wordt er een Properties/launchSettings.json bestand gemaakt waarin de poorten worden opgegeven waarop de app reageert. In de volgende voorbeelden van poortinstellingen retourneert het uitvoeren van de app vanuit Visual Studio een foutdialoogvenster Unable to connect to web server 'AppName'. Visual Studio retourneert een fout omdat deze de poort verwacht die is opgegeven in Properties/launchSettings.json, maar de app de poort gebruikt die is opgegeven door app.Run("http://localhost:3000"). Voer de volgende voorbeelden die de poort wijzigen uit vanuit de opdrachtregel.

In de volgende secties wordt de poort van de app ingesteld.

var app = WebApplication.Create(args);

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

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

In de voorgaande code reageert de app op poort 3000.

Meerdere poorten

In de volgende code reageert de app op poort 3000 en 4000:

var app = WebApplication.Create(args);

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

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

app.Run();

De poort instellen via de opdrachtregel

Met de volgende opdracht reageert de app op 7777poort:

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

Als het Kestrel eindpunt ook in het appsettings.json bestand is geconfigureerd, wordt de opgegeven URL van het appsettings.json bestand gebruikt. Zie de eindpuntconfiguratie voor meer informatie Kestrel

De poort uit de omgevingsvariabelen lezen

Met de volgende code wordt de poort uit de omgeving gelezen:

var app = WebApplication.Create(args);

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

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

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

De voorkeursmethode voor het instellen van de poort vanuit de omgeving is het gebruik van de ASPNETCORE_URLS omgevingsvariabele, die wordt weergegeven in de volgende sectie.

De poorten instellen via de ASPNETCORE_URLS omgevingsvariabele

De ASPNETCORE_URLS omgevingsvariabele is beschikbaar om de poort in te stellen:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS ondersteunt meerdere URL's:

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

Zie ASP.NET Core runtime-omgevingen voor meer informatie over het gebruik van de omgeving.

Luisteren op alle interfaces

In de volgende voorbeelden ziet u hoe u luistert op alle interfaces

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

Luisteren op alle interfaces met ASPNETCORE_URLS

De voorgaande voorbeelden kunnen het volgende gebruiken ASPNETCORE_URLS:

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

HTTPS specificeren met ontwikkelingscertificaat

var app = WebApplication.Create(args);

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

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

app.Run();

Zie Het ASP.NET Core HTTPS-ontwikkelingscertificaat vertrouwen in Windows en macOS voor meer informatie over het ontwikkelingscertificaat.

HTTPS opgeven met behulp van een aangepast certificaat

In de volgende secties ziet u hoe u het aangepaste certificaat opgeeft met behulp van het appsettings.json bestand en via de configuratie.

Geef het aangepaste certificaat op met appsettings.json

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

Het aangepaste certificaat opgeven via configuratie

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

De certificaat-API's gebruiken

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

De volgende code leest uit het configuratiesysteem:

var app = WebApplication.Create(args);

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

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

app.Run();

Zie Configuratie in ASP.NET Core voor meer informatie.

Logging

Met de volgende code wordt bij de start van de toepassing een bericht naar het logboek geschreven.

var app = WebApplication.Create(args);

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

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

app.Run();

Zie Logboekregistratie in .NET en ASP.NET Core voor meer informatie.

Toegang tot de Dependency Injection-container (DI)

De volgende code laat zien hoe u services uit de DI-container kunt ophalen tijdens het opstarten van de toepassing:

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

Zie Afhankelijkheidsinjectie in ASP.NET Corevoor meer informatie.

WebApplicationBuilder

Deze sectie bevat voorbeeldcode met behulp van WebApplicationBuilder.

De inhoudsbasis, de naam van de toepassing en de omgeving wijzigen

De volgende code stelt de inhoudsmap, toepassingsnaam en omgeving in.

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 initialiseert een nieuw exemplaar van de WebApplication klasse met vooraf geconfigureerde standaardwaarden.

Zie ASP.NET Overzicht van basisbeginselen van Core voor meer informatie.

Het wijzigen van de hoofdmap, app-naam en omgeving via omgevingsvariabelen of de opdrachtregel

In de volgende tabel ziet u de omgevingsvariabele en het opdrachtregelargument dat wordt gebruikt om de hoofdmap, de naam van de app en de omgeving te wijzigen.

Configuratieproviders toevoegen

In het volgende voorbeeld wordt de INI-configuratieprovider toegevoegd:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Zie Bestandsconfiguratieproviders in Configuratie in ASP.NET Core voor gedetailleerde informatie.

Configuratie lezen

Standaard leest de WebApplicationBuilder de configuratie uit meerdere bronnen, waaronder:

• appSettings.json en appSettings.{environment}.json
• Omgevingsvariabelen
• De opdrachtregel

De volgende code leest HelloKey uit de configuratie en geeft de waarde weer op het / eindpunt. Als de configuratiewaarde null is, wordt 'Hallo' toegewezen aan message:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Zie De standaardconfiguratiein Configuratie in ASP.NET Core voor een volledige lijst met configuratiebronnen die worden gelezen.

Logboekregistratieproviders toevoegen

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

Services toevoegen

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

Pas de IHostBuilder aan

Bestaande uitbreidingsmethoden IHostBuilder kunnen worden geopend met behulp van de eigenschap 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();

Pas de IWebHostBuilder aan

Extensiemethoden voor IWebHostBuilder zijn toegankelijk via de eigenschap 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();

De webroot wijzigen

De webroot is standaard relatief ten opzichte van de inhoudsmap in de map wwwroot. De webroot is de locatie waar de middleware voor statische bestanden naar statische bestanden zoekt. Webhoofdmap kan worden gewijzigd met WebHostOptions, de opdrachtregel of met de UseWebRoot methode:

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

var app = builder.Build();

app.Run();

Afhankelijkheidsinjectiecontainer op maat (DI)

In het volgende voorbeeld wordt Autofac gebruikt:

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

Middleware toevoegen

Alle bestaande ASP.NET Core-middleware kan worden geconfigureerd op WebApplication.

var app = WebApplication.Create(args);

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

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

app.Run();

Zie ASP.NET Core middleware voor meer informatie.

Uitzonderingspagina voor ontwikkelaars

WebApplication.CreateBuilder initialiseert een nieuw exemplaar van de WebApplicationBuilder klasse met vooraf geconfigureerde standaardwaarden. De uitzonderingspagina voor ontwikkelaars is ingeschakeld in de vooraf geconfigureerde standaardinstellingen. Wanneer de volgende code wordt uitgevoerd in de ontwikkelomgeving, wordt er genavigeerd naar een vriendelijke pagina die de uitzondering toont.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();

WebApplication

De volgende code wordt gegenereerd door een ASP.NET Core-sjabloon:

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

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

app.Run();

De voorgaande code kan worden gemaakt via dotnet new web de opdrachtregel of door de lege websjabloon in Visual Studio te selecteren.

Met de volgende code wordt een WebApplication (app) gemaakt zonder expliciet een WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.CreateBuilder initialiseert een nieuw exemplaar van de WebApplicationBuilder klasse met vooraf geconfigureerde standaardwaarden:

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

Werken met poorten

Wanneer een web-app wordt gemaakt met Visual Studio of dotnet new, wordt er een Properties/launchSettings.json bestand gemaakt waarin de poorten worden opgegeven waarop de app reageert. In de volgende voorbeelden van poortinstellingen retourneert het uitvoeren van de app vanuit Visual Studio een foutdialoogvenster Unable to connect to web server 'AppName'. Visual Studio retourneert een fout omdat deze de poort verwacht die is opgegeven in Properties/launchSettings.json, maar de app de poort gebruikt die is opgegeven door app.Run("http://localhost:3000"). Voer de volgende voorbeelden die de poort wijzigen uit vanuit de opdrachtregel.

In de volgende secties wordt de poort van de app ingesteld.

var app = WebApplication.Create(args);

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

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

In de voorgaande code reageert de app op poort 3000.

Meerdere poorten

In de volgende code reageert de app op poort 3000 en 4000:

var app = WebApplication.Create(args);

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

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

app.Run();

De poort instellen via de opdrachtregel

Met de volgende opdracht reageert de app op 7777poort:

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

Als het Kestrel eindpunt ook in het appsettings.json bestand is geconfigureerd, wordt de opgegeven URL van het appsettings.json bestand gebruikt. Zie de eindpuntconfiguratie voor meer informatie Kestrel

De poort uit de omgevingsvariabelen lezen

Met de volgende code wordt de poort uit de omgeving gelezen:

var app = WebApplication.Create(args);

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

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

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

De voorkeursmethode voor het instellen van de poort vanuit de omgeving is het gebruik van de ASPNETCORE_URLS omgevingsvariabele, die wordt weergegeven in de volgende sectie.

De poorten instellen via de ASPNETCORE_URLS omgevingsvariabele

De ASPNETCORE_URLS omgevingsvariabele is beschikbaar om de poort in te stellen:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS ondersteunt meerdere URL's:

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

Luisteren op alle interfaces

In de volgende voorbeelden ziet u hoe u luistert op alle interfaces.

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

Luisteren op alle interfaces met ASPNETCORE_URLS

De voorgaande voorbeelden kunnen het volgende gebruiken ASPNETCORE_URLS:

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

Luisteren op alle interfaces met behulp van ASPNETCORE_HTTP_PORTS en ASPNETCORE_HTTPS_PORTS

De voorgaande voorbeelden kunnen ook worden gebruikt ASPNETCORE_HTTP_PORTS en ASPNETCORE_HTTPS_PORTS, maar ASPNETCORE_URLS (wanneer ingesteld) overschrijft de volgende instellingen:

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Zie Eindpunten configureren voor webservers voor Kestrelmeer informatie.

HTTPS specificeren met ontwikkelingscertificaat

var app = WebApplication.Create(args);

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

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

app.Run();

Zie Het ASP.NET Core HTTPS-ontwikkelingscertificaat vertrouwen in Windows en macOS voor meer informatie over het ontwikkelingscertificaat.

HTTPS opgeven met behulp van een aangepast certificaat

In de volgende secties ziet u hoe u het aangepaste certificaat opgeeft met behulp van het appsettings.json bestand en via de configuratie.

Geef het aangepaste certificaat op met appsettings.json

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

Het aangepaste certificaat opgeven via configuratie

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

De certificaat-API's gebruiken

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

De omgeving lezen

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

Zie ASP.NET Core runtime-omgevingen voor meer informatie over het gebruik van de omgeving.

Configuration

De volgende code leest uit het configuratiesysteem:

var app = WebApplication.Create(args);

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

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

app.Run();

Zie Configuratie in ASP.NET Core voor meer informatie.

Logging

Met de volgende code wordt bij de start van de toepassing een bericht naar het logboek geschreven.

var app = WebApplication.Create(args);

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

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

app.Run();

Zie Logboekregistratie in .NET en ASP.NET Core voor meer informatie.

Toegang tot de Dependency Injection-container (DI)

De volgende code laat zien hoe u services uit de DI-container kunt ophalen tijdens het opstarten van de toepassing:

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

De volgende code laat zien hoe u toegang hebt tot sleutels uit de DI-container met behulp van het [FromKeyedServices] kenmerk:

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.";
}

Zie Afhankelijkheidsinjectie in ASP.NET Core voor meer informatie over DI.

WebApplicationBuilder

Deze sectie bevat voorbeeldcode met behulp van WebApplicationBuilder.

De inhoudsbasis, de naam van de toepassing en de omgeving wijzigen

De volgende code stelt de inhoudsmap, toepassingsnaam en omgeving in.

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 initialiseert een nieuw exemplaar van de WebApplication klasse met vooraf geconfigureerde standaardwaarden.

Zie ASP.NET Overzicht van basisbeginselen van Core voor meer informatie

De hoofdmap, app-naam en omgeving wijzigen met behulp van omgevingsvariabelen of opdrachtregel

In de volgende tabel ziet u de omgevingsvariabele en het opdrachtregelargument dat wordt gebruikt om de hoofdmap, de naam van de app en de omgeving te wijzigen.

Configuratieproviders toevoegen

In het volgende voorbeeld wordt de INI-configuratieprovider toegevoegd:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Zie Bestandsconfiguratieproviders in Configuratie in ASP.NET Core voor gedetailleerde informatie.

Configuratie lezen

Standaard leest de WebApplicationBuilder de configuratie uit meerdere bronnen, waaronder:

• appSettings.json en appSettings.{environment}.json
• Omgevingsvariabelen
• De opdrachtregel

Zie De standaardconfiguratiein Configuratie in ASP.NET Core voor een volledige lijst met configuratiebronnen die worden gelezen.

De volgende code leest HelloKey uit de configuratie en geeft de waarde weer op het / eindpunt. Als de configuratiewaarde null is, wordt 'Hallo' toegewezen aan message:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

De omgeving lezen

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Logboekregistratieproviders toevoegen

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

Services toevoegen

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

Pas de IHostBuilder aan

Bestaande uitbreidingsmethoden IHostBuilder kunnen worden geopend met behulp van de eigenschap 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();

Pas de IWebHostBuilder aan

Extensiemethoden voor IWebHostBuilder zijn toegankelijk via de eigenschap 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();

De webroot wijzigen

De webroot is standaard relatief ten opzichte van de inhoudsmap in de map wwwroot. De webroot is de locatie waar de middleware voor statische bestanden naar statische bestanden zoekt. Webhoofdmap kan worden gewijzigd met WebHostOptions, de opdrachtregel of met de UseWebRoot methode:

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

var app = builder.Build();

app.Run();

Afhankelijkheidsinjectiecontainer op maat (DI)

In het volgende voorbeeld wordt Autofac gebruikt:

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

Middleware toevoegen

Alle bestaande ASP.NET Core-middleware kan worden geconfigureerd op WebApplication.

var app = WebApplication.Create(args);

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

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

app.Run();

Zie ASP.NET Core middleware voor meer informatie.

Uitzonderingspagina voor ontwikkelaars

WebApplication.CreateBuilder initialiseert een nieuw exemplaar van de WebApplicationBuilder klasse met vooraf geconfigureerde standaardwaarden. De uitzonderingspagina voor ontwikkelaars is ingeschakeld in de vooraf geconfigureerde standaardinstellingen. Wanneer de volgende code wordt uitgevoerd in de ontwikkelomgeving, wordt er genavigeerd naar een vriendelijke pagina die de uitzondering toont.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();

WebApplication

De volgende code wordt gegenereerd door een ASP.NET Core-sjabloon:

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

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

app.Run();

De voorgaande code kan worden gemaakt via dotnet new web de opdrachtregel of door de lege websjabloon in Visual Studio te selecteren.

Met de volgende code wordt een WebApplication (app) gemaakt zonder expliciet een WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.CreateBuilder initialiseert een nieuw exemplaar van de WebApplicationBuilder klasse met vooraf geconfigureerde standaardwaarden:

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

Werken met poorten

Wanneer een web-app wordt gemaakt met Visual Studio of dotnet new, wordt er een Properties/launchSettings.json bestand gemaakt waarin de poorten worden opgegeven waarop de app reageert. In de volgende voorbeelden van poortinstellingen retourneert het uitvoeren van de app vanuit Visual Studio een foutdialoogvenster Unable to connect to web server 'AppName'. Visual Studio retourneert een fout omdat deze de poort verwacht die is opgegeven in Properties/launchSettings.json, maar de app de poort gebruikt die is opgegeven door app.Run("http://localhost:3000"). Voer de volgende voorbeelden die de poort wijzigen uit vanuit de opdrachtregel.

In de volgende secties wordt de poort van de app ingesteld.

var app = WebApplication.Create(args);

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

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

In de voorgaande code reageert de app op poort 3000.

Meerdere poorten

In de volgende code reageert de app op poort 3000 en 4000:

var app = WebApplication.Create(args);

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

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

app.Run();

De poort instellen via de opdrachtregel

Met de volgende opdracht reageert de app op 7777poort:

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

Als het Kestrel eindpunt ook in het appsettings.json bestand is geconfigureerd, wordt de opgegeven URL van het appsettings.json bestand gebruikt. Zie de eindpuntconfiguratie voor meer informatie Kestrel

De poort uit de omgevingsvariabelen lezen

Met de volgende code wordt de poort uit de omgeving gelezen:

var app = WebApplication.Create(args);

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

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

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

De voorkeursmethode voor het instellen van de poort vanuit de omgeving is het gebruik van de ASPNETCORE_URLS omgevingsvariabele, die wordt weergegeven in de volgende sectie.

De poorten instellen via de ASPNETCORE_URLS omgevingsvariabele

De ASPNETCORE_URLS omgevingsvariabele is beschikbaar om de poort in te stellen:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS ondersteunt meerdere URL's:

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

Luisteren op alle interfaces

In de volgende voorbeelden ziet u hoe u luistert op alle interfaces

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

Luisteren op alle interfaces met ASPNETCORE_URLS

De voorgaande voorbeelden kunnen het volgende gebruiken ASPNETCORE_URLS:

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

Luisteren op alle interfaces met behulp van ASPNETCORE_HTTP_PORTS en ASPNETCORE_HTTPS_PORTS

De voorgaande voorbeelden kunnen ook worden gebruikt ASPNETCORE_HTTP_PORTS en ASPNETCORE_HTTPS_PORTS, maar ASPNETCORE_URLS (wanneer ingesteld) overschrijft de volgende instellingen:

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Zie Eindpunten configureren voor webservers voor Kestrelmeer informatie.

HTTPS specificeren met ontwikkelingscertificaat

var app = WebApplication.Create(args);

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

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

app.Run();

Zie Het ASP.NET Core HTTPS-ontwikkelingscertificaat vertrouwen in Windows en macOS voor meer informatie over het ontwikkelingscertificaat.

HTTPS opgeven met behulp van een aangepast certificaat

In de volgende secties ziet u hoe u het aangepaste certificaat opgeeft met behulp van het appsettings.json bestand en via de configuratie.

Geef het aangepaste certificaat op met appsettings.json

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

Het aangepaste certificaat opgeven via configuratie

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

De certificaat-API's gebruiken

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

De omgeving lezen

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

Zie ASP.NET Core runtime-omgevingen voor meer informatie over het gebruik van de omgeving.

Configuration

De volgende code leest uit het configuratiesysteem:

var app = WebApplication.Create(args);

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

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

app.Run();

Zie Configuratie in ASP.NET Core voor meer informatie.

Logging

Met de volgende code wordt bij de start van de toepassing een bericht naar het logboek geschreven.

var app = WebApplication.Create(args);

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

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

app.Run();

Zie Logboekregistratie in .NET en ASP.NET Core voor meer informatie.

Toegang tot de Dependency Injection-container (DI)

De volgende code laat zien hoe u services uit de DI-container kunt ophalen tijdens het opstarten van de toepassing:

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

De volgende code laat zien hoe u toegang hebt tot sleutels uit de DI-container met behulp van het [FromKeyedServices] kenmerk:

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.";
}

Zie Afhankelijkheidsinjectie in ASP.NET Core voor meer informatie over DI.

WebApplicationBuilder

Deze sectie bevat voorbeeldcode met behulp van WebApplicationBuilder.

De inhoudsbasis, de naam van de toepassing en de omgeving wijzigen

De volgende code stelt de inhoudsmap, toepassingsnaam en omgeving in.

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 initialiseert een nieuw exemplaar van de WebApplication klasse met vooraf geconfigureerde standaardwaarden.

Zie ASP.NET Overzicht van basisbeginselen van Core voor meer informatie

De hoofdmap, app-naam en omgeving wijzigen met behulp van omgevingsvariabelen of opdrachtregel

In de volgende tabel ziet u de omgevingsvariabele en het opdrachtregelargument dat wordt gebruikt om de hoofdmap, de naam van de app en de omgeving te wijzigen.

Configuratieproviders toevoegen

In het volgende voorbeeld wordt de INI-configuratieprovider toegevoegd:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Zie Bestandsconfiguratieproviders in Configuratie in ASP.NET Core voor gedetailleerde informatie.

Configuratie lezen

Standaard leest de WebApplicationBuilder de configuratie uit meerdere bronnen, waaronder:

• appSettings.json en appSettings.{environment}.json
• Omgevingsvariabelen
• De opdrachtregel

Zie De standaardconfiguratiein Configuratie in ASP.NET Core voor een volledige lijst met configuratiebronnen die worden gelezen.

De volgende code leest HelloKey uit de configuratie en geeft de waarde weer op het / eindpunt. Als de configuratiewaarde null is, wordt 'Hallo' toegewezen aan message:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

De omgeving lezen

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Logboekregistratieproviders toevoegen

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

Services toevoegen

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

Pas de IHostBuilder aan

Bestaande uitbreidingsmethoden IHostBuilder kunnen worden geopend met behulp van de eigenschap 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();

Pas de IWebHostBuilder aan

Extensiemethoden voor IWebHostBuilder zijn toegankelijk via de eigenschap 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();

De webroot wijzigen

De webroot is standaard relatief ten opzichte van de inhoudsmap in de map wwwroot. De webroot is de locatie waar de middleware voor statische bestanden naar statische bestanden zoekt. Webhoofdmap kan worden gewijzigd met WebHostOptions, de opdrachtregel of met de UseWebRoot methode:

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

var app = builder.Build();

app.Run();

Afhankelijkheidsinjectiecontainer op maat (DI)

In het volgende voorbeeld wordt Autofac gebruikt:

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

Middleware toevoegen

Alle bestaande ASP.NET Core-middleware kan worden geconfigureerd op WebApplication.

var app = WebApplication.Create(args);

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

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

app.Run();

Zie ASP.NET Core middleware voor meer informatie.

Uitzonderingspagina voor ontwikkelaars

WebApplication.CreateBuilder initialiseert een nieuw exemplaar van de WebApplicationBuilder klasse met vooraf geconfigureerde standaardwaarden. De uitzonderingspagina voor ontwikkelaars is ingeschakeld in de vooraf geconfigureerde standaardinstellingen. Wanneer de volgende code wordt uitgevoerd in de ontwikkelomgeving, wordt er genavigeerd naar een vriendelijke pagina die de uitzondering toont.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();

WebApplication

De volgende code wordt gegenereerd door een ASP.NET Core-sjabloon:

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

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

app.Run();

De voorgaande code kan worden gemaakt via dotnet new web de opdrachtregel of door de lege websjabloon in Visual Studio te selecteren.

Met de volgende code wordt een WebApplication (app) gemaakt zonder expliciet een WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.CreateBuilder initialiseert een nieuw exemplaar van de WebApplicationBuilder klasse met vooraf geconfigureerde standaardwaarden:

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

Werken met poorten

Wanneer een web-app wordt gemaakt met Visual Studio of dotnet new, wordt er een Properties/launchSettings.json bestand gemaakt waarin de poorten worden opgegeven waarop de app reageert. In de volgende voorbeelden van poortinstellingen retourneert het uitvoeren van de app vanuit Visual Studio een foutdialoogvenster Unable to connect to web server 'AppName'. Visual Studio retourneert een fout omdat deze de poort verwacht die is opgegeven in Properties/launchSettings.json, maar de app de poort gebruikt die is opgegeven door app.Run("http://localhost:3000"). Voer de volgende voorbeelden die de poort wijzigen uit vanuit de opdrachtregel.

In de volgende secties wordt de poort van de app ingesteld.

var app = WebApplication.Create(args);

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

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

In de voorgaande code reageert de app op poort 3000.

Meerdere poorten

In de volgende code reageert de app op poort 3000 en 4000:

var app = WebApplication.Create(args);

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

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

app.Run();

De poort instellen via de opdrachtregel

Met de volgende opdracht reageert de app op 7777poort:

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

Als het Kestrel eindpunt ook in het appsettings.json bestand is geconfigureerd, wordt de opgegeven URL van het appsettings.json bestand gebruikt. Zie de eindpuntconfiguratie voor meer informatie Kestrel

De poort uit de omgevingsvariabelen lezen

Met de volgende code wordt de poort uit de omgeving gelezen:

var app = WebApplication.Create(args);

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

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

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

De voorkeursmethode voor het instellen van de poort vanuit de omgeving is het gebruik van de ASPNETCORE_URLS omgevingsvariabele, die wordt weergegeven in de volgende sectie.

De poorten instellen via de ASPNETCORE_URLS omgevingsvariabele

De ASPNETCORE_URLS omgevingsvariabele is beschikbaar om de poort in te stellen:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS ondersteunt meerdere URL's:

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

Luisteren op alle interfaces

In de volgende voorbeelden ziet u hoe u luistert op alle interfaces.

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

Luisteren op alle interfaces met ASPNETCORE_URLS

De voorgaande voorbeelden kunnen het volgende gebruiken ASPNETCORE_URLS:

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

Luisteren op alle interfaces met behulp van ASPNETCORE_HTTP_PORTS en ASPNETCORE_HTTPS_PORTS

De voorgaande voorbeelden kunnen ook worden gebruikt ASPNETCORE_HTTP_PORTS en ASPNETCORE_HTTPS_PORTS, maar ASPNETCORE_URLS (wanneer ingesteld) overschrijft de volgende instellingen:

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Zie Eindpunten configureren voor webservers voor Kestrelmeer informatie.

HTTPS specificeren met ontwikkelingscertificaat

var app = WebApplication.Create(args);

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

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

app.Run();

Zie Het ASP.NET Core HTTPS-ontwikkelingscertificaat vertrouwen in Windows en macOS voor meer informatie over het ontwikkelingscertificaat.

HTTPS opgeven met behulp van een aangepast certificaat

In de volgende secties ziet u hoe u het aangepaste certificaat opgeeft met behulp van het appsettings.json bestand en via de configuratie.

Geef het aangepaste certificaat op met appsettings.json

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

Het aangepaste certificaat opgeven via configuratie

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

De certificaat-API's gebruiken

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

De omgeving lezen

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

Zie ASP.NET Core runtime-omgevingen voor meer informatie over het gebruik van de omgeving.

Configuration

De volgende code leest uit het configuratiesysteem:

var app = WebApplication.Create(args);

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

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

app.Run();

Zie Configuratie in ASP.NET Core voor meer informatie.

Logging

Met de volgende code wordt bij de start van de toepassing een bericht naar het logboek geschreven.

var app = WebApplication.Create(args);

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

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

app.Run();

Zie Logboekregistratie in .NET en ASP.NET Core voor meer informatie.

Toegang tot de Dependency Injection-container (DI)

De volgende code laat zien hoe u services uit de DI-container kunt ophalen tijdens het opstarten van de toepassing:

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

De volgende code laat zien hoe u toegang hebt tot sleutels uit de DI-container met behulp van het [FromKeyedServices] kenmerk:

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.";
}

Zie Afhankelijkheidsinjectie in ASP.NET Core voor meer informatie over DI.

WebApplicationBuilder

Deze sectie bevat voorbeeldcode met behulp van WebApplicationBuilder.

De inhoudsbasis, de naam van de toepassing en de omgeving wijzigen

De volgende code stelt de inhoudsmap, toepassingsnaam en omgeving in.

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 initialiseert een nieuw exemplaar van de WebApplication klasse met vooraf geconfigureerde standaardwaarden.

Zie ASP.NET Overzicht van basisbeginselen van Core voor meer informatie

De hoofdmap, app-naam en omgeving wijzigen met behulp van omgevingsvariabelen of opdrachtregel

In de volgende tabel ziet u de omgevingsvariabele en het opdrachtregelargument dat wordt gebruikt om de hoofdmap, de naam van de app en de omgeving te wijzigen.

Configuratieproviders toevoegen

In het volgende voorbeeld wordt de INI-configuratieprovider toegevoegd:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Zie Bestandsconfiguratieproviders in Configuratie in ASP.NET Core voor gedetailleerde informatie.

Configuratie lezen

Standaard leest de WebApplicationBuilder de configuratie uit meerdere bronnen, waaronder:

• appSettings.json en appSettings.{environment}.json
• Omgevingsvariabelen
• De opdrachtregel

Zie De standaardconfiguratiein Configuratie in ASP.NET Core voor een volledige lijst met configuratiebronnen die worden gelezen.

De volgende code leest HelloKey uit de configuratie en geeft de waarde weer op het / eindpunt. Als de configuratiewaarde null is, wordt 'Hallo' toegewezen aan message:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

De omgeving lezen

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Logboekregistratieproviders toevoegen

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

Services toevoegen

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

Pas de IHostBuilder aan

Bestaande uitbreidingsmethoden IHostBuilder kunnen worden geopend met behulp van de eigenschap 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();

Pas de IWebHostBuilder aan

Extensiemethoden voor IWebHostBuilder zijn toegankelijk via de eigenschap 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();

De webroot wijzigen

De webroot is standaard relatief ten opzichte van de inhoudsmap in de map wwwroot. De webroot is de locatie waar de middleware voor statische bestanden naar statische bestanden zoekt. Webhoofdmap kan worden gewijzigd met WebHostOptions, de opdrachtregel of met de UseWebRoot methode:

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

var app = builder.Build();

app.Run();

Afhankelijkheidsinjectiecontainer op maat (DI)

In het volgende voorbeeld wordt Autofac gebruikt:

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

Middleware toevoegen

Alle bestaande ASP.NET Core-middleware kan worden geconfigureerd op WebApplication.

var app = WebApplication.Create(args);

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

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

app.Run();

Zie ASP.NET Core middleware voor meer informatie.

Uitzonderingspagina voor ontwikkelaars

WebApplication.CreateBuilder initialiseert een nieuw exemplaar van de WebApplicationBuilder klasse met vooraf geconfigureerde standaardwaarden. De uitzonderingspagina voor ontwikkelaars is ingeschakeld in de vooraf geconfigureerde standaardinstellingen. Wanneer de volgende code wordt uitgevoerd in de ontwikkelomgeving, wordt er genavigeerd naar een vriendelijke pagina die de uitzondering toont.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();