What are runtime identifiers (RIDs), and when do you need to set one in a .NET project?

1. Anatomy of a RID

   linux - musl - arm64
     |      |       |
     |      |       +-- architecture: x64, x86, arm64, arm
     |      +---------- C library (Linux only): omitted = glibc, musl = Alpine and similar
     +----------------- operating system: win, linux, osx, (ios, android, browser ...)

These are portable RIDs. Since .NET 8 they are the only ones the SDK and runtime understand by default.

2. What changes when you set a RID

 PackageReference (with runtimes/* assets)
          |
       restore  -- RuntimeIdentifiers=linux-x64;win-x64
          |         --> RID-specific assets recorded in obj/project.assets.json
          |         --> runtime packs downloaded if self-contained
          |
       build    -- RuntimeIdentifier=linux-x64
          |         --> bin/Release/net10.0/linux-x64/
          |         --> apphost for Linux, linux-x64 native files only
          |
       publish  -- --self-contained --> + the .NET runtime for linux-x64
                -- PublishSingleFile --> one executable for linux-x64
                -- PublishAot        --> native executable for linux-x64

 portable (no RID):
     bin/Release/net10.0/
        App.dll, App.deps.json, App.runtimeconfig.json
        App / App.exe          <- apphost for the build machine's OS
        runtimes/win-x64/native/...
        runtimes/linux-x64/native/...
        runtimes/osx-arm64/native/...
     the host reads App.deps.json at start-up and loads the matching folder

3. When you need a RID

Instead of -r, you can pass --os linux --arch arm64 and the SDK builds the RID for you. --arch alone uses the current OS.

4. RuntimeIdentifier versus RuntimeIdentifiers

Publishing with --no-restore for a RID that wasn't restored fails with NETSDK1047, which asks you to add the RID to RuntimeIdentifiers.

5. Native assets in packages

Packages with native code (SQLite, SkiaSharp, gRPC, some compression and crypto libraries) ship one folder per platform:

runtimes/
  win-x64/native/e_sqlite3.dll
  linux-x64/native/libe_sqlite3.so
  linux-musl-x64/native/libe_sqlite3.so
  linux-arm64/native/libe_sqlite3.so
  osx-arm64/native/libe_sqlite3.dylib

• A portable app copies all of them, and the host picks one at start-up.
• A RID-specific app copies only the match, falling back along the portable graph (for example linux-musl-x64 falls back to linux-x64, then linux, then unix, then any).
• If no folder matches, the app starts but fails when it first calls the native library, with DllNotFoundException or a "cannot open shared object file" error.

6. The .NET 8 RID changes (still true in .NET 10)

1. Portable RID graph only. The old graph had distro- and version-specific RIDs (ubuntu.22.04-x64, rhel.8-x64, alpine.3.18-x64). The SDK now reports NETSDK1083 for them. <UseRidGraph>true</UseRidGraph> restores the old graph as a temporary workaround, mainly for old packages that only ship distro-specific assets. Move to packages with portable assets and remove the workaround.
2. -r no longer implies self-contained. Before .NET 8, dotnet publish -r linux-x64 produced a self-contained app; now it's framework-dependent unless you add --self-contained.
3. RuntimeInformation.RuntimeIdentifier returns the portable RID (linux-x64), not the distro RID, which is the right value to log.

7. Cross-building

For AOT and multi-platform releases, CI usually runs a matrix of agents (Windows, Linux x64, Linux arm64, macOS).

8. RIDs and containers

When you build the image with a Dockerfile on an Apple silicon Mac or an arm64 agent, the default platform is arm64. Use --platform linux/amd64 (or build for both) if production runs on x64.

9. Diagnosing RID problems

Log RuntimeInformation.RuntimeIdentifier, RuntimeInformation.OSArchitecture and RuntimeInformation.OSDescription at start-up so every native load failure comes with the platform in the log.

10. Performance, cost and security

• Self-contained and AOT outputs pin a runtime version. You must republish for every .NET security patch; framework-dependent apps pick up patches when the host or base image is updated.
• Arm64 VMs and containers are often cheaper per unit of compute in Azure and AWS. A linux-arm64 build plus a performance test can be an easy saving.
• RID-specific output removes other platforms' native binaries, which shrinks images and reduces what a vulnerability scanner reports.

11. .NET 11 awareness

The portable RID model is stable. Watch the .NET 11 release notes for changes to supported OS versions and architectures, and for any new RIDs, before relying on them. Keep production builds on .NET 10 until you've tested the upgrade.

12. Try it yourself

1. Create a console app, run dotnet publish -o out/portable, and list out/portable (no RID folder).
2. Add Microsoft.Data.Sqlite, publish again and look inside out/portable/runtimes/.
3. Run dotnet publish -r linux-x64 -o out/linux and compare: only the Linux native file remains.
4. Run dotnet publish -r ubuntu.22.04-x64 and read NETSDK1083.
5. Run dotnet publish -r linux-musl-x64 --self-contained -o out/alpine and compare its size with step 3.
6. Add <RuntimeIdentifiers>linux-x64;win-x64</RuntimeIdentifiers>, restore once, then publish both with --no-restore.
7. Print RuntimeInformation.RuntimeIdentifier in the app and run it on your machine and in an Alpine container.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <!--
      RuntimeIdentifiers (plural) only tells restore to prepare assets for these platforms.
      Normal builds stay portable; we pick a platform at publish time with -r.
      Using RuntimeIdentifier (singular) here would make every local build linux-specific.
    -->
    <RuntimeIdentifiers>linux-x64;linux-musl-x64</RuntimeIdentifiers>
  </PropertyGroup>
</Project>

# Restore once for both platforms
dotnet restore

# Debian/Ubuntu-based image (glibc)
dotnet publish -c Release -r linux-x64 --self-contained --no-restore -o out/linux-x64

# Alpine-based image (musl): a different RID because native libraries differ
dotnet publish -c Release -r linux-musl-x64 --self-contained --no-restore -o out/linux-musl-x64

// Log the platform at start-up: invaluable when a native load fails
using System.Runtime.InteropServices;

Console.WriteLine($"RID {RuntimeInformation.RuntimeIdentifier}, OS {RuntimeInformation.OSDescription}");