WebApplication y WebApplicationBuilder en aplicaciones ASP.NET Core

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

if (isDevelopment)
{
    app.UseDeveloperExceptionPage();
}

app.UseRouting();

if (isAuthenticationConfigured)
{
    app.UseAuthentication();
}

if (isAuthorizationConfigured)
{
    app.UseAuthorization();
}

// user middleware/endpoints
app.CustomMiddleware(...);
app.MapGet("/", () => "hello world");
// end user middleware/endpoints

app.UseEndpoints(e => {});

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

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

app.UseRouting();

// other middleware and endpoints

app.UseRouting();

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

app.UseEndpoints(e => {});

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

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 de 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 al puerto 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, consulte Kestrel configuración del endpoint

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.

Configure 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

Para obtener más información sobre el uso del entorno, consulte ASP.NET Core entornos en tiempo de ejecución.

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

Escuche en todas las interfaces con ASPNETCORE_URLS

Los ejemplos anteriores pueden usar ASPNETCORE_URLS:

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

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

Configuration

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 obtener más información, consulte Configuración en ASP.NET Core.

Logging

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, consulte Registro en .NET 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();

Para más información, 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.Create inicializa una nueva instancia de la clase WebApplication con valores predeterminados preconfigurados.

Para obtener más información, consulte visión general de los fundamentos de ASP.NET Core.

Cambio de la raíz del contenido, el nombre de la aplicación y el 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 que se usan para cambiar la raíz del contenido, el nombre de la aplicación y el entorno.

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.

Leer 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

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

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

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

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

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

Personalizar el IWebHostBuilder

Se puede tener acceso a los métodos de extensión en IWebHostBuilder mediante la WebApplicationBuilder.WebHost propiedad .

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 los 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 personalizado de inyección de dependencias (DI)

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

Añadir 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 ASP.NET Core middleware.

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 siguiente código en el entorno de desarrollo, al navegar a / se muestra una página informativa 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();

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

if (isDevelopment)
{
    app.UseDeveloperExceptionPage();
}

app.UseRouting();

if (isAuthenticationConfigured)
{
    app.UseAuthentication();
}

if (isAuthorizationConfigured)
{
    app.UseAuthorization();
}

// User middleware/endpoints
app.CustomMiddleware(...);
app.MapGet("/", () => "hello world");
// End user middleware/endpoints

app.UseEndpoints(e => {});

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

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

app.UseRouting();

// Other middleware and endpoints

app.UseRouting();

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

app.UseEndpoints(e => {});

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

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 de 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 al puerto 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, consulte Kestrel configuración del endpoint

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.

Configure 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

Los ejemplos siguientes muestran 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();

Escuche en todas las interfaces con ASPNETCORE_URLS

Los ejemplos anteriores pueden usar ASPNETCORE_URLS:

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

Escuchar en todas las interfaces usando ASPNETCORE_HTTP_PORTS y ASPNETCORE_HTTPS_PORTS

Los ejemplos anteriores también pueden usar ASPNETCORE_HTTP_PORTS y ASPNETCORE_HTTPS_PORTS, pero ASPNETCORE_URLS (cuando se establece) invalida la siguiente configuración:

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Para obtener más información, consulte Configuración de puntos de conexión para el Kestrel servidor web.

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

Lee el 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 obtener más información sobre el uso del entorno, consulte ASP.NET Core entornos en tiempo de ejecución.

Configuration

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 obtener más información, consulte Configuración en ASP.NET Core.

Logging

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, consulte Registro en .NET 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 código muestra cómo acceder a las claves del contenedor de inserción de dependencias mediante el atributo [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.";
}

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.Create inicializa una nueva instancia de la clase WebApplication 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 que se usan para cambiar la raíz del contenido, el nombre de la aplicación y el entorno.

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.

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

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

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

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

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

Personalizar el IWebHostBuilder

Se puede tener acceso a los métodos de extensión en IWebHostBuilder mediante la WebApplicationBuilder.WebHost propiedad .

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 los 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 personalizado de inyección de dependencias (DI)

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

Añadir 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 ASP.NET Core middleware.

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 siguiente código en el entorno de desarrollo, al navegar a / se muestra una página informativa 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();

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

if (isDevelopment)
{
    app.UseDeveloperExceptionPage();
}

app.UseRouting();

if (isAuthenticationConfigured)
{
    app.UseAuthentication();
}

if (isAuthorizationConfigured)
{
    app.UseAuthorization();
}

// User middleware/endpoints
app.CustomMiddleware(...);
app.MapGet("/", () => "hello world");
// End user middleware/endpoints

app.UseEndpoints(e => {});

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

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

app.UseRouting();

// Other middleware and endpoints

app.UseRouting();

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

app.UseEndpoints(e => {});

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

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 de 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 al puerto 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, consulte Kestrel configuración del endpoint

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.

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

Escuche en todas las interfaces con ASPNETCORE_URLS

Los ejemplos anteriores pueden usar ASPNETCORE_URLS:

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

Escuchar en todas las interfaces usando ASPNETCORE_HTTP_PORTS y ASPNETCORE_HTTPS_PORTS

Los ejemplos anteriores también pueden usar ASPNETCORE_HTTP_PORTS y ASPNETCORE_HTTPS_PORTS, pero ASPNETCORE_URLS (cuando se establece) invalida la siguiente configuración:

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Para obtener más información, consulte Configuración de puntos de conexión para el Kestrel servidor web.

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

Lee el 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 obtener más información sobre el uso del entorno, consulte ASP.NET Core entornos en tiempo de ejecución.

Configuration

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 obtener más información, consulte Configuración en ASP.NET Core.

Logging

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, consulte Registro en .NET 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 código muestra cómo acceder a las claves del contenedor de inserción de dependencias mediante el atributo [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.";
}

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.Create inicializa una nueva instancia de la clase WebApplication 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 que se usan para cambiar la raíz del contenido, el nombre de la aplicación y el entorno.

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.

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

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

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

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

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

Personalizar el IWebHostBuilder

Se puede tener acceso a los métodos de extensión en IWebHostBuilder mediante la WebApplicationBuilder.WebHost propiedad .

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 los 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 personalizado de inyección de dependencias (DI)

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

Añadir 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 ASP.NET Core middleware.

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 siguiente código en el entorno de desarrollo, al navegar a / se muestra una página informativa 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();

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

if (isDevelopment)
{
    app.UseDeveloperExceptionPage();
}

app.UseRouting();

if (isAuthenticationConfigured)
{
    app.UseAuthentication();
}

if (isAuthorizationConfigured)
{
    app.UseAuthorization();
}

// User middleware/endpoints
app.CustomMiddleware(...);
app.MapGet("/", () => "hello world");
// End user middleware/endpoints

app.UseEndpoints(e => {});

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

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

app.UseRouting();

// Other middleware and endpoints

app.UseRouting();

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

app.UseEndpoints(e => {});

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

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 de 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 al puerto 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, consulte Kestrel configuración del endpoint

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.

Configure 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

Los ejemplos siguientes muestran 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();

Escuche en todas las interfaces con ASPNETCORE_URLS

Los ejemplos anteriores pueden usar ASPNETCORE_URLS:

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

Escuchar en todas las interfaces usando ASPNETCORE_HTTP_PORTS y ASPNETCORE_HTTPS_PORTS

Los ejemplos anteriores también pueden usar ASPNETCORE_HTTP_PORTS y ASPNETCORE_HTTPS_PORTS, pero ASPNETCORE_URLS (cuando se establece) invalida la siguiente configuración:

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Para obtener más información, consulte Configuración de puntos de conexión para el Kestrel servidor web.

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

Lee el 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 obtener más información sobre el uso del entorno, consulte ASP.NET Core entornos en tiempo de ejecución.

Configuration

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 obtener más información, consulte Configuración en ASP.NET Core.

Logging

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, consulte Registro en .NET 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 código muestra cómo acceder a las claves del contenedor de inserción de dependencias mediante el atributo [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.";
}

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.Create inicializa una nueva instancia de la clase WebApplication 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 que se usan para cambiar la raíz del contenido, el nombre de la aplicación y el entorno.

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.

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

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

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

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

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

Personalizar el IWebHostBuilder

Se puede tener acceso a los métodos de extensión en IWebHostBuilder mediante la WebApplicationBuilder.WebHost propiedad .

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 los 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 personalizado de inyección de dependencias (DI)

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

Añadir 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 ASP.NET Core middleware.

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 siguiente código en el entorno de desarrollo, al navegar a / se muestra una página informativa 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();