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

  • Artículo

Nota:

Esta no es la versión más reciente de este artículo. Para la versión actual, consulta 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, consulta la Directiva de soporte técnico de .NET y .NET Core. Para la versión actual, consulta 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.

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:

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

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.

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

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.

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:

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

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.

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

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.

Clase Startup

La clase Startup 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.

Aquí tiene una clase Startup de ejemplo:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddDbContext<RazorPagesMovieContext>(options =>
            options.UseSqlServer(Configuration.GetConnectionString("RazorPagesMovieContext")));

        services.AddControllersWithViews();
        services.AddRazorPages();
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseHttpsRedirection();
        app.UseStaticFiles();

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapDefaultControllerRoute();
            endpoints.MapRazorPages();
        });
    }
}

Para obtener más información, vea Inicio de la aplicación en ASP.NET Core.

Inserción de dependencias (servicios)

ASP.NET Core incluye un marco de inserción de dependencias (DI) integrado que pone a disposición los servicios configurados a lo largo de una aplicación. Por ejemplo, un componente de registro es un servicio.

Se agrega al método Startup.ConfigureServices el código para configurar (o registrar) servicios. Por ejemplo:

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<RazorPagesMovieContext>(options =>
        options.UseSqlServer(Configuration.GetConnectionString("RazorPagesMovieContext")));

    services.AddControllersWithViews();
    services.AddRazorPages();
}

Los servicios se suelen resolver desde la inserción de dependencias mediante la inserción de constructores. Con la inserción de constructores, una clase declara un parámetro de constructor del tipo requerido o una interfaz. El marco de inserción de dependencias proporciona una instancia de este servicio en tiempo de ejecución.

En el ejemplo siguiente se usa la inserción de constructores para resolver un elemento RazorPagesMovieContext desde la inserción de constructores:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;

    public IndexModel(RazorPagesMovieContext context)
    {
        _context = context;
    }

    // ...

    public async Task OnGetAsync()
    {
        Movies = await _context.Movies.ToListAsync();
    }
}

Si el contenedor Inversión de control (IoC) integrado no satisface todas las necesidades de una aplicación, se puede usar en su lugar un contenedor de IoC de terceros.

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

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 software intermedio a la canalización al invocar un método de extensión Use... en el método Startup.Configure. Por ejemplo, para habilitar la representación de los archivos estáticos, llame a UseStaticFiles.

En el ejemplo siguiente se configura una canalización de control de solicitudes:

public void Configure(IApplicationBuilder app)
{
    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute();
        endpoints.MapRazorPages();
    });
}

ASP.NET Core incluye un amplio conjunto de middleware integrado. También se pueden escribir componentes de middleware personalizados.

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 dos hosts distintos:

  • Host genérico de .NET
  • Host web de ASP.NET Core

Se recomienda el host genérico de .NET. El host web de ASP.NET Core solo está disponible para la compatibilidad con versiones anteriores.

En el ejemplo siguiente se crea un host genérico de .NET:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Los métodos CreateDefaultBuilder y ConfigureWebHostDefaults configuran 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, appsettings.{Environment}.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.

Para obtener más información, consulte Hospedaje genérico de .NET en ASP.NET Core.

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.

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.

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.

La mejor manera de leer valores de configuración relacionados es usar el patrón de opciones. Para más información, consulte Enlace de datos de configuración jerárquica mediante el patrón de opciones.

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, son un concepto de primera clase 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 la aplicación para proporcionar información detallada del error cuando se ejecuta en el entorno de Development:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

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

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute();
        endpoints.MapRazorPages();
    });
}

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 TodoController : ControllerBase
{
    private readonly ILogger _logger;

    public TodoController(ILogger<TodoController> logger)
    {
        _logger = logger;
    }

    [HttpGet("{id}", Name = "GetTodo")]
    public ActionResult<TodoItem> GetById(string id)
    {
        _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
        
        // Item lookup code removed.
        
        if (item == null)
        {
            _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
            return NotFound();
        }
        
        return item;
    }
}

Los métodos de registro como LogInformation admiten cualquier número de campos. Por lo general, estos campos se utilizan para construir un mensaje string, pero algunos proveedores de registro los envían a un almacén de datos como campos independientes. Esta característica permite a los proveedores de registro implementar el registro semántico, también conocido como registro estructurado.

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.

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, la virgulilla (~/) 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.