Application Startup in ASP.NET Core

By Steve Smith and Tom Dykstra

The Startup class configures services and the application's request pipeline.

The Startup class

ASP.NET Core apps require a Startup class. By convention, the Startup class is named "Startup". You specify the startup class name in the Main program's WebHostBuilderExtensions UseStartup<TStartup> method. See Hosting to learn more about WebHostBuilder, which runs before Startup.

You can define separate Startup classes for different environments, and the appropriate one will be selected at runtime. If you specify startupAssembly in the WebHost configuration or options, hosting will load that startup assembly and search for a Startup or Startup[Environment] type. The class whose name suffix matches the current environment will be prioritized, so if the app is run in the Development environment, and includes both a Startup and a StartupDevelopment class, the StartupDevelopment class will be used. See FindStartupType in StartupLoader and Working with multiple environments.

Alternatively, you can define a fixed Startup class that will be used regardless of the environment by calling UseStartup<TStartup>. This is the recommended approach.

The Startup class constructor can accept dependencies that are provided through dependency injection. A common approach is to use IHostingEnvironment to set up configuration sources.

The Startup class must include a Configure method and can optionally include a ConfigureServices method, both of which are called when the application starts. The class can also include environment-specific versions of these methods. ConfigureServices, if present, is called before Configure.

Learn about handling exceptions during application startup.

The ConfigureServices method

The ConfigureServices method is optional; but if used, it's called before the Configure method by the web host. The web host may configure some services before Startup methods are called (see hosting). By convention, Configuration options are set in this method.

For features that require substantial setup there are Add[Service] extension methods on IServiceCollection. This example from the default web site template configures the app to use 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>();
}

Adding services to the services container makes them available within your application via dependency injection.

Services Available in Startup

ASP.NET Core dependency injection provides services during an application's startup. You can request these services by including the appropriate interface as a parameter on your Startup class's constructor or its Configure method. The ConfigureServices method only takes an IServiceCollection parameter (but any registered service can be retrieved from this collection, so additional parameters are not necessary).

Below are some of the services typically requested by Startup methods:

  • In the constructor: IHostingEnvironment, ILogger<Startup>
  • In ConfigureServices: IServiceCollection
  • In Configure: IApplicationBuilder, IHostingEnvironment, ILoggerFactory

Any services added by the WebHostBuilder ConfigureServices method may be requested by the Startup class constructor or its Configure method. Use WebHostBuilder to provide any services you need during Startup methods.

The Configure method

The Configure method is used to specify how the ASP.NET application will respond to HTTP requests. The request pipeline is configured by adding middleware components to an IApplicationBuilder instance that is provided by dependency injection.

In the following example from the default web site template, several extension methods are used to configure the pipeline with support for BrowserLink, error pages, static files, ASP.NET MVC, and Identity.

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
    loggerFactory.AddConsole(Configuration.GetSection("Logging"));
    loggerFactory.AddDebug();

    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
        app.UseDatabaseErrorPage();
        app.UseBrowserLink();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
    }

    app.UseStaticFiles();

    app.UseIdentity();

    app.UseMvc(routes =>
    {
        routes.MapRoute(
            name: "default",
            template: "{controller=Home}/{action=Index}/{id?}");
    });
}

Each Use extension method adds a middleware component to the request pipeline. For instance, the UseMvc extension method adds the routing middleware to the request pipeline and configures MVC as the default handler.

For more information about how to use IApplicationBuilder, see Middleware.

Additional services, like IHostingEnvironment and ILoggerFactory may also be specified in the method signature, in which case these services will be injected if they are available.

Additional Resources