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 información sobre aspectos básicos de Blazor, que agrega o reemplaza las instrucciones de este artículo, consulte Aspectos básicos de ASP.NET Core Blazor.

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.
• El canal de procesamiento de solicitudes de la aplicación se define como una serie de componentes de middleware.

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

• Blazor Web Apps
• Razor Páginas
• Controladores MVC con vistas
• API web con controladores
• API web mínimas

using WebAll.Components;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();
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.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.UseAntiforgery();

app.Run();

Inserción de dependencias (servicios)

ASP.NET Core incluye inserción de dependencias (DI) integrada que hace que estén disponibles los servicios configurados en una aplicación. Los servicios se agregan al contenedor de inyección de dependencias con WebApplicationBuilder.Services, builder.Services en el código anterior. Cuando se crea una instancia de WebApplicationBuilder, se agregan muchos servicios proporcionados automáticamente 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 anterior, CreateBuilder agrega la configuración, el registro y muchos otros servicios al contenedor de DI. El marco de DI ofrece una instancia de un servicio solicitado en tiempo de ejecución.

El siguiente código añade unos componentes personalizados DbContext y Blazor al contenedor DI:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContextFactory<BlazorWebAppMoviesContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("MoviesContext") 
        ?? throw new InvalidOperationException("Connection string not found.")));

builder.Services.AddQuickGridEntityFrameworkAdapter();

builder.Services.AddDatabaseDeveloperPageExceptionFilter();

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

var app = builder.Build();

En Blazor Web Apps, los servicios a menudo se resuelven desde DI en tiempo de ejecución mediante la directiva @inject en un componente Razor, como se muestra en el ejemplo siguiente:

@page "/movies"
@rendermode InteractiveServer
@using Microsoft.EntityFrameworkCore
@using Microsoft.AspNetCore.Components.QuickGrid
@using BlazorWebAppMovies.Models
@using BlazorWebAppMovies.Data
@implements IAsyncDisposable
@inject IDbContextFactory<BlazorWebAppMovies.Data.BlazorWebAppMoviesContext> DbFactory

<PageTitle>Index</PageTitle>

<h1>Index</h1>

<div>
    <input type="search" @bind="titleFilter" @bind:event="oninput" />
</div>

<p>
    <a href="movies/create">Create New</a>
</p>

<QuickGrid Class="table" Items="FilteredMovies" Pagination="pagination">
    <PropertyColumn Property="movie => movie.Title" Sortable="true" />
    <PropertyColumn Property="movie => movie.ReleaseDate" Title="Release Date" />
    <PropertyColumn Property="movie => movie.Genre" />
    <PropertyColumn Property="movie => movie.Price" />
    <PropertyColumn Property="movie => movie.Rating" />

    <TemplateColumn Context="movie">
        <a href="@($"movies/edit?id={movie.Id}")">Edit</a> |
        <a href="@($"movies/details?id={movie.Id}")">Details</a> |
        <a href="@($"movies/delete?id={movie.Id}")">Delete</a>
    </TemplateColumn>
</QuickGrid>

<Paginator State="pagination" />

@code {
    private BlazorWebAppMoviesContext context = default!;
    private PaginationState pagination = new PaginationState { ItemsPerPage = 10 };
    private string titleFilter = string.Empty;

    private IQueryable<Movie> FilteredMovies =>
        context.Movie.Where(m => m.Title!.Contains(titleFilter));

    protected override void OnInitialized()
    {
        context = DbFactory.CreateDbContext();
    }

    public async ValueTask DisposeAsync() => await context.DisposeAsync();
}

En el código anterior:

• Se usa la directiva @inject.
• El servicio se resuelve en el método OnInitialized y se asigna a la variable context.
• El servicio context crea la lista de FilteredMovie.

Otra manera de resolver un servicio desde di es mediante la inserción de constructores. El código siguiente Páginas Razor 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();
    }
}

En el código anterior, el constructor IndexModel toma un parámetro de tipo RazorPagesMovieContext, que se resuelve en tiempo de ejecución en la variable _context. El objeto de contexto se usa para crear una lista de películas en el método OnGetAsync.

Para obtener más información, consulte inyección de dependencias ASP.NET Core Blazor e Inyección de dependencias en ASP.NET Core.

Middleware

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 uso de métodos denominados Use{Feature} para agregar middleware a una aplicación se muestra en el código siguiente:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContextFactory<BlazorWebAppMoviesContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("MoviesContext") 
        ?? throw new InvalidOperationException("Connection string not found.")));

builder.Services.AddQuickGridEntityFrameworkAdapter();

builder.Services.AddDatabaseDeveloperPageExceptionFilter();

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

var app = builder.Build();

using (var scope = app.Services.CreateScope())
{
    var services = scope.ServiceProvider;

    SeedData.Initialize(services);
}

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    app.UseHsts();
    app.UseMigrationsEndPoint();
}
app.UseHttpsRedirection();

app.UseAntiforgery();

app.MapStaticAssets();
app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.Run();

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

Host

Al iniciarse, una aplicación 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 middleware
• Logging
• Servicios de inserción de dependencias (DI)
• Configuration

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

Los tipos de ASP.NET Core WebApplication y WebApplicationBuilder se recomiendan y se utilizan en todas las plantillas de ASP.NET Core. WebApplication se comporta de manera similar al host genérico de .NET y expone muchas de las mismas interfaces, pero requiere menos llamadas de retorno para configurarse. El WebHost de ASP.NET Core solo está disponible para la compatibilidad con versiones anteriores.

En el ejemplo siguiente se crea una instancia de un WebApplication y se asigna a una variable denominada app:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContextFactory<BlazorWebAppMoviesContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("MoviesContext") 
        ?? throw new InvalidOperationException("Connection string not found.")));

builder.Services.AddQuickGridEntityFrameworkAdapter();

builder.Services.AddDatabaseDeveloperPageExceptionFilter();

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

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 desde appsettings.json, variables de entorno, 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 no-web

El host genérico permite que otros tipos de aplicaciones usen extensiones de marco 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.

Servers

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

Windows

ASP.NET Core proporciona las siguientes implementaciones de servidor:

• Kestrel es un servidor web multiplataforma. Kestrel a menudo se ejecuta en una configuración de proxy inverso mediante 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 para 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 a menudo se ejecuta 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 a menudo se ejecuta 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.

Configuration

ASP.NET Core proporciona un entorno de configuración que obtiene los ajustes 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 forma predeterminada, las aplicaciones ASP.NET Core están configuradas para consultar appsettings.json, variables de entorno, la línea de comandos y mucho más. 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 datos de configuración confidenciales, como contraseñas en el entorno de desarrollo, .NET 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.

Environments

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:

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    app.UseHsts();
    app.UseMigrationsEndPoint();
}

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

Logging

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:

• Console
• Debug
• 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. En el siguiente ejemplo, se muestra cómo obtener y utilizar un logger en un archivo .razor para una página en un Blazor Web App. Un objeto registrador y un proveedor de consola para él se almacenan automáticamente en el contenedor de DI cuando se llama al método CreateBuilder en Program.cs.

@page "/weather"
@attribute [StreamRendering]
@inject ILogger<Weather> Logger

<PageTitle>Weather</PageTitle>

<h1>Weather</h1>

<p>This component demonstrates showing data and logging.</p>

@if (forecasts == null)
{
    <p><em>Loading...</em></p>
}
else
{
    <table class="table">
        <thead>
            <tr>
                <th>Date</th>
                <th aria-label="Temperature in Celsius">Temp. (C)</th>
                <th aria-label="Temperature in Fahrenheit">Temp. (F)</th>
                <th>Summary</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var forecast in forecasts)
            {
                <tr>
                    <td>@forecast.Date.ToShortDateString()</td>
                    <td>@forecast.TemperatureC</td>
                    <td>@forecast.TemperatureF</td>
                    <td>@forecast.Summary</td>
                </tr>
            }
        </tbody>
    </table>
}

@code {
    private WeatherForecast[]? forecasts;

    protected override async Task OnInitializedAsync()
    {
        // Simulate asynchronous loading to demonstrate streaming rendering
       
        await Task.Delay(500);

        Logger.LogInformation("This is an information log message.");
        Logger.LogWarning("This is a warning log message.");
        Logger.LogError("This is an error log message.");

        var startDate = DateOnly.FromDateTime(DateTime.Now);
        var summaries = new[] { "Freezing", "Bracing", "Chilly",
            "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" };
        forecasts = Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = startDate.AddDays(index),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = summaries[Random.Shared.Next(summaries.Length)]
        }).ToArray();
    }

    private class WeatherForecast
    {
        public DateOnly Date { get; set; }
        public int TemperatureC { get; set; }
        public string? Summary { get; set; }
        public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
    }
}

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

Routing

El enrutamiento en ASP.NET Core es un mecanismo que asigna las solicitudes entrantes a puntos de conexión específicos de una aplicación. Permite definir patrones de dirección URL que corresponden a distintos componentes, como componentes de Blazor, páginas de Razor, acciones del controlador MVC o middleware.

El método UseRouting(IApplicationBuilder) agrega el middleware de enrutamiento a la pipeline de solicitudes. Este middleware procesa la información de enrutamiento y determina el punto de conexión adecuado para cada solicitud. No tiene que llamar explícitamente a UseRouting a menos que desee cambiar el orden en el que se procesa el middleware.

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

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 biblioteca popular 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:

• Archivo ejecutable que hospeda la aplicación (.exe).
• Ensamblajes compilados que componen la aplicación (.dll).
• Los archivos de contenido usados por la aplicación, como:
  • Archivos Razor (.cshtml, .razor)
  • Archivos de configuración (.json, .xml)
  • Archivos de datos (.db)
• La raíz web, normalmente 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, consulte Raíz de 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 tiene como valor predeterminado {CONTENT ROOT}/wwwroot, donde el marcador de posición {CONTENT ROOT} es la raíz del contenido. Para especificar otra raíz web, establezca su ruta de acceso al compilar el host. Para obtener más información, consulte Raíz web.

Impedir la publicación de archivos en wwwroot usando el elemento de proyecto <Content> en el archivo del proyecto. En el ejemplo siguiente se evita 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 comienza con ~/ se conoce como ruta de acceso virtual.

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

Cómo descargar un ejemplo

En muchos de los artículos y tutoriales se incluyen vínculos a código de ejemplo.

1. Descargue el archivo ZIP del repositorio de ASP.NET.
2. Descomprima el archivo AspNetCore.Docs-main.zip.
3. Para acceder a la aplicación de ejemplo de un artículo en el repositorio descomprimido, use la dirección URL del vínculo de ejemplo del artículo para ayudarle a navegar a la carpeta del ejemplo. Normalmente, el vínculo de ejemplo de un artículo aparece en la parte superior del artículo con el texto del vínculo Ver o descargar código de ejemplo.

Directivas de preprocesador en código de ejemplo

Para mostrar varios escenarios, las aplicaciones de ejemplo usan las directivas de preprocesador #define y #if-#else/#elif-#endif para compilar de forma selectiva y ejecutar secciones distintas de código de ejemplo. Para los ejemplos que usan este enfoque, establezca la directiva #define en la parte superior de los archivos C# para definir el símbolo asociado con el escenario que quiera ejecutar. Algunos ejemplos requieren la definición del símbolo en la parte superior de varios archivos para ejecutar un escenario.

Por ejemplo, la siguiente lista de símbolos de #define indica que hay cuatro escenarios disponibles (un escenario por símbolo). La configuración de ejemplo actual ejecuta el escenario TemplateCode:

#define TemplateCode // or LogFromMain or ExpandDefault or FilterInCode

Para cambiar el ejemplo el escenario ExpandDefault, defina el símbolo ExpandDefault y deje los símbolos restantes comentados:

#define ExpandDefault // TemplateCode or LogFromMain or FilterInCode

Para obtener más información sobre el uso de directivas de preprocesador de C# para compilar de forma selectiva secciones de código, vea #define (Referencia de C#) y #if (Referencia de C#).

Regiones en código de ejemplo

Algunas aplicaciones de ejemplo contienen secciones de código rodeadas de directivas de #region y #endregion de C#. El sistema de compilación de documentación inserta estas regiones en los temas de documentación representados.

Los nombres de región suelen contener la palabra "fragmento de código". En el ejemplo siguiente se muestra una región denominada snippet_WebHostDefaults:

#region snippet_WebHostDefaults
Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    });
#endregion

Se hace referencia al fragmento de código de C# anterior en el archivo Markdown del tema con la siguiente línea:

[!code-csharp[](sample/SampleApp/Program.cs?name=snippet_WebHostDefaults)]

Puede ignorar o quitar de forma segura las directivas #region y #endregion que rodean el código. No modifique el código dentro de estas directivas si tiene previsto ejecutar los escenarios de ejemplo descritos en el tema.

Para obtener más información, consulte Contribución a la documentación de ASP.NET: Fragmentos de código.

Recursos adicionales

Conceptos básicos Blazor de ASP.NET Core