C# project templates breaking change

docs/core/compatibility/6.0.md

@@ -75,6 +75,7 @@ If you're migrating an app to .NET 6, the breaking changes listed here might aff
 | Title | Preview introduced |
 | - | - |
 | [`-p` option for `dotnet run` is deprecated](sdk/6.0/deprecate-p-option-dotnet-run.md) | Preview 6 |
+| [C# code in templates not supported by earlier versions](sdk/6.0/csharp-template-code.md) | Preview 7 |
 | [Generate apphost for macOS](sdk/6.0/apphost-generated-for-macos.md) | Preview 6 |
 | [Generate error for duplicate files in publish output](sdk/6.0/duplicate-files-in-output.md) | Preview 1 |
 | [GetTargetFrameworkProperties and GetNearestTargetFramework removed from ProjectReference protocol](sdk/6.0/gettargetframeworkproperties-and-getnearesttargetframework-removed.md) | Preview 1 |

docs/core/compatibility/sdk/6.0/csharp-template-code.md

@@ -0,0 +1,53 @@
+---
+title: "Breaking change: C# code in templates not supported by earlier versions"
+description: Learn about the breaking change in .NET 6 where project templates use new C# features that aren't available in previous versions.
+ms.date: 07/30/2021
+---
+# C# code in templates not supported by earlier versions
+
+Starting in .NET 6, the project templates that ship with the .NET SDK use the latest C# language features. The following language features are used in template-generated code or enabled by default in the project:
+
+- [Top-level statements](../../../../csharp/fundamentals/program-structure/top-level-statements.md)
+- [Global using directives](https://github.com/dotnet/csharplang/blob/main/proposals/csharp-10.0/GlobalUsingDirective.md)
+- [File-scoped namespaces](https://github.com/dotnet/csharplang/blob/main/proposals/csharp-10.0/file-scoped-namespaces.md)
+- [Target-typed new expressions](/dotnet/csharp/language-reference/proposals/csharp-9.0/target-typed-new)
+- [Nullable reference types](../../../../csharp/nullable-references.md)
+- [`async` Main method](/dotnet/csharp/language-reference/proposals/csharp-7.1/async-main)
+
+Some of the latest C# language features are not supported by previous target frameworks, so you might experience issues in the following scenarios:
+
+- When you use a .NET 6 template and then change the target framework to a previous version.
+- When you use a .NET 6 template and then multi-target by adding a previous target framework version.
+
+## Version introduced
+
+.NET SDK 6.0.100 Preview 7
+
+## Old behavior
+
+In previous .NET versions, you can change the target framework to a previous version or add an additional version without having to change the C# code created by the project template.
+
+## New behavior
+
+Starting in .NET 6, when you change or add a target framework, you may need to change the C# code generated by the template to avoid using unsupported language features. The project won't build without these changes. The compiler errors and warnings usually guide you on how to change the generated code to make it compatible with new target framework.
+
+## Change category
+
+This change affects [*source compatibility*](../../categories.md#source-compatibility).
+
+## Reason for change
+
+We want the project templates to be synchronized with the latest language features. The main usage scenario of targeting the latest framework uses the latest C# language features.
+
+## Recommended action
+
+If you encounter compile-time errors and warnings when you retarget to an earlier framework version, use that information to guide you in changing the generated code to make it compatible with the target framework you selected.
+
+To avoid compile-time errors when targeting an older framework, follow these suggestions:
+
+- Avoid changing the target framework to a previous version. Instead, select the target framework you want during project creation in Visual Studio or at the command line by using `dotnet new <templateName> --framework <targetFramework>`.
+- When creating a multi-target project, select the *lowest* target-framework version when you create the project. Add the additional target frameworks after the project is created.
+
+## Affected APIs
+
+N/A

docs/core/compatibility/toc.yml

@@ -101,6 +101,8 @@ items:
         items:
         - name: -p option for `dotnet run` is deprecated
           href: sdk/6.0/deprecate-p-option-dotnet-run.md
+        - name: C# code in templates not supported by earlier versions
+          href: sdk/6.0/csharp-template-code.md
         - name: Generate apphost for macOS
           href: sdk/6.0/apphost-generated-for-macos.md
         - name: Generate error for duplicate files in publish output
@@ -701,6 +703,8 @@ items:
         items:
         - name: -p option for `dotnet run` is deprecated
           href: sdk/6.0/deprecate-p-option-dotnet-run.md
+        - name: C# code in templates not supported by earlier versions
+          href: sdk/6.0/csharp-template-code.md
         - name: Generate apphost for macOS
           href: sdk/6.0/apphost-generated-for-macos.md
         - name: Generate error for duplicate files in publish output