Notions de base d’ASP.NET CoreASP.NET Core fundamentals

Cet article est une vue d’ensemble des sujets clés pour comprendre comment développer des applications ASP.NET Core.This article is an overview of key topics for understanding how to develop ASP.NET Core apps.

Classe StartupThe Startup class

La classe Startup est l’endroit où :The Startup class is where:

  • Tous les services requis par l’application sont configurés.Any services required by the app are configured.

  • Le pipeline de traitement des requêtes est défini.The request handling pipeline is defined.

  • Le code pour configurer (ou enregistrer) des services est ajouté à la méthode Startup.ConfigureServices.Code to configure (or register) services is added to the Startup.ConfigureServices method. Les services sont des composants utilisés par l’application.Services are components that are used by the app. Par exemple, un objet de contexte Entity Framework Core est un service.For example, an Entity Framework Core context object is a service.

  • Le code pour configurer le pipeline de traitement des requêtes est ajouté à la méthode Startup.Configure.Code to configure the request handling pipeline is added to the Startup.Configure method. Le pipeline est composé comme une série de composants d’intergiciel (middleware).The pipeline is composed as a series of middleware components. Par exemple, un intergiciel (middleware) peut gérer les demandes de fichiers statiques ou rediriger les requêtes HTTP vers HTTPS.For example, a middleware might handle requests for static files or redirect HTTP requests to HTTPS. Chaque intergiciel (middleware) effectue des opérations asynchrones sur HttpContext, puis appelle l’intergiciel (middleware) suivant dans le pipeline ou met fin à la requête.Each middleware performs asynchronous operations on an HttpContext and then either invokes the next middleware in the pipeline or terminates the request.

Voici un exemple de classe Startup :Here's a sample Startup class:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

        services.AddDbContext<MovieContext>(options =>
                options.UseSqlServer(Configuration.GetConnectionString("MovieDb")));
    }

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

Pour plus d’informations, consultez Démarrage des applications.For more information, see App startup.

Injection de dépendances (services)Dependency injection (services)

ASP.NET Core offre une infrastructure d’injection de dépendances (DI) intégrée qui rend disponibles les services configurés aux classes d’une application.ASP.NET Core has a built-in dependency injection (DI) framework that makes configured services available to an app's classes. Pour obtenir une instance d’un service dans une classe, vous pouvez créer un constructeur avec un paramètre du type requis.One way to get an instance of a service in a class is to create a constructor with a parameter of the required type. Le paramètre peut être le type de service ou une interface.The parameter can be the service type or an interface. Le système d’injection de dépendances fournit le service lors de l’exécution.The DI system provides the service at runtime.

Voici une classe qui utilise l’injection de dépendances pour obtenir un objet de contexte Entity Framework Core.Here's a class that uses DI to get an Entity Framework Core context object. La ligne en surbrillance est un exemple d’injection de constructeur :The highlighted line is an example of constructor injection:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;

    public IndexModel(RazorPagesMovieContext context)
    {
        _context = context;
    }
    // ...
    public async Task OnGetAsync()
    {
        var movies = from m in _context.Movies
                        select m;
        Movies = await movies.ToListAsync();
    }
}

Si l’injection de dépendances est intégrée, elle est conçue pour vous permettre d’incorporer un conteneur d’inversion de contrôle (IoC) tiers si vous préférez.While DI is built in, it's designed to let you plug in a third-party Inversion of Control (IoC) container if you prefer.

Pour plus d’informations, consultez Injection de dépendances.For more information, see Dependency injection.

Intergiciel (middleware)Middleware

Le pipeline de traitement des requêtes est composé comme une série de composants d’intergiciel (middleware).The request handling pipeline is composed as a series of middleware components. Chaque composant effectue des opérations asynchrones sur HttpContext, puis appelle l’intergiciel (middleware) suivant dans le pipeline ou met fin à la requête.Each component performs asynchronous operations on an HttpContext and then either invokes the next middleware in the pipeline or terminates the request.

Par convention, un composant d’intergiciel (middleware) est ajouté au pipeline en appelant sa méthode d’extension Use... dans la méthode Startup.Configure.By convention, a middleware component is added to the pipeline by invoking its Use... extension method in the Startup.Configure method. Par exemple, pour activer le rendu des fichiers statiques, appelez UseStaticFiles.For example, to enable rendering of static files, call UseStaticFiles.

Le code en surbrillance dans l’exemple suivant configure le pipeline de traitement des requêtes :The highlighted code in the following example configures the request handling pipeline:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

        services.AddDbContext<MovieContext>(options =>
                options.UseSqlServer(Configuration.GetConnectionString("MovieDb")));
    }

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

ASP.NET Core inclut un ensemble complet de middlewares intégrés, et vous pouvez écrire un middleware personnalisé.ASP.NET Core includes a rich set of built-in middleware, and you can write custom middleware.

Pour plus d’informations, consultez Middleware.For more information, see Middleware.

L’hôteThe host

Une application ASP.NET Core génère un hôte au démarrage.An ASP.NET Core app builds a host on startup. L’hôte est un objet qui encapsule toutes les ressources de l’application, telles que :The host is an object that encapsulates all of the app's resources, such as:

  • Une implémentation serveur HTTPAn HTTP server implementation
  • Composants d’intergiciel (middleware)Middleware components
  • JournalisationLogging
  • INJECTION DE DÉPENDANCESDI
  • ConfigurationConfiguration

La principale raison d’inclure toutes les ressources interdépendantes de l’application dans un objet est la gestion de la durée de vie : contrôler le démarrage de l’application et l’arrêt approprié.The main reason for including all of the app's interdependent resources in one object is lifetime management: control over app startup and graceful shutdown.

Le code pour créer un hôte se trouve dans Program.Main et suit le modèle de conception.The code to create a host is in Program.Main and follows the builder pattern. Les méthodes sont appelées pour configurer chaque ressource faisant partie de l’hôte.Methods are called to configure each resource that is part of the host. Une méthode de générateur est appelée pour tout rassembler et instancier l’objet hôte.A builder method is called to pull it all together and instantiate the host object.

ASP.NET Core 2.x utilise l’hôte web (la classe WebHost) pour les applications web.ASP.NET Core 2.x uses Web Host (the WebHost class) for web apps. Le framework fournit CreateDefaultBuilder pour définir un hôte avec des options fréquemment utilisées, telles que :The framework provides CreateDefaultBuilder to set up a host with commonly used options, such as the following:

  • Utilisez Kestrel en tant que serveur web et activez l’intégration IIS.Use Kestrel as the web server and enable IIS integration.
  • Chargez la configuration à partir de appsettings.json, des variables d’environnement, des arguments de ligne de commande et d’autres sources.Load configuration from appsettings.json, environment variables, command line arguments, and other sources.
  • Envoyez la sortie de journalisation aux fournisseurs Console et Debug.Send logging output to the console and debug providers.

Voici l’exemple de code qui génère un hôte :Here's sample code that builds a host:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

Pour plus d’informations, consultez Hôte web.For more information, see Web Host.

Dans ASP.NET Core 3.0, un hôte web (classe WebHost) ou un hôte générique (classe Host) peuvent être utilisés dans une application web.In ASP.NET Core 3.0, Web Host (WebHost class) or Generic Host (Host class) can be used in a web app. L’hôte générique est recommandée, et l’hôte web est disponible pour la compatibilité descendante.Generic Host is recommended, and Web Host is available for backwards compatibility.

Le framework fournit les méthodes CreateDefaultBuilder et ConfigureWebHostDefaults pour définir un hôte avec des options fréquemment utilisées, telles que :The framework provides the CreateDefaultBuilder and ConfigureWebHostDefaults methods to set up a host with commonly used options, such as the following:

  • Utilisez Kestrel en tant que serveur web et activez l’intégration IIS.Use Kestrel as the web server and enable IIS integration.
  • Chargez la configuration à partir de appsettings.json, appsettings.[EnvironmentName].json, des variables d’environnement, des arguments de ligne de commande et d’autres sources.Load configuration from appsettings.json, appsettings.[EnvironmentName].json, environment variables, and command line arguments.
  • Envoyez la sortie de journalisation aux fournisseurs Console et Debug.Send logging output to the console and debug providers.

Voici l’exemple de code qui génère un hôte.Here's sample code that builds a host. Les méthodes qui configurent l’hôte avec les options fréquemment utilisées sont mises en surbrillance.The methods that set up the host with commonly used options are highlighted.

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

Pour plus d’informations, consultez Hôte générique et Hôte webFor more information, see Generic Host and Web Host

Scénarios d’hôte avancésAdvanced host scenarios

L’hôte web est conçu pour inclure une implémentation de serveur HTTP, ce qui n’est pas nécessaire pour d’autres types d’applications .NET.Web Host is designed to include an HTTP server implementation, which isn't needed for other kinds of .NET apps. À compter de la version 2.1, l’hôte générique (classe Host) est disponible pour une utilisation par toutes les applications .NET Core—pas uniquement les applications ASP.NET Core.Starting in 2.1, Generic Host (Host class) is available for any .NET Core app to use—not just ASP.NET Core apps. L’hôte générique vous permet d’utiliser des fonctionnalités composites telles que la journalisation, l’injection de dépendances, la configuration et la gestion de la durée de vie d’application dans d’autres types d’applications.Generic Host lets you use cross-cutting features such as logging, DI, configuration, and app lifetime management in other types of apps. Pour plus d’informations, consultez Hôtes génériques.For more information, see Generic Host.

L’hôte générique est disponible pour une utilisation par toutes les applications .NET Core—pas uniquement les applications ASP.NET Core.Generic Host is available for any .NET Core app to use—not just ASP.NET Core apps. L’hôte générique vous permet d’utiliser des fonctionnalités composites telles que la journalisation, l’injection de dépendances, la configuration et la gestion de la durée de vie d’application dans d’autres types d’applications.Generic Host lets you use cross-cutting features such as logging, DI, configuration, and app lifetime management in other types of apps. Pour plus d’informations, consultez Hôtes génériques.For more information, see Generic Host.

Vous pouvez également utiliser l’hôte pour exécuter des tâches en arrière-plan.You can also use the host to run background tasks. Pour plus d’informations, consultez Tâches en arrière-plan.For more information, see Background tasks.

ServeursServers

Une application ASP.NET Core utilise une implémentation de serveur HTTP pour écouter les requêtes HTTP.An ASP.NET Core app uses an HTTP server implementation to listen for HTTP requests. Les surfaces de serveur envoient des requêtes à l’application comme un ensemble de fonctionnalités de requête composées dans un HttpContext.The server surfaces requests to the app as a set of request features composed into an HttpContext.

ASP.NET Core fournit les implémentations de serveur suivantes :ASP.NET Core provides the following server implementations:

  • Kestrel est un serveur web multiplateforme.Kestrel is a cross-platform web server. Kestrel est souvent exécuté dans une configuration de proxy inverse à l’aide d’IIS.Kestrel is often run in a reverse proxy configuration using IIS. Dans ASP.NET Core 2.0 ou versions ultérieures, Kestrel peut être exécuté en tant que serveur de périphérie public exposé directement à Internet.In ASP.NET Core 2.0 or later, Kestrel can be run as a public-facing edge server exposed directly to the Internet.
  • Le serveur HTTP IIS est un serveur pour Windows qui utilise IIS.IIS HTTP Server is a server for windows that uses IIS. Avec ce serveur, l’application ASP.NET Core et IIS s’exécutent dans le même processus.With this server, the ASP.NET Core app and IIS run in the same process.
  • HTTP.sys est un serveur Windows qui n’est pas utilisé avec IIS.HTTP.sys is a server for Windows that isn't used with IIS.

ASP.NET Core fournit les implémentations de serveur suivantes :ASP.NET Core provides the following server implementations:

  • Kestrel est un serveur web multiplateforme.Kestrel is a cross-platform web server. Kestrel est souvent exécuté dans une configuration de proxy inverse à l’aide d’IIS.Kestrel is often run in a reverse proxy configuration using IIS. Dans ASP.NET Core 2.0 ou versions ultérieures, Kestrel peut être exécuté en tant que serveur de périphérie public exposé directement à Internet.In ASP.NET Core 2.0 or later, Kestrel can be run as a public-facing edge server exposed directly to the Internet.
  • HTTP.sys est un serveur Windows qui n’est pas utilisé avec IIS.HTTP.sys is a server for Windows that isn't used with IIS.

Pour plus d’informations, consultez Serveurs.For more information, see Servers.

ConfigurationConfiguration

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.ASP.NET Core provides a configuration framework that gets settings as name-value pairs from an ordered set of configuration providers. Il existe des fournisseurs de configuration intégrés pour une grande variété de sources, tels que des fichiers .json, .xml, des variables d’environnement et des arguments de ligne de commande.There are built-in configuration providers for a variety of sources, such as .json files, .xml files, environment variables, and command-line arguments. Vous pouvez également écrire des fournisseurs de configuration.You can also write custom configuration providers.

Par exemple, vous pouvez spécifier que la configuration provient de appsettings.json et de variables d’environnement.For example, you could specify that configuration comes from appsettings.json and environment variables. Lorsque la valeur de ConnectionString est demandée, l’infrastructure recherche d’abord dans le fichier appsettings.json.Then when the value of ConnectionString is requested, the framework looks first in the appsettings.json file. Si la valeur est trouvée dans ce fichier, mais également dans une variable d’environnement, la valeur de la variable d’environnement est prioritaire.If the value is found there but also in an environment variable, the value from the environment variable would take precedence.

Pour gérer des données de configuration confidentielles telles que les mots de passe, ASP.NET Core fournit un outil Secret Manager.For managing confidential configuration data such as passwords, ASP.NET Core provides a Secret Manager tool. Pour les secrets de production, nous vous recommandons Azure Key Vault.For production secrets, we recommend Azure Key Vault.

Pour plus d’informations, consultez Configuration.For more information, see Configuration.

OptionsOptions

Lorsque cela est possible, ASP.NET Core suit le modèle d’options pour stocker et récupérer des valeurs de configuration.Where possible, ASP.NET Core follows the options pattern for storing and retrieving configuration values. Le modèle d’options utilise des classes pour représenter les groupes de paramètres associés.The options pattern uses classes to represent groups of related settings.

Par exemple, le code suivant définit des options WebSockets :For example, the following code sets WebSockets options:

var options = new WebSocketOptions  
{  
   KeepAliveInterval = TimeSpan.FromSeconds(120),  
   ReceiveBufferSize = 4096
};  
app.UseWebSockets(options);

Pour plus d’informations, consultez Options .For more information, see Options.

EnvironnementsEnvironments

Les environnements d’exécution, tels que Développement, Mise en lots et Production, sont une notion de premier plan dans ASP.NET Core.Execution environments, such as Development, Staging, and Production, are a first-class notion in ASP.NET Core. Vous pouvez spécifier l’environnement d’exécution d’une application en définissant la variable d’environnement ASPNETCORE_ENVIRONMENT.You can specify the environment an app is running in by setting the ASPNETCORE_ENVIRONMENT environment variable. ASP.NET Core lit la variable d’environnement au démarrage de l’application et stocke la valeur dans une implémentation IHostingEnvironment.ASP.NET Core reads that environment variable at app startup and stores the value in an IHostingEnvironment implementation. L’objet d’environnement est disponible partout dans l’application par le biais de l’injection de dépendances.The environment object is available anywhere in the app via DI.

L’exemple de code suivant de la classe Startup configure l’application pour fournir des informations d’erreur détaillées uniquement lorsqu’elle s’exécute en développement :The following sample code from the Startup class configures the app to provide detailed error information only when it runs in development:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();
    app.UseMvc();
}

Pour plus d’informations, consultez Environnements.For more information, see Environments.

JournalisationLogging

ASP.NET Core prend en charge une API de journalisation qui fonctionne avec différents fournisseurs de journalisation tiers et intégrés.ASP.NET Core supports a logging API that works with a variety of built-in and third-party logging providers. Les fournisseurs disponibles sont les suivants :Available providers include the following:

  • ConsoleConsole
  • DébogageDebug
  • Suivi des événements sur WindowsEvent Tracing on Windows
  • Journal des événements WindowsWindows Event Log
  • TraceSourceTraceSource
  • Azure App ServiceAzure App Service
  • Azure Application InsightsAzure Application Insights

Écrivez des journaux à partir de n’importe quel emplacement dans le code d’une application en obtenant un objet ILogger à partir de l’injection de dépendances et en appelant les méthodes de journal.Write logs from anywhere in an app's code by getting an ILogger object from DI and calling log methods.

Voici un exemple de code qui utilise un objet ILogger, avec l’injection de constructeur et les appels de méthode de journalisation mis en surbrillance.Here's sample code that uses an ILogger object, with constructor injection and the logging method calls highlighted.

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

L’interface ILogger vous permet de passer un certain nombre de champs au fournisseur de journalisation.The ILogger interface lets you pass any number of fields to the logging provider. Les champs sont couramment utilisés pour construire une chaîne de message, mais le fournisseur peut également les envoyer en tant que champs distincts dans un magasin de données.The fields are commonly used to construct a message string, but the provider can also send them as separate fields to a data store. Cette fonctionnalité permet aux fournisseurs de journalisation d’implémenter la journalisation sémantique, également appelée journalisation structurée.This feature makes it possible for logging providers to implement semantic logging, also known as structured logging.

Pour plus d’informations, consultez Journalisation.For more information, see Logging.

RoutageRouting

Un itinéraire est un modèle d’URL qui est mappé à un gestionnaire.A route is a URL pattern that is mapped to a handler. Le gestionnaire est généralement une page Razor, une méthode d’action dans un contrôleur MVC, ou un intergiciel (middleware).The handler is typically a Razor page, an action method in an MVC controller, or a middleware. Le routage ASP.NET Core vous permet de contrôler les URL utilisées par votre application.ASP.NET Core routing gives you control over the URLs used by your app.

Pour plus d’informations, consultez Routage.For more information, see Routing.

Gestion des erreursError handling

ASP.NET Core offre des fonctionnalités intégrées pour gérer des erreurs, telles que :ASP.NET Core has built-in features for handling errors, such as:

  • Une page d’exceptions du développeurA developer exception page
  • Pages d’erreurs personnaliséesCustom error pages
  • Pages de codes d’état statiqueStatic status code pages
  • Gestion des exceptions de démarrageStartup exception handling

Pour plus d’informations, consultez Gestion des erreurs.For more information, see Error handling.

Effectuer des requêtes HTTPMake HTTP requests

Une implémentation de IHttpClientFactory est disponible pour la création d’instances HttpClient.An implementation of IHttpClientFactory is available for creating HttpClient instances. La fabrique :The factory:

  • Fournit un emplacement central pour le nommage et la configuration d’instance de HttpClient logiques.Provides a central location for naming and configuring logical HttpClient instances. Par exemple, un client github peut être inscrit et configuré pour accéder à GitHub.For example, a github client can be registered and configured to access GitHub. Un client par défaut peut être inscrit à d’autres fins.A default client can be registered for other purposes.
  • 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.Supports registration and chaining of multiple delegating handlers to build an outgoing request middleware pipeline. Ce modèle est similaire au pipeline de middlewares entrants dans ASP.NET Core.This pattern is similar to the inbound middleware pipeline in ASP.NET Core. Le modèle fournit un mécanisme permettant de gérer les problèmes transversaux liés aux des requêtes HTTP, notamment la mise en cache, la gestion des erreurs, la sérialisation et la journalisation.The pattern provides a mechanism to manage cross-cutting concerns around HTTP requests, including caching, error handling, serialization, and logging.
  • S’intègre à Polly, une bibliothèque tierce populaire pour la gestion des erreurs temporaires.Integrates with Polly, a popular third-party library for transient fault handling.
  • Gère le regroupement et la durée de vie des instances de HttpClientMessageHandler sous-jacentes pour éviter les problèmes DNS courants qui se produisent lors de la gestion manuelle des durées de vie de HttpClient.Manages the pooling and lifetime of underlying HttpClientMessageHandler instances to avoid common DNS problems that occur when manually managing HttpClient lifetimes.
  • Ajoute une expérience de journalisation configurable (via ILogger) pour toutes les requêtes envoyées via des clients créés par la fabrique.Adds a configurable logging experience (via ILogger) for all requests sent through clients created by the factory.

Pour plus d’informations, consultez Effectuer des requêtes HTTP.For more information, see Make HTTP requests.

Racine de contenuContent root

La racine de contenu est le chemin de base de tout contenu privé utilisé par l’application, comme les fichiers Razor.The content root is the base path to any private content used by the app, such as its Razor files. Par défaut, la racine de contenu est le chemin de base pour l’exécutable qui héberge l’application.By default, the content root is the base path for the executable hosting the app. Un autre emplacement peut être spécifié lors de la création de l’hôte.An alternative location can be specified when building the host.

Pour plus d’informations, consultez Racine de contenu.For more information, see Content root.

Pour plus d’informations, consultez Racine de contenu.For more information, see Content root.

Racine webWeb root

La racine web (également appelée webroot) est le chemin d’accès de base aux ressources statiques publiques, telles que les fichiers CSS, JavaScript et image.The web root (also known as webroot) is the base path to public, static resources, such as CSS, JavaScript, and image files. Par défaut, l’intergiciel (middleware) des fichiers statiques traite uniquement les fichiers provenant du répertoire racine web (et des sous-répertoires).The static files middleware will only serve files from the web root directory (and sub-directories) by default. Le chemin d’accès par défaut de la racine web est <content root>/wwwroot, mais un autre emplacement peut être spécifié lors de la création de l’hôte.The web root path defaults to <content root>/wwwroot, but a different location can be specified when building the host.

Dans les fichiers Razor (.cshtml), la barre oblique tilde ~/ pointe vers la racine web.In Razor (.cshtml) files, the tilde-slash ~/ points to the web root. Les chemins commençant par ~/ sont appelés chemins virtuels.Paths beginning with ~/ are referred to as virtual paths.

Pour plus d’informations, consultez Fichiers statiques.For more information, see Static files.