WebApplication és WebApplicationBuilder minimális API-alkalmazásokban

WebApplication

A következő kódot egy ASP.NET Core-sablon hozza létre:

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

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

app.Run();

Az előző kód a parancssori dotnet new web vagy a Visual Studio Üres websablonjának kiválasztásával hozható létre.

A következő kód létrehoz egy WebApplication (app) anélkül, hogy explicit módon létrehoz egy WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.Create inicializálja a WebApplication osztály új példányát előre konfigurált alapértelmezett értékekkel.

Portok használata

Amikor webalkalmazást hoz létre a Visual Studióval vagy dotnet new, létrejön egy Properties/launchSettings.json fájl, amely meghatározza azokat a portokat, amelyekre az alkalmazás válaszol. Az alábbi portbeállítási mintákban az alkalmazás Visual Studióból való futtatása hibaüzenetet ad vissza Unable to connect to web server 'AppName'. A Visual Studio hibát ad vissza, mert a Properties/launchSettings.jsonmegadott portot várja, de az alkalmazás a app.Run("http://localhost:3000")által megadott portot használja. Futtassa a következő portmódosítási mintákat a parancssorból.

Az alábbi szakaszok azt a portot állítják be, amelyekre az alkalmazás válaszol.

var app = WebApplication.Create(args);

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

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

Az előző kódban az alkalmazás reagál a 3000porton.

Több port

Az alábbi kódban az alkalmazás válaszol a port 3000 és 4000.

var app = WebApplication.Create(args);

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

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

app.Run();

A port beállítása a parancssorból

Az alábbi parancs lehetővé teszi, hogy az alkalmazás a 7777porton fogadjon.

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

Ha a Kestrel végpont is konfigurálva van a appsettings.json fájlban, a appsettings.json megadott URL-címet használja a rendszer. További információért lásd: Kestrel végpont konfiguráció

A port beolvasása a környezetből

A következő kód beolvassa a portot a környezetből:

var app = WebApplication.Create(args);

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

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

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

A port környezetből való beállításának elsődleges módja a ASPNETCORE_URLS környezeti változó használata, amely az alábbi szakaszban látható.

Portok beállítása a ASPNETCORE_URLS környezeti változón keresztül

A port beállításához elérhető a ASPNETCORE_URLS környezeti változó:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS több URL-címet is támogat:

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

Figyelés az összes felületen

Az alábbi minták azt mutatják be, hogy az összes felületen figyelnek

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

Hallgatás minden felületen az ASPNETCORE_URLS használatával

Az előző minták használhatják a ASPNETCORE_URLS-t.

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

Figyeljen minden interfészen az ASPNETCORE_HTTPS_PORTS használatával

Az előző minták használhatják a ASPNETCORE_HTTPS_PORTS és ASPNETCORE_HTTP_PORTSkódokat.

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

További információ: Végpontok konfigurálása a ASP.NET Core Kestrel webkiszolgálóhoz

HTTPS beállítása fejlesztési tanúsítvánnyal

var app = WebApplication.Create(args);

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

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

app.Run();

A fejlesztési tanúsítvánnyal kapcsolatos további információkért lásd: Az ASP.NET Core HTTPS fejlesztési tanúsítvány hitelesítése Windows és macOS.

HTTPS megadása egyéni tanúsítvány használatával

Az alábbi szakaszok bemutatják, hogyan adhatja meg az egyéni tanúsítványt a appsettings.json fájllal és konfigurációval.

Adja meg a testreszabott tanúsítványt a appsettings.json jelöléssel

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

Az egyéni tanúsítvány megadása konfigurációval

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

A tanúsítvány API-k használata

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

A környezet olvasása

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

További információ a környezet használatáról: ASP.NET Core futtatókörnyezetek

Configuration

A következő kód a konfigurációs rendszerből olvas be:

var app = WebApplication.Create(args);

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

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

app.Run();

Lásd a(z) ASP.NET Core konfigurációt a további információkért.

Logging

Az alábbi kód egy üzenetet ír az alkalmazás indítási naplójába:

var app = WebApplication.Create(args);

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

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

app.Run();

További információ: Naplózás a .NET-ben és a ASP.NET Core-ban

A függőség-injektálás (DI) konténer elérése

Az alábbi kód bemutatja, hogyan kérhet le szolgáltatásokat a DI-tárolóból az alkalmazás indításakor:

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

Az alábbi kód bemutatja, hogyan érheti el a kulcsokat a DI-tárolóból a [FromKeyedServices] attribútum használatával:

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

További információ a DI-ről a Függőséginjektálás az ASP.NET Corecímű részben található.

WebApplicationBuilder

Ez a szakasz WebApplicationBuilderhasználatával tartalmaz mintakódot.

A tartalomgyöker, az alkalmazásnév és a környezet módosítása

A következő kód állítja be a tartalom gyökerét, az alkalmazás nevét és a környezetet:

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 inicializálja a WebApplicationBuilder osztály új példányát előre konfigurált alapértelmezett beállításokkal.

További információ: ASP.NET Alapvető alapismeretek áttekintése

A tartalomgyöker, az alkalmazás neve és a környezet módosítása környezeti változók vagy parancssor használatával

Az alábbi táblázat a tartalomgyöker, az alkalmazásnév és a környezet módosításához használt környezeti változót és parancssori argumentumot mutatja be:

funkció	Környezet változó	Parancssori argumentum
Alkalmazás neve	ASPNETCORE_APPLICATIONNAME	--applicationName
Környezet neve	ASPNETCORE_ENVIRONMENT	--environment
Tartalomgyökér	ASPNETCORE_CONTENTROOT	--contentRoot

Konfigurációszolgáltatók hozzáadása

Az alábbi minta hozzáadja az INI-konfigurációszolgáltatót:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Részletes információért lásd: Fájlkonfigurációs szolgáltatók az ASP.NET Core konfigurációjában.

Olvasási konfiguráció

Alapértelmezés szerint a WebApplicationBuilder több forrásból olvassa be a konfigurációt, beleértve a következőket:

• appSettings.json és appSettings.{environment}.json
• Környezeti változók
• A parancssor

A konfigurációs források teljes listáját a Alapértelmezett konfiguráció című részben találja, amely része a konfigurációnak az ASP.NET Coredokumentumban.

Az alábbi kód beolvassa HelloKey konfigurációból, és megjeleníti az értéket a / végponton. Ha a konfiguráció értéke null, a "Hello" messagevan hozzárendelve:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

A környezet olvasása

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Naplózási szolgáltatók hozzáadása

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

Szolgáltatások hozzáadása

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

Az IHostBuilder testreszabása

A IHostBuilder meglévő bővítési metódusok a Gazdagép tulajdonsághasználatával érhetők el.

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

Az IWebHostBuilder testreszabása

A IWebHostBuilder bővítménymetelyek a WebApplicationBuilder.WebHost tulajdonság használatával érhetők el.

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

Webes gyökér módosítása

Alapértelmezés szerint a webes gyökér a wwwroot mappában lévő tartalomgyökerhez képest van. A webes gyökér az, ahol a Statikus fájl köztes szoftver statikus fájlokat keres. A webes gyökér a WebHostOptions, a parancssor vagy a UseWebRoot metódus használatával módosítható:

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

var app = builder.Build();

app.Run();

Egyéni függőséginjektáló (DI) tároló

Az alábbi példa Autofachasznál:

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

Köztes szoftver hozzáadása

Bármely meglévő ASP.NET Core middleware konfigurálható a WebApplication:

var app = WebApplication.Create(args);

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

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

app.Run();

További információ: ASP.NET Core Middleware

Fejlesztői kivételoldal

WebApplication.CreateBuilder inicializálja a WebApplicationBuilder osztály új példányát előre konfigurált alapértelmezett értékekkel. A fejlesztői kivételoldal engedélyezve van az előre konfigurált alapértelmezett beállításokban. Ha a következő kódot a fejlesztési környezetben futtatja, a / navigálással egy barátságos oldal jelenik meg, ami megmutatja a kivételt.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();