Catálogo de RIDs do .NET

Artigo
11/16/2024

RID é a abreviação de identificador de runtime. Os valores do RID são usados para identificar plataformas de destino onde o aplicativo é executado. Eles são usados por pacotes .NET para representar ativos específicos de plataforma em pacotes NuGet. Os seguintes valores são exemplos de RIDs: linux-x64, win-x64 ou osx-x64. Para os pacotes com dependências nativas, o RID designará as plataformas em que o pacote pode ser restaurado.

Um único RID pode ser definido no elemento <RuntimeIdentifier> do arquivo de projeto. Vários RIDs podem ser definidos como uma lista separada por ponto-e-vírgula no elemento <RuntimeIdentifiers> do arquivo de projeto. Eles também são usados por meio da opção --runtime com os seguintes comandos da CLI do .NET:

RIDs que representem sistemas operacionais concretos geralmente seguem este padrão: [os].[version]-[architecture]-[additional qualifiers] em que:

[os] é o moniker do sistema operacional/plataforma. Por exemplo, ubuntu.
[version] é a versão do sistema operacional na forma de um separado de versão separado por ponto (.). Por exemplo, 15.10.

A versão não deve ser uma versão de marketing, pois esse tipo de versão geralmente representam várias versões distintas do sistema operacional com diferentes áreas de superfície de API da plataforma.
[architecture] é a arquitetura do processador. Por exemplo: x86, x64, arm ou arm64.
[additional qualifiers] distingue diferentes plataformas. Por exemplo: aot.

Gráfico RID

O gráfico RID ou gráfico de fallback de runtime é uma lista de RIDs que são compatíveis entre si.

Esses RIDs são definidos em PortableRuntimeIdentifierGraph.json no repositório dotnet/runtime. Nesse arquivo, você pode ver todos os RIDs, exceto para a base um, que contém uma instrução "#import". Essas instruções indicam RIDs compatíveis.

Antes do .NET 8, os RIDs específicos da versão e da distribuição eram adicionados regularmente ao arquivo runtime.json, que está localizado no repositório dotnet/runtime. Esse grafo não é mais atualizado e existe como uma opção de compatibilidade com versões anteriores. Os desenvolvedores devem usar RIDs que são não específicas à versão e não específicas à distribuição.

Quando o NuGet restaura pacotes, ele tenta encontrar uma correspondência exata para o runtime especificado. Se uma correspondência exata não for encontrada, o NuGet voltará ao gráfico até encontrar o sistema compatível mais próximo de acordo com o gráfico RID.

O exemplo a seguir é a entrada real para o RID osx-x64:

"osx-x64": {
    "#import": [ "osx", "unix-x64" ]
}

O RID acima especifica que osx-x64 importa unix-x64. Desse modo, quando o NuGet restaura pacotes, ele tenta encontrar uma correspondência exata para osx-x64 no pacote. Se o NuGet não conseguir encontrar o runtime específico, ele poderá restaurar pacotes que especificam runtimes unix-x64, por exemplo.

O seguinte exemplo mostra um gráfico RID ligeiramente maior, também definido no arquivo runtime.json:

    linux-arm64     linux-arm32
         |     \   /     |
         |     linux     |
         |       |       |
    unix-arm64   |    unix-x64
             \   |   /
               unix
                 |
                any

Como alternativa, você pode usar a ferramenta RidGraph para visualizar facilmente o grafo RID (ou qualquer subconjunto do grafo).

Todos os RIDs eventualmente mapeiam para a raiz de any RID.

Há algumas considerações sobre RIDs das quais você precisa se lembrar ao trabalhar com eles:

Não tente analisar RIDs para recuperar partes do componente.
Use RIDs que já estão definidos para a plataforma.
Os RIDs precisam ser específicos, portanto, não presuma nada usando o valor RID real.
Não crie RIDs programaticamente, a menos que seja absolutamente necessário.

Alguns aplicativos precisam calcular RIDs programaticamente. Nesse caso, os RIDs computados devem corresponder exatamente ao catálogo, inclusive no uso de maiúsculas e minúsculas. RIDs com maiúsculas e minúsculas diferentes causariam problemas quando o sistema operacional diferencia maiúsculas de minúsculas, por exemplo, Linux, porque o valor geralmente é usado ao construir itens como caminhos de saída. Por exemplo, considere um assistente de publicação personalizado no Visual Studio que depende de informações do gerenciador de configurações da solução e das propriedades do projeto. Se a configuração da solução passar um valor inválido, por exemplo, ARM64 em vez de arm64, poderá resultar em um RID inválido, como win-ARM64.

Usando RIDs

Para poder usar RIDs, você precisa saber quais RIDs existem. Para obter a versão completa e mais recente, confira o arquivo PortableRuntimeIdentifierGraph.json no repositório dotnet/runtime.

OS RIDs considerados "portáteis", ou seja, não estão vinculados a uma versão específica ou à distribuição do sistema operacional, são a opção recomendada. Isso significa que OS RIDs portáteis devem ser usados para criar um aplicativo específico da plataforma e criar um pacote NuGet com ativos específicos do RID.

A partir do .NET 8, o comportamento padrão do SDK do .NET e do runtime é considerar apenas RIDs não específicos à versão e não específicos à distribuição. Ao restaurar e compilar, o SDK usa um grafo RID portátil menor. O RuntimeInformation.RuntimeIdentifier retorna a plataforma para a qual o tempo de execução foi criado. Em tempo de execução, o .NET localiza ativos específicos do RID usando um conjunto conhecido de RIDs portáteis. Ao criar um aplicativo com ativos específicos de RID que podem ser ignorados em runtime, o SDK emitirá um aviso: NETSDK1206.

Carregando ativos para uma versão ou distribuição específica do sistema operacional

O .NET não tenta mais fornecer suporte de primeira classe para resolver dependências específicas de uma versão ou distribuição do sistema operacional. Se seu aplicativo ou pacote precisar carregar ativos diferentes com base na versão ou distribuição do sistema operacional, ele deverá implementar a lógica para carregar condicionalmente ativos.

Para obter informações sobre a plataforma, use System.OperatingSystem APIs. No Windows e no macOS, Environment.OSVersion retornará a versão do sistema operacional. No Linux, pode ser a versão do kernel, para obter o nome de distribuição do Linux e as informações de versão, a abordagem recomendada é ler o arquivo /etc/os-release.

O .NET fornece vários pontos de extensão para personalizar a lógica de carregamento, por exemplo NativeLibrary.SetDllImportResolver(Assembly, DllImportResolver), AssemblyLoadContext.ResolvingUnmanagedDll, AssemblyLoadContext.Resolving e AppDomain.AssemblyResolve. Eles podem ser usados para carregar o ativo correspondente à plataforma atual.

RIDs conhecidas

A lista a seguir mostra um pequeno subconjunto dos RIDs mais comuns usados para cada SO. Para obter a versão completa e mais recente, confira o arquivo PortableRuntimeIdentifierGraph.json no repositório dotnet/runtime.

RIDs do Windows

win-x64
win-x86
win-arm64

Para obter mais informações, consulte Instalar o .NET no Windows.

RIDs do Linux

linux-x64 (A maioria das distribuições de desktop como CentOS Stream, Debian, Fedora, Ubuntu e derivados)
linux-musl-x64 (Distribuições leves usando musl, como o Alpine Linux)
linux-musl-arm64 (Usado para criar imagens do Docker para Arm v8 de 64 bits e imagens base minimalistas)
linux-arm (Distribuições Linux em execução em ARM, como Raspbian no Raspberry Pi modelo 2+)
linux-arm64 (Distribuições do Linux em execução no Arm de 64 bits, como Ubuntu Server de 64 bits no Raspberry Pi Model 3+)
linux-bionic-arm64 (Distribuições usando o libc biônico do Android, por exemplo, Termux)
linux-loongarch64 (Distribuições Linux rodando no LoongArch64)

Para obter mais informações, confira Dependências e os requisitos do .NET.

RIDs do macOS

Os RIDs do macOS usam a identidade visual “OSX” mais antiga.

osx-x64 (A versão mínima do sistema operacional é macOS 10.12 Sierra)
osx-arm64