Dela via

WebApplication och WebApplicationBuilder i minimala API-appar

Note

Det här är inte den senaste versionen av den här artikeln. För den nuvarande utgåvan, se .NET 9-versionen av den här artikeln .

Warning

Den här versionen av ASP.NET Core stöds inte längre. Mer information finns i supportpolicyn för .NET och .NET Core. För den nuvarande utgåvan, se .NET 9-versionen av den här artikeln .

Important

Den här informationen gäller en förhandsversionsprodukt som kan ändras avsevärt innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som tillhandahålls här.

För den nuvarande utgåvan, se .NET 9-versionen av den här artikeln .

WebApplication

Följande kod genereras av en ASP.NET Core-mall:

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

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

app.Run();

Föregående kod kan skapas via dotnet new web på kommandoraden eller genom att välja mallen Tom webb i Visual Studio.

Följande kod skapar en WebApplication (app) utan att uttryckligen skapa en WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.Create initierar en ny instans av klassen WebApplication med förkonfigurerade standardvärden.

WebApplication lägger automatiskt till följande mellanprogram i Minimala API-program beroende på vissa villkor:

  • UseDeveloperExceptionPage läggs till först när HostingEnvironment är "Development".
  • UseRouting läggs till som nummer två om användarkoden inte redan har anropat UseRouting och om det finns konfigurerade slutpunkter, till exempel app.MapGet.
  • UseEndpoints läggs till i slutet av pipelinen för mellanprogram om några slutpunkter har konfigurerats.
  • UseAuthentication läggs till omedelbart efter UseRouting om användarkoden inte redan anropade UseAuthentication och om IAuthenticationSchemeProvider kan identifieras i tjänstleverantören. IAuthenticationSchemeProvider läggs till som standard när du använder AddAuthenticationoch tjänster identifieras med hjälp av IServiceProviderIsService.
  • UseAuthorization läggs till nästa om användarkoden inte redan anropar UseAuthorization och om IAuthorizationHandlerProvider kan identifieras i tjänstleverantören. IAuthorizationHandlerProvider läggs till som standard när du använder AddAuthorizationoch tjänster identifieras med hjälp av IServiceProviderIsService.
  • Användar konfigurerade mellanprogram och slutpunkter läggs till mellan UseRouting och UseEndpoints.

Följande kod är i praktiken vad det automatiska mellanprogrammet som läggs till i appen genererar:

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

I vissa fall är standardkonfigurationen för mellanprogram inte korrekt för appen och kräver ändringar. Till exempel ska UseCors anropas före UseAuthentication och UseAuthorization. Appen måste anropa UseAuthentication och UseAuthorization om UseCors anropas:

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

Om mellanprogram ska köras innan routningsmatchning sker ska UseRouting anropas och mellanprogrammet placeras innan anropet till UseRouting. UseEndpoints krävs inte i det här fallet eftersom det läggs till automatiskt enligt beskrivningen ovan:

app.Use((context, next) =>
{
    return next(context);
});

app.UseRouting();

// other middleware and endpoints

När du lägger till ett terminalmellanprogram:

  • Mellanprogrammet måste läggas till efter UseEndpoints.
  • Appen måste anropa UseRouting och UseEndpoints så att terminalmellanprogrammet kan placeras på rätt plats.
app.UseRouting();

app.MapGet("/", () => "hello world");

app.UseEndpoints(e => {});

app.Run(context =>
{
    context.Response.StatusCode = 404;
    return Task.CompletedTask;
});

Terminalmellanprogram är mellanprogram som körs om ingen slutpunkt hanterar begäran.

Arbeta med portar

När en webbapp skapas med Visual Studio eller dotnet newskapas en Properties/launchSettings.json fil som anger de portar som appen svarar på. I portinställningsexemplen som följer returnerar körning av appen från Visual Studio en feldialogruta Unable to connect to web server 'AppName'. Visual Studio returnerar ett fel eftersom den förväntar sig att porten som anges i Properties/launchSettings.json, men appen använder den port som anges av app.Run("http://localhost:3000"). Kör följande portförändrande exempel från kommandoraden.

Följande avsnitt anger den port som appen svarar på.

var app = WebApplication.Create(args);

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

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

I föregående kod svarar appen på port 3000.

Flera portar

I följande kod svarar appen på port 3000 och 4000.

var app = WebApplication.Create(args);

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

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

app.Run();

Ange porten från kommandoraden

Följande kommando gör att appen svarar på port 7777:

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

Om slutpunkten Kestrel också har konfigurerats i filen appsettings.json, används den URL som specificerats i filen appsettings.json. Mer information finns i Kestrel slutpunktskonfiguration

Läsa porten från miljön

Följande kod läser porten från miljön:

var app = WebApplication.Create(args);

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

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

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

Det bästa sättet att ange porten från miljön är att använda ASPNETCORE_URLS miljövariabeln, som visas i följande avsnitt.

Ange portarna via miljövariabeln ASPNETCORE_URLS

Miljövariabeln ASPNETCORE_URLS är tillgänglig för att ange porten:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS stöder flera URL:er:

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

Mer information om hur du använder miljön finns i ASP.NET Core-körningsmiljöer

Lyssna på alla gränssnitt

Följande exempel visar hur alla gränssnitt avlyssnas

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

Lyssna på alla gränssnitt med hjälp av ASPNETCORE_URLS

Föregående exempel kan använda ASPNETCORE_URLS

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

Ange HTTPS med utvecklingscertifikat

var app = WebApplication.Create(args);

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

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

app.Run();

Mer information om utvecklingscertifikatet finns i Trust the ASP.NET Core HTTPS development certificate on Windows and macOS.

Ange HTTPS med ett anpassat certifikat

Följande avsnitt visar hur du anger det anpassade certifikatet med hjälp av appsettings.json-filen och via konfiguration.

Ange det anpassade certifikatet med appsettings.json

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

Ange det anpassade certifikatet via konfiguration

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

Använda certifikat-API:erna

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

Följande kod läser från konfigurationssystemet:

var app = WebApplication.Create(args);

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

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

app.Run();

Mer information finns i Configuration i ASP.NET Core

Logging

Följande kod skriver ett meddelande till loggen vid programstart:

var app = WebApplication.Create(args);

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

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

app.Run();

Mer information finns i Loggning i .NET och ASP.NET Core

Få åtkomst till beroendeinjektionscontainern (DI)

Följande kod visar hur du hämtar tjänster från DI-containern under programstarten:


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

Mer information finns i Beroendeinmatning i ASP.NET Core.

WebApplicationBuilder

Det här avsnittet innehåller exempelkod med hjälp av WebApplicationBuilder.

Ändra innehållsrot, programnamn och miljö

Följande kod anger innehållsrot, programnamn och miljö:

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 initierar en ny instans av klassen WebApplicationBuilder med förkonfigurerade standardvärden.

Mer information finns i översikten över grunderna i ASP.NET Core

Ändra innehållsrot, appnamn och miljö efter miljövariabler eller kommandorad

I följande tabell visas miljövariabeln och kommandoradsargumentet som används för att ändra innehållsrot, appnamn och miljö:

feature Miljövariabel Kommandoradsargument
Programnamn ASPNETCORE_APPLICATIONNAME --applicationName
Miljönamn ASPNETCORE_ENVIRONMENT --environment
Innehållsrot ASPNETCORE_CONTENTROOT --contentRoot

Lägga till konfigurationsprovidrar

Följande exempel lägger till INI-konfigurationsprovidern:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Detaljerad information finns i Filkonfigurationsproviders i Configuration i ASP.NET Core.

Läs konfiguration

Som standard läser WebApplicationBuilder konfigurationen från flera källor, inklusive:

  • appSettings.json och appSettings.{environment}.json
  • Miljövariabler
  • Kommandorad

Följande kod läser HelloKey från konfigurationen och visar värdet vid / slutpunkten. Om konfigurationsvärdet är null tilldelas "Hello" till message:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

En fullständig lista över konfigurationskällor finns i Standardkonfiguration i Configuration i ASP.NET Core

Lägg till loggningsleverantörer

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

Lägga till tjänster

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

Anpassa IHostBuilder

Befintliga tilläggsmetoder på IHostBuilder kan nås med egenskapen 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();

Anpassa IWebHostBuilder

Tilläggsmetoder på IWebHostBuilder kan nås med hjälp av egenskapen 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();

Ändra webbplatsens rot

Som standard är webbroten relativ till innehållsroten i mappen wwwroot. Webbrooten är där det statiska filmellanprogrammet letar efter statiska filer. Webbroten kan ändras med WebHostOptions, kommandoraden eller med metoden UseWebRoot:

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

var app = builder.Build();

app.Run();

Container för anpassad beroendeinjektion (DI)

I följande exempel används 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();

Lägg till mellanprogram

Alla befintliga ASP.NET Core-mellanprogram kan konfigureras på WebApplication:

var app = WebApplication.Create(args);

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

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

app.Run();

Mer information finns i ASP.NET Core Middleware

Undantagssida för utvecklare

WebApplication.CreateBuilder initierar en ny instans av klassen WebApplicationBuilder med förkonfigurerade standardvärden. Undantagssidan för utvecklare är aktiverad i de förkonfigurerade standardvärdena. När följande kod körs i utvecklingsmiljönrenderar navigering till / en vänlig sida som visar undantaget.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();

WebApplication

Följande kod genereras av en ASP.NET Core-mall:

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

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

app.Run();

Föregående kod kan skapas via dotnet new web på kommandoraden eller genom att välja mallen Tom webb i Visual Studio.

Följande kod skapar en WebApplication (app) utan att uttryckligen skapa en WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.Create initierar en ny instans av klassen WebApplication med förkonfigurerade standardvärden.

WebApplication lägger automatiskt till följande mellanprogram i Minimala API-program beroende på vissa villkor:

  • UseDeveloperExceptionPage läggs till först när HostingEnvironment är "Development".
  • UseRouting läggs till som nummer två om användarkoden inte redan har anropat UseRouting och om det finns konfigurerade slutpunkter, till exempel app.MapGet.
  • UseEndpoints läggs till i slutet av pipelinen för mellanprogram om några slutpunkter har konfigurerats.
  • UseAuthentication läggs till omedelbart efter UseRouting om användarkoden inte redan anropade UseAuthentication och om IAuthenticationSchemeProvider kan identifieras i tjänstleverantören. IAuthenticationSchemeProvider läggs till som standard när du använder AddAuthenticationoch tjänster identifieras med hjälp av IServiceProviderIsService.
  • UseAuthorization läggs till nästa om användarkoden inte redan anropar UseAuthorization och om IAuthorizationHandlerProvider kan identifieras i tjänstleverantören. IAuthorizationHandlerProvider läggs till som standard när du använder AddAuthorizationoch tjänster identifieras med hjälp av IServiceProviderIsService.
  • Användar konfigurerade mellanprogram och slutpunkter läggs till mellan UseRouting och UseEndpoints.

Följande kod är i praktiken vad det automatiska mellanprogrammet som läggs till i appen genererar:

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

I vissa fall är standardkonfigurationen för mellanprogram inte korrekt för appen och kräver ändringar. Till exempel ska UseCors anropas före UseAuthentication och UseAuthorization. Appen måste anropa UseAuthentication och UseAuthorization om UseCors anropas:

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

Om mellanprogram ska köras innan routningsmatchning sker ska UseRouting anropas och mellanprogrammet placeras innan anropet till UseRouting. UseEndpoints krävs inte i det här fallet eftersom det läggs till automatiskt enligt beskrivningen ovan:

app.Use((context, next) =>
{
    return next(context);
});

app.UseRouting();

// other middleware and endpoints

När du lägger till ett terminalmellanprogram:

  • Mellanprogrammet måste läggas till efter UseEndpoints.
  • Appen måste anropa UseRouting och UseEndpoints så att terminalmellanprogrammet kan placeras på rätt plats.
app.UseRouting();

app.MapGet("/", () => "hello world");

app.UseEndpoints(e => {});

app.Run(context =>
{
    context.Response.StatusCode = 404;
    return Task.CompletedTask;
});

Terminalmellanprogram är mellanprogram som körs om ingen slutpunkt hanterar begäran.

Arbeta med portar

När en webbapp skapas med Visual Studio eller dotnet newskapas en Properties/launchSettings.json fil som anger de portar som appen svarar på. I portinställningsexemplen som följer returnerar körning av appen från Visual Studio en feldialogruta Unable to connect to web server 'AppName'. Visual Studio returnerar ett fel eftersom den förväntar sig att porten som anges i Properties/launchSettings.json, men appen använder den port som anges av app.Run("http://localhost:3000"). Kör följande portförändrande exempel från kommandoraden.

Följande avsnitt anger den port som appen svarar på.

var app = WebApplication.Create(args);

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

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

I föregående kod svarar appen på port 3000.

Flera portar

I följande kod svarar appen på port 3000 och 4000.

var app = WebApplication.Create(args);

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

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

app.Run();

Ange porten från kommandoraden

Följande kommando gör att appen svarar på port 7777:

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

Om slutpunkten Kestrel också har konfigurerats i filen appsettings.json, används den URL som specificerats i filen appsettings.json. Mer information finns i Kestrel slutpunktskonfiguration

Läsa porten från miljön

Följande kod läser porten från miljön:

var app = WebApplication.Create(args);

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

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

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

Det bästa sättet att ange porten från miljön är att använda ASPNETCORE_URLS miljövariabeln, som visas i följande avsnitt.

Ange portarna via miljövariabeln ASPNETCORE_URLS

Miljövariabeln ASPNETCORE_URLS är tillgänglig för att ange porten:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS stöder flera URL:er:

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

Lyssna på alla gränssnitt

Följande exempel visar hur alla gränssnitt avlyssnas

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

Lyssna på alla gränssnitt med hjälp av ASPNETCORE_URLS

Föregående exempel kan använda ASPNETCORE_URLS

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

Lyssna på alla gränssnitt med ASPNETCORE_HTTPS_PORTS

Föregående exempel kan använda ASPNETCORE_HTTPS_PORTS och ASPNETCORE_HTTP_PORTS.

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Mer information finns i Konfigurera slutpunkter för webbservern ASP.NET Core Kestrel

Ange HTTPS med utvecklingscertifikat

var app = WebApplication.Create(args);

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

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

app.Run();

Mer information om utvecklingscertifikatet finns i Trust the ASP.NET Core HTTPS development certificate on Windows and macOS.

Ange HTTPS med ett anpassat certifikat

Följande avsnitt visar hur du anger det anpassade certifikatet med hjälp av appsettings.json-filen och via konfiguration.

Ange det anpassade certifikatet med appsettings.json

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

Ange det anpassade certifikatet via konfiguration

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

Använda certifikat-API:erna

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

Förstå miljön

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

Mer information om hur du använder miljön finns i ASP.NET Core-körningsmiljöer

Configuration

Följande kod läser från konfigurationssystemet:

var app = WebApplication.Create(args);

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

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

app.Run();

Mer information finns i Configuration i ASP.NET Core

Logging

Följande kod skriver ett meddelande till loggen vid programstart:

var app = WebApplication.Create(args);

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

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

app.Run();

Mer information finns i Loggning i .NET och ASP.NET Core

Få åtkomst till beroendeinjektionscontainern (DI)

Följande kod visar hur du hämtar tjänster från DI-containern under programstarten:


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

Följande kod visar hur du kommer åt nycklar från DI-containern med hjälp av attributet [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.";
}

Mer information om DI finns i Beroendeinmatning i ASP.NET Core.

WebApplicationBuilder

Det här avsnittet innehåller exempelkod med hjälp av WebApplicationBuilder.

Ändra innehållsrot, programnamn och miljö

Följande kod anger innehållsrot, programnamn och miljö:

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 initierar en ny instans av klassen WebApplicationBuilder med förkonfigurerade standardvärden.

Mer information finns i översikten över grunderna i ASP.NET Core

Ändra innehållsrot, appnamn och miljö med hjälp av miljövariabler eller kommandorad

I följande tabell visas miljövariabeln och kommandoradsargumentet som används för att ändra innehållsrot, appnamn och miljö:

feature Miljövariabel Kommandoradsargument
Programnamn ASPNETCORE_APPLICATIONNAME --applicationName
Miljönamn ASPNETCORE_ENVIRONMENT --environment
Innehållsrot ASPNETCORE_CONTENTROOT --contentRoot

Lägga till konfigurationsprovidrar

Följande exempel lägger till INI-konfigurationsprovidern:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Detaljerad information finns i Filkonfigurationsproviders i Configuration i ASP.NET Core.

Läs konfiguration

Som standard läser WebApplicationBuilder konfigurationen från flera källor, inklusive:

  • appSettings.json och appSettings.{environment}.json
  • Miljövariabler
  • Kommandorad

En fullständig lista över konfigurationskällor finns i Standardkonfiguration i Configuration i ASP.NET Core.

Följande kod läser HelloKey från konfigurationen och visar värdet vid / slutpunkten. Om konfigurationsvärdet är null tilldelas "Hello" till message:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Förstå miljön

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Lägg till loggningsleverantörer

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

Lägga till tjänster

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

Anpassa IHostBuilder

Befintliga tilläggsmetoder på IHostBuilder kan nås med egenskapen 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();

Anpassa IWebHostBuilder

Tilläggsmetoder på IWebHostBuilder kan nås med hjälp av egenskapen 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();

Ändra webbplatsens rot

Som standard är webbroten relativ till innehållsroten i mappen wwwroot. Webbrooten är där det statiska filmellanprogrammet letar efter statiska filer. Webbroten kan ändras med WebHostOptions, kommandoraden eller med metoden UseWebRoot:

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

var app = builder.Build();

app.Run();

Container för anpassad beroendeinjektion (DI)

I följande exempel används 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();

Lägg till mellanprogram

Alla befintliga ASP.NET Core-mellanprogram kan konfigureras på WebApplication:

var app = WebApplication.Create(args);

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

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

app.Run();

Mer information finns i ASP.NET Core Middleware

Undantagssida för utvecklare

WebApplication.CreateBuilder initierar en ny instans av klassen WebApplicationBuilder med förkonfigurerade standardvärden. Undantagssidan för utvecklare är aktiverad i de förkonfigurerade standardvärdena. När följande kod körs i utvecklingsmiljönrenderar navigering till / en vänlig sida som visar undantaget.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();

WebApplication

Följande kod genereras av en ASP.NET Core-mall:

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

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

app.Run();

Föregående kod kan skapas via dotnet new web på kommandoraden eller genom att välja mallen Tom webb i Visual Studio.

Följande kod skapar en WebApplication (app) utan att uttryckligen skapa en WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.Create initierar en ny instans av klassen WebApplication med förkonfigurerade standardvärden.

WebApplication lägger automatiskt till följande mellanprogram i Minimala API-program beroende på vissa villkor:

  • UseDeveloperExceptionPage läggs till först när HostingEnvironment är "Development".
  • UseRouting läggs till som nummer två om användarkoden inte redan har anropat UseRouting och om det finns konfigurerade slutpunkter, till exempel app.MapGet.
  • UseEndpoints läggs till i slutet av pipelinen för mellanprogram om några slutpunkter har konfigurerats.
  • UseAuthentication läggs till omedelbart efter UseRouting om användarkoden inte redan anropade UseAuthentication och om IAuthenticationSchemeProvider kan identifieras i tjänstleverantören. IAuthenticationSchemeProvider läggs till som standard när du använder AddAuthenticationoch tjänster identifieras med hjälp av IServiceProviderIsService.
  • UseAuthorization läggs till nästa om användarkoden inte redan anropar UseAuthorization och om IAuthorizationHandlerProvider kan identifieras i tjänstleverantören. IAuthorizationHandlerProvider läggs till som standard när du använder AddAuthorizationoch tjänster identifieras med hjälp av IServiceProviderIsService.
  • Användar konfigurerade mellanprogram och slutpunkter läggs till mellan UseRouting och UseEndpoints.

Följande kod är i praktiken vad det automatiska mellanprogrammet som läggs till i appen genererar:

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

I vissa fall är standardkonfigurationen för mellanprogram inte korrekt för appen och kräver ändringar. Till exempel ska UseCors anropas före UseAuthentication och UseAuthorization. Appen måste anropa UseAuthentication och UseAuthorization om UseCors anropas:

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

Om mellanprogram ska köras innan routningsmatchning sker ska UseRouting anropas och mellanprogrammet placeras innan anropet till UseRouting. UseEndpoints krävs inte i det här fallet eftersom det läggs till automatiskt enligt beskrivningen ovan:

app.Use((context, next) =>
{
    return next(context);
});

app.UseRouting();

// other middleware and endpoints

När du lägger till ett terminalmellanprogram:

  • Mellanprogrammet måste läggas till efter UseEndpoints.
  • Appen måste anropa UseRouting och UseEndpoints så att terminalmellanprogrammet kan placeras på rätt plats.
app.UseRouting();

app.MapGet("/", () => "hello world");

app.UseEndpoints(e => {});

app.Run(context =>
{
    context.Response.StatusCode = 404;
    return Task.CompletedTask;
});

Terminalmellanprogram är mellanprogram som körs om ingen slutpunkt hanterar begäran.

Arbeta med portar

När en webbapp skapas med Visual Studio eller dotnet newskapas en Properties/launchSettings.json fil som anger de portar som appen svarar på. I portinställningsexemplen som följer returnerar körning av appen från Visual Studio en feldialogruta Unable to connect to web server 'AppName'. Visual Studio returnerar ett fel eftersom den förväntar sig att porten som anges i Properties/launchSettings.json, men appen använder den port som anges av app.Run("http://localhost:3000"). Kör följande portförändrande exempel från kommandoraden.

Följande avsnitt anger den port som appen svarar på.

var app = WebApplication.Create(args);

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

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

I föregående kod svarar appen på port 3000.

Flera portar

I följande kod svarar appen på port 3000 och 4000.

var app = WebApplication.Create(args);

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

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

app.Run();

Ange porten från kommandoraden

Följande kommando gör att appen svarar på port 7777:

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

Om slutpunkten Kestrel också har konfigurerats i filen appsettings.json, används den URL som specificerats i filen appsettings.json. Mer information finns i Kestrel slutpunktskonfiguration

Läsa porten från miljön

Följande kod läser porten från miljön:

var app = WebApplication.Create(args);

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

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

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

Det bästa sättet att ange porten från miljön är att använda ASPNETCORE_URLS miljövariabeln, som visas i följande avsnitt.

Ange portarna via miljövariabeln ASPNETCORE_URLS

Miljövariabeln ASPNETCORE_URLS är tillgänglig för att ange porten:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS stöder flera URL:er:

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

Lyssna på alla gränssnitt

Följande exempel visar hur alla gränssnitt avlyssnas

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

Lyssna på alla gränssnitt med hjälp av ASPNETCORE_URLS

Föregående exempel kan använda ASPNETCORE_URLS

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

Lyssna på alla gränssnitt med ASPNETCORE_HTTPS_PORTS

Föregående exempel kan använda ASPNETCORE_HTTPS_PORTS och ASPNETCORE_HTTP_PORTS.

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Mer information finns i Konfigurera slutpunkter för webbservern ASP.NET Core Kestrel

Ange HTTPS med utvecklingscertifikat

var app = WebApplication.Create(args);

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

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

app.Run();

Mer information om utvecklingscertifikatet finns i Trust the ASP.NET Core HTTPS development certificate on Windows and macOS.

Ange HTTPS med ett anpassat certifikat

Följande avsnitt visar hur du anger det anpassade certifikatet med hjälp av appsettings.json-filen och via konfiguration.

Ange det anpassade certifikatet med appsettings.json

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

Ange det anpassade certifikatet via konfiguration

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

Använda certifikat-API:erna

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

Förstå miljön

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

Mer information om hur du använder miljön finns i ASP.NET Core-körningsmiljöer

Configuration

Följande kod läser från konfigurationssystemet:

var app = WebApplication.Create(args);

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

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

app.Run();

Mer information finns i Configuration i ASP.NET Core

Logging

Följande kod skriver ett meddelande till loggen vid programstart:

var app = WebApplication.Create(args);

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

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

app.Run();

Mer information finns i Loggning i .NET och ASP.NET Core

Få åtkomst till beroendeinjektionscontainern (DI)

Följande kod visar hur du hämtar tjänster från DI-containern under programstarten:


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

Följande kod visar hur du kommer åt nycklar från DI-containern med hjälp av attributet [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.";
}

Mer information om DI finns i Beroendeinmatning i ASP.NET Core.

WebApplicationBuilder

Det här avsnittet innehåller exempelkod med hjälp av WebApplicationBuilder.

Ändra innehållsrot, programnamn och miljö

Följande kod anger innehållsrot, programnamn och miljö:

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 initierar en ny instans av klassen WebApplicationBuilder med förkonfigurerade standardvärden.

Mer information finns i översikten över grunderna i ASP.NET Core

Ändra innehållsrot, appnamn och miljö med hjälp av miljövariabler eller kommandorad

I följande tabell visas miljövariabeln och kommandoradsargumentet som används för att ändra innehållsrot, appnamn och miljö:

feature Miljövariabel Kommandoradsargument
Programnamn ASPNETCORE_APPLICATIONNAME --applicationName
Miljönamn ASPNETCORE_ENVIRONMENT --environment
Innehållsrot ASPNETCORE_CONTENTROOT --contentRoot

Lägga till konfigurationsprovidrar

Följande exempel lägger till INI-konfigurationsprovidern:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Detaljerad information finns i Filkonfigurationsproviders i Configuration i ASP.NET Core.

Läs konfiguration

Som standard läser WebApplicationBuilder konfigurationen från flera källor, inklusive:

  • appSettings.json och appSettings.{environment}.json
  • Miljövariabler
  • Kommandorad

En fullständig lista över konfigurationskällor finns i Standardkonfiguration i Configuration i ASP.NET Core.

Följande kod läser HelloKey från konfigurationen och visar värdet vid / slutpunkten. Om konfigurationsvärdet är null tilldelas "Hello" till message:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Förstå miljön

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Lägg till loggningsleverantörer

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

Lägga till tjänster

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

Anpassa IHostBuilder

Befintliga tilläggsmetoder på IHostBuilder kan nås med egenskapen 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();

Anpassa IWebHostBuilder

Tilläggsmetoder på IWebHostBuilder kan nås med hjälp av egenskapen 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();

Ändra webbplatsens rot

Som standard är webbroten relativ till innehållsroten i mappen wwwroot. Webbrooten är där det statiska filmellanprogrammet letar efter statiska filer. Webbroten kan ändras med WebHostOptions, kommandoraden eller med metoden UseWebRoot:

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

var app = builder.Build();

app.Run();

Container för anpassad beroendeinjektion (DI)

I följande exempel används 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();

Lägg till mellanprogram

Alla befintliga ASP.NET Core-mellanprogram kan konfigureras på WebApplication:

var app = WebApplication.Create(args);

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

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

app.Run();

Mer information finns i ASP.NET Core Middleware

Undantagssida för utvecklare

WebApplication.CreateBuilder initierar en ny instans av klassen WebApplicationBuilder med förkonfigurerade standardvärden. Undantagssidan för utvecklare är aktiverad i de förkonfigurerade standardvärdena. När följande kod körs i utvecklingsmiljönrenderar navigering till / en vänlig sida som visar undantaget.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();

WebApplication

Följande kod genereras av en ASP.NET Core-mall:

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

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

app.Run();

Föregående kod kan skapas via dotnet new web på kommandoraden eller genom att välja mallen Tom webb i Visual Studio.

Följande kod skapar en WebApplication (app) utan att uttryckligen skapa en WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.Create initierar en ny instans av klassen WebApplication med förkonfigurerade standardvärden.

WebApplication lägger automatiskt till följande mellanprogram i Minimala API-program beroende på vissa villkor:

  • UseDeveloperExceptionPage läggs till först när HostingEnvironment är "Development".
  • UseRouting läggs till som nummer två om användarkoden inte redan har anropat UseRouting och om det finns konfigurerade slutpunkter, till exempel app.MapGet.
  • UseEndpoints läggs till i slutet av pipelinen för mellanprogram om några slutpunkter har konfigurerats.
  • UseAuthentication läggs till omedelbart efter UseRouting om användarkoden inte redan anropade UseAuthentication och om IAuthenticationSchemeProvider kan identifieras i tjänstleverantören. IAuthenticationSchemeProvider läggs till som standard när du använder AddAuthenticationoch tjänster identifieras med hjälp av IServiceProviderIsService.
  • UseAuthorization läggs till nästa om användarkoden inte redan anropar UseAuthorization och om IAuthorizationHandlerProvider kan identifieras i tjänstleverantören. IAuthorizationHandlerProvider läggs till som standard när du använder AddAuthorizationoch tjänster identifieras med hjälp av IServiceProviderIsService.
  • Användar konfigurerade mellanprogram och slutpunkter läggs till mellan UseRouting och UseEndpoints.

Följande kod är i praktiken vad det automatiska mellanprogrammet som läggs till i appen genererar:

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

I vissa fall är standardkonfigurationen för mellanprogram inte korrekt för appen och kräver ändringar. Till exempel ska UseCors anropas före UseAuthentication och UseAuthorization. Appen måste anropa UseAuthentication och UseAuthorization om UseCors anropas:

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

Om mellanprogram ska köras innan routningsmatchning sker ska UseRouting anropas och mellanprogrammet placeras innan anropet till UseRouting. UseEndpoints krävs inte i det här fallet eftersom det läggs till automatiskt enligt beskrivningen ovan:

app.Use((context, next) =>
{
    return next(context);
});

app.UseRouting();

// other middleware and endpoints

När du lägger till ett terminalmellanprogram:

  • Mellanprogrammet måste läggas till efter UseEndpoints.
  • Appen måste anropa UseRouting och UseEndpoints så att terminalmellanprogrammet kan placeras på rätt plats.
app.UseRouting();

app.MapGet("/", () => "hello world");

app.UseEndpoints(e => {});

app.Run(context =>
{
    context.Response.StatusCode = 404;
    return Task.CompletedTask;
});

Terminalmellanprogram är mellanprogram som körs om ingen slutpunkt hanterar begäran.

Arbeta med portar

När en webbapp skapas med Visual Studio eller dotnet newskapas en Properties/launchSettings.json fil som anger de portar som appen svarar på. I portinställningsexemplen som följer returnerar körning av appen från Visual Studio en feldialogruta Unable to connect to web server 'AppName'. Visual Studio returnerar ett fel eftersom den förväntar sig att porten som anges i Properties/launchSettings.json, men appen använder den port som anges av app.Run("http://localhost:3000"). Kör följande portförändrande exempel från kommandoraden.

Följande avsnitt anger den port som appen svarar på.

var app = WebApplication.Create(args);

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

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

I föregående kod svarar appen på port 3000.

Flera portar

I följande kod svarar appen på port 3000 och 4000.

var app = WebApplication.Create(args);

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

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

app.Run();

Ange porten från kommandoraden

Följande kommando gör att appen svarar på port 7777:

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

Om slutpunkten Kestrel också har konfigurerats i filen appsettings.json, används den URL som specificerats i filen appsettings.json. Mer information finns i Kestrel slutpunktskonfiguration

Läsa porten från miljön

Följande kod läser porten från miljön:

var app = WebApplication.Create(args);

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

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

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

Det bästa sättet att ange porten från miljön är att använda ASPNETCORE_URLS miljövariabeln, som visas i följande avsnitt.

Ange portarna via miljövariabeln ASPNETCORE_URLS

Miljövariabeln ASPNETCORE_URLS är tillgänglig för att ange porten:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS stöder flera URL:er:

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

Lyssna på alla gränssnitt

Följande exempel visar hur alla gränssnitt avlyssnas

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

Lyssna på alla gränssnitt med hjälp av ASPNETCORE_URLS

Föregående exempel kan använda ASPNETCORE_URLS

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

Lyssna på alla gränssnitt med ASPNETCORE_HTTPS_PORTS

Föregående exempel kan använda ASPNETCORE_HTTPS_PORTS och ASPNETCORE_HTTP_PORTS.

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Mer information finns i Konfigurera slutpunkter för webbservern ASP.NET Core Kestrel

Ange HTTPS med utvecklingscertifikat

var app = WebApplication.Create(args);

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

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

app.Run();

Mer information om utvecklingscertifikatet finns i Trust the ASP.NET Core HTTPS development certificate on Windows and macOS.

Ange HTTPS med ett anpassat certifikat

Följande avsnitt visar hur du anger det anpassade certifikatet med hjälp av appsettings.json-filen och via konfiguration.

Ange det anpassade certifikatet med appsettings.json

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

Ange det anpassade certifikatet via konfiguration

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

Använda certifikat-API:erna

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

Förstå miljön

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

Mer information om hur du använder miljön finns i ASP.NET Core-körningsmiljöer

Configuration

Följande kod läser från konfigurationssystemet:

var app = WebApplication.Create(args);

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

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

app.Run();

Mer information finns i Configuration i ASP.NET Core

Logging

Följande kod skriver ett meddelande till loggen vid programstart:

var app = WebApplication.Create(args);

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

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

app.Run();

Mer information finns i Loggning i .NET och ASP.NET Core

Få åtkomst till beroendeinjektionscontainern (DI)

Följande kod visar hur du hämtar tjänster från DI-containern under programstarten:


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

Följande kod visar hur du kommer åt nycklar från DI-containern med hjälp av attributet [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.";
}

Mer information om DI finns i Beroendeinmatning i ASP.NET Core.

WebApplicationBuilder

Det här avsnittet innehåller exempelkod med hjälp av WebApplicationBuilder.

Ändra innehållsrot, programnamn och miljö

Följande kod anger innehållsrot, programnamn och miljö:

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 initierar en ny instans av klassen WebApplicationBuilder med förkonfigurerade standardvärden.

Mer information finns i översikten över grunderna i ASP.NET Core

Ändra innehållsrot, appnamn och miljö med hjälp av miljövariabler eller kommandorad

I följande tabell visas miljövariabeln och kommandoradsargumentet som används för att ändra innehållsrot, appnamn och miljö:

feature Miljövariabel Kommandoradsargument
Programnamn ASPNETCORE_APPLICATIONNAME --applicationName
Miljönamn ASPNETCORE_ENVIRONMENT --environment
Innehållsrot ASPNETCORE_CONTENTROOT --contentRoot

Lägga till konfigurationsprovidrar

Följande exempel lägger till INI-konfigurationsprovidern:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Detaljerad information finns i Filkonfigurationsproviders i Configuration i ASP.NET Core.

Läs konfiguration

Som standard läser WebApplicationBuilder konfigurationen från flera källor, inklusive:

  • appSettings.json och appSettings.{environment}.json
  • Miljövariabler
  • Kommandorad

En fullständig lista över konfigurationskällor finns i Standardkonfiguration i Configuration i ASP.NET Core.

Följande kod läser HelloKey från konfigurationen och visar värdet vid / slutpunkten. Om konfigurationsvärdet är null tilldelas "Hello" till message:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Förstå miljön

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Lägg till loggningsleverantörer

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

Lägga till tjänster

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

Anpassa IHostBuilder

Befintliga tilläggsmetoder på IHostBuilder kan nås med egenskapen 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();

Anpassa IWebHostBuilder

Tilläggsmetoder på IWebHostBuilder kan nås med hjälp av egenskapen 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();

Ändra webbplatsens rot

Som standard är webbroten relativ till innehållsroten i mappen wwwroot. Webbrooten är där det statiska filmellanprogrammet letar efter statiska filer. Webbroten kan ändras med WebHostOptions, kommandoraden eller med metoden UseWebRoot:

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

var app = builder.Build();

app.Run();

Container för anpassad beroendeinjektion (DI)

I följande exempel används 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();

Lägg till mellanprogram

Alla befintliga ASP.NET Core-mellanprogram kan konfigureras på WebApplication:

var app = WebApplication.Create(args);

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

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

app.Run();

Mer information finns i ASP.NET Core Middleware

Undantagssida för utvecklare

WebApplication.CreateBuilder initierar en ny instans av klassen WebApplicationBuilder med förkonfigurerade standardvärden. Undantagssidan för utvecklare är aktiverad i de förkonfigurerade standardvärdena. När följande kod körs i utvecklingsmiljönrenderar navigering till / en vänlig sida som visar undantaget.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();