Upgrade assistant - overview

Analyzers

Analyzer functionality is included in the Upgrade assistant to analyze your solution and determine the components that need to be migrated to ASP.NET Core standard. After the analyzers evaluate your code, you can let the Upgrade assistant automatically convert your solution to ASP.NET Core.

Some tasks are not fully automated. For example, the Upgrade assistant does not handle Razor views or CSHTML, but the analyzer functionality does. The analyzer functionality flags non-ASP.NET Core standard with green squiggles directly in the Visual Studio project. You can fix these errors with code quick fix functionality in Visual Studio.

The analyzer also works on an already-converted solution, so when you open your updated ASP.NET Core site in Visual Studio and pull in more code that was not converted to ASP.NET Core standard, the analyzer flags any code that does not follow .NET Core standard (for example, occurrances of System.Web or Owin).

The analyzer tool also works for non-framework libraries, such as business logic libraries.

If you have a library that targets ASP.NET Standard and you convert this into ASP.NET Core, it cannot be consumed by ASP.NET Standard anymore.
If you have a library with multiple solutions depending on it, other apps targeting this library cannot use it, so in this case you should have a full framework library and then a library specifically for ASP.NET Core code on the side, to make sure shared libraries can still be used by apps not on ASP.NET Core.

Startup code

One challenge with going from ASP.NET Standard to ASP.NET Core is that you no longer have a global.asax file, which allowed you to write code that would run in response to higher "system level" events, such as Application_Start, Application_End, Session_Start, Session_End.

Instead, you have two methods, Configure and ConfigureServices, and a Startup class, and those are significantly different. These cannot be migrated automatically because there are too many app-specific things in global.asax.

At step 5 in the migration process (adding templates), you need four startup files: Program.cs, Startup.cs, appsettings.json, and appsettings.Development.json. If they are missing, Upgrade assistant creates them. It pulls some template files, changes some namespaces (System.Web and Owin are no longer used, and are removed) and then adds them to the project. Your old Startup.cs is saved under the name Startup.old.cs.

In Startup.cs, you can configure services required by the app and define the app's request handling pipeline as a series of middleware components.

Program.cs is often very similar from project-to-project and should not require many changes.

Application configuration files replacing web.config

In previous versions of ASP.NET, web.config stored application configuration settings such as database connection strings, global variables, and so on. In ASP.NET Core, the application configuration settings can come from different configurations sources such as files, user secrets, environment variables, or command-line arguments.

The appsettings.json file stores configuration settings previously found in web.config. If you do not already have appsettings.json in your solution, the Upgrade assistant creates one for you (by adding a template file in step 5) and migrates your web.config settings to this file.

If you had a list of namespaces in web.config that were automatically imported into Razor views, (such as System.Web.Mvc.Html, System.Web.Routing, AlloyTemplates.Models.Pages, and AlloyTemplates.Models.Blocks), you cannot automatically import these namespaces in the views using ASP.NET Core. In ASP.NET Core, you must import them by the _ViewImports.cshtml file instead. Upgrade assistant creates _ViewImports.cshtml and moves the namespaces from web.config to this new file, along with TagHelpers because they can be useful in ASP.NET Core projects. Also, Upgrade assistant does not migrate namespaces starting with System.Web because they are not supported by ASP.NET Core; you should replace them with other namespaces.

The appsettings.{Environment}.json file is a configuration file where {Environment} equals the application's current hosting environments, such as Development, Staging, or Production. This is valuable as you can use different appsettings for different environments.

ExtensionManifest.json

The Upgrade assistant is divided into two repositories. The first one, [], contains the general Upgrade assistant that handles general code conversions from ASP.NET standard to ASP.NET Core. The second repository, [], contains code that is Optimizely specific.

In this second repository, there is an ExtensionManifest.json file which contains the configuration settings for migrating Optimizely-specific code to ASP.NET Core. From the start, it looks something like this, with four sections for different configuration options for the migration steps.

{
  "ConfigUpdater": {
    "ConfigUpdaterPath": "ConfigUpdaters"
  },
  "PackageUpdater": {
    "PackageMapPath": "PackageMaps"
  },
  "TemplateInserter": {
    "TemplateConfigFiles": [
      "Templates\\EPiServerTemplates\\TemplateConfig.json"
    ]
  }
}

ConfigUpdater. For any configuration updaters.
PackageUpdater. Contains the map file that maps old NuGet packages and versions to new packages and versions.
SourceUpdater. For analyzers and code fix providers.
TemplateInserter. Contains template files for the Optimizely-specific code, such as Program.cs and Startup.cs.

Related information

If you are just starting to look at .NET Core and want to understand more about potential challenges in migrating any particular project .NET Core, start by looking at .NET Framework dependencies the project has, and third-party libraries or NuGet packages it depends on, and understand whether those dependencies are likely to work on .NET Core. Resources that can help with that analysis include:

Do you find this information helpful? Please log in to provide feedback.

Last updated: Jul 02, 2021