Comparteix a través de


WebApplication y WebApplicationBuilder en aplicaciones de API mínimas

Nota:

Esta no es la versión más reciente de este artículo. Para la versión actual, consulte la versión .NET 8 de este artículo.

Advertencia

Esta versión de ASP.NET Core ya no se admite. Para obtener más información, consulte la Directiva de soporte técnico de .NET y .NET Core. Para la versión actual, consulte la versión .NET 8 de este artículo.

Importante

Esta información hace referencia a un producto en versión preliminar, el cual puede sufrir importantes modificaciones antes de que se publique la versión comercial. Microsoft no proporciona ninguna garantía, expresa o implícita, con respecto a la información proporcionada aquí.

Para la versión actual, consulte la versión .NET 8 de este artículo.

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.

WebApplication agrega automáticamente el siguiente middleware en Minimal API applications en función de determinadas condiciones:

  • UseDeveloperExceptionPage se agrega primero cuando HostingEnvironment es "Development".
  • UseRouting se agrega en segundo lugar si el código de usuario aún no llamó UseRouting a y si hay puntos de conexión configurados, por ejemplo app.MapGet.
  • UseEndpoints se agrega al final de la canalización de middleware si hay algún punto de conexión configurado.
  • UseAuthentication se agrega inmediatamente después de UseRouting si el código de usuario no llamó aún a UseAuthentication y si IAuthenticationSchemeProvider se puede detectar en el proveedor de servicios. IAuthenticationSchemeProvider se agrega de forma predeterminada cuando se usa AddAuthentication, y los servicios se detectan mediante IServiceProviderIsService.
  • UseAuthorization se agrega a continuación si el código de usuario no llamó aún a UseAuthorization y si IAuthorizationHandlerProvider se puede detectar en el proveedor de servicios. IAuthorizationHandlerProvider se agrega de forma predeterminada cuando se usa AddAuthorization, y los servicios se detectan mediante IServiceProviderIsService.
  • El middleware y los puntos de conexión configurados por el usuario se agregan entre UseRouting y UseEndpoints.

El código siguiente es eficazmente lo que produce el middleware automático que se agrega a la aplicación:

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

En algunos casos, la configuración predeterminada del middleware no es correcta para la aplicación y requiere modificación. Por ejemplo, UseCors se debe llamar a antes UseAuthentication de y UseAuthorization. La aplicación debe llamar a UseAuthentication y UseAuthorization si se llama a UseCors:

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

Si se debe ejecutar el middleware antes de que se produzca la coincidencia de rutas, se debe llamar a UseRouting y se debe colocar el middleware antes de la llamada a UseRouting. UseEndpoints no es necesario en este caso, ya que se agrega automáticamente como se ha descrito anteriormente:

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

app.UseRouting();

// other middleware and endpoints

Al agregar un middleware de terminal:

  • El middleware debe agregarse después de UseEndpoints.
  • La aplicación debe llamar UseRouting a y UseEndpoints para que el middleware de terminal se pueda colocar en la ubicación correcta.
app.UseRouting();

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

app.UseEndpoints(e => {});

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

El middleware de terminal es un middleware que se ejecuta si ningún punto de conexión controla la solicitud.

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

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

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

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

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

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.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, 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 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

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.

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

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.

WebApplication agrega automáticamente el siguiente middleware en Minimal API applications en función de determinadas condiciones:

  • UseDeveloperExceptionPage se agrega primero cuando HostingEnvironment es "Development".
  • UseRouting se agrega en segundo lugar si el código de usuario aún no llamó UseRouting a y si hay puntos de conexión configurados, por ejemplo app.MapGet.
  • UseEndpoints se agrega al final de la canalización de middleware si hay algún punto de conexión configurado.
  • UseAuthentication se agrega inmediatamente después de UseRouting si el código de usuario no llamó aún a UseAuthentication y si IAuthenticationSchemeProvider se puede detectar en el proveedor de servicios. IAuthenticationSchemeProvider se agrega de forma predeterminada cuando se usa AddAuthentication, y los servicios se detectan mediante IServiceProviderIsService.
  • UseAuthorization se agrega a continuación si el código de usuario no llamó aún a UseAuthorization y si IAuthorizationHandlerProvider se puede detectar en el proveedor de servicios. IAuthorizationHandlerProvider se agrega de forma predeterminada cuando se usa AddAuthorization, y los servicios se detectan mediante IServiceProviderIsService.
  • El middleware y los puntos de conexión configurados por el usuario se agregan entre UseRouting y UseEndpoints.

El código siguiente es eficazmente lo que produce el middleware automático que se agrega a la aplicación:

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

En algunos casos, la configuración predeterminada del middleware no es correcta para la aplicación y requiere modificación. Por ejemplo, UseCors se debe llamar a antes UseAuthentication de y UseAuthorization. La aplicación debe llamar a UseAuthentication y UseAuthorization si se llama a UseCors:

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

Si se debe ejecutar el middleware antes de que se produzca la coincidencia de rutas, se debe llamar a UseRouting y se debe colocar el middleware antes de la llamada a UseRouting. UseEndpoints no es necesario en este caso, ya que se agrega automáticamente como se ha descrito anteriormente:

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

app.UseRouting();

// other middleware and endpoints

Al agregar un middleware de terminal:

  • El middleware debe agregarse después de UseEndpoints.
  • La aplicación debe llamar UseRouting a y UseEndpoints para que el middleware de terminal se pueda colocar en la ubicación correcta.
app.UseRouting();

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

app.UseEndpoints(e => {});

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

El middleware de terminal es un middleware que se ejecuta si ningún punto de conexión controla la solicitud.

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