In a C# project file, how do the LangVersion values default, latest, latestMajor, preview and a number differ, and when does the build reject one?
answer
- default is not the framework default
- keywords float with the installed SDK
- preview and EnablePreviewFeatures
- CS1617 and CS8303
basics
~20 sA number pins the language. default, latest and latestMajor all mean the compiler's newest release (C# 14 in the .NET 10 SDK), whatever the target framework; preview adds unreleased features. An unknown value fails with CS1617.
solid answer
~50 sThe SDK only fills `LangVersion` from the target framework when the property is empty. Any value you set goes straight to the compiler. A number such as `12` pins the language. `latestMajor` and `default` mean the newest major version this compiler knows, and `latest` the newest release including minor ones; on the .NET 10 SDK all three are C# 14, so `<LangVersion>default</LangVersion>` in a `netstandard2.0` project compiles as C# 14, not 7.3. `preview` also turns on features of the next, unreleased version. The keywords move whenever someone builds with a newer SDK, so builds stop being reproducible. Setting `EnablePreviewFeatures` to `true` on the newest target framework makes the SDK set `LangVersion` to `Preview`, over the project file's own value. The build rejects a value the compiler does not know with CS1617 (for example `15` on this SDK) and leading zeroes with CS8303.
code
xml · 7 lines<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>netstandard2.0</TargetFramework>
<!-- not the framework default: the compiler reads this as its newest major version -->
<LangVersion>default</LangVersion>
</PropertyGroup>
</Project>go deeper
Know that a number pins the C# version and that the keywords follow whatever SDK runs the build.
Explain that the SDK fills LangVersion only when it is empty, so default, latest and latestMajor all mean the compiler's newest version, and name CS1617 for an unknown value.
Spot the default trap on old targets, explain EnablePreviewFeatures overriding LangVersion, and tell language preview features apart from preview runtime APIs.
Make pinned numbers the policy wherever LangVersion is set, so an SDK upgrade never changes the language a project compiles with by itself.
## Where LangVersion comes from `LangVersion` is an MSBuild property that the SDK passes to the C# compiler as `-langversion`. The SDK's `Microsoft.CSharp.Core.targets` assigns the framework's default **only when the property is empty**. Whatever a project, a `Directory.Build.props` or a command-line `-p:LangVersion=` sets is passed through unchanged, and the compiler interprets it. ## The values | Value | Meaning on the .NET 10.0.401 SDK | |---|---| | a number (`7.3`, `10`, `12`, `14.0`) | exactly that version's rules | | `latestMajor` | the newest major version the compiler knows: C# 14 | | `default` | the same as `latestMajor`: C# 14 | | `latest` | the newest released version, minor versions included: C# 14 | | `preview` | C# 14 plus features of the next version that are in preview | The compiler's `LanguageVersionFacts` maps `Latest`, `Default` and `LatestMajor` to `CSharp14` in this compiler. Numbers accept both `12` and `12.0`. ## The `default` trap The word suggests 'whatever the framework would pick'. It does not mean that. In a `netstandard2.0` library with `<LangVersion>default</LangVersion>`, the SDK leaves the value alone, and the compiler treats it as its newest major version. Building with `#error version` prints *Language version: default (14.0)*. The keywords `latest` and `latestMajor` behave the same way. The project now accepts C# 14 syntax on a target whose supported default is C# 7.3, which is exactly the unsupported combination the docs warn about. To get the framework default, delete the element. ## Why the keywords hurt reproducibility `latest`, `latestMajor` and `default` resolve on the machine that builds. A developer on an older SDK and a CI agent on a newer one compile the same project with different C# versions; code that builds in CI may not build locally, and a newer SDK can introduce the language's breaking changes without anyone editing the project. The C# docs explicitly advise against `latest` for this reason, and because it can enable features the target's libraries or runtime do not support. A pinned number changes only when someone edits it. ## Preview: two switches There are two separate preview opt-ins: - **`LangVersion` `preview`** turns on unreleased **language** features. Using one without it fails with **CS8652**, *The feature '...' is currently in Preview and \*unsupported\*. To use Preview features, use the 'preview' language version.* - **`EnablePreviewFeatures`** is about **preview runtime APIs** marked `[RequiresPreviewFeatures]`. When it is `true`, the SDK adds `[assembly: RequiresPreviewFeatures]` to the assembly, and the CA2252 analyzer requires consumers to opt in too. On a project that targets the newest framework, the SDK's common targets also set `LangVersion` to `Preview`, overriding a number set in the project file. The second point surprises teams: a project with `<LangVersion>12</LangVersion>` and `<EnablePreviewFeatures>true</EnablePreviewFeatures>` on `net10.0` evaluates `LangVersion` as `Preview`. ## When the build rejects a value 1. **CS1617** *Invalid option '15' for /langversion. Use '/langversion:?' to list supported values.* The compiler does not know the value. The docs table already lists `15.0`, because C# 15 is in preview for .NET 11, but the .NET 10.0.401 SDK's compiler stops at 14. 2. **CS8303** *Specified language version '012' cannot have leading zeroes.* 3. **CS8304** is not a rejection: it is the error `#error version` produces to report the versions. A newer target framework does not raise the cap either: evaluated for `net11.0`, this SDK's targets still compute `MaxSupportedLangVersion` 14.0, because they cap the default at the compiler's newest version. ## Where the value comes from wins The property can be set in the project file, in a `Directory.Build.props` that covers many projects, or on the command line. A value passed as `-p:LangVersion=12` is an MSBuild global property, which project files and targets cannot overwrite; evaluated on this SDK it stays 12 even with `EnablePreviewFeatures` set to `true`. That makes command-line overrides handy for experiments and confusing in CI scripts, where a forgotten switch silently beats the project file. ## Practical rules - Leave `LangVersion` unset on projects that can use the framework default. - When a project needs another value, set a **number**, never `default`, `latest` or `latestMajor`. - Use `preview` only in experiments, and know that `EnablePreviewFeatures` implies it on the newest framework.
- Why do the C# docs advise against LangVersion latest?`latest` resolves to the newest version of whichever compiler runs the build, so two machines with different SDKs compile the same project with different language rules. Builds become unreliable, a newer SDK can bring source-breaking changes without a project edit, and the setting can enable features that the target framework's libraries or runtime do not support.
- A net10.0 project sets LangVersion 12 and EnablePreviewFeatures true. Which C# version compiles it?Preview. The SDK's common targets set `LangVersion` to `Preview` when `EnablePreviewFeatures` is `true` and the project targets the newest framework, and that assignment comes after the project file's own value. The assembly also gets `[assembly: RequiresPreviewFeatures]`, so consumers hit CA2252 unless they opt in too.
- LangVersion default means the target framework's default version
- latest is safe because it always matches the SDK in CI
- LangVersion preview is what opts a project in to RequiresPreviewFeatures APIs
- A newer TargetFramework raises the cap past the compiler's newest version
- CS8304 means the LangVersion value is invalid
Assumes the .NET 10.0.401 SDK, whose compiler maps default, latest and latestMajor to C# 14 and rejects 15.