Skip to content

Commit

Permalink
Fix C# reference TOC for offline book (dotnet#40794)
Browse files Browse the repository at this point in the history
  • Loading branch information
gewarren authored May 8, 2024
1 parent 6ae8f61 commit 9bcc9db
Show file tree
Hide file tree
Showing 8 changed files with 480 additions and 465 deletions.
8 changes: 4 additions & 4 deletions docs/core/tools/dotnet-new-sdk-templates.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ The templates that ship with the .NET SDK have the following additional options:

Sets the `LangVersion` property in the created project file. For example, use `--langVersion 7.3` to use C# 7.3. Not supported for F#. Available since .NET Core 2.2 SDK.

For a list of default C# versions, see [Defaults](../../csharp/language-reference/configure-language-version.md#defaults).
For a list of default C# versions, see [Defaults](../../csharp/language-reference/language-versioning.md#defaults).

- **`--no-restore`**

Expand All @@ -68,7 +68,7 @@ The templates that ship with the .NET SDK have the following additional options:

Sets the `LangVersion` property in the created project file. For example, use `--langVersion 7.3` to use C# 7.3. Not supported for F#. Available since .NET Core 2.2 SDK.

For a list of default C# versions, see [Defaults](../../csharp/language-reference/configure-language-version.md#defaults).
For a list of default C# versions, see [Defaults](../../csharp/language-reference/language-versioning.md#defaults).

- **`--no-restore`**

Expand All @@ -86,7 +86,7 @@ The templates that ship with the .NET SDK have the following additional options:

Sets the `LangVersion` property in the created project file. For example, use `--langVersion 7.3` to use C# 7.3.

For a list of default C# versions, see [Defaults](../../csharp/language-reference/configure-language-version.md#defaults).
For a list of default C# versions, see [Defaults](../../csharp/language-reference/language-versioning.md#defaults).

- **`--no-restore`**

Expand All @@ -100,7 +100,7 @@ The templates that ship with the .NET SDK have the following additional options:

Sets the `LangVersion` property in the created project file. For example, use `--langVersion 7.3` to use C# 7.3.

For a list of default C# versions, see [Defaults](../../csharp/language-reference/configure-language-version.md#defaults).
For a list of default C# versions, see [Defaults](../../csharp/language-reference/language-versioning.md#defaults).

- **`--no-restore`**

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ This option specifies the names of one or more symbols that you want to define.
## LangVersion

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](../configure-language-version.md#defaults).
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).

The **LangVersion** option causes the compiler to accept only syntax that is included in the specified C# language specification, for example:

Expand Down
40 changes: 6 additions & 34 deletions docs/csharp/language-reference/configure-language-version.md
Original file line number Diff line number Diff line change
@@ -1,34 +1,15 @@
---
title: C# language versioning - C# Guide
description: Learn about how the C# language version is determined based on your project and the reasons behind that choice. Learn how to override the default manually.
title: Configure C# language version - C# Guide
description: Learn how to override the default C# language version manually.
ms.custom: "updateeachrelease"
ms.date: 10/30/2023
---

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

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.

## Defaults

The compiler determines a default based on these rules:

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

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](#override-the-default) 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.
## Override the default
# Configure C# language version

If you must specify your C# version explicitly, you can do so in several ways:

- Manually edit your [project file](#edit-the-project-file).
- Manually edit the [project file](#edit-the-project-file).
- Set the language version [for multiple projects in a subdirectory](#configure-multiple-projects).
- Configure the [LangVersion compiler option](compiler-options/language.md#langversion).

Expand All @@ -37,7 +18,7 @@ If you must specify your C# version explicitly, you can do so in several ways:
>
> 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.
### Edit the project file
## Edit the project file

You can set the language version in your project file. For example, if you explicitly want access to preview features, add an element like this:

Expand All @@ -49,7 +30,7 @@ You can set the language version in your project file. For example, if you expli

The value `preview` uses the latest available preview C# language version that your compiler supports.

### Configure multiple projects
## Configure multiple projects

To configure multiple projects, you can create a *Directory.Build.props* file, typically in your solution directory, that contains the `<LangVersion>` element. Add the following setting to the *Directory.Build.props* file:

Expand All @@ -62,12 +43,3 @@ 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).

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

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

>[!NOTE]
>Specifying **LangVersion** with the `default` value is different from omitting the **LangVersion** option. Specifying `default` uses the latest version of the language that the compiler supports, without taking into account the target framework. For example, building a project that targets .NET 6 from the current version of Visual Studio 2022 uses C# 10 if **LangVersion** isn't specified, but uses C# 12 if **LangVersion** is set to `default`.
34 changes: 34 additions & 0 deletions docs/csharp/language-reference/language-versioning.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
title: C# language versioning - C# Guide
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: 10/30/2023
---

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

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.

## Defaults

The compiler determines a default based on these rules:

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

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.

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

>[!NOTE]
>Specifying **LangVersion** with the `default` value is different from omitting the **LangVersion** option. Specifying `default` uses the latest version of the language that the compiler supports, without taking into account the target framework. For example, building a project that targets .NET 6 from the current version of Visual Studio 2022 uses C# 10 if **LangVersion** isn't specified, but uses C# 12 if **LangVersion** is set to `default`.
Loading

0 comments on commit 9bcc9db

Please sign in to comment.