diff --git a/.vale.ini b/.vale.ini index 46c368d0f..a5338f5bf 100644 --- a/.vale.ini +++ b/.vale.ini @@ -19,6 +19,7 @@ Microsoft.Accessibility = NO Microsoft.Passive = NO Microsoft.Suspended = NO Microsoft.Vocab = NO +Microsoft.Spacing = NO Microsoft.Semicolon = NO # Mostly just picks up code Microsoft.SentenceLength = NO # Mostly just picks up code Microsoft.Dashes = NO diff --git a/.vale/styles/FernStyles/Acronyms.yml b/.vale/styles/FernStyles/Acronyms.yml index 093d745cc..8fab0bc23 100644 --- a/.vale/styles/FernStyles/Acronyms.yml +++ b/.vale/styles/FernStyles/Acronyms.yml @@ -65,6 +65,10 @@ exceptions: - XSS - YAML - ZIP + - SEO + - TLS + - BCL + - LLM - MDX - SEO - AWS diff --git a/.vale/styles/FernStyles/Headings.yml b/.vale/styles/FernStyles/Headings.yml index 6cf6d35cf..9b8d270d2 100644 --- a/.vale/styles/FernStyles/Headings.yml +++ b/.vale/styles/FernStyles/Headings.yml @@ -27,6 +27,10 @@ exceptions: - Support - Markdown - Docs + - Mono + - Unity + - SDK + - SDKs - API Reference - API Explorer - GitHub diff --git a/fern/products/sdks/overview/csharp/version-compatibility.mdx b/fern/products/sdks/overview/csharp/version-compatibility.mdx new file mode 100644 index 000000000..97aa0fa95 --- /dev/null +++ b/fern/products/sdks/overview/csharp/version-compatibility.mdx @@ -0,0 +1,227 @@ +--- +title: .NET compatibility +description: Learn about supported .NET Framework versions (net462, net472, net48) and Unity compatibility for Fern-generated SDKs. +--- + +Fern-generated .NET SDKs support modern .NET versions, .NET Framework versions, and Unity. + +Because these SDKs are built with modern C# features, you'll need the following even when targeting older .NET Framework targets: +- A modern compiler (Visual Studio 2022 or .NET SDK) +- The appropriate .NET Framework Developer Pack or reference assemblies + +## Supported frameworks + +Fern .NET SDKs support [all officially supported .NET versions](https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-framework), except for net35. + +| Framework | Target Framework Moniker (TFM) | +|--------|----------| +| .NET 9 | net9.0 | +| .NET 8 | net8.0 | +| .NET Framework 4.8.1 | net481 | +| .NET Framework 4.8 | net48 | +| .NET Framework 4.7.2 | net472 | +| .NET Framework 4.7.1 | net471 | +| .NET Framework 4.7 | net47 | +| .NET Framework 4.6.2 | net462 | + + + The C# language version is determined by your compiler, while the target framework determines which runtime and base class library APIs are available. Fern SDKs use modern C# features but compile to older framework versions. + + + + +All major IDEs support Fern-generated SDKs when targeting `net462`, `net472`, and `net48` versions: + +- **Visual Studio 2022** (recommended) - Works out of the box. Set `` in your project and install the appropriate [developer pack](#developer-packs). +- **Visual Studio 2019** - Supports C# 9 natively. For newer C# versions, add the `Microsoft.Net.Compilers.Toolset` package. +- **Rider** - Uses Roslyn. Set `` and ensure reference assemblies are available. +- **VS Code** - Works via OmniSharp and .NET SDK builds. +- **Unity** - Uses Unity's own C# compiler. See [Using SDKs with Unity](#using-sdks-with-unity). + + +You can "bring your own compiler" with the `Microsoft.Net.Compilers.Toolset` package on any environment. + + + + +Use the **Roslyn compiler** (`csc`) that comes with Visual Studio 2022+ or the .NET SDK. Set your C# version via `` to `latest`, `preview`, or a specific version (minimum `9`). + +Fern's .NET SDK doesn't support the legacy Mono compiler (`mcs`, `gmcs`) or the pre-Roslyn `csc.exe` compiler. Use Roslyn even when building on Mono. + + + +Use the .NET SDK (`dotnet`) with the `Microsoft.NETFramework.ReferenceAssemblies` package to supply `net48` references on non-Windows. Use Roslyn via `dotnet build` or Mono's MSBuild. + +```bash title="macOS/Linux" +dotnet build -c Release +``` + + + + +- [.NET Framework 4.6.2 Developer Pack](https://dotnet.microsoft.com/en-us/download/dotnet-framework/net462) +- [.NET Framework 4.7.2 Developer Pack](https://dotnet.microsoft.com/en-us/download/dotnet-framework/net472) +- [.NET Framework 4.8 Developer Pack](https://dotnet.microsoft.com/en-us/download/dotnet-framework/net48) + + + +## Using SDKs with Unity + +Unity controls its own C# compiler and .NET profile, which affects how you use Fern's .NET SDK. + + + +Unity compiles projects using Roslyn, typically supporting C# 9 (varies by Unity version). You can't force Unity to use a newer C# compiler by changing your package because Unity controls the compiler inside the Editor. + + +Configure this in Unity: `Edit → Project Settings → Player → Other Settings → Api Compatibility Level` + +- **.NET Standard 2.1** (recommended for cross-platform plugins) +- **.NET Framework 4.x** (Unity's "4.x equivalent" profile) + + + + +Unity doesn't support NuGet packages, so you must manually download and add these assemblies to your Unity project: + +| Assembly | NuGet Package | +|----------|---------------| +| Microsoft.Bcl.AsyncInterfaces | [10.0.0-preview.6.25358.103](https://www.nuget.org/packages/Microsoft.Bcl.AsyncInterfaces/10.0.0-preview.6.25358.103) | +| OneOf | [3.0.271](https://www.nuget.org/packages/OneOf/3.0.271) | +| OneOf.Extended | [3.0.271](https://www.nuget.org/packages/OneOf.Extended/3.0.271) | +| System.Buffers | [4.6.1](https://www.nuget.org/packages/System.Buffers/4.6.1) | +| System.IO.Pipelines | [10.0.0-preview.6.25358.103](https://www.nuget.org/packages/System.IO.Pipelines/10.0.0-preview.6.25358.103) | +| System.Memory | [4.6.3](https://www.nuget.org/packages/System.Memory/4.6.3) | +| System.Runtime.CompilerServices.Unsafe | [6.1.2](https://www.nuget.org/packages/System.Runtime.CompilerServices.Unsafe/6.1.2) | +| System.Text.Encodings.Web | [10.0.0-preview.6.25358.103](https://www.nuget.org/packages/System.Text.Encodings.Web/10.0.0-preview.6.25358.103) | +| System.Text.Json | [10.0.0-preview.6.25358.103](https://www.nuget.org/packages/System.Text.Json/10.0.0-preview.6.25358.103) | +| System.Threading.Tasks.Extensions | [4.6.3](https://www.nuget.org/packages/System.Threading.Tasks.Extensions/4.6.3) | +| portable.system.datetimeonly | [9.0.0](https://www.nuget.org/packages/portable.system.datetimeonly/9.0.0) | + + + + +## Project configuration examples + +Use SDK-style projects where possible, as they provide modern compilers and simpler multi-targeting. If you have a classic project format, consider converting to SDK-style. The [legacy projects section](#legacy-projects) covers legacy setups that can't be converted. + + + When building for `net48` on macOS/Linux, you won't have the Windows targeting packs. Add the reference assemblies package: + + ```xml title="YourProject.csproj" + + + + ``` + This provides the `net48` reference assemblies so Roslyn can compile for `net48` on any platform. You'll still need Mono or Wine to execute the result. + + + + + +Targeting `net48` with modern C# + + + + + + Install the [.NET Framework 4.8 Developer Pack](#developer-packs) so the `net48` reference assemblies are available to the compiler. + + +```xml title="YourProject.csproj" + + + + net48 + + + latest + + + enable + + +``` + + + +```bash +dotnet build -c Release +``` + + + +To support multiple frameworks, use ``: +{/* */} +```xml title="YourProject.csproj" +net48;net8.0 +``` +{/* */} + + + + + +For older MSBuild/Visual Studio versions, Visual Studio 2019, or legacy `packages.config` setups, add a modern Roslyn toolset and target the old framework. + + + + Install the appropriate [.NET Framework Developer Pack](#developer-packs) so Visual Studio can find the reference assemblies. + + + + ```xml title="YourProject.csproj" + + + latest + + ``` + Or use a specific version: `9`, `10`, `11`, `12`, or `preview`. + + + + ```xml title="YourProject.csproj" + + + + all + + + ``` + This ensures your build uses a modern `csc.exe` even if your IDE/MSBuild is older. + + + + + + +## Troubleshooting + + + + Add a small shim in your project or reference a helper package. + + + - Windows: install the [.NET Framework 4.8 Developer Pack](#developer-packs). + - Cross-platform/CI: add `Microsoft.NETFramework.ReferenceAssemblies` to the project (as `PrivateAssets=all`). + + + Add `Microsoft.Net.Compilers.Toolset` to the project, or move to VS 2022+. + + +This error occurs when using the `required` keyword with older Visual Studio versions. Follow the instructions at [Legacy projects](#legacy-projects) to add a modern compiler. + + + Some versions of Visual Studio may show this error in the IDE but compile the project successfully when using the package-provided compiler. + + + + + + + + + + + + diff --git a/fern/products/sdks/sdks.yml b/fern/products/sdks/sdks.yml index c11297654..ac3c9b610 100644 --- a/fern/products/sdks/sdks.yml +++ b/fern/products/sdks/sdks.yml @@ -130,6 +130,8 @@ navigation: - page: Publishing to NuGet path: ./overview/csharp/publishing-to-nuget.mdx slug: publishing + - page: Version compatibility + path: ./overview/csharp/version-compatibility.mdx - page: Adding custom code hidden: true path: ./overview/csharp/custom-code.mdx