ASP.NET Visão geral dos fundamentos principais

Este artigo fornece uma visão geral dos fundamentos para a criação de aplicativos ASP.NET Core, incluindo injeção de dependência (DI), configuração, middleware e muito mais.

Para obter Blazor orientações sobre fundamentos, que adicionam ou substituem as orientações deste artigo, consulte ASP.NET Core Blazor fundamentals.

Program.cs

ASP.NET Os aplicativos principais criados com os modelos da Web contêm o código de inicialização do aplicativo no arquivo Program.cs. O arquivo Program.cs é onde:

• Os serviços exigidos pelo aplicativo são configurados.
• O fluxo de tratamento de solicitações da aplicação é definido como uma série de componentes de middleware .

O código de inicialização do aplicativo a seguir oferece suporte a vários tipos de aplicativos:

• Blazor Web Apps
• Razor Páginas
• controladores MVC com visualizações
• API Web com controladores
• APIs 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();

Injeção de dependência (serviços)

ASP.NET Principais apresenta de injeção de dependência (DI) de integrada que disponibiliza serviços configurados em todo um aplicativo. Os serviços são adicionados ao contêiner DI com WebApplicationBuilder.Services, builder.Services no código anterior. Quando o WebApplicationBuilder é instanciado, muitos serviços fornecidos pelo framework são adicionados automaticamente. builder é um WebApplicationBuilder no seguinte código:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

No código anterior, CreateBuilder adiciona configuração, registo e muitos outros serviços no container DI. A estrutura DI fornece uma instância de um serviço solicitado em tempo de execução.

O código a seguir adiciona componentes DbContext e Blazor personalizados ao container 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();

Em Blazor Web Apps, os serviços geralmente são resolvidos a partir da DI em tempo de execução usando a diretiva @inject em um componente Razor, conforme mostrado no exemplo a seguir:

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

No código anterior:

• É utilizada a diretiva @inject.
• O serviço é resolvido no método OnInitialized e atribuído à variável context.
• O serviço context cria a lista de FilteredMovie.

Outra maneira de resolver um serviço de DI é usando a injeção do construtor. O código Razor Pages a seguir usa a injeção do construtor para resolver o contexto do banco de dados e um registrador da DI:

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

No código anterior, o construtor IndexModel usa um parâmetro do tipo RazorPagesMovieContext, que é resolvido em tempo de execução na variável _context. O objeto de contexto é usado para criar uma lista de filmes no método OnGetAsync.

Para obter mais informações, consulte ASP.NET de injeção de dependência do Core Blazor e injeção de dependência no ASP.NET Core.

Middleware

O pipeline de tratamento de solicitações é composto por uma série de componentes de middleware. Cada componente executa operações em um HttpContext e invoca o próximo middleware no pipeline ou encerra a solicitação.

Por convenção, um componente de middleware é adicionado ao pipeline invocando um método de extensão Use{Feature}. O uso de métodos chamados Use{Feature} para adicionar middleware a um aplicativo é ilustrado no código a seguir:

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 obter mais informações, consulte ASP.NET Core Middleware.

Anfitrião

Na inicialização, um aplicativo ASP.NET Core cria um host . O host encapsula todos os recursos do aplicativo, como:

• Uma implementação de servidor HTTP
• Componentes de middleware
• Registo
• Serviços de injeção de dependência (DI)
• Configuração

Há três hosts diferentes capazes de executar um aplicativo ASP.NET Core:

• ASP.NET Core WebApplication, também conhecido como Minimal Host
• de Host Genérico .NET combinado com o ConfigureWebHostDefaults do ASP.NET Core
• ASP.NET Core WebHost

Os tipos ASP.NET Core WebApplication e WebApplicationBuilder são recomendados e usados em todos os modelos ASP.NET Core. WebApplication se comporta de forma semelhante ao Host Genérico do .NET e expõe muitas das mesmas interfaces, mas requer menos retornos de chamada para configurar. O ASP.NET Core WebHost está disponível apenas para compatibilidade com versões anteriores.

O exemplo a seguir instancia um WebApplication e o atribui a uma variável chamada 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();

O método WebApplicationBuilder.Build configura um host com um conjunto de opções padrão, como:

• Use Kestrel como o servidor Web e habilite a integração do IIS.
• Carregue a configuração do appsettings.json, variáveis de ambiente, argumentos de linha de comando e outras fontes de configuração.
• Envie a saída de log para o console e os provedores de depuração.

Cenários não Web

O Host Genérico permite que outros tipos de aplicativos usem extensões de estrutura transversais, como registro, injeção de dependência (DI), configuração e gerenciamento do tempo de vida do aplicativo. Para obter mais informações, consulte .NET Generic Host no ASP.NET Core e Tarefas em Segundo Plano com Serviços Hospedados no ASP.NET Core.

Servidores

Um aplicativo ASP.NET Core usa uma implementação de servidor HTTP para ouvir solicitações HTTP. O servidor apresenta as solicitações à aplicação como um conjunto de funcionalidades de pedido de integradas num HttpContext.

Windows

O ASP.NET Core fornece as seguintes implementações de servidor:

• Kestrel é um servidor web multiplataforma. Kestrel geralmente é executado em uma configuração de proxy reverso usando IIS. No ASP.NET Core 2.0 e posterior, Kestrel pode ser executado como um servidor de borda voltado para o público exposto diretamente à Internet.
• IIS HTTP Server é um servidor para Windows que usa o IIS. Com esse servidor, o aplicativo ASP.NET Core e o IIS são executados no mesmo processo.
• HTTP.sys é um servidor para Windows que não é usado com o IIS.

macOS

ASP.NET Core fornece a Kestrel implementação de servidor multiplataforma. No ASP.NET Core 2.0 ou posterior, Kestrel pode ser executado como um servidor de borda voltado para o público exposto diretamente à Internet. Kestrel geralmente é executado em uma configuração de proxy reverso com Nginx ou Apache.

Linux

ASP.NET Core fornece a implementação de servidor multiplataforma Kestrel. No ASP.NET Core 2.0 ou posterior, Kestrel pode ser executado como um servidor de borda voltado para o público exposto diretamente à Internet. Kestrel geralmente é executado em uma configuração de proxy reverso com Nginx ou Apache.

Para obter mais informações, consulte as implementações do servidor Web no ASP.NET Core.

Configuração

ASP.NET Core fornece um framework de configuração que obtém configurações como pares nome-valor de um conjunto ordenado de provedores de configuração. Os provedores de configuração internos estão disponíveis para uma variedade de fontes, como arquivos .json, arquivos .xml, variáveis de ambiente e argumentos de linha de comando. Escreva provedores de configuração personalizados para oferecer suporte a outras fontes.

Por padrão, os aplicativos ASP.NET Core são configurados para ler a partir de appsettings.json, variáveis de ambiente, linha de comando e muito mais. Quando a configuração do aplicativo é carregada, os valores das variáveis de ambiente substituem os valores de appsettings.json.

Para gerenciar dados de configuração confidenciais, como senhas no ambiente de desenvolvimento, o .NET Core fornece o Secret Manager. Para segredos de produção, recomendamos Azure Key Vault.

Para obter mais informações, consulte Configuração no ASP.NET Core.

Ambientes

Ambientes de execução, como Development, Staginge Production, estão disponíveis no ASP.NET Core. Especifique o ambiente em que um aplicativo está sendo executado definindo a variável de ambiente ASPNETCORE_ENVIRONMENT. ASP.NET Core lê essa variável de ambiente na inicialização do aplicativo e armazena o valor em uma implementação IWebHostEnvironment. Essa implementação está disponível em qualquer lugar em um aplicativo por meio de injeção de dependência (DI).

O exemplo a seguir configura o manipulador de exceções e HTTP Strict Transport Security Protocol (HSTS) middleware quando não em execução no ambiente Development:

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

Para obter mais informações, consulte Usar vários ambientes no ASP.NET Core.

Registo

O ASP.NET Core suporta uma API de registro em log que funciona com uma variedade de provedores de log internos e de terceiros. Os fornecedores disponíveis incluem:

• Consola
• Depurar
• Rastreamento de eventos no Windows
• Registo de Eventos do Windows
• TraceSource
• Serviço de Aplicativo do Azure
• Azure Application Insights

Para criar logs, resolva um serviço de ILogger<TCategoryName> a partir de métodos de injeção de dependência (DI) e de registro de chamadas, como LogInformation. Este exemplo mostra como obter e usar o logger num arquivo .razor para uma página em Blazor Web App. Um objeto logger e um provedor de console para ele são armazenados no contentor DI automaticamente quando o método CreateBuilder é chamado em 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 Farenheit">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 obter mais informações, consulte Logging in .NET Core e ASP.NET Core.

Roteamento

O roteamento no ASP.NET Core é um mecanismo que mapeia solicitações de entrada para pontos de extremidade específicos em um aplicativo. Ele permite definir padrões de URL que correspondem a diferentes componentes, como componentes Blazor, páginas Razor, ações do controlador MVC ou middleware.

O método UseRouting(IApplicationBuilder) adiciona middleware de roteamento ao pipeline de solicitação. Esse middleware processa as informações de roteamento e determina o ponto de extremidade apropriado para cada solicitação. Você não precisa chamar UseRouting explicitamente, a menos que queira alterar a ordem na qual o middleware é processado.

Para obter mais informações, consulte Roteamento no ASP.NET Core e ASP.NETde roteamento e navegação do Core Blazor .

Tratamento de erros

ASP.NET Core tem recursos integrados para lidar com erros, como:

• Uma página de exceção do desenvolvedor
• Páginas de erro personalizadas
• Páginas de código de status estático
• Manejo de exceções durante a inicialização

Para obter mais informações, consulte Gerir erros no ASP.NET Core.

Fazer solicitações HTTP

Uma implementação de IHttpClientFactory está disponível para criar instâncias HttpClient. A fábrica:

• Fornece um ponto central para nomear e configurar instâncias lógicas de HttpClient. Por exemplo, registre e configure um cliente do github para acessar o GitHub. Registre e configure um cliente padrão para outros fins.
• Suporta o registo e encadeamento de múltiplos manipuladores delegados para criar um pipeline de middleware de pedidos de saída. Esse padrão é semelhante ao pipeline de middleware de entrada do ASP.NET Core. O padrão fornece um mecanismo para gerenciar preocupações transversais para solicitações HTTP, incluindo cache, tratamento de erros, serialização e registro.
• Integra-se com o Polly, uma biblioteca de terceiros popular para tratamento de falhas transitórias.
• Gere o pool e o tempo de vida das instâncias de HttpClientHandler subjacentes para evitar problemas comuns de DNS que ocorrem ao gerenciar manualmente os tempos de vida de HttpClient.
• Adiciona uma experiência de registro configurável via ILogger para todas as solicitações enviadas através de clientes criados pela fábrica.

Para obter mais informações, consulte Fazer solicitações HTTP usando IHttpClientFactory em ASP.NET Core.

Raiz do conteúdo

A raiz do conteúdo é o caminho base para:

• O executável que hospeda o aplicativo (.exe).
• Assemblies compilados que compõem a aplicação (.dll).
• Arquivos de conteúdo usados pelo aplicativo, como:
  • Razor arquivos (.cshtml, .razor)
  • Arquivos de configuração (.json, .xml)
  • Arquivos de dados (.db)
• A raiz da Web , normalmente a pasta wwwroot.

Durante o desenvolvimento, a raiz de conteúdo é, por padrão, o diretório raiz do projeto. Esse diretório é também o caminho base tanto para os arquivos de conteúdo do aplicativo quanto para a raiz da web . Especifique uma raiz de conteúdo diferente definindo seu caminho ao criar o host . Para obter mais informações, consulte Raiz de conteúdo.

Diretório raiz da web

A raiz da Web é o caminho base para arquivos de recursos públicos estáticos, como:

• Folhas de estilo (.css)
• JavaScript (.js)
• Imagens (.png, .jpg)

Por padrão, os arquivos estáticos são servidos apenas a partir do diretório raiz da Web e seus subdiretórios. O caminho da raiz da Web, por padrão, é {content root}/wwwroot. Especifique uma raiz web diferente ao definir o seu caminho ao construir o host . Para obter mais informações, consulte raiz da Web .

Impeça a publicação de arquivos em wwwroot com o <Content> item de projeto no arquivo de projeto. O exemplo a seguir impede a publicação de conteúdo em wwwroot/local e seus subdiretórios:

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

Nos arquivos Razor.cshtml, ~/ aponta para a raiz da rede. Um caminho que começa com ~/ é referido como um caminho virtual .

Para obter mais informações, consulte ficheiros estáticos no ASP.NET Core.

Recursos adicionais

• Fundamentos do ASP.NET Core Blazor