Document the legacy project upgrade breaking changes

[JanKrivanek]

Background

As part of MSBuild deprecated code removal effort (dotnet/msbuild#8826) an upgrade support from pre-MSBuild projects (and pre-MSBuild webprojects) will be dropped in dev17.12

The document to be updated

https://learn.microsoft.com/en-us/visualstudio/releases/2022/port-migrate-and-upgrade-visual-studio-projects

Previous behavior

When encountered those legacy project types (from .NET 1.1 and prior), Visual Studio was able to automatically run upgrade wizard to make the necessary one-way changes in order to open the projects.

New behavior

Upgrade wizard will run, but it will not be able to convert those old project types (rest of the upgrade will run successfuly).
Conversion upgrade log will display a clear customized error, that will provida an aka.ms link for more details:

Once the microsoft.learn article is properly updated (anchor should be added as well) - the aka.ms link will be pointed to the article.

Workaround

Older VS version can be used to run the conversion, after which the upgraded project can be saved and then opened in the new VS version.

Envisioned Timeline

The change is planned for dev17.12 P1

Required changes

• Add section for 'Unsupported upgrade scenarios' - describing the above described behavior and workaround.
• The added section should be directly linkable (so that we can direct to it via the aka.ms link)

[welcome]

Thank you for opening an issue! One of our team members will get back to you with additional information.

If this is a product issue, please close this issue and contact the product's support instead. For a list of support websites, see Support for Microsoft products and apps.

[gewarren]

FYI @ghogen @anandmeg

[ghogen]

This can be assigned to me.

[JanKrivanek]

UPDATE 8/23:

• The conversion functionality of pre-MSBuild projects is going to be removed in 17.13 (for other project types it will continue to exist going forward)

• We should explicitly guide users to save & commit the converted projects - as the original formats might not be convertible in future VS versions. This will be messaged by curred wording:
  

  and

  

• We should have that information in the documentation document pointed by this bug (the dialog 'More information' hyperlink will point to it)

• This documentation should be bit more explicit - informing that pre-MSBuild project formats (replaced with MSBuild project format about 20 years ago) will be convertible only up to Visual Studio version 17.12 and won't be convertible from Visual Studio version 17.13 - so users should store the converted results. The other project formats will continue to be convertible for now and older Visual Studio versions will continue to convert even pre-MSBuild project files going forward. But the advise to store the converted results applies globaly - as in future versions of Visual Studio or future updates of previous releases of Visual Studio (2019, 2017) additional restrictions of upgrade functionality can apply.

The last bullet point summarizes what should appear in the doc. It should be in a section that is directly linkable (so there should be an anchor or linkable heading)