Migrating from .NET Web Forms to Blazor: A Step-by-Step Guide - Configuration

Switching from .NET Web Forms to Blazor requires migrating security settings like authentication and authorization. Learn how in this step-by-step guide.

Steven Lieberman

1/23/20243 min read



Blazor, a web framework developed by Microsoft, offers a modern and efficient way to build interactive web applications using .NET. If you have been working with .NET Web Forms and are considering migrating to Blazor, one important aspect to consider is the configuration. In this step-by-step guide, we will explore how configuration in Blazor differs from Web Forms and provide guidance on how to migrate your configuration settings.

Understanding Web Forms Configuration

In .NET Web Forms, configuration settings are typically stored in the web.config file. This file contains various sections, such as <appSettings> and <connectionStrings>, where you can define key-value pairs and connection strings respectively. These settings are accessible throughout your Web Forms application using the ConfigurationManager class.

Configuration in Blazor

Blazor follows a different approach to configuration compared to Web Forms. Instead of using a web.config file, Blazor relies on the .NET Core configuration system, which is based on JSON files and environment variables.

JSON Configuration Files

In Blazor, you can define your configuration settings in JSON files. By convention, the appsettings.json file is used for general application settings, while appsettings.{environment}.json files are used to override or add environment-specific settings. These files are typically located in the root directory of your Blazor project.

To migrate your Web Forms configuration settings to Blazor, you can create the corresponding sections and key-value pairs in the appsettings.json file. For example, if you had the following setting in your Web Forms web.config file:

  <add key="MySetting" value="123" />

You can migrate it to the appsettings.json file as:

  "MySetting": "123"

Similarly, if you had connection strings defined in the <connectionStrings> section of your web.config file, you can migrate them to the appsettings.json file as well. Here's an example:

  "ConnectionStrings": {
    "MyConnectionString": "Server=myServerAddress;Database=myDataBase;User Id=myUsername;Password=myPassword;"

Once you have defined your configuration settings in the JSON files, you can access them in your Blazor application using the IConfiguration interface.

Environment Variables

In addition to JSON configuration files, Blazor also supports configuration through environment variables. Environment variables provide a way to configure your application without modifying the JSON files. This can be useful when deploying your application to different environments.

To use environment variables in Blazor, you can prefix your configuration keys with "Blazor_" and set the corresponding environment variable. For example, if you have a configuration key called "MySetting", you can set it as an environment variable named "Blazor_MySetting". Blazor will automatically pick up the value from the environment variable if it exists.

Migrating Your Web Forms Configuration

Now that you understand how configuration works in Blazor, let's walk through the steps to migrate your Web Forms configuration to Blazor:

  1. Identify the configuration settings used in your Web Forms application, including both app settings and connection strings.
  2. Create the corresponding sections and key-value pairs in the appsettings.json file.
  3. Update your Blazor application code to use the IConfiguration interface to access the configuration settings.
  4. If you have any environment-specific configuration, create the appropriate appsettings.{environment}.json files and override the necessary settings.
  5. If desired, use environment variables to configure your application without modifying the JSON files.

By following these steps, you can successfully migrate your Web Forms configuration to Blazor and ensure that your application functions correctly with the new framework.


Migrating from .NET Web Forms to Blazor opens up new possibilities for building modern and interactive web applications. While configuration in Blazor differs from Web Forms, understanding the differences and following the migration steps outlined in this guide will help you seamlessly transition your configuration settings. Embrace the power of Blazor and enjoy the benefits of a modern web framework built on .NET.