C# .NET: SDK, Runtime e CLR

O C# é a linguagem; o .NET é a plataforma que transforma o seu código em programa e o faz rodar. Quem procura "instalar C#" acaba instalando ".NET SDK", e nos tutoriais aparecem siglas como CLR, IL e JIT. Nesta aula você abre o .NET instalado no computador da Ana, vê o que tem dentro do arquivo que o compilador cria e assiste o .NET transformando o seu código em instruções do processador.

Todas as saídas desta aula vêm da máquina da Ana: Ubuntu 26.04 com o pacote dotnet-sdk-10.0 do próprio Ubuntu. Se você ainda não instalou o .NET, pode ler esta aula do mesmo jeito; a instalação vem logo depois, em Instalar no Linux.

A ideia: a receita em língua universal

Imagine uma rede de restaurantes com cozinhas no Brasil, no Japão e na Alemanha. A chef escreve as receitas em português, mas os cozinheiros de cada país falam línguas diferentes. Em vez de escrever três versões, a rede faz assim:

1. Um tradutor oficial passa a receita do português para uma língua universal da rede, simples e exata, que todo cozinheiro da rede aprendeu.
2. Em cada país, o cozinheiro lê a receita universal e, na hora de cozinhar, vai traduzindo cada passo para o jeito da cozinha dele, com os fogões e panelas que ele tem.
3. Os ingredientes básicos (farinha, sal, ovos) já estão na despensa de toda cozinha da rede: a receita só diz "use farinha", sem explicar como fazer farinha.

O .NET funciona exatamente assim:

A grande vantagem: o mesmo arquivo .dll roda no Linux, no Windows e no macOS, em processadores Intel, AMD ou ARM. Quem se adapta a cada computador é o CLR, não o seu programa.

SDK e Runtime: as duas caixas do .NET

O .NET vem em dois tamanhos, para dois tipos de pessoa:

Para seguir o guia, instale o SDK: ele já traz o Runtime junto. O comando dotnet mostra as duas coisas separadas:

$ dotnet --list-sdks                            « os SDKs instalados
10.0.112 [/usr/lib/dotnet/sdk]
$ dotnet --list-runtimes                        « os Runtimes instalados
Microsoft.AspNetCore.App 10.0.12 [/usr/lib/dotnet/shared/Microsoft.AspNetCore.App]
Microsoft.NETCore.App 10.0.12 [/usr/lib/dotnet/shared/Microsoft.NETCore.App]

10.0.112

A versão do SDK. Os dois primeiros números (10.0) dizem a versão do .NET. O terceiro (112) tem duas partes: o 1 é a "faixa" de recursos do SDK e o 12 é a 12.ª correção. A aula Versões do C# e do .NET explica a numeração.

Microsoft.NETCore.App 10.0.12

O Runtime básico, versão 10.0.12: tudo o que um programa de terminal precisa. É o que este guia usa.

Microsoft.AspNetCore.App 10.0.12

Um runtime extra, para sites e serviços na internet (ASP.NET Core). O SDK do Ubuntu o instala junto.

[/usr/lib/dotnet/…]

A pasta onde cada um está. No Ubuntu, o .NET mora em /usr/lib/dotnet.

Abrindo o .NET da Ana

Vamos olhar a pasta do .NET por dentro. O ls lista o que há nela, e o du -sh mostra o tamanho:

$ ls /usr/lib/dotnet
dnx
dotnet                                          « o comando dotnet
host
library-packs
LICENSE.txt
metadata
packs
sdk                                             « o SDK: compilador, MSBuild, comandos
sdk-manifests
shared                                          « os Runtimes
templates                                       « os modelos do dotnet new
ThirdPartyNotices.txt
$ du -sh /usr/lib/dotnet
545M	/usr/lib/dotnet
$ du -sh /usr/lib/dotnet/sdk; du -sh /usr/lib/dotnet/shared; du -sh /usr/lib/dotnet/packs
340M	/usr/lib/dotnet/sdk
96M	/usr/lib/dotnet/shared
98M	/usr/lib/dotnet/packs

O .NET inteiro ocupa 545 MB, e a maior parte (340 MB) é o SDK: as ferramentas de quem programa. Os Runtimes, que é o que um programa precisa para rodar, ficam em shared, com menos de 100 MB. A pasta packs guarda as "plantas" da biblioteca que o compilador consulta para saber quais classes existem.

O compilador e o MSBuild, dentro do SDK

$ ls /usr/lib/dotnet/sdk/10.0.112 | grep -i -E "^(MSBuild.dll|dotnet.dll|Roslyn)$"
dotnet.dll                                      « os comandos run, new, build…
MSBuild.dll                                     « o "mestre de obras" do build
Roslyn                                          « a pasta do compilador de C#
$ ls /usr/lib/dotnet/sdk/10.0.112/Roslyn/bincore | head
cs
csc                                             « csc = C Sharp Compiler
csc.deps.json
csc.dll
csc.runtimeconfig.json
de
es
fr
it
ja

O compilador de C# se chama csc (C Sharp Compiler), e o projeto que o criou se chama Roslyn. Repare num detalhe curioso: o csc.dll também é um programa .NET, escrito em C#. O compilador de C# é escrito em C#. As pastas cs, de, es, fr… guardam as mensagens de erro traduzidas (cs, aqui, é tcheco). É de uma pasta dessas, a pt-BR, que vêm as mensagens em português que você vê no terminal da Ana. Você nunca precisa chamar o csc diretamente: o dotnet run e o MSBuild fazem isso por você.

O Runtime e a biblioteca de classes

$ cd /usr/lib/dotnet/shared/Microsoft.NETCore.App/10.0.12
$ ls *.dll | wc -l
172                                             « 172 bibliotecas prontas
$ du -h System.Console.dll System.Private.CoreLib.dll libcoreclr.so libclrjit.so
184K	System.Console.dll                      « onde mora o Console
14M	System.Private.CoreLib.dll              « o coração da biblioteca: int, string, Math…
6,9M	libcoreclr.so                           « o CLR, o motor
3,2M	libclrjit.so                            « o JIT, o tradutor de última hora

Aqui está a "despensa" do restaurante: 172 arquivos .dll, cada um com uma parte da biblioteca de classes. Quando você escreve Console.WriteLine, o código do WriteLine vem do System.Console.dll; ele não fica dentro do seu programa. Os arquivos .so são programas do Linux de verdade, em código de máquina: o libcoreclr.so é o CLR e o libclrjit.so é o JIT.

Um programa consegue perguntar ao .NET quem ele é. Rode e compare com o terminal da Ana:

using System.Runtime.InteropServices;

Console.WriteLine($".NET: {RuntimeInformation.FrameworkDescription}");
Console.WriteLine($"Sistema: {RuntimeInformation.OSDescription}");
Console.WriteLine($"Processador: {RuntimeInformation.ProcessArchitecture}");
Console.WriteLine($"O Console vem de: {typeof(Console).Assembly.GetName().Name}");

$ dotnet run info.cs
.NET: .NET 10.0.12                              « o Runtime, não o SDK
Sistema: Ubuntu 26.04.1 LTS
Processador: X64                                « Intel/AMD de 64 bits
O Console vem de: System.Console                « o System.Console.dll da despensa

Não se preocupe com o using nem com o typeof: eles aparecem nas aulas Namespaces e using e Reflexão. O importante aqui é que o programa mostrou .NET 10.0.12, a versão do Runtime: quem roda o programa é o Runtime; o SDK só ajudou a construí-lo.

Do .cs ao programa: o caminho completo

Quando a Ana digita dotnet run ola.cs, acontecem estas etapas, nesta ordem:

1. O SDK prepara o build. O MSBuild descobre o que precisa ser compilado e com quais bibliotecas.
2. O Roslyn compila. Ele lê o ola.cs, confere tudo (tipos, nomes, ponto e vírgula) e, se não houver erro, escreve a IL num arquivo ola.dll. Se houver erro, para aqui, e nada roda.
3. O CLR carrega o programa. Ele abre o ola.dll e as bibliotecas que ele usa (como o System.Console.dll).
4. O JIT traduz. Na primeira vez que cada método é chamado, o JIT transforma a IL dele em instruções do processador (x64, no computador da Ana) e guarda o resultado na memória.
5. O processador executa essas instruções, e o texto aparece na tela.

O dotnet run esconde os arquivos que cria. O comando dotnet build faz só as etapas 1 e 2, e diz onde guardou o resultado:

$ dotnet build ola.cs
  Determinando os projetos a serem restaurados...
  Todos os projetos estão atualizados para restauração.
  ola -> /home/ana/.local/share/dotnet/runfile/ola-d3e0b993ea942ae2aa43a2c132f9667a87cb5c1410a99c454aae33ed39b33823/bin/debug/ola.dll

O ola.dll foi parar numa pasta escondida, dentro de ~/.local/share/dotnet/runfile, com um nome comprido (o nome do arquivo mais um código que identifica a pasta onde ele está). Vamos entrar nela:

$ cd ~/.local/share/dotnet/runfile/ola-*/bin/debug
$ ls -l
total 108
-rwxr-xr-x 1 ana ana 78904 out 17 12:37 ola                     « um "lançador" para Linux
-rw-rw-r-- 1 ana ana   381 out 17 12:37 ola.deps.json           « a lista de bibliotecas usadas
-rw-rw-r-- 1 ana ana  4608 out 17 12:37 ola.dll                 « o seu programa, em IL
-rw-rw-r-- 1 ana ana 10872 out 17 12:37 ola.pdb                 « informações para depurar
-rw-rw-r-- 1 ana ana  2000 out 17 12:37 ola.runtimeconfig.json  « qual Runtime usar

O comando file do Linux diz que tipo de arquivo cada um é:

$ file ola ola.dll
ola:     ELF 64-bit LSB pie executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 3.2.0, BuildID[sha1]=622d7093dbcd55b2ef4ff850254d90f54a4213c7, stripped
ola.dll: PE32 executable for MS Windows 4.00 (console), Intel i386 Mono/.Net assembly, 3 sections
$ head -c 2 ola.dll; echo
MZ                                              « a assinatura dos programas do Windows

O ola é um programa do Linux (ELF, para processador x86-64). Já o ola.dll o file chama de "executável do Windows", com a etiqueta Mono/.Net assembly: ele usa o mesmo formato de arquivo dos programas do Windows (que começam com as letras MZ, as iniciais de um engenheiro da Microsoft dos anos 1980), mas por dentro não tem instruções de processador nenhum, só IL. Por isso o mesmo ola.dll roda em qualquer sistema. Um arquivo assim, com IL e metadados, se chama assembly no mundo .NET.

Dá para rodar o programa pronto de dois jeitos, sem compilar de novo:

$ ./ola                                         « pelo lançador
Olá, mundo!
$ dotnet ola.dll                                « entregando o .dll direto ao dotnet
Olá, mundo!

Por dentro: a IL e o JIT

Vamos seguir um método pequeno do código-fonte até o processador. Este programa tem um método Somar, que soma dois números (os métodos têm aula própria, Métodos; por enquanto, leia Somar(2, 3) como "some 2 e 3"):

Console.WriteLine(Conta.Somar(2, 3));

static class Conta
{
    public static int Somar(int a, int b) => a + b;
}

$ dotnet run soma.cs
5

1. O que o Roslyn escreveu: a IL

Dentro do soma.dll, o método Somar virou só quatro bytes de IL: 02 03 58 2A (lidos com um programa de reflexão, assunto da aula Reflexão). Cada byte é uma instrução da "língua universal":

Repare que a IL não fala de nenhum processador: ela não sabe se vai rodar num Intel, num ARM do celular ou num Mac. É o "passo a passo universal" da receita.

2. O que o JIT fez: código de máquina

O .NET tem uma chave de diagnóstico, a variável DOTNET_JitDisasm, que pede ao JIT para mostrar o que ele gerou para um método. A Ana pediu o Somar (o -c Release pede a versão "de entrega", sem os extras de depuração, para a listagem ficar menor):

$ DOTNET_JitDisasm=Somar dotnet run soma.cs -c Release
; Assembly listing for method Conta:Somar(int,int):int (Tier0)
; Emitting BLENDED_CODE for generic X64 + VEX on Unix
; Tier0 code
; rbp based frame
; partially interruptible
; compiling with minopt

G_M000_IG01:                ;; offset=0x0000
       push     rbp
       sub      rsp, 16
       lea      rbp, [rsp+0x10]
       mov      dword ptr [rbp-0x04], edi       « guarda o a
       mov      dword ptr [rbp-0x08], esi       « guarda o b

G_M000_IG02:                ;; offset=0x0010
       mov      eax, dword ptr [rbp-0x04]       « pega o a
       add      eax, dword ptr [rbp-0x08]       « soma o b: aqui está o a + b

G_M000_IG03:                ;; offset=0x0016
       add      rsp, 16
       pop      rbp
       ret                                      « devolve o resultado

; Total bytes of code 28

5                                               « só agora o Somar roda e o resultado aparece

Isso é código de máquina x64 de verdade, escrito na forma legível (assembly): as instruções que o processador Intel/AMD da Ana executou. Os 4 bytes de IL viraram 28 bytes de instruções do processador. Você não precisa entender cada linha; repare só no add, que é o a + b do seu código, e em três detalhes da primeira parte:

• Tier0: "nível 0". Na primeira vez, o JIT traduz rápido, sem caprichar, para o programa começar logo. Se o método for chamado muitas vezes, o .NET o traduz de novo, agora caprichando (o "nível 1"). Isso se chama compilação em camadas.
• X64 e on Unix: o JIT gerou código para o processador e o sistema desta máquina. No Mac com chip M, a mesma IL viraria código ARM64.
• A listagem aparece antes do 5: o JIT traduz o Somar na primeira vez que ele é chamado, um instante antes de rodar. Só depois a conta é feita e o 5 chega à tela.

Console.WriteLine(Conta.Somar(2, 3));

static class Conta
{
    public static int Somar(int a, int b) => a + b;
}

Console.WriteLine(Conta.Somar(10, 20));

static class Conta
{
    public static int Somar(int a, int b) => a + b;
}

Muitos nomes, um .NET só

O .NET mudou de nome algumas vezes, e a internet está cheia de material de todas as épocas. Este é o mapa:

Qual usar? Para programas novos, sempre o .NET atual (hoje, o .NET 10). O .NET Framework só faz sentido para manter um programa antigo do Windows que já usa ele. Quando um tutorial disser "crie um projeto .NET Framework", ou mostrar um caminho como C:\Windows\Microsoft.NET\Framework, ele é dessa época antiga.

Quem faz o seu .NET

O código do .NET é aberto, então outras empresas podem compilá-lo. O .NET da Ana não foi baixado do site da Microsoft: foi a Canonical, a empresa do Ubuntu, que o compilou a partir do código-fonte e o colocou no repositório do Ubuntu. Por isso as versões são um pouco diferentes: no mesmo mês, o site da Microsoft tinha o SDK 10.0.402 com o Runtime 10.0.13, e o Ubuntu, o SDK 10.0.112 com o Runtime 10.0.12. Os dois são o mesmo .NET 10 e o mesmo C# 14; a aula Versões explica os números e a aula Instalar no Linux mostra as duas formas de instalar.

Quando dá errado

$ ls ~/rt ~/rt/shared
/home/ana/rt:
dotnet
host
shared

/home/ana/rt/shared:
Microsoft.NETCore.App                           « só o Runtime; nada de sdk
$ ~/rt/dotnet run ola.cs
The command could not be loaded, possibly because:
  * You intended to execute a .NET application:
      The application 'run' does not exist or is not a managed .dll or .exe.
  * You intended to execute a .NET SDK command:
      No .NET SDKs were found.

Download a .NET SDK:
https://aka.ms/dotnet/download

Learn about SDK resolution:
https://aka.ms/dotnet/sdk-not-found
$ echo $?
155

$ grep version ~/ola-pronto/ola.runtimeconfig.json
      "version": "11.0.0"
$ dotnet ~/ola-pronto/ola.dll
You must install or update .NET to run this application.

App: /home/ana/ola-pronto/ola.dll
Architecture: x64
Framework: 'Microsoft.NETCore.App', version '11.0.0' (x64)    « o que o programa pede
.NET location: /usr/lib/dotnet/

The following frameworks were found:
  10.0.12 at [/usr/lib/dotnet/shared/Microsoft.NETCore.App]   « o que a Ana tem

Learn more:
https://aka.ms/dotnet/app-launch-failed

To install missing framework, download:
https://aka.ms/dotnet-core-applaunch?framework=Microsoft.NETCore.App&framework_version=11.0.0&arch=x64&rid=ubuntu.26.04-x64&os=ubuntu.26.04
$ echo $?
150

Referência

Exercícios

Missão final: o caminho do código

Console.WriteLine("3. JIT: IL vira código de máquina");
Console.WriteLine("1. Roslyn: .cs vira IL");
Console.WriteLine("2. CLR: carrega o .dll");

Console.WriteLine("1. Roslyn: .cs vira IL");
Console.WriteLine("2. CLR: carrega o .dll");
Console.WriteLine("3. JIT: IL vira código de máquina");

Resumo

• O .NET é a plataforma por baixo do C#. O SDK é para quem programa (compilador e comandos); o Runtime é para quem só roda programas. O SDK já traz o Runtime.
• O caminho: o Roslyn compila o .cs para IL num .dll; o CLR carrega o .dll; o JIT traduz a IL para o processador na hora de rodar.
• O Console e as outras classes prontas vêm da biblioteca de classes, nos 172 .dll do Runtime. O coletor de lixo cuida da memória.
• dotnet --list-sdks e dotnet --list-runtimes mostram o que está instalado. No Ubuntu, tudo fica em /usr/lib/dotnet.
• .NET Framework (só Windows, antigo), Mono, .NET Core e .NET 5 a 10 são a mesma família; o guia usa o .NET 10.
• Próximo passo: entender os números das versões, em Versões do C# e do .NET.