Vue d’ensemble des notions de base d’ASP.NET Core

Cet article fournit une vue d’ensemble des principes fondamentaux de la génération d’applications ASP.NET Core, notamment l’injection de dépendances, la configuration, les middlewares, etc.

Pour des conseils sur les principes fondamentaux sur Blazor, qui complètent ou remplacent les conseils de cet article, voir les principes fondamentaux d'ASP.NET CoreBlazor.

Program.cs

Les applications ASP.NET Core créées avec les modèles web contiennent le code de démarrage de l’application dans le fichier Program.cs. Le fichier Program.cs se trouve à l’emplacement où :

• Les services nécessaires à l’application sont configurés.
• Le pipeline de gestion des demandes de l’application est défini comme une série de composants middleware.

Le code de démarrage d’application suivant prend en charge plusieurs types d’applications :

• Blazor Web Apps
• Razor Pages
• Contrôleurs MVC avec vues
• API web avec contrôleurs
• API web minimales

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

Injection de dépendances (services)

ASP.NET Core est doté de fonctionnalités intégrées d'injection de dépendances (DI) qui rendent les services configurés disponibles dans l'ensemble d'une application. Les services sont ajoutés au conteneur d’adresses di avec WebApplicationBuilder.Services, builder.Services dans le code précédent. Lorsque le WebApplicationBuilder est instancié, de nombreux services fournis par le framework sont ajoutés automatiquement. builder est un WebApplicationBuilder dans le code suivant :

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Dans le code précédent, CreateBuilder ajoute la configuration, le journal et de nombreux autres services au conteneur DI. L’infrastructure d’interface de base de données fournit une instance d’un service demandé au moment de l’exécution.

Le code suivant ajoute un composant personnalisé DbContext et les composants Blazor au conteneur 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();

Dans Blazor Web Apps, les services sont souvent résolus à partir de DI au moment de l'exécution en utilisant la directive @inject dans un composant Razor, comme illustré dans l'exemple suivant :

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

Dans le code précédent :

• La directive @inject est utilisée.
• Le service est résolu dans la méthode OnInitialized et affecté à la variable context.
• Le service context crée la liste des FilteredMovie.

Une autre façon de résoudre un service à partir de DI consiste à utiliser l’injection de constructeur. Le code des pages suivantes Razor utilise l'injection de constructeur pour résoudre le contexte de la base de données et un enregistreur à partir de 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();
    }
}

Dans le code précédent, le constructeur IndexModel prend un paramètre de type RazorPagesMovieContext, qui est résolu au moment de l’exécution dans la variable _context. L’objet de contexte est utilisé pour créer une liste de films dans la méthode OnGetAsync.

Pour plus d'informations, consultez les sections Injection de dépendances dans ASP.NET CoreBlazor et Injection de dépendances dans ASP.NET Core.

Middleware

Le pipeline de traitement des requêtes est composé comme une série de composants d’intergiciel (middleware). Chaque composant effectue des opérations sur un HttpContext, puis appelle le middleware suivant dans le pipeline, ou met fin à la requête.

Par convention, un composant de middleware est ajouté au pipeline via l’appel d’une méthode d’extension Use{Feature}. L’utilisation de méthodes nommées Use{Feature} pour ajouter un intergiciel à une application est illustrée dans le code suivant :

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

Pour plus d’informations, consultez Intergiciel (middleware) ASP.NET Core.

Host

Au démarrage, une application ASP.NET Core génère un hôte. L’hôte encapsule toutes les ressources de l’application, par exemple :

• Une implémentation serveur HTTP
• Composants d’intergiciel
• Logging
• Services d’injection de dépendances
• Configuration

Il existe trois types d’hôtes capables d’exécuter une application ASP.NET Core :

• ASP.NET Core WebApplication, également appelé Hôte minimal
• Hôte générique .NET combiné au ConfigureWebHostDefaults d'ASP.NET Core
• ASP.NET Core WebHost

Les types ASP.NET Core WebApplication et WebApplicationBuilder sont recommandés et sont utilisés dans tous les modèles ASP.NET Core. WebApplication se comporte de la même façon que l’hôte générique .NET et expose la plupart des mêmes interfaces, mais nécessite moins de rappels à configurer. L’hôte web ASP.NET Core WebHost est disponible uniquement à des fins de compatibilité descendante.

L’exemple suivant instancie un WebApplication et l’affecte à une variable nommée 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();

La méthode WebApplicationBuilder.Build configure un hôte avec un ensemble d’options par défaut, telles que :

• Utilisez Kestrel en tant que serveur web, et activez l’intégration d’IIS.
• Chargez la configuration à partir de appsettings.json , des variables d’environnement, des arguments de ligne de commande et d’autres sources de configuration.
• Envoyez la sortie de journalisation aux fournisseurs Console et Debug.

Scénarios non web

L’hôte générique permet à d’autres types d’applications d’utiliser des extensions de framework multi-coupe, telles que la journalisation, l’injection de dépendances (DI), la configuration et la gestion de la durée de vie des applications. Pour plus d’informations, consultez Hôte générique .NET dans ASP.NET Core et Tâches en arrière-plan avec des services hébergés dans ASP.NET Core.

Servers

Une application ASP.NET Core utilise une implémentation de serveur HTTP pour écouter les requêtes HTTP. Le serveur expose les requêtes à l’application sous la forme d’un ensemble de fonctionnalités de requête composées en un HttpContext.

Windows

ASP.NET Core fournit les implémentations de serveur suivantes :

• Kestrel est un serveur web multiplateforme. Kestrel est souvent exécuté dans une configuration de proxy inverse à l’aide d’IIS. Dans ASP.NET Core 2.0 ou les versions ultérieures, Kestrel peut être exécuté en tant que serveur de périphérie public exposé directement à Internet.
• Le serveur HTTP IIS est un serveur pour Windows qui utilise IIS. Avec ce serveur, l’application ASP.NET Core et IIS s’exécutent dans le même processus.
• HTTP.sys est un serveur pour Windows qui n’est pas utilisé avec IIS.

macOS

ASP.NET Core fournit l’implémentation du serveur multiplateforme Kestrel. Dans ASP.NET Core 2.0 ou les versions ultérieures, Kestrel peut s’exécuter en tant que serveur de périphérie public exposé directement à Internet. Kestrel est souvent exécuté dans une configuration de proxy inverse avec Nginx ou Apache.

Linux

ASP.NET Core fournit l’implémentation du serveur multiplateforme Kestrel. Dans ASP.NET Core 2.0 ou les versions ultérieures, Kestrel peut s’exécuter en tant que serveur de périphérie public exposé directement à Internet. Kestrel est souvent exécuté dans une configuration de proxy inverse avec Nginx ou Apache.

Pour plus d’informations, consultez Implémentations du serveur web dans ASP.NET Core.

Configuration

ASP.NET Core fournit une infrastructure de configuration qui obtient des paramètres en tant que paires nom-valeur à partir d’un ensemble ordonné de fournisseurs de configuration. Des fournisseurs de configuration intégrés sont disponibles pour diverses sources, par exemple les fichiers .json, les fichiers .xml, les variables d’environnement et les arguments de ligne de commande. Écrivez des fournisseurs de configuration personnalisés pour prendre en charge d’autres sources.

Par défaut, les applications ASP.NET Core sont configurées pour lire à partir des variables d'environnement, de la ligne de commande et de bien plus encore. Quand la configuration de l’application est chargée, les valeurs des variables d’environnement remplacent les valeurs de appsettings.json.

Pour gérer les données de configuration confidentielles telles que les mots de passe dans l’environnement de développement, .NET fournit le Gestionnaire de secrets. Pour les secrets de production, nous vous recommandons Azure Key Vault.

Pour plus d’informations, consultez Configuration dans ASP.NET Core.

Environments

Les environnements d’exécution, par exemple Development, Staging et Production, sont disponibles dans ASP.NET Core. Spécifiez l’environnement d’exécution d’une application en définissant la variable d’environnement ASPNETCORE_ENVIRONMENT. ASP.NET Core lit la variable d’environnement au démarrage de l’application et stocke la valeur dans une implémentation IWebHostEnvironment. Cette implémentation est disponible n’importe où dans une application via l’injection de dépendances.

L’exemple suivant configure le gestionnaire d’exceptions et le middleware (intergiciel) HSTS (HTTP Strict Transport Security Protocol) quand l’environnement d’exécution n’est pas l’environnement Development :

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

Pour plus d’informations, consultez ASP.NET environnements d’exécution Core.

Logging

ASP.NET Core prend en charge une API de journalisation qui fonctionne avec un large éventail de fournisseurs de journalisation intégrés et tiers. Les fournisseurs disponibles sont les suivants :

• Console
• Debug
• Suivi des événements sur Windows
• Journal des événements Windows
• TraceSource
• Azure App Service
• Azure Application Insights

Pour créer des journaux, résolvez un service ILogger<TCategoryName> à partir de l’injection de dépendances et des méthodes de journalisation des appels telles que LogInformation. L’exemple suivant montre comment obtenir et utiliser un enregistreur d’événements dans un fichier .razor pour une page d’un Blazor Web App. Un objet logger et un fournisseur de console pour celui-ci sont automatiquement stockés dans le conteneur DI lorsque la méthode CreateBuilder est appelée dans 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);
    }
}

Pour plus d’informations, consultez Journalisation dans .NET et ASP.NET Core.

Routing

Le routage dans ASP.NET Core est un mécanisme qui mappe les requêtes entrantes à des points de terminaison spécifiques dans une application. Il vous permet de définir des modèles d’URL qui correspondent à différents composants, tels que des composants Blazor, des pages Razor, des actions de contrôleur MVC ou des intergiciels.

La méthode UseRouting(IApplicationBuilder) ajoute un intergiciel de routage au pipeline de requête. Ce middleware traite les informations de routage et détermine le point de terminaison approprié pour chaque requête. Vous n’avez pas besoin d’appeler explicitement UseRouting, sauf si vous souhaitez modifier l’ordre dans lequel le middleware est traité.

Pour plus d’informations, consultez Routage dans ASP.NET Core et ASP.NET Core Blazor routage et navigation.

Gestion des erreurs

ASP.NET Core offre des fonctionnalités intégrées pour gérer des erreurs, telles que :

• Une page d’exceptions du développeur
• Pages d’erreur personnalisées
• Pages de codes d’état statique
• Gestion des exceptions de démarrage

Pour plus d’informations, consultez Gérer les erreurs dans ASP.NET Core.

Effectuer des requêtes HTTP

Une implémentation de IHttpClientFactory est disponible pour la création d’instances HttpClient. La fabrique :

• Fournit un emplacement central pour le nommage et la configuration d’instance de HttpClient logiques. Par exemple, inscrivez et configurez un client github pour accéder à GitHub. Inscrivez et configurez un client par défaut à d’autres fins.
• Prend en charge l’inscription et le chaînage de plusieurs gestionnaires de délégation pour créer un pipeline de middlewares pour les requêtes sortantes. Ce modèle est similaire au pipeline de middleware entrant d’ASP.NET Core. Le modèle fournit un mécanisme permettant de gérer les problèmes transversaux pour les requêtes HTTP, notamment la mise en cache, la gestion des erreurs, la sérialisation et la journalisation.
• S’intègre à Polly, une bibliothèque tierce populaire pour la gestion des erreurs temporaires.
• Gère le regroupement et la durée de vie des instances de HttpClientHandler sous-jacentes pour éviter les problèmes DNS courants qui se produisent durant la gestion manuelle des durées de vie de HttpClient.
• Ajoute une expérience de journalisation configurable (via ILogger) pour toutes les requêtes envoyées via les clients créés par la fabrique.

Pour plus d’informations, consultez Effectuer des requêtes HTTP en utilisant IHttpClientFactory dans ASP.NET Core.

Racine du contenu

La racine du contenu est le chemin de base pour :

• Exécutable hébergeant l’application (.exe).
• Assemblys compilés qui composent l’application (.dll).
• Fichiers de contenu utilisés par l’application, par exemple :
  • Fichiers Razor (.cshtml, .razor)
  • Fichiers config (.json, .xml)
  • Fichiers de données (.db)
• La racine Web, généralement le wwwroot répertoire.

Durant le développement, la racine du contenu correspond par défaut au répertoire racine du projet. Ce répertoire est également le chemin d’accès de base pour les fichiers de contenu de l’application et la racine web. Spécifiez une autre racine de contenu en définissant son chemin au moment de la génération de l’hôte. Pour plus d’informations, consultez la racine du contenu.

La racine Web

La racine web est le chemin de base des fichiers de ressources publics statiques, par exemple :

• Feuilles de style (.css)
• JavaScript (.js)
• Images (.png, .jpg)

Par défaut, les fichiers statiques sont traités uniquement à partir du répertoire racine web et de ses sous-répertoires. Le chemin racine web est défini par défaut sur {CONTENT ROOT}/wwwroot, où l’espace réservé {CONTENT ROOT} est la racine de contenu. Spécifiez une autre racine web en définissant son chemin au moment de la génération de l’hôte. Pour plus d’informations, consultez la Racine Web.

Empêchez la publication de fichiers dans wwwroot en utilisant l’élément de projet <Content> dans le fichier projet. L’exemple suivant empêche la publication de contenu dans wwwroot/local et de ses sous-répertoires :

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

Dans les fichiers Razor.cshtml, ~/ pointe vers la racine web. Un chemin d’accès commençant ~/ par est appelé chemin d’accès virtuel.

Pour plus d’informations, consultez Fichiers statiques dans ASP.NET Core.

Comment télécharger un exemple

La plupart des articles et tutoriels contiennent des liens vers des exemples de code.

1. Téléchargez le fichier zip du dépôt ASP.NET.
2. Décompressez le fichier AspNetCore.Docs-main.zip.
3. Pour accéder à l’exemple d’application d’un article dans le référentiel décompressé, utilisez l’URL du lien de l’exemple de cet article. En règle générale, l’exemple de lien d’un article apparaît en haut de l’article avec le texte de lien Afficher ou télécharger l’exemple de code.

Directives de préprocesseur dans l’exemple de code

Pour montrer plusieurs scénarios, les exemples d’applications utilisent les directives pré-processeur #define et #if-#else/#elif-#endif pour compiler et exécuter différentes sections de l’exemple de code de manière sélective. Pour ces exemples qui utilisent cette approche, définissez la directive #define en haut des fichiers C# pour définir le symbole associé au scénario que vous souhaitez exécuter. Certains exemples exigent que vous définissiez le symbole en haut de plusieurs fichiers afin d’exécuter un scénario.

Par exemple, la liste des symboles #define suivante indique que les quatre scénarios sont disponibles (un scénario par symbole). La configuration actuelle de l’exemple exécute le scénario TemplateCode :

#define TemplateCode // or LogFromMain or ExpandDefault or FilterInCode

Pour que l’exemple exécute le scénario ExpandDefault, définissez le symbole ExpandDefault et laissez les symboles restants commentés :

#define ExpandDefault // TemplateCode or LogFromMain or FilterInCode

Pour plus d’informations sur l’utilisation des directives de préprocesseur C# pour compiler de manière sélective des sections de code, consultez #define (référence C#) et #if (référence C#).

Régions dans l’exemple de code

Certains exemples d’applications contiennent des sections de code entourées de directives #region et #endregion C#. Le système de génération de documentation injecte ces régions dans les rubriques de documentation rendues.

Les noms de région contiennent généralement le mot « extrait de code ». L’exemple suivant montre une région nommée snippet_WebHostDefaults:

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

L’extrait de code C# précédent est référencé dans le fichier markdown de la rubrique avec la ligne suivante :

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

Vous pouvez ignorer ou supprimer en toute sécurité les directives #region et #endregion qui entourent le code. Ne modifiez pas le code dans ces directives si vous envisagez d’exécuter les exemples de scénarios décrits dans la rubrique.

Pour plus d’informations, consultez Contribuer à la documentation ASP.NET : extraits de code.

Ressources supplémentaires

ASP.NET notions de base Blazor