WebApplication y WebApplicationBuilder en aplicaciones de API mínimas

WebApplication

Una plantilla de ASP.NET Core genera el código siguiente:

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

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

app.Run();

El código anterior se puede crear a través de dotnet new web en la línea de comandos o seleccionando la plantilla web vacía en Visual Studio.

El código siguiente crea una clase WebApplication (app) sin crear explícitamente una clase WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.Create inicializa una nueva instancia de la clase WebApplication con valores predeterminados preconfigurados.

Trabajo con puertos

Cuando se crea una aplicación web con Visual Studio o dotnet new, se crea un archivo Properties/launchSettings.json que especifica los puertos a los que responde la aplicación. En los siguientes ejemplos de configuración de los puertos, al ejecutar la aplicación desde Visual Studio se devuelve un cuadro de diálogo de error Unable to connect to web server 'AppName'. Visual Studio devuelve un error porque espera el puerto especificado en Properties/launchSettings.json, pero la aplicación usa el puerto que especifica app.Run("http://localhost:3000"). Ejecute los siguientes ejemplos de cambio de puertos desde la línea de comandos.

En las secciones siguientes se establece el puerto al que responde la aplicación.

var app = WebApplication.Create(args);

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

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

En el código anterior, la aplicación responde al puerto 3000.

Varios puertos

En el código siguiente, la aplicación responde a los puertos 3000 y 4000.

var app = WebApplication.Create(args);

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

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

app.Run();

Establecimiento del puerto desde la línea de comandos

El siguiente comando hace que la aplicación responda al puerto 7777:

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

Si el punto de conexión Kestrel también está configurado en el archivo appsettings.json , se usa la dirección URL especificada del archivo appsettings.json . Para más información, vea Configuración del punto de conexión de Kestrel.

Lectura del puerto desde el entorno

El código siguiente lee el puerto desde el entorno:

var app = WebApplication.Create(args);

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

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

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

La manera preferida de establecer el puerto desde el entorno es usar la variable de entorno ASPNETCORE_URLS, que se muestra en la sección siguiente.

Establecimiento de los puertos mediante la variable de entorno ASPNETCORE_URLS

La variable de entorno ASPNETCORE_URLS está disponible para establecer el puerto:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS admite varias direcciones URL:

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

Escucha en todas las interfaces

En los ejemplos siguientes se muestra la escucha en todas las 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();

Escucha en todas las interfaces mediante ASPNETCORE_URLS

Los ejemplos anteriores pueden usar ASPNETCORE_URLS.

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

Escucha en todas las interfaces mediante ASPNETCORE_HTTPS_PORTS

Los ejemplos anteriores pueden usar ASPNETCORE_HTTPS_PORTS y ASPNETCORE_HTTP_PORTS.

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Para obtener más información, vea Configuración de puntos de conexión para el servidor web Kestrel de ASP.NET Core.

Especificación de HTTPS con certificado de desarrollo

var app = WebApplication.Create(args);

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

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

app.Run();

Para más información sobre el certificado de desarrollo, vea Confianza en el certificado de desarrollo HTTPS de ASP.NET Core en Windows y macOS.

Especificación de HTTPS mediante un certificado personalizado

En las secciones siguientes se muestra cómo especificar el certificado personalizado con el archivo appsettings.json y mediante la configuración.

Especificación del certificado personalizado con appsettings.json

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

Especificación del certificado personalizado mediante la configuración

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

Uso de las API de certificado

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

Lectura del entorno

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

Para más información sobre el uso de los entornos, consulte Uso de varios entornos en ASP.NET Core.

Configuración

El código siguiente lee del sistema de configuración:

var app = WebApplication.Create(args);

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

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

app.Run();

Para más información, consulte Configuración en ASP.NET Core.

Registro

El código siguiente escribe un mensaje en el registro al iniciar la aplicación:

var app = WebApplication.Create(args);

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

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

app.Run();

Para obtener más información, vea Registro en .NET Core y ASP.NET Core.

Acceso al contenedor de inserción de dependencias (DI)

En el código siguiente se muestra cómo obtener servicios del contenedor de DI durante el inicio de la aplicación:

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

El siguiente programa muestra cómo acceder a las claves del contenedor de inserción de dependencias mediante el [FromKeyedServices] atributo :

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

Para obtener más información sobre DI, consulte Inserción de dependencias en ASP.NET Core.

WebApplicationBuilder

Esta sección contiene código de ejemplo mediante WebApplicationBuilder.

Cambio de la raíz del contenido, el nombre de la aplicación y el entorno

El código siguiente establece la raíz del contenido, el nombre de la aplicación y el entorno:

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 inicializa una nueva instancia de la clase WebApplicationBuilder con valores predeterminados preconfigurados.

Para obtener más información, consulte Información general de los conceptos básicos de ASP.NET Core.

Cambio de la raíz del contenido, del nombre de la aplicación y del entorno mediante variables de entorno o la línea de comandos

En la tabla siguiente se muestra la variable de entorno y el argumento de la línea de comandos usados para cambiar la raíz del contenido, el nombre de la aplicación y el entorno:

feature	Variable de entorno	Argumento de línea de comandos
Nombre de la aplicación	ASPNETCORE_APPLICATIONNAME	--applicationName
Nombre del entorno	ASPNETCORE_ENVIRONMENT	--environment
Raíz del contenido	ASPNETCORE_CONTENTROOT	--contentRoot

Incorporación de proveedores de configuración

En el ejemplo siguiente se agrega el proveedor de configuración INI:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Para obtener información detallada, vea Proveedores de configuración de archivos en Configuración en ASP.NET Core.

Lectura de la configuración

De forma predeterminada, WebApplicationBuilder lee la configuración de varios orígenes, incluidos:

• appSettings.json y appSettings.{environment}.json
• Variables de entorno
• Línea de comandos

Para obtener una lista completa de orígenes de configuración leídos, vea Configuración predeterminada en Configuración en ASP.NET Core.

El código siguiente lee HelloKey de la configuración y muestra el valor en el punto de conexión /. Si el valor de configuración es null, "Hello" se asigna a message:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Lectura del entorno

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Adición de proveedores de registro

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

Agrega servicios

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

Personalización de IHostBuilder

Se puede acceder a los métodos de extensión existentes en IHostBuilder mediante la propiedad de 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();

Personalización de IWebHostBuilder

Se puede acceder a los métodos de extensión en IWebHostBuilder mediante la propiedad 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();

Cambio de la raíz web

De forma predeterminada, la raíz web guarda relación con la raíz de contenido de la carpeta wwwroot. La raíz web es donde el middleware de archivos estáticos busca archivos estáticos. La raíz web se puede cambiar con WebHostOptions, la línea de comandos o el método UseWebRoot:

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

var app = builder.Build();

app.Run();

Contenedor de inserción de dependencias (ID) personalizado

En el ejemplo siguiente se usa Autofac:

var builder = WebApplication.CreateBuilder(args);

builder.Host.UseServiceProviderFactory(new AutofacServiceProviderFactory());

// Register services directly with Autofac here. Don't
// call builder.Populate(), that happens in AutofacServiceProviderFactory.
builder.Host.ConfigureContainer<ContainerBuilder>(builder => builder.RegisterModule(new MyApplicationModule()));

var app = builder.Build();

Adición de middleware

Cualquier middleware de ASP.NET Core existente se puede configurar en WebApplication:

var app = WebApplication.Create(args);

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

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

app.Run();

Para obtener más información, consulte Middleware de ASP.NET Core.

Página de excepciones para el desarrollador

WebApplication.CreateBuilder inicializa una nueva instancia de la clase WebApplicationBuilder con valores predeterminados preconfigurados. La página de excepciones para el desarrollador está habilitada en los valores predeterminados preconfigurados. Cuando se ejecuta el código siguiente en el entorno de desarrollo, la navegación a / representa una página descriptiva que muestra la excepción.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();