From 5d01b47707cce6efde41bf2e8cc6ff4b1d5fd7dd Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Sat, 21 Dec 2024 09:41:09 -0500 Subject: [PATCH] Address issues related to C# versions (#44050) * Include C# 13 in history Fixes #33401 Add the new features in C# 13, and add a link to the full feature history in the csharplang repository. * Version updates Fixes #33554: Add a link to selecting the UWP version, because UWP uses a different project format. Fixes #36919: Add that the directory.props.build method should be used only with C# projects, not folders that include both C# and VB projects. Fixes #41296: Move the paragraph that explains why the version dropdown is greyed out to the top of the article. * Apply suggestions from code review Co-authored-by: Andy (Steve) De George <67293991+adegeo@users.noreply.github.com> --------- Co-authored-by: Andy (Steve) De George <67293991+adegeo@users.noreply.github.com> --- .../configure-language-version.md | 24 +++++++++++-------- .../whats-new/csharp-version-history.md | 23 ++++++++++++++++-- 2 files changed, 35 insertions(+), 12 deletions(-) diff --git a/docs/csharp/language-reference/configure-language-version.md b/docs/csharp/language-reference/configure-language-version.md index 5c61af79d3717..6bf5faee80508 100644 --- a/docs/csharp/language-reference/configure-language-version.md +++ b/docs/csharp/language-reference/configure-language-version.md @@ -7,6 +7,14 @@ ms.date: 09/17/2024 # Configure C# language version +The information in this article applies to .NET 5 and above. For UWP projects, see this information in the article on [Choosing a UWP version](/windows/uwp/updates-and-versions/choose-a-uwp-version). + +In Visual Studio, the option to change the language version through the UI is disabled because the default version is aligned with the project's target framework (`TFM`). This default configuration ensures compatibility between language features and runtime support. To change the language version in Visual Studio, change the project's target framework. + +For example, changing the target `TFM` (for example, from [.NET 6](https://dotnet.microsoft.com/en-us/download/dotnet/6.0) to [.NET 9](https://dotnet.microsoft.com/en-us/download/dotnet/9.0)) updates the language version accordingly, from C# 10 to C# 13. This approach prevents issues with runtime compatibility and minimizes unexpected build errors due to unsupported language features. + +If you need a specific language version that differs from the one automatically selected, refer to the methods in this article to override the default settings directly in the project file. + > [!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. @@ -20,15 +28,7 @@ If you must specify your C# version explicitly, you can do so in several ways: > [!TIP] > You can see the language version in Visual Studio in the project properties page. Under the *Build* tab, the *Advanced* pane displays the version selected. > -> To know what language version you're currently using, put `#error version` (case sensitive) in your code. This makes the compiler report a compiler error, CS8304, with a message containing the compiler version being used and the current selected language version. See [#error (C# Reference)](preprocessor-directives.md#error-and-warning-information) for more information. - -## Why you can't select a different C# version in Visual Studio - -In Visual Studio, the option to change the language version through the UI might be disabled because the default version is aligned with the project's target framework (`TFM`). This default configuration ensures compatibility between language features and runtime support. - -For example, changing the target `TFM` (for example, from [.NET 6](https://dotnet.microsoft.com/en-us/download/dotnet/6.0) to [.NET 9](https://dotnet.microsoft.com/en-us/download/dotnet/9.0)) will update the language version accordingly, from C# 10 to C# 13. This approach prevents issues with runtime compatibility and minimizes unexpected build errors due to unsupported language features. - -If you need a specific language version that differs from the one automatically selected, refer to the methods below to override the default settings directly in the project file. +> To know what language version you're currently using, put `#error version` (case sensitive) in your code. This makes the compiler report a compiler error, CS8304, with a message containing the compiler version being used and the current selected language version. For more information about this pragma, see [#error (C# Reference)](preprocessor-directives.md#error-and-warning-information). ## Edit the project file @@ -44,7 +44,7 @@ The value `preview` uses the latest available preview C# language version that y ## Configure multiple projects -To configure multiple projects, you can create a *Directory.Build.props* file, typically in your solution directory, that contains the `` element. Add the following setting to the *Directory.Build.props* file: +To configure multiple C# projects, you can create a *Directory.Build.props* file, typically in your solution directory, that contains the `` element. Add the following setting to the *Directory.Build.props* file: ```xml @@ -56,6 +56,10 @@ To configure multiple projects, you can create a *Directory.Build.props* file, t Builds in all subdirectories of the directory containing that file now use the preview C# version. For more information, see [Customize your build](/visualstudio/msbuild/customize-your-build). +> [!NOTE] +> +> The versions for C# and VB are different. Don't use the *Directory.Build.Props* file for a folder where subdirectories contain projects for both languages. The versions won't match. + ## C# language version reference > [!IMPORTANT] diff --git a/docs/csharp/whats-new/csharp-version-history.md b/docs/csharp/whats-new/csharp-version-history.md index 193815804c5df..0aaea5b91b759 100644 --- a/docs/csharp/whats-new/csharp-version-history.md +++ b/docs/csharp/whats-new/csharp-version-history.md @@ -2,17 +2,36 @@ title: The history of C# description: Learn how the C# language has changed over its many releases. Learn when different features were introduced in the language. author: erikdietrich -ms.date: 11/22/2024 +ms.date: 12/20/2024 ms.custom: "updateeachrelease, UpdateFrequency1" --- # The history of C\# -This article provides a history of each major release of the C# language. The C# team is continuing to innovate and add new features. Detailed language feature status, including features considered for upcoming releases can be found [on the dotnet/roslyn repository](https://github.com/dotnet/roslyn/blob/main/docs/Language%20Feature%20Status.md) on GitHub. +This article provides a history of each major release of the C# language. The C# team is continuing to innovate and add new features. Detailed language feature status, including features considered for upcoming releases can be found [on the dotnet/roslyn repository](https://github.com/dotnet/roslyn/blob/main/docs/Language%20Feature%20Status.md) on GitHub. To find when a particular feature was added to the language, consult the [C# version history](https://github.com/dotnet/csharplang/blob/main/Language-Version-History.md) file in the [`dotnet/csharplang`](https://github.com/dotnet/csharplang) repository on GitHub. > [!IMPORTANT] > The C# language relies on types and methods in what the C# specification defines as a *standard library* for some of the features. The .NET platform delivers those types and methods in a number of packages. One example is exception processing. Every `throw` statement or expression is checked to ensure the object being thrown is derived from . Similarly, every `catch` is checked to ensure that the type being caught is derived from . Each version may add new requirements. To use the latest language features in older environments, you may need to install specific libraries. These dependencies are documented in the page for each specific version. You can learn more about the [relationships between language and library](relationships-between-language-and-library.md) for background on this dependency. +## C# version 13 + +*Released November 2024* + +C# 13 includes the following new features: + +- `params` collections: he `params` modifier isn't limited to array types. You can now use `params` with any recognized collection type, including `Span`, and interface types. +- New `lock` type and semantics: If the target of a `lock` statement is a , compiler generates code to use the method to enter an exclusive scope. The `ref struct` returned from that supports the `Dispose()` pattern to exit the exclusive scope. +- New escape sequence - `\e`: You can use `\e` as a character literal escape sequence for the `ESCAPE` character, Unicode `U+001B`. +- Small optimizations to overload resolution involving method groups. +- Implicit indexer access in object initializers: The implicit "from the end" index operator, `^`, is now allowed in an object initializer expression. +- You can use `ref` locals and `unsafe` contexts in iterators and async methods. +- You can use `ref struct` types to implement interfaces. +- You can allow `ref struct` types as arguments for type parameters in generics. +- Partial properties and indexers are now allowed in `partial` types. +- Overload resolution priority allows library authors to designate one overload as better than others. + +And, the `field` contextual keyword to access the compiler generated backing field in an automatically implemented property was released as a preview feature. + ## C# version 12 *Released November 2023*