[Breaking change]: C# code created using .NET 6 templates does not support targeting earlier .NET versions

[vlada-shubina]

Description

Area: .NET SDK templates

In .NET 6 Preview 7 we made a change to the templates shipped with .NET SDK to use latest C# language features.

The following language features will be used or enabled by default in the SDK-included project templates:

• Top-level statements
• Global using directives
• File-scoped namespaces
• Target-typed new expressions
• Nullable reference types
• async Main

Some of the latest C# language features are not supported by previous target frameworks, so the users might experience the issues in the following scenarios:

• Use a .NET 6 template and then change the target framework to previous version
• Use a .NET 6 template and then add a previous version TFM to multi-target

Version

.NET 6 Preview 7

Previous behavior

It was possible to change target framework by editing project file or in project file properties without needing to change the C# code created from a template.

It was possible to add additional target framework by editing project file without needing to change the C# code created from a template.

New behavior

When changing the target framework or adding target framework the users may need to change the C# code generated by the template to avoid using unsupported language features. Without these change the project cannot be built. The compiler errors and warnings should usually guide the user on how to change the generated code to make it compatible with new target framework.

Type of breaking change

• Binary incompatible (existing binaries may encounter a breaking change in behavior - for example, failure to load/execute or different run-time behavior)
• Source incompatible (existing source code may encounter a breaking change in behavior when targeting the new runtime/component/SDK - for example, compile errors or different run-time behavior)

Reason for change

We would like the templates to be in sync with latest language features so that main scenario of using single latest target framework uses the latest language features.

Recommended action

1. Avoid changing the target framework to previous version. Select the target framework you want during project creation in Visual Studio or via dotnet new <templateName> --framework <targetFramework>.

2. When creating multi-target project, select the lowest target framework during project creation in Visual Studio or via dotnet new.

Feature area

Other (please put exact area in description textbox)

Affected APIs

none

[dsplaisted]

This looks good. I would avoid using the term "down-level" though.

[vlada-shubina]

This looks good. I would avoid using the term "down-level" though.

I replaced "down-level" with "previous version".