Información general de los conceptos básicos de ASP.NET Core

En este artículo se proporciona información general sobre los aspectos básicos para crear aplicaciones ASP.NET Core, incluida la inserción de dependencias, la configuración, el middleware, etc.

Para obtener una guía sobre los conceptos básicos de Blazor, que se agregue o reemplace a la guía de este nodo, consulte los aspectos básicos de Blazor de ASP.NET Core.

Program.cs

Las aplicaciones de ASP.NET Core creadas con las plantillas web contienen el código de inicio de la aplicación en el archivo Program.cs. El archivo Program.cs es donde:

• Se configuran los servicios requeridos por la aplicación.
• La canalización de control de solicitudes de la aplicación se define como una serie de componentes de middleware.

El siguiente código de inicio de la aplicación admite:

• Razor Pages
• Controladores MVC con vistas
• API web con controladores
• API web mínimas

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

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

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

Inserción de dependencias (servicios)

ASP.NET Core incluye inserción de dependencias (DI) que hace que estén disponibles los servicios configurados en una aplicación. Los servicios se agregan al contenedor de DI con WebApplicationBuilder.Services, builder.Services en el código anterior. Cuando se crea una instancia de WebApplicationBuilder, se agregan muchos servicios proporcionados por el marco. builder es un objeto WebApplicationBuilder en el código siguiente:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

En el código resaltado anterior, builder tiene la configuración, el registro y muchos otros servicios agregados al contenedor de DI.

El código siguiente agrega Razor Pages, controladores MVC con vistas y un objeto DbContext personalizado al contenedor de DI:

using Microsoft.EntityFrameworkCore;
using RazorPagesMovie.Data;
var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

builder.Services.AddDbContext<RazorPagesMovieContext>(options =>
   options.UseSqlServer(builder.Configuration.GetConnectionString("RPMovieContext")));

var app = builder.Build();

Los servicios se suelen resolver desde la inserción de dependencias mediante la inserción de constructores. El marco de inserción de dependencias proporciona una instancia de este servicio en tiempo de ejecución.

El código siguiente usa la inserción de constructores para resolver el contexto de base de datos y el registrador desde la inserción de dependencias:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;
    private readonly ILogger<IndexModel> _logger;

    public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
    {
        _context = context;
        _logger = logger;
    }

    public IList<Movie> Movie { get;set; }

    public async Task OnGetAsync()
    {
        _logger.LogInformation("IndexModel OnGetAsync.");
        Movie = await _context.Movie.ToListAsync();
    }
}

Software intermedio

La canalización de control de solicitudes se compone de una serie de componentes de software intermedio. Cada componente lleva a cabo las operaciones en un contexto HttpContext e invoca el middleware siguiente de la canalización, o bien finaliza la solicitud.

Normalmente, se agrega un componente de middleware a la canalización mediante la invocación de un método de extensión Use{Feature}. El middleware agregado a la aplicación se resalta en el código siguiente:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

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

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

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

Host

En el inicio, una aplicación de ASP.NET Core compila un host. El host encapsula todos los recursos de la aplicación, como:

• Una implementación de servidor de HTTP
• Componentes de software intermedio
• Registro
• Servicios de inserción de dependencias (DI)
• Configuración

Hay tres hosts diferentes capaces de ejecutar una aplicación de ASP.NET Core:

• WebApplication para ASP.NET Core, también conocido como host mínimo
• Host genérico de .NET combinado con ConfigureWebHostDefaults de ASP.NET Core
• WebHost de ASP.NET Core

WebApplication y WebApplicationBuilder de ASP.NET Core son los tipos recomendables y se usan en todas las plantillas de ASP.NET Core. WebApplication se comporta de forma similar al host genérico de .NET y expone muchas de las mismas interfaces, pero requiere menos devoluciones de llamada para configurar. El WebHost de ASP.NET Core solo está disponible para la compatibilidad con versiones anteriores.

En el ejemplo siguiente se crea una instancia de WebApplication:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

El método WebApplicationBuilder.Build configura un host con un conjunto de opciones predeterminadas, como:

• Use Kestrel como servidor web y habilite la integración de IIS.
• Cargue la configuración de appsettings.json, las variables de entorno, los argumentos de línea de comandos y otros orígenes de configuración.
• Envíe la salida de registro a la consola y los proveedores de depuración.

Escenarios que no son web

El host genérico permite que otros tipos de aplicaciones usen las extensiones de marcos transversales, como el registro, la inserción de dependencias (DI), la configuración y la administración de la duración de la aplicación. Para más información, consulte Host genérico de .NET en ASP.NET Core y Tareas en segundo plano con servicios hospedados en ASP.NET Core.

Servidores

Una aplicación ASP.NET Core usa una implementación de servidor HTTP para escuchar las solicitudes HTTP. El servidor expone las solicitudes a la aplicación como un conjunto de características de solicitud integradas en un contexto HttpContext.

Windows

ASP.NET Core proporciona las siguientes implementaciones de servidor:

• Kestrel es un servidor web multiplataforma. Kestrel se suele ejecutar en una configuración de proxy inverso con IIS. En ASP.NET Core 2.0 y versiones posteriores, Kestrel se puede ejecutar como servidor perimetral de acceso público expuesto directamente a Internet.
• Servidor HTTP de IIS es un servidor para Windows que usa IIS. Con este servidor, la aplicación de ASP.NET Core e IIS se ejecutan en el mismo proceso.
• HTTP.sys es un servidor de Windows que no se usa con IIS.

macOS

ASP.NET Core proporciona la implementación de servidor multiplataforma Kestrel. En ASP.NET Core 2.0 y versiones posteriores, Kestrel se puede ejecutar como servidor perimetral de acceso público expuesto directamente a Internet. Kestrel se suele ejecutar en una configuración de proxy inverso con Nginx o Apache.

Linux

ASP.NET Core proporciona la implementación de servidor multiplataforma Kestrel. En ASP.NET Core 2.0 y versiones posteriores, Kestrel se puede ejecutar como servidor perimetral de acceso público expuesto directamente a Internet. Kestrel se suele ejecutar en una configuración de proxy inverso con Nginx o Apache.

Para más información, consulte Implementaciones de servidores web en ASP.NET Core.

Configuración

ASP.NET Core proporciona un marco de configuración que obtiene la configuración como pares nombre-valor de un conjunto ordenado de proveedores de configuración. Hay disponibles proveedores de configuración integrados para varios orígenes, como archivos .json, archivos .xml, variables de entorno y argumentos de línea de comandos. Escriba proveedores de configuración personalizados para admitir otros orígenes.

De manera predeterminada, las aplicaciones de ASP.NET Core están configuradas para leer desde appsettings.json, variables de entorno, la línea de comandos, etc. Cuando se carga la configuración de la aplicación, los valores de las variables de entorno invalidan los valores de appsettings.json.

Para administrar los datos de configuración confidencial como las contraseñas, NET Core proporciona el Administrador de secretos. Para los secretos de producción, se recomienda Azure Key Vault.

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

Entornos

Los entornos de ejecución, como Development, Staging y Production, están disponibles en ASP.NET Core. Especifique el entorno que ejecuta una aplicación estableciendo la variable de entorno ASPNETCORE_ENVIRONMENT. ASP.NET Core lee dicha variable de entorno al inicio de la aplicación y almacena el valor en una implementación IWebHostEnvironment. Esta implementación está disponible en cualquier parte de una aplicación a través de la inserción de dependencias (DI).

En el ejemplo siguiente se configura el controlador de excepciones y el middleware del Protocolo de seguridad de transporte estricto HTTP (HSTS) cuando no se ejecutan en el entorno Development:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

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

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

Para obtener más información, consulte Usar varios entornos en ASP.NET Core.

Registro

ASP.NET Core es compatible con una API de registro que funciona con una variedad de proveedores de registro integrados y de terceros. Entre los proveedores disponibles se incluyen:

• Consola
• Depurar
• Seguimiento de eventos en Windows
• Registro de sucesos de Windows
• TraceSource
• Azure App Service
• Azure Application Insights

Para crear registros, resuelva un servicio ILogger<TCategoryName> a partir de la inserción de dependencias (DI) y llame a métodos de registro como LogInformation. Por ejemplo:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;
    private readonly ILogger<IndexModel> _logger;

    public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
    {
        _context = context;
        _logger = logger;
    }

    public IList<Movie> Movie { get;set; }

    public async Task OnGetAsync()
    {
        _logger.LogInformation("IndexModel OnGetAsync.");
        Movie = await _context.Movie.ToListAsync();
    }
}

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

Enrutamiento

Una ruta es un patrón de dirección URL que se asigna a un controlador. El controlador normalmente es una página de Razor, un método de acción en un controlador MVC o un software intermedio. El enrutamiento de ASP.NET Core le permite controlar las direcciones URL usadas por la aplicación.

El código siguiente, generado por la plantilla de aplicación web de ASP.NET Core, llama a UseRouting:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

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

Control de errores

ASP.NET Core tiene características integradas para controlar los errores, tales como:

• Una página de excepciones para el desarrollador
• Páginas de error personalizadas
• Páginas de códigos de estado estáticos
• Control de excepciones de inicio

Para más información, consulte Control de errores en ASP.NET Core.

Realización de solicitudes HTTP

Una implementación de IHttpClientFactory está disponible para crear instancias de HttpClient. Este servicio:

• Proporciona una ubicación central para denominar y configurar instancias de HttpClient lógicas. Por ejemplo, registre y configure un cliente de github para acceder a GitHub. Registre y configure un cliente predeterminado para otros fines.
• Admite el registro y encadenamiento de varios controladores de delegación para crear una canalización de middleware de solicitud saliente. Este patrón es similar a la canalización de middleware de entrada de ASP.NET Core. Dicho patrón proporciona un mecanismo para administrar cuestiones transversales relativas a las solicitudes HTTP, como el almacenamiento en caché, el control de errores, la serialización y el registro.
• Se integra con Polly, una conocida biblioteca de terceros para el control de errores transitorios.
• Administra la agrupación y duración de las instancias de HttpClientHandler subyacentes para evitar los problemas de DNS que suelen producirse al administrar manualmente las duraciones de HttpClient.
• Agrega una experiencia de registro configurable a través de ILogger en todas las solicitudes enviadas a través de los clientes creados por Factory.

Para más información, consulte Realización de solicitudes HTTP con IHttpClientFactory en ASP.NET Core.

Raíz del contenido

La raíz del contenido es la ruta de acceso base para:

• El archivo ejecutable que hospeda la aplicación (.exe).
• Los ensamblados compilados que componen la aplicación (.dll).
• Los archivos de contenido usados por la aplicación, como:
  • Razor archivos (.cshtml, .razor)
  • Archivos de configuración (.json, .xml)
  • Archivos de datos (.db)
• La raíz web, por lo general la carpeta wwwroot.

Durante el desarrollo, la raíz del contenido tiene como valor predeterminado el directorio raíz del proyecto. Este directorio también es la ruta de acceso base para los archivos de contenido de la aplicación y la raíz web. Especifique una raíz de contenido diferente estableciendo su ruta de acceso al compilar el host. Para obtener más información, vea Raíz del contenido.

Raíz web

La raíz web es la ruta de acceso base para los archivos de recursos estáticos públicos, como:

• Hojas de estilo (.css)
• JavaScript (.js)
• Imágenes (.png, .jpg)

De manera predeterminada, los archivos estáticos solo se sirven desde el directorio raíz web y sus subdirectorios. La ruta de acceso raíz web se establece de manera predeterminada en {raíz del contenido}/wwwroot. Para especificar otra raíz web, establezca su ruta de acceso al compilar el host. Para obtener más información, vea Raíz web.

Evite la publicación de archivos en wwwroot con el elemento de proyecto <Content> del archivo de proyecto. En el ejemplo siguiente se impide la publicación de contenido en wwwroot/local y sus subdirectorios:

<ItemGroup>
  <Content Update="wwwroot\local\**\*.*" CopyToPublishDirectory="Never" />
</ItemGroup>

En los archivos Razor.cshtml, ~/ apunta a la raíz web. Una ruta de acceso que empieza por ~/ se conoce como ruta de acceso virtual.

Para obtener más información, vea Archivos estáticos en ASP.NET Core.

Recursos adicionales

• Código fuente de WebApplicationBuilder