Upgrading from .NET Framework to .NET 6 is possible via assistants, in this article we are exploring the .NET Upgrade Assistant provided by Microsoft. This is part 2 of 2 in this series.
The assistant
Microsoft provides a command-line tool1 to assess .NET Framework apps. It provides an analysis report for each of the projects in the solution containing details on:
Package dependencies that need to be removed/added/upgraded.
References that need to be removed/added/upgraded.
Framework References that need to be removed/added/upgraded.
Call out if there is a package upgrade across major versions that could lead towards breaking changes.
Unsupported API used in the projects with pointers to a recommended path forward if one is available.
Similarly to the Porting Assistant, the tool is not going to do magical things but will help you to identify critical points in the solution that need to be reviewed.
Supported project types and languages
It is worth mentioning that the tool supports the following project types:
Interestingly enough this solution works on .NET Framework 4.5, but I didn’t dare to install it on my current machine, so I manually tweaked the Project file to .NET Framework 4.8.
I recommend a separate machine, probably a VM to run this sort of exercise.
If you are in Visual Studio 2022 you get this warning.
As you do the framework change, it modifies the project Target Framework:
Usage:upgrade-assistantanalyze[options]<project>Arguments:<project>Options:--extension<extension>Specifiesa.NETUpgradeAssistantextensionpackagetoinclude.ThiscouldbeanExtensionManifest.jsonfile,adirectorycontaininganExtensionManifest.jsonfile,oraziparchivecontaininganextension.Thisoptioncanbespecifiedmultipletimes.-v,--verboseEnableverbosediagnostics--target-tfm-support<Current|LTS|Preview>SelectifyouwouldliketheLongTermSupport(LTS),Current,orPreviewTFM.Seehttps://dotnet.microsoft.com/platform/support/policy/dotnet-core for
detailsforwhatthesemean.--format<HTML>Specifytheformatinwhichtheanalysisreportwillbegenerated.CurrentlysupportshtmlotherthanthedefaultSARIFformat.--versionShowversioninformation-?,-h,--helpShowhelpandusageinformation
I have both .NET 6 and .NET 7 available in my machine, but I enforced .NET 6 LTS to be used with –target-tfm-support
The default output produced will be a file of type .SARIF format, which can be opened on VStudio Code via extension:
Upgrading
Run the analyzer to upgrade the solution on .NET 6:
Usage:upgrade-assistantupgrade<project>[command][options]Arguments:<project>Thepathtoaprojectorsolutionfiletobeused.Options:-x,--extension<extension>Specifiesa.NETUpgradeAssistantextensionpackagetoinclude.ThiscouldbeanExtensionManifest.jsonfile,adirectorycontaininganExtensionManifest.jsonfile,oraziparchivecontaininganextension.Thisoptioncanbespecifiedmultipletimes.-o,--option<option>SpecifiesanoptionthatshouldbeaddedtoUpgradeAssistantthatmaybeusedbyextensions.-e,--entry-point<entry-point>Providestheentry-pointprojecttostarttheupgradeprocess.Thismayincludeglobbingpatternssuchas'*'formatch.-i,--ignore-unsupported-featuresAcknowledgesthatupgrade-assistantwillnotbeabletocompletelyupgradeaproject.Thisindicatesthatthesolutionmustberedesigned(e.g.considerBlazortoreplaceWebForms).--vs-path<vs-path>PathtoaVSinstalldirectorytobeusedfor%VSINSTALLDIR%.Ifnotprovided,thelatestinstalledversionwillbeused.--msbuild-path<msbuild-path>PathtoaMSBuildinstalldirectorytobeused.Ifnotprovided,thelatestinstalledversionwillbeused.-t,--target-tfm-support<LTS|Preview|STS>SelectifyouwouldliketheLongTermSupport(LTS),StandardTermSupport(STS),orPreviewTFM.Seehttps://dotnet.microsoft.com/platform/support/policy/dotnet-core for details on what these mean.
-v,--verboseEnableverbosediagnostics-f,--format<format>Specifyformatofanalyzeresult.Ifnotprovided,asariffilewillbeproduced.Availabledefaultvalues:"sarif","html"--skip-backupDisablesbackinguptheproject.Thisisnotrecommendedunlesstheprojectisinsourcecontrolsincethistoolwillmakelargechangestoboththeprojectandsourcefiles.--non-interactiveAutomaticallyselecteachfirstoptioninnon-interactivemode.--non-interactive-wait<non-interactive-wait>Waitthesuppliedsecondsbeforemovingontothenextoptioninnon-interactivemode.-?,-h,--helpShowhelpandusageinformationCommands:list-formats
The same .SARIF report is created at the end of processing on a file called UpgradeReport.sarif.
The new upgraded solution
So the solution was migrated from .NET Framework 4.8 to .NET 6, but will it work?
Similar to the previous article, the solution will not even compile. This will give you an idea of the efforts required, so you can provide estimates, and get the team to work on it.
A lot is going on in this MVC project, as you can see in the csproj below. A good approach in this case would be to start a new project and move files across.
This is a great tool, that will help to point out the issues ahead of time during upgrades.
I tried using the HTML format when generating the report output, but the HTML is too simple and it doesn’t allow interactions, but the .SARIF extension on VStudio Code works much better, as you can drill down to the issues dynamically.
If I was to upgrade a single project, rather than do it non-interactively, I would go one step at a time as the tool asks for you to take decisions. This is much more verbose, but it gives you a better understanding of what the tool is trying to do.
Join the conversation! Share your thoughts and connect with other readers.