How to create projects that target earlier frameworks

[tdykstra]

Fixes #24544

File Type	File Name	Published Url
Content	docs/core/tools/dotnet-new-sdk-templates.md	https://review.docs.microsoft.com/en-us/dotnet/core/tools/dotnet-new-sdk-templates?branch=pr-en-us-25603

[BillWagner]

This LGTM @tdykstra

I had one question that we should address if it's a quick change.

[BillWagner]

Not related to your PR, but we should make an explicit statement about VB support for --langVersion.

[vlada-shubina]

@tdykstra could we please take a pause on this PR to discuss it?

It seems that different templates owners have different rules:

• common project templates and web templates are following package per tfm approach and the packages are available on NuGet.org; so installing older package from NuGet.org will work.
• test, wpf and winforms templates are following single package approach. For WPF / winforms only supported TFMs are available (3.1, 5.0, 6.0) and for test templates only 6.0 is available. Additionally those packages are not available on NuGet.org. For those templates only installing older EOL SDK will probably help to get older framework available.
• additionally some templates support hidden --target-framework-override parameter which allows setting any text value as tfm. However this value is not validated, and will not be taken into account when evaluating language feature support, so using it after [EPIC] .NET 6 C# project templates use latest language idioms templating#3359 will probably result in the template that cannot be compiled.

Adding @KathleenDollard and @DamianEdwards here for discussion.

[DamianEdwards]

Ideally all templates should be updating to use the template identifier to produce a package per version and accept the framework version as an option, along with publishing all versions to NuGet.org. As I understand it, that way the templating engine can discover and suggest the correct package when a framework option value is passed that isn't supported by any installed templates, but is supported by a template in a package on NuGet.org. This is how the web templates work.

[KathleenDollard]

I agree that moving to a single approach (package per TFM, available on NuGet) would be extremely helpful. I think for Microsoft templates we just move this direction as fast as the teams can manage it.

This seems overly complex for third party template authors. I think if templates are delivered to NuGet separately, the single package approach makes sense for these templates. Adding that so template authors happening upon this aren't confused and to clarify with Tom.

@vlada-shubina when we complete that approach, then will @tdykstra text be correct?

[vlada-shubina]

imo, both single package and package per TFM approaches are possible and have their pros and cons; it's more about finding a common ground here.
In case we want to continue with package per TFM test-templates, wpf and winforms should align their templates and publishing accordingly.
In case we want to continue with single package, probably all repos and possibly template engine itself have some work to do.
Single package seems easier approach for understanding, however however we probably should somehow distinguish supported and EOL tfms when displaying them to users and this approach might involve higher maintenance costs (for example in case hot fix is needed for 3.1 template, it should be applied to 3.1 and higher template pack).

As I understand it, that way the templating engine can discover and suggest the correct package when a framework option value is passed that isn't supported by any installed templates, but is supported by a template in a package on NuGet.org.

This is not a case anymore, we removed implicit templates search on template instantiation to avoid unnecessary delays on searching. Potentially we can enable behavior when the user can do the search to check for package availability: dotnet new webapi --search --framework netcoreapp3.0, but we need to put the SDK templates back to search cache file (now that SDK templates are not checked for updates any longer any way it should be ok to have them in search cache). I can work on this if needed.

This seems overly complex for third party template authors. I think if templates are delivered to NuGet separately, the single package approach makes sense for these templates. Adding that so template authors happening upon this aren't confused and to clarify with Tom.

Definitely agree, we should recommend creating single package for template authors in all tutorials. However should also probably give an explanation of advanced scenario too (template grouping was highlighted as understanding pain point in couple issues already).

@vlada-shubina when we complete that approach, then will @tdykstra text be correct?

Tom's text is correct.
I would probably only suggest to reorder paragraphs and put installing the SDK as the first option, and installing NuGet package as alternative, smth like:

The ability to create a project for an earlier TFM depends on having that version of the SDK installed. For example, if you have only SDK 5.0 installed, then the only value available for --framework is net5.0. If you install SDK 3.1, the value netcoreapp3.1 becomes available for --framework. If you install SDK 2.1, netcoreapp2.1 becomes available, and so on. So by specifying --framework netcoreapp2.1 you can use SDK 2.1 even while running dotnet new in SDK 5.0.

Alternatively, to create a project that targets a framework earlier than the SDK that you're using, you might need to install the NuGet package for the template. Common, web, and SPA project types use different packages per target framework moniker (TFM). For example, to be able to create a console project that targets netcoreapp1.0, run dotnet new --install on Microsoft.DotNet.Common.ProjectTemplates.1.x.

[tdykstra]

Tom's text is correct.

With your reordering of the options applied, is this correct for the current state of things, meaning we could merge this PR and revise the text when we make the changes under discussion? Or hold the PR open until then?

[vlada-shubina]

Fine with me. I will open the tickets to test-templates, wpf and winforms repos (those that are not available on NuGet.org and following different packaging approach) tomorrow to continue discussion.