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 obtenir des instructions de base sur Blazor, en complément ou en remplacement des instructions de ce nœud, consultez Notions fondamentales Blazor ASP.NET Core.

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 traitement des requêtes de l’application est défini sous la forme d’une série de composants de middlewares.

Le code de démarrage d’application suivant prend en charge les éléments suivants :

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

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

Injection de dépendances (services)

ASP.NET Core inclut l’injection de dépendances (DI) qui rend les services configurés disponibles dans l’ensemble d’une application. Les services sont ajoutés au conteneur d’injection de dépendances avec WebApplicationBuilder.Services, builder.Services dans le code précédent. Quand WebApplicationBuilder est instancié, de nombreux services fournis par le framework sont ajoutés. 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 en surbrillance précédent, builder permet l’ajout de la configuration, de la journalisation et de nombreux autres services au conteneur d’injection de dépendances.

Le code suivant ajoute des pages Razor, des contrôleurs MVC avec vues et un DbContext personnalisé au conteneur d’injection de dépendances :

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

Les services sont généralement résolus à partir de l’interface d’injection de dépendances à l’aide de l’injection de constructeurs. Le framework d’injection de dépendances fournit une instance de ce service au moment de l’exécution.

Le code suivant utilise l’injection de constructeurs pour résoudre le contexte de base de données et le journaliseur à partir de l’injection de dépendances :

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

Intergiciel (middleware)

Le pipeline de traitement des requêtes est composé d’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}. Le middleware ajouté à l’application est mis en évidence dans le code suivant :

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

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 (middleware)
• Journalisation
• Services d’injection de dépendances
• Configuration

Il existe trois hôtes différents 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é à ASP.NET CoreConfigureWebHostDefaults
• WebHost ASP.NET Core

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

L’exemple suivant instancie un WebApplication :

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

• 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 basés sur le web

L’hôte générique permet à d’autres types d’application d’utiliser des extensions de framework composites, par exemple la journalisation, l’injection de dépendance, la configuration et la gestion de la durée de vie de l’application. 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.

Serveurs

Une application ASP.NET Core utilise une implémentation de serveur HTTP pour écouter les requêtes HTTP. Les surfaces de serveur envoient des requêtes à l’application comme un ensemble de fonctionnalités de requête composées dans 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 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 un framework de configuration qui obtient les paramètres sous forme de 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 appsettings.json, les variables d’environnement, la ligne de commande, etc. 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, .NET Core fournit l’outil Secret Manager. Pour les secrets de production, nous vous recommandons Azure Key Vault.

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

Environnements

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 :

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

Pour plus d’informations, consultez Utiliser plusieurs environnements dans ASP.NET Core.

Journalisation

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
• Déboguer
• 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. Par exemple :

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

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

Routage

Un itinéraire est un modèle d’URL qui est mappé à un gestionnaire. Le gestionnaire est généralement une page Razor, une méthode d’action dans un contrôleur MVC ou un middleware. Le routage ASP.NET Core vous permet de contrôler les URL utilisées par votre application.

Le code suivant, généré par le modèle d’application web ASP.NET Core, appelle 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();

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

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 de contenu

La racine du contenu est le chemin de base pour :

• L’exécutable hébergeant l’application (.exe).
• Les 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 dossier wwwroot.

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 de base des fichiers de contenu de l’application et de 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 Racine de contenu.

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 de la racine web par défaut est {racine_du_contenu}/wwwroot. 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 Racine web.

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

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

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

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

Ressources supplémentaires

• Code source de WebApplicationBuilder