Skip to content

Commit

Permalink
Emphasize concerns with latest LangVersion
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
BillWagner committed Sep 17, 2024
1 parent fadc18d commit fa32c7a
Show file tree
Hide file tree
Showing 4 changed files with 22 additions and 13 deletions.
9 changes: 5 additions & 4 deletions docs/csharp/language-reference/compiler-options/language.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: "C# Compiler Options for language feature rules. These options control how the compiler interprets certain language constructs."
title: "Compiler Options - language feature rules"
ms.date: 10/30/2023
ms.date: 09/17/2024
f1_keywords:
- "cs.build.options"
helpviewer_keywords:
Expand Down Expand Up @@ -65,6 +65,10 @@ This option specifies the names of one or more symbols that you want to define.

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).

> [!WARNING]
>
> 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.
The **LangVersion** option causes the compiler to accept only syntax that is included in the specified C# language specification, for example:

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

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

> [!IMPORTANT]
> 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.
### Considerations

- 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.
Expand Down
8 changes: 6 additions & 2 deletions docs/csharp/language-reference/configure-language-version.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,16 @@
---
title: Configure language version
description: Learn how to override the default C# language version manually.
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.
ms.custom: "updateeachrelease"
ms.date: 08/02/2024
ms.date: 09/17/2024
---

# Configure C# language version

> [!WARNING]
>
> 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.
If you must specify your C# version explicitly, you can do so in several ways:

- Manually edit the [project file](#edit-the-project-file).
Expand Down
7 changes: 2 additions & 5 deletions docs/csharp/language-reference/language-versioning.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,14 @@
title: Language versioning
description: Learn about how the C# language version is determined based on your project and the reasons behind that choice.
ms.custom: "updateeachrelease"
ms.date: 08/02/2024
ms.date: 09/17/2024
---

# C# language versioning

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.

[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.
[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.

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.

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

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.

> [!IMPORTANT]
> 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.
## C# language version reference

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.
Expand Down
11 changes: 9 additions & 2 deletions docs/csharp/versioning.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,22 @@
---
title: Versioning
description: Understand how versioning works in C# and .NET
ms.date: 01/08/2017
ms.date: 09/17/2024
ms.subservice: advanced-concepts
ms.assetid: aa8732d7-5cd0-46e1-994a-78017f20d861
---

# Versioning in C\#

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.

## Language version

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).

> [!WARNING]
>
> 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.
## Authoring Libraries

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:
Expand Down

0 comments on commit fa32c7a

Please sign in to comment.