Démarrage d’une application dans ASP.NET CoreApp startup in ASP.NET Core

  • 12 minutes de lecture
  • Contributeurs
    • Tom Dykstra
    • olprod
    • Antoine Griffard
    • v-radelg
    • hinault

Par Tom Dykstra, Luke Latham et Steve SmithBy Tom Dykstra, Luke Latham, and Steve Smith

La classe Startup configure les services et le pipeline de demande de l’application.The Startup class configures services and the app's request pipeline.

Classe StartupThe Startup class

Les applications ASP.NET Core utilisent une classe Startup, appelée Startup par convention.ASP.NET Core apps use a Startup class, which is named Startup by convention. La classe Startup :The Startup class:

  • Inclut éventuellement une méthode ConfigureServices pour configurer les services de l’application.Optionally includes a ConfigureServices method to configure the app's services. Un service est un composant réutilisable qui fournit une fonctionnalité d’application.A service is a reusable component that provides app functionality. Les services sont configurés —ou inscrits—dans ConfigureServices et consommés dans l’application via l’injection de dépendances ou ApplicationServices.Services are configured—also described as registered—in ConfigureServices and consumed across the app via dependency injection (DI) or ApplicationServices.
  • Inclut une méthode Configure pour créer le pipeline de traitement des requêtes de l’application.Includes a Configure method to create the app's request processing pipeline.

ConfigureServices et Configure sont appelées par le runtime au démarrage de l’application :ConfigureServices and Configure are called by the runtime when the app starts:

public class Startup
{
    // Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        ...
    }

    // Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app)
    {
        ...
    }
}

La classe Startup est spécifiée pour l’application quand sonhôte est généré.The Startup class is specified to the app when the app's host is built. L’hôte de l’application est généré quand Build est appelé sur le générateur de l’hôte dans la classe Program.The app's host is built when Build is called on the host builder in the Program class. La classe Startup est généralement spécifiée via l’appel de la méthode WebHostBuilderExtensions.UseStartup <TStartup> sur le générateur de l’hôte :The Startup class is usually specified by calling the WebHostBuilderExtensions.UseStartup<TStartup> method on the host builder:

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

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

L’hôte fournit des services accessibles au constructeur de classe Startup.The host provides services that are available to the Startup class constructor. L’application ajoute des services supplémentaires à l’aide de ConfigureServices.The app adds additional services via ConfigureServices. Les services de l’hôte ainsi que ceux de l’application sont alors disponibles dans Configure et dans l’ensemble de l’application.Both the host and app services are then available in Configure and throughout the app.

Une utilisation courante de l’injection de dépendances dans la classe Startup consiste à injecter :A common use of dependency injection into the Startup class is to inject:

public class Startup
{
    private readonly IHostingEnvironment _env;
    private readonly IConfiguration _config;
    private readonly ILoggerFactory _loggerFactory;

    public Startup(IHostingEnvironment env, IConfiguration config, 
        ILoggerFactory loggerFactory)
    {
        _env = env;
        _config = config;
        _loggerFactory = loggerFactory;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        var logger = _loggerFactory.CreateLogger<Startup>();

        if (_env.IsDevelopment())
        {
            // Development service configuration

            logger.LogInformation("Development environment");
        }
        else
        {
            // Non-development service configuration

            logger.LogInformation($"Environment: {_env.EnvironmentName}");
        }

        // Configuration is available during startup.
        // Examples:
        //   _config["key"]
        //   _config["subsection:suboption1"]
    }
}

Une alternative à l’injection de IHostingEnvironment consiste à utiliser une approche basée sur les conventions.An alternative to injecting IHostingEnvironment is to use a conventions-based approach. Quand l’application définit différentes classes Startup pour différents environnements (par exemple, StartupDevelopment), la classe Startup appropriée est sélectionnée au moment de l’exécution.When the app defines separate Startup classes for different environments (for example, StartupDevelopment), the appropriate Startup class is selected at runtime. La classe dont le suffixe du nom correspond à l'environnement actuel est prioritaire.The class whose name suffix matches the current environment is prioritized. Si l’application est exécutée dans l’environnement de développement et comprend à la fois une classe Startup et une classe StartupDevelopment, la classe StartupDevelopment est utilisée.If the app is run in the Development environment and includes both a Startup class and a StartupDevelopment class, the StartupDevelopment class is used. Pour plus d’informations, consultez Utiliser plusieurs environnements.For more information, see Use multiple environments.

Pour en savoir plus sur l’hôte, consultez Hôte web et hôte générique dans ASP.NET Core.To learn more about the host, see Hôte web et hôte générique dans ASP.NET Core. Pour plus d’informations sur la gestion des erreurs lors du démarrage, consultez Gestion des exceptions de démarrage.For information on handling errors during startup, see Startup exception handling.

Méthode ConfigureServicesThe ConfigureServices method

La méthode ConfigureServices est :The ConfigureServices method is:

  • Optionnel.Optional.
  • Appelée par l’hôte avant la méthode Configure pour configurer les services de l’applicationCalled by the host before the Configure method to configure the app's services.
  • L’emplacement où les options de configuration sont définies par convention.Where configuration options are set by convention.

Le modèle par défaut consiste à appeler toutes les méthodes Add{Service}, puis toutes les méthodes services.Configure{Service}.The typical pattern is to call all the Add{Service} methods and then call all of the services.Configure{Service} methods. Par exemple, consultez Configurer les services d’identité.For example, see Configure Identity services.

L’hôte peut configurer certains services avant l’appel des méthodes Startup.The host may configure some services before Startup methods are called. Pour plus d'informations, consultez Hôte web et hôte générique dans ASP.NET Core.For more information, see Hôte web et hôte générique dans ASP.NET Core.

Pour les fonctionnalités qui nécessitent une configuration importante, il existe des méthodes d’extension Add{Service} pour IServiceCollection.For features that require substantial setup, there are Add{Service} extension methods on IServiceCollection. Une application ASP.NET Core classique inscrit des services pour Entity Framework, Identity et MVC :A typical ASP.NET Core app registers services for Entity Framework, Identity, and MVC:

public void ConfigureServices(IServiceCollection services)
{
    // Add framework services.
    services.AddDbContext<ApplicationDbContext>(options =>
        options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")));

    services.AddIdentity<ApplicationUser, IdentityRole>()
        .AddEntityFrameworkStores<ApplicationDbContext>()
        .AddDefaultTokenProviders();

    services.AddMvc();

    // Add application services.
    services.AddTransient<IEmailSender, AuthMessageSender>();
    services.AddTransient<ISmsSender, AuthMessageSender>();
}

L'ajout de services au conteneur de service les rend disponibles au sein de l’application et dans la méthode Configure.Adding services to the service container makes them available within the app and in the Configure method. Les services sont résolus via l’injection de dépendances ou à partir de ApplicationServices.The services are resolved via dependency injection or from ApplicationServices.

Méthode ConfigureThe Configure method

La méthode Configure permet de spécifier le mode de réponse de l’application aux requêtes HTTP.The Configure method is used to specify how the app responds to HTTP requests. Vous configurez le pipeline de requête en ajoutant des composants d’intergiciel (middleware) à une instance de IApplicationBuilder.The request pipeline is configured by adding middleware components to an IApplicationBuilder instance. IApplicationBuilder est disponible pour la méthode Configure, mais elle n’est pas inscrite dans le conteneur de service.IApplicationBuilder is available to the Configure method, but it isn't registered in the service container. L’hébergement crée un IApplicationBuilder et le passe directement à Configure.Hosting creates an IApplicationBuilder and passes it directly to Configure.

Les modèles ASP.NET Core configurent le pipeline pour permettre la prise en charge des éléments suivants :The ASP.NET Core templates configure the pipeline with support for:

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

    app.UseHttpsRedirection();
    app.UseStaticFiles();
    app.UseCookiePolicy();

    app.UseMvc();
}

Chaque méthode d’extension Use ajoute un ou plusieurs composants de middleware au pipeline de requête.Each Use extension method adds one or more middleware components to the request pipeline. Par exemple, la méthode d’extension UseMvc ajoute le middleware de routage au pipeline de requête et configure MVC en tant que gestionnaire par défaut.For instance, the UseMvc extension method adds Routing Middleware to the request pipeline and configures MVC as the default handler.

Chaque composant de middleware du pipeline des requêtes est chargé d’appeler le composant suivant du pipeline ou de court-circuiter la chaîne, si c’est approprié.Each middleware component in the request pipeline is responsible for invoking the next component in the pipeline or short-circuiting the chain, if appropriate. Si un court-circuit ne se produit pas dans la chaîne de middlewares, chaque middleware a une deuxième occasion de traiter la requête avant qu’elle soit envoyée au client.If short-circuiting doesn't occur along the middleware chain, each middleware has a second chance to process the request before it's sent to the client.

Vous pouvez spécifier des services supplémentaires, par exemple IHostingEnvironment et ILoggerFactory, dans la signature de méthode Configure.Additional services, such as IHostingEnvironment and ILoggerFactory, may also be specified in the Configure method signature. Si tel est le cas, les services supplémentaires sont injectés s’ils sont disponibles.When specified, additional services are injected if they're available.

Pour plus d’informations sur l’utilisation de IApplicationBuilder et sur l’ordre de traitement des middlewares, consultez Intergiciel (middleware) ASP.NET Core.For more information on how to use IApplicationBuilder and the order of middleware processing, see Intergiciel (middleware) ASP.NET Core.

Méthodes pratiquesConvenience methods

Pour configurer les services et le pipeline de traitement de requête sans utiliser de classe Startup, appelez les méthodes pratiques ConfigureServices et Configure sur le générateur de l’hôte.To configure services and the request processing pipeline without using a Startup class, call ConfigureServices and Configure convenience methods on the host builder. Les appels multiples à ConfigureServices s’ajoutent les uns aux autres.Multiple calls to ConfigureServices append to one another. S’il existe plusieurs appels de méthode Configure, le dernier appel de Configure est utilisé.If multiple Configure method calls exist, the last Configure call is used.

public class Program
{
    public static IHostingEnvironment HostingEnvironment { get; set; }
    public static IConfiguration Configuration { get; set; }

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                HostingEnvironment = hostingContext.HostingEnvironment;
                Configuration = config.Build();
            })
            .ConfigureServices(services =>
            {
                ...
            })
            .Configure(app =>
            {
                var loggerFactory = app.ApplicationServices
                    .GetRequiredService<ILoggerFactory>();
                var logger = loggerFactory.CreateLogger<Program>();

                logger.LogInformation("Logged in Configure");

                if (HostingEnvironment.IsDevelopment())
                {
                    ...
                }
                else
                {
                    ...
                }

                var configValue = Configuration["subsection:suboption1"];

                ...
            });
}

Étendre le démarrage avec les filtres de démarrageExtend Startup with startup filters

Utilisez IStartupFilter pour configurer le middleware au début ou à la fin du pipeline de middleware de la méthode Configure d’une application.Use IStartupFilter to configure middleware at the beginning or end of an app's Configure middleware pipeline. IStartupFilter est utile pour s’assurer qu’un intergiciel s’exécute avant ou après l’intergiciel ajouté par des bibliothèques au début ou à la fin du pipeline de traitement de requête de l’application.IStartupFilter is useful to ensure that a middleware runs before or after middleware added by libraries at the start or end of the app's request processing pipeline.

IStartupFilter implémente une seule méthode, Configure, qui reçoit et retourne Action<IApplicationBuilder>.IStartupFilter implements a single method, Configure, which receives and returns an Action<IApplicationBuilder>. IApplicationBuilder définit une classe pour configurer le pipeline de requête d’une application.An IApplicationBuilder defines a class to configure an app's request pipeline. Pour plus d’informations, consultez Créer un pipeline de middlewares avec IApplicationBuilder.For more information, see Create a middleware pipeline with IApplicationBuilder.

Chaque IStartupFilter implémente un ou plusieurs intergiciels dans le pipeline de requête.Each IStartupFilter implements one or more middlewares in the request pipeline. Les filtres sont appelés dans l’ordre dans lequel ils ont été ajoutés au conteneur de service.The filters are invoked in the order they were added to the service container. Les filtres peuvent ajouter l’intergiciel avant ou après la transmission du contrôle au filtre suivant. Par conséquent, ils s’ajoutent au début ou à la fin du pipeline de l’application.Filters may add middleware before or after passing control to the next filter, thus they append to the beginning or end of the app pipeline.

L’exemple suivant montre comment inscrire un middleware auprès de IStartupFilter.The following example demonstrates how to register a middleware with IStartupFilter.

Le middleware RequestSetOptionsMiddleware définit une valeur d’options à partir d’un paramètre de chaîne de requête :The RequestSetOptionsMiddleware middleware sets an options value from a query string parameter:

public class RequestSetOptionsMiddleware
{
    private readonly RequestDelegate _next;
    private IOptions<AppOptions> _injectedOptions;

    public RequestSetOptionsMiddleware(
        RequestDelegate next, IOptions<AppOptions> injectedOptions)
    {
        _next = next;
        _injectedOptions = injectedOptions;
    }

    public async Task Invoke(HttpContext httpContext)
    {
        Console.WriteLine("RequestSetOptionsMiddleware.Invoke");

        var option = httpContext.Request.Query["option"];

        if (!string.IsNullOrWhiteSpace(option))
        {
            _injectedOptions.Value.Option = WebUtility.HtmlEncode(option);
        }

        await _next(httpContext);
    }
}

RequestSetOptionsMiddleware est configuré dans la classe RequestSetOptionsStartupFilter :The RequestSetOptionsMiddleware is configured in the RequestSetOptionsStartupFilter class:

public class RequestSetOptionsStartupFilter : IStartupFilter
{
    public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
    {
        return builder =>
        {
            builder.UseMiddleware<RequestSetOptionsMiddleware>();
            next(builder);
        };
    }
}

IStartupFilter est inscrit dans le conteneur de service de ConfigureServices et augmente Startup à partir de l’extérieur de la classe Startup :The IStartupFilter is registered in the service container in ConfigureServices and augments Startup from outside of the Startup class:

WebHost.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddTransient<IStartupFilter, 
            RequestSetOptionsStartupFilter>();
    })
    .UseStartup<Startup>()
    .Build();

Quand un paramètre de chaîne de requête pour option est fourni, l’intergiciel traite l’affectation de valeur avant que l’intergiciel MVC affiche la réponse :When a query string parameter for option is provided, the middleware processes the value assignment before the MVC middleware renders the response:

Fenêtre de navigateur affichant la page d’index rendue.

L’ordre d’exécution de l’intergiciel est défini par l’ordre des inscriptions d’IStartupFilter :Middleware execution order is set by the order of IStartupFilter registrations:

  • Plusieurs implémentations d’IStartupFilter peuvent interagir avec les mêmes objets.Multiple IStartupFilter implementations may interact with the same objects. Si l’ordre est important, définissez l’ordre des inscriptions de leurs services IStartupFilter pour qu’il corresponde à l’ordre dans lequel leurs intergiciels doivent s’exécuter.If ordering is important, order their IStartupFilter service registrations to match the order that their middlewares should run.
  • Les bibliothèques peuvent ajouter des intergiciels avec une ou plusieurs implémentations IStartupFilter qui s’exécutent avant ou après l’autre intergiciel d’application inscrit avec IStartupFilter.Libraries may add middleware with one or more IStartupFilter implementations that run before or after other app middleware registered with IStartupFilter. Pour appeler un intergiciel IStartupFilter avant un intergiciel ajouté à l’IStartupFilter d’une bibliothèque, placez l’inscription du service avant l’ajout de la bibliothèque au conteneur de service.To invoke an IStartupFilter middleware before a middleware added by a library's IStartupFilter, position the service registration before the library is added to the service container. Pour l’appeler par la suite, placez l’inscription du service après l’ajout de la bibliothèque.To invoke it afterward, position the service registration after the library is added.

Ajouter la configuration au démarrage à partir d’un assembly externeAdd configuration at startup from an external assembly

Une implémentation de IHostingStartup permet d’ajouter des améliorations à une application au démarrage à partir d’un assembly externe, en dehors de la classe Startup de l’application.An IHostingStartup implementation allows adding enhancements to an app at startup from an external assembly outside of the app's Startup class. Pour plus d'informations, consultez Utiliser des assemblys de démarrage d’hébergement dans ASP.NET Core.For more information, see Utiliser des assemblys de démarrage d’hébergement dans ASP.NET Core.

Ressources supplémentairesAdditional resources