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.

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

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.

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.

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

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.

Classe Startup

La classe Startup est l’endroit 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.

Voici un exemple de classe Startup :

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

Pour plus d’informations, consultez Start-up de l’application dans ASP.NET Core.

Injection de dépendances (services)

ASP.NET Core inclut un framework d’injection de dépendances intégré, qui rend les services configurés disponibles dans l’ensemble d’une application. Par exemple, un composant de journalisation est un service.

Le code pour configurer (ou enregistrer) des services est ajouté à la méthode Startup.ConfigureServices. Par exemple :

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

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

Les services sont généralement résolus à partir de l’interface d’injection de dépendances à l’aide de l’injection de constructeurs. Avec l’injection de constructeurs, une classe déclare un paramètre de constructeur ayant le type ou l’interface nécessaire. Le framework d’injection de dépendances fournit une instance de ce service au moment de l’exécution.

L’exemple suivant utilise l’injection de constructeurs pour résoudre un RazorPagesMovieContext à partir de l’injection de dépendances :

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;

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

    // ...

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

Si le conteneur IoC (inversion de contrôle) intégré ne répond pas à tous les besoins d’une application, vous pouvez utiliser un conteneur IoC tiers à la place.

Pour plus d’informations, consultez Injection de dépendances dans ASP.NET Core.

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... dans la méthode Startup.Configure. Par exemple, pour activer le rendu des fichiers statiques, appelez UseStaticFiles.

L’exemple suivant configure un pipeline de traitement de requêtes :

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

    app.UseRouting();

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

ASP.NET Core comprend un vaste ensemble de middlewares intégrés. Vous pouvez également écrire des composants de middlewares personnalisés.

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 deux hôtes différents :

• Hôte générique .NET
• Hôte web ASP.NET Core

L’hôte générique .NET est recommandé. L’hôte web ASP.NET Core est disponible uniquement à des fins de compatibilité descendante.

L’exemple suivant crée un hôte générique .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>();
            });
}

Les méthodes CreateDefaultBuilder et ConfigureWebHostDefaults configurent 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, de appsettings.{Environment}.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.

Pour plus d’informations, consultez Hôte générique .NET dans ASP.NET Core.

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.

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.

La meilleure méthode pour lire les valeurs de configuration associées consiste à utiliser le modèle d’options. Pour plus d’informations, consultez Lier des données de configuration hiérarchiques à l’aide du modèle d’options.

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 une notion de premier plan 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 l’application pour fournir des informations détaillées sur l’erreur quand l’environnement d’exécution est l’environnement 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();
    });
}

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

Les méthodes de journalisation telles que LogInformation prennent en charge n’importe quel nombre de champs. Ces champs sont couramment utilisés pour construire un message string. Toutefois, certains fournisseurs de journalisation les envoient à un magasin de données en tant que champs distincts. Cette fonctionnalité permet aux fournisseurs de journalisation d’implémenter la journalisation sémantique, également appelée journalisation structurée.

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.

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, ~/ (tilde-barre oblique) 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.