Skip to content

Commit a75a614

Browse files
BillWagnerWeihanLi
BillWagner
and
WeihanLi
authored
Emphasize concerns with latest LangVersion (dotnet#42639)
* Emphasize concerns with `latest` `LangVersion` Fixes dotnet#42400 Add more emphasis to discourage use of `latest` as the `LangVersion` element: - Change the style to `WARNING` - Add that `latest` can use a different language version on different machines. - Add that note and link from other C# docs discussing versioning. * Update docs/csharp/language-reference/language-versioning.md Co-authored-by: Weihan Li <[email protected]> --------- Co-authored-by: Weihan Li <[email protected]>
1 parent 5d6225c commit a75a614

File tree

4 files changed

+22
-13
lines changed

4 files changed

+22
-13
lines changed

‎docs/csharp/language-reference/compiler-options/language.md

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
description: "C# Compiler Options for language feature rules. These options control how the compiler interprets certain language constructs."
33
title: "Compiler Options - language feature rules"
4-
ms.date: 10/30/2023
4+
ms.date: 09/17/2024
55
f1_keywords:
66
- "cs.build.options"
77
helpviewer_keywords:
@@ -65,6 +65,10 @@ This option specifies the names of one or more symbols that you want to define.
6565

6666
The default language version for the C# compiler depends on the target framework for your application and the version of the SDK or Visual Studio installed. Those rules are defined in [C# language versioning](../language-versioning.md#defaults).
6767

68+
> [!WARNING]
69+
>
70+
> Setting the `LangVersion` element to `latest` is discouraged. The `latest` setting means the installed compiler uses its latest version. That can change from machine to machine, making builds unreliable. In addition, it enables language features that may require runtime or library features not included in the current SDK.
71+
6872
The **LangVersion** option causes the compiler to accept only syntax that is included in the specified C# language specification, for example:
6973

7074
```xml
@@ -75,9 +79,6 @@ The following values are valid:
7579

7680
[!INCLUDE [lang-versions-table](../includes/langversion-table.md)]
7781

78-
> [!IMPORTANT]
79-
> The `latest` value is generally not recommended. With `latest`, the compiler enables the latest features, even if those features depend on updates not included in the configured target framework.
80-
8182
### Considerations
8283

8384
- To ensure that your project uses the default compiler version recommended for your target framework, don't use the **LangVersion** option. You can update the target framework to access newer language features.

‎docs/csharp/language-reference/configure-language-version.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,16 @@
11
---
22
title: Configure language version
3-
description: Learn how to override the default C# language version manually.
3+
description: Learn how to override the default C# language version manually. The C# compiler can support any language version up to the version in the installed SDK.
44
ms.custom: "updateeachrelease"
5-
ms.date: 08/02/2024
5+
ms.date: 09/17/2024
66
---
77

88
# Configure C# language version
99

10+
> [!WARNING]
11+
>
12+
> Setting the `LangVersion` element to `latest` is discouraged. The `latest` setting means the installed compiler uses its latest version. That can change from machine to machine, making builds unreliable. In addition, it enables language features that may require runtime or library features not included in the current SDK.
13+
1014
If you must specify your C# version explicitly, you can do so in several ways:
1115

1216
- Manually edit the [project file](#edit-the-project-file).

‎docs/csharp/language-reference/language-versioning.md

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,14 @@
22
title: Language versioning
33
description: Learn about how the C# language version is determined based on your project and the reasons behind that choice.
44
ms.custom: "updateeachrelease"
5-
ms.date: 08/02/2024
5+
ms.date: 09/17/2024
66
---
77

88
# C# language versioning
99

1010
The latest C# compiler determines a default language version based on your project's target framework or frameworks. Visual Studio doesn't provide a UI to change the value, but you can change it by editing the *csproj* file. The choice of default ensures that you use the latest language version compatible with your target framework. You benefit from access to the latest language features compatible with your project's target. This default choice also ensures you don't use a language that requires types or runtime behavior not available in your target framework. Choosing a language version newer than the default can cause hard to diagnose compile-time and runtime errors.
1111

12-
[C# 12](../whats-new/csharp-12.md) is supported only on .NET 8 and newer versions. [C# 11](../whats-new/csharp-11.md) is supported only on .NET 7 and newer versions. [C# 10](../whats-new/csharp-10.md) is supported only on .NET 6 and newer versions.
12+
[C# 13](../whats-new/csharp-13.md) is supported only on .NET 9 and newer versions. [C# 12](../whats-new/csharp-12.md) is supported only on .NET 8 and newer versions. [C# 11](../whats-new/csharp-11.md) is supported only on .NET 7 and newer versions.
1313

1414
Check the [Visual Studio platform compatibility](/visualstudio/releases/2022/compatibility#-visual-studio-2022-support-for-net-development) page for details on which .NET versions are supported by versions of Visual Studio. Check the [Visual Studio for Mac platform compatibility](/visualstudio/mac/supported-versions-net) page for details on which .NET versions are supported by versions of Visual Studio for Mac. Check the [Mono page for C#](https://www.mono-project.com/docs/about-mono/languages/csharp/) for Mono compatibility with C# versions.
1515

@@ -21,9 +21,6 @@ The compiler determines a default based on these rules:
2121

2222
If your project targets a `preview` framework that has a corresponding preview language version, the language version used is the preview language version. You use the latest features with that preview in any environment, without affecting projects that target a released .NET Core version.
2323

24-
> [!IMPORTANT]
25-
> The new project template for Visual Studio 2017 added a `<LangVersion>latest</LangVersion>` entry to new project files. If you upgrade the target framework for these projects, the `<LangVersion>` setting can [override the default](configure-language-version.md) for the new target framework. Be sure to remove the `<LangVersion>latest</LangVersion>` from your project file to ensure your project uses the recommended compiler version for your target framework. You can update the target framework to access newer language features.
26-
2724
## C# language version reference
2825

2926
The following table shows all current C# language versions. Older compilers might not understand every value. If you install the latest .NET SDK, you have access to everything listed.

‎docs/csharp/versioning.md

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,22 @@
11
---
22
title: Versioning
33
description: Understand how versioning works in C# and .NET
4-
ms.date: 01/08/2017
4+
ms.date: 09/17/2024
55
ms.subservice: advanced-concepts
6-
ms.assetid: aa8732d7-5cd0-46e1-994a-78017f20d861
76
---
87

98
# Versioning in C\#
109

1110
In this tutorial you'll learn what versioning means in .NET. You'll also learn the factors to consider when versioning your library as well as upgrading to a new version of a library.
1211

12+
## Language version
13+
14+
The C# compiler is part of the .NET SDK. By default, the compiler chooses the C# language version that matches the chosen [TFM](../standard/frameworks.md) for your project. If the SDK version is greater than your chosen framework, the compiler could use a greater language version. You can change the default by setting the `LangVersion` element in your project. You can learn how in our article on [compiler options](language-reference/compiler-options/language.md#langversion).
15+
16+
> [!WARNING]
17+
>
18+
> Setting the `LangVersion` element to `latest` is discouraged. The `latest` setting means the installed compiler uses its latest version. That can change from machine to machine, making builds unreliable. In addition, it enables language features that may require runtime or library features not included in the current SDK.
19+
1320
## Authoring Libraries
1421

1522
As a developer who has created .NET libraries for public use, you've most likely been in situations where you have to roll out new updates. How you go about this process matters a lot as you need to ensure that there's a seamless transition of existing code to the new version of your library. Here are several things to consider when creating a new release:

0 commit comments

Comments
 (0)