Compartilhar via

Testar os SDKs de pré-lançamento .NET localmente com caminhos global.json

A partir do .NET 10, o arquivo global.json dá suporte a uma propriedade sdk.paths que informa à CLI .NET onde procurar instalações do SDK além do local padrão do sistema. Esse recurso permite que você instale um SDK de pré-lançamento em uma pasta local do projeto e use-o somente quando estiver trabalhando nesse projeto. O processo não modifica instalações em todo o sistema e não altera sua variável de ambiente no nível do computador ou no nível PATH do usuário. (O script de instalação pode atualizar temporariamente PATH na sessão atual do shell, mas essa alteração não persiste.)

Se você deseja experimentar um novo recurso de idioma, avaliar uma versão prévia para sua equipe ou validar sua biblioteca de software livre em relação a uma versão futura do SDK no CI, sdk.paths oferece uma maneira segura e reversível de fazer isso. Se algo der errado, você excluirá uma pasta e voltará exatamente onde começou.

Observação

Este artigo usa .NET 11 (o pré-lançamento atual no momento da escrita) como exemplo. O sdk.paths recurso funciona com qualquer versão do SDK, pré-lançamento ou estável, atual ou futura. Substitua 11.0 e preview nos comandos de instalação pela versão e a qualidade que você precisar.

Pré-requisitos

  • .NET 10 ou posterior deve estar instalado em seu sistema, para que o host dotnet em seu PATH seja da versão 10.0 ou posterior. O host é o executável disponível para todo o sistema do seu computador. Quando você executa qualquer comando dotnet, esse host entra em ação primeiro: ele lê global.json, decide qual versão do SDK deve ser usada e passa o controle para esse SDK. Neste artigo de instruções, você usa esse host em todo o sistema para direcionar a CLI para um SDK de versão prévia instalado localmente.
  • Um terminal ou prompt de comando (bash, zsh, PowerShell ou Prompt de Comando).
  • (Opcional) Um repositório Git no qual você deseja definir o escopo do SDK de pré-lançamento.

Importante

O recurso sdk.paths requer um .NET 10 ou posterior host (o executável dotnet em seu PATH). Se o host em todo o sistema for .NET 8 ou .NET 9, ele não reconhecerá a propriedade paths e retornará ao comportamento de resolução padrão. Você ainda pode usar o SDK local invocando ./.dotnet/dotnet (ou .\.dotnet\dotnet em Windows) diretamente, o que ignora o host do sistema.

Para verificar a versão do host, execute dotnet --info e procure a seção Host perto da parte superior da saída:

Host:
  Version:      10.0.0
  Architecture: x64
  Commit:       abc123def4

A Version linha deve mostrar 10.0 ou posterior. A versão do host não é a mesma da versão do SDK relatada por dotnet --version. Se o host mostrar uma versão mais antiga (por exemplo, 8.0.x ou 9.0.x), instale .NET 10+ em todo o sistema para atualizar o host dotnet em seu PATH.

Funcionamento do sdk.paths

A propriedade sdk.paths é uma matriz JSON de caminhos de pasta em que o host .NET procura instalações do SDK. O host pesquisa esses caminhos na ordem em que você os lista e usa o primeiro SDK que atende às restrições de versão em global.json.

Dois detalhes principais:

  • Os caminhos são relativos à global.json localização do arquivo, não ao diretório de trabalho atual. Se o global.json estiver na raiz do repositório e você especificar ".dotnet", o host procurará um SDK na pasta .dotnet na raiz do repositório, mesmo que você execute comandos de dotnet a partir de um subdiretório.
  • $host$ é um token especial que representa o diretório de instalação .NET em todo o sistema (o local do executável dotnet em seu PATH). Inclua $host$ na matriz quando desejar que o SDK do sistema seja usado como opção de recurso.

Observação

Ambos o token $host$ e toda a propriedade paths são reconhecidos apenas por hosts do .NET 10+. Os hosts mais antigos os ignoram completamente: eles não produzem um erro, simplesmente ignoram a propriedade e retornam à resolução padrão do SDK.

Por exemplo, a configuração a seguir informa ao host para procurar primeiro um SDK em uma pasta local .dotnet e, em seguida, recorrer à instalação do sistema.

{
  "sdk": {
    "paths": [".dotnet", "$host$"]
  }
}

Se você omitir $host$ da matriz, o host pesquisa apenas os diretórios especificados. Se nenhum deles contiver um SDK correspondente, o comando falhará, o que pode ser útil quando você quiser impor que um SDK específico esteja presente.

Você pode listar mais de duas entradas. Por exemplo, você pode manter pastas separadas para uma visualização e um SDK estável e pesquisá-las na ordem: [".dotnet-preview", ".dotnet-stable", "$host$"].

Etapa 1: instalar um SDK de pré-lançamento localmente

Use os scripts oficiais de instalação do dotnet para baixar um SDK de pré-lançamento em um diretório local do projeto. Esses scripts não exigem privilégios de administrador e não modificam seu sistema PATH ou qualquer instalação em todo o sistema.

curl -sSL https://dot.net/v1/dotnet-install.sh -o dotnet-install.sh
chmod +x dotnet-install.sh
./dotnet-install.sh --channel 11.0 --quality preview --install-dir .dotnet

O --install-dir parâmetro (ou -InstallDir) coloca o SDK em uma .dotnet pasta dentro do diretório atual. Nenhum arquivo é gravado em nenhum outro lugar em seu computador.

Dica

O --quality parâmetro aceita três valores: daily (build noturno mais recente), preview (versão prévia oficial mais recente) e GA (versão estável mais recente). Você também pode usar --version para instalar uma versão exata do SDK, como --version 11.0.100-preview.2.26159.112.

Etapa 2: Adicionar .dotnet/ a .gitignore

A instalação do SDK local pode ter várias centenas de megabytes. Adicione-o ao seu .gitignore para mantê-lo fora do controle do código-fonte:

echo '.dotnet/' >> .gitignore

Se o projeto já tiver um .gitignore, verifique se .dotnet/ não está sendo rastreado antes de fazer o commit:

git status --ignored

Observação

Cada desenvolvedor (e cada agente de CI) executa o script de instalação de forma independente. A .dotnet pasta é um cache local, não um artefato compartilhado.

Etapa 3: Configurar global.json

Crie ou atualize um global.json arquivo na raiz do repositório. No mínimo, você só precisa da paths propriedade para começar:

{
  "sdk": {
    "paths": [".dotnet", "$host$"]
  }
}

Isso informa ao host para procurar um SDK primeiro na pasta local .dotnet e, em seguida, recorrer à instalação do sistema. Nenhum número de versão é necessário – o host escolhe o SDK mais recente encontrado.

Para obter mais controle, você pode definir uma versão mínima e configurar o comportamento de avanço:

{
  "sdk": {
    "version": "11.0.100-preview.2.26159.112",
    "allowPrerelease": true,
    "rollForward": "latestFeature",
    "paths": [".dotnet", "$host$"],
    "errorMessage": "Required .NET SDK not found. Run the install-dotnet script for your platform to install it locally."
  }
}

Veja o que cada propriedade faz:

Propriedade Propósito
version A versão mínima do SDK exigida pelo projeto.
allowPrerelease Permite que o host selecione versões do SDK de pré-lançamento durante o roll-forward. Defina para true quando testar as pré-visualizações.
rollForward Controla como o host seleciona um SDK mais recente quando a versão exata não está disponível. latestFeature permite avançar para uma banda de recursos mais recente dentro da mesma versão principal.minor.
paths Diretórios para pesquisar instalações do SDK, em ordem. ".dotnet" é a pasta local; "$host$" é o padrão do sistema.
errorMessage Uma mensagem personalizada mostrada quando nenhum SDK correspondente é encontrado. Use-o para informar aos colaboradores exatamente como configurar seu ambiente.

Dica

Listar ".dotnet" antes de "$host$" significa que o SDK de pré-lançamento local tem prioridade. Inverta a ordem se você quiser que o SDK do sistema ganhe quando ele atender à restrição de versão.

Dica

Mudou de ideia? Consulte Limpeza no final deste artigo. Nenhum arquivo do sistema é tocado.

Início rápido: comando tudo-em-um

Agora que você entende o que cada etapa faz, aqui está um único comando que executa as Etapas 1 a 3 de uma só vez. Cole o comando para o seu sistema operacional em um terminal no diretório raiz do seu projeto.

curl -sSL https://dot.net/v1/dotnet-install.sh -o /tmp/dotnet-install.sh \
  && bash /tmp/dotnet-install.sh --channel 11.0 --quality preview --install-dir .dotnet \
  && rm /tmp/dotnet-install.sh \
  && echo '.dotnet/' >> .gitignore \
  && cat > global.json << 'EOF'
{
  "sdk": {
    "paths": [".dotnet", "$host$"]
  }
}
EOF
echo "Installed: $(.dotnet/dotnet --version)"

Etapa 4: Criar scripts de instalação de equipe (opcional)

Quando várias pessoas trabalham no mesmo repositório, um script de conveniência impede que todos tenham que se lembrar dos comandos de instalação. Crie um script para cada plataforma na raiz do repositório. Esses scripts instalam o SDK, criam global.json, atualizam .gitignoree, opcionalmente, instalam cargas de trabalho — tudo em uma etapa.

install-dotnet.sh (macOS/Linux):

#!/usr/bin/env bash
set -e

# -------- Configuration --------
CHANNEL="11.0"
QUALITY="preview"
# Uncomment the workloads your project needs:
# WORKLOADS="maui wasm-tools"
# --------------------------------

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
INSTALL_DIR="$SCRIPT_DIR/.dotnet"

echo "Installing .NET $CHANNEL ($QUALITY) SDK to $INSTALL_DIR ..."

curl -sSL https://dot.net/v1/dotnet-install.sh -o "$SCRIPT_DIR/dotnet-install.sh"
chmod +x "$SCRIPT_DIR/dotnet-install.sh"
"$SCRIPT_DIR/dotnet-install.sh" --channel "$CHANNEL" --quality "$QUALITY" --install-dir "$INSTALL_DIR"
rm -f "$SCRIPT_DIR/dotnet-install.sh"

# Auto-detect the installed SDK version
SDK_VERSION="$("$INSTALL_DIR/dotnet" --version)"

# Create global.json with the installed version
cat > "$SCRIPT_DIR/global.json" << EOF
{
  "sdk": {
    "version": "$SDK_VERSION",
    "allowPrerelease": true,
    "rollForward": "latestFeature",
    "paths": [".dotnet", "\$host\$"],
    "errorMessage": "Required .NET SDK not found. Run ./install-dotnet.sh (macOS/Linux) or .\\\\install-dotnet.ps1 (Windows) to install it locally."
  }
}
EOF

# Ensure .dotnet/ is in .gitignore
if ! grep -qxF '.dotnet/' "$SCRIPT_DIR/.gitignore" 2>/dev/null; then
    echo '.dotnet/' >> "$SCRIPT_DIR/.gitignore"
fi

# Install workloads if configured
if [ -n "${WORKLOADS:-}" ]; then
    echo "Installing workloads: $WORKLOADS"
    # shellcheck disable=SC2086
    "$INSTALL_DIR/dotnet" workload install $WORKLOADS
fi

echo ""
echo "Done! SDK $SDK_VERSION installed to $INSTALL_DIR"
echo "Run 'dotnet --version' to verify."

Torne o script de shell executável e adicione ambos os scripts ao repositório:

chmod +x install-dotnet.sh
git add install-dotnet.sh install-dotnet.ps1

Com esses scripts checados, o errorMessage em global.json pode direcionar os colaboradores para executar o script apropriado para sua plataforma. Um novo membro da equipe clona o repositório, executa o script e está pronto para compilar, sem etapas manuais de instalação do SDK a seguir.

Etapa 5: Verificar a instalação

No diretório que contém seu global.json (ou qualquer subdiretório), execute os seguintes comandos para confirmar se o host está resolvendo o SDK de pré-lançamento local:

dotnet --version

A saída deve mostrar a versão de pré-lançamento que você instalou, por exemplo:

11.0.100-preview.2.26159.112

Para obter informações mais detalhadas sobre qual SDK foi resolvido e de onde foi carregado, execute:

dotnet --info

Encontre a linha Base Path na saída. Ele deve apontar para a .dotnet pasta relativa ao seu projeto, confirmando que a instalação local está em uso.

Observação

Se a saída mostrar a versão do SDK do sistema em vez do pré-lançamento, verifique o seguinte:

  • Versão do host versus versão do SDK: A versão do host (mostrada sob o título Host) determina se paths é compreendida. Tem que ser 10.0 ou mais recente. A versão do SDK (mostrada por dotnet --version) é a versão resolvida após os processos global.json do host.
  • O arquivo global.json está em um diretório pai do seu diretório de trabalho atual.
  • A .dotnet pasta contém uma instalação completa do SDK (verifique se há uma sdk subpasta dentro dela).

Etapa 6: Instalar cargas de trabalho no SDK local (opcional)

Depois de instalar um SDK local, você pode instalar cargas de trabalho opcionais como .NET MAUI ou Blazor WebAssembly AOT nele. As cargas de trabalho instaladas no SDK local são completamente independentes das cargas de trabalho em sua instalação em todo o sistema.

Instalar uma carga de trabalho

Verifique se você executou isso na pasta que contém seu global.json (ou um subdiretório dele). Use o binário local dotnet diretamente para garantir que a carga de trabalho esteja instalada no SDK local e não na instalação do sistema:

./.dotnet/dotnet workload install maui

Importante

Sempre use ./.dotnet/dotnet (ou .\.dotnet\dotnet em Windows) para comandos de carga de trabalho. O global.jsonpaths recurso roteia a resolução do SDK corretamente para comandos como dotnet build e dotnet run, mas os comandos de carga de trabalho armazenam metadados relativos à dotnet raiz do host que os executa. Quando você usa o host do sistema, as cargas de trabalho acabam na instalação do sistema em vez de na instalação local. Essa é uma lacuna conhecida em como sdk.paths interage com DOTNET_ROOT. Usar o binário local garante diretamente que as cargas de trabalho sejam instaladas e rastreadas no lugar certo.

Observação

No macOS e no Linux, você não precisa da instalação da carga de trabalho ao usar um SDK local. A .dotnet/ pasta é de propriedade do usuário, portanto, todos os arquivos de carga de trabalho são gravados com suas permissões de usuário normais. Isso é diferente das instalações em todo o sistema, o que pode exigir privilégios elevados.

Cargas de trabalho comuns

A tabela a seguir lista cargas de trabalho comumente usadas:

Carga de Trabalho Comando de Instalação
.NET MAUI ./.dotnet/dotnet workload install maui
ASP.NET Core (Blazor WASM AOT) ./.dotnet/dotnet workload install wasm-tools

Você pode instalar várias cargas de trabalho em um único comando:

./.dotnet/dotnet workload install maui wasm-tools

Verificar cargas de trabalho instaladas

Para ver quais cargas de trabalho estão instaladas no SDK local:

./.dotnet/dotnet workload list

Dica

As cargas de trabalho instaladas no SDK local são armazenadas dentro do .dotnet/ diretório. Excluir o diretório remove o SDK e todas as suas cargas de trabalho. Os caches de download compartilhados (como ~/.nuget/packages) podem permanecer, mas não afetam seu sistema.

Etapa 7: Usar o SDK de pré-lançamento em CI (opcional)

A mesma abordagem funciona em pipelines de integração contínua. No entanto, os executores de CI podem não ter um host .NET 10+ pré-instalado, portanto, você precisa garantir que o host esteja disponível antes de contar com sdk.paths.

Exemplo do GitHub Actions

O fluxo de trabalho a seguir instala um host .NET 10 usando actions/setup-dotnet e instala o SDK de versão prévia do .NET 11 localmente. A etapa setup-dotnet garante que o executor tenha um host .NET 10+ em PATH que consiga ler a propriedade paths em global.json.

name: Build with preview SDK

on: [push, pull_request]

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]

    steps:
      - uses: actions/checkout@v4

      - name: Install .NET 10 host
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '10.0.x'
          dotnet-quality: 'preview'

      - name: Cache local SDK
        uses: actions/cache@v4
        with:
          path: .dotnet
          key: dotnet-local-${{ matrix.os }}-${{ hashFiles('global.json') }}

      - name: Install .NET 11 preview SDK locally
        # Use bash shell explicitly — Windows runners default to PowerShell,
        # which doesn't support the curl/chmod/shell-script syntax below.
        shell: bash
        run: |
          curl -sSL https://dot.net/v1/dotnet-install.sh -o dotnet-install.sh
          chmod +x dotnet-install.sh
          ./dotnet-install.sh --channel 11.0 --quality preview --install-dir .dotnet

      - name: Build
        run: dotnet build

      - name: Test
        run: dotnet test

Como global.json já tem a paths configuração, as etapas dotnet build e dotnet test automaticamente detectam o SDK local. Nenhuma alteração na instalação do agente de CI em todo o sistema é necessária.

Dica

A actions/cache etapa armazena em cache o .dotnet/ diretório entre execuções, chaveado pelo sistema operacional e pelo hash de global.json. O cache é atualizado automaticamente quando você atualiza a versão do SDK em global.json.

Observação

A strategy.matrix seção executa o build em vários sistemas operacionais. Você pode estender a matriz para testar em várias versões do SDK adicionando uma sdk-version dimensão e usando-a na etapa de instalação.

Fallback: utilize diretamente o host local

Se você não puder instalar o .NET 10+ no sistema como um todo no agente (por exemplo, em um ambiente de CI bloqueado), invoque o próprio host do SDK local diretamente ao invés de depender do sistema dotnet:

- name: Install .NET 11 preview SDK locally
  run: |
    curl -sSL https://dot.net/v1/dotnet-install.sh -o dotnet-install.sh
    chmod +x dotnet-install.sh
    ./dotnet-install.sh --channel 11.0 --quality preview --install-dir .dotnet

- name: Build using local host
  run: ./.dotnet/dotnet build

- name: Test using local host
  run: ./.dotnet/dotnet test

Essa abordagem ignora completamente o host do sistema e não requer resolução de sdk.paths – o executável local dotnet sabe a localização de seu próprio SDK.

Limitações

O sdk.paths recurso tem algumas restrições a serem observadas:

  • Requer um host .NET 10 ou posterior em PATH. O dotnet executável que lê global.json deve ser a versão 10.0 ou posterior. Se o host do sistema for mais antigo, ele ignorará totalmente a paths propriedade.
  • Aplica-se somente a comandos do SDK. A paths propriedade afeta a resolução do SDK para comandos como dotnet build, dotnet rune dotnet test. Ele não afeta a resolução do host do aplicativo ou a execução dependente de framework (por exemplo, dotnet myapp.dll).
  • Os caminhos são relativos à localização do arquivo global.json. Se você mover o arquivo global.json, atualize os caminhos adequadamente. Um caminho absoluto também funciona, mas reduz a portabilidade entre computadores.

Limpeza

A remoção de um SDK de pré-lançamento local executa duas etapas:

  1. Exclua a pasta do SDK local:

    rm -rf .dotnet/
  1. Remova a propriedade paths de global.json, ou exclua o arquivo se você não precisar mais dele. Seu projeto é revertido para o uso do SDK em todo o sistema.

Como tudo é local do projeto, incluindo todas as cargas de trabalho instaladas, não há entradas do Registro, variáveis de ambiente ou arquivos do sistema para limpar. Remover a pasta e reverter global.json é tudo o que você precisa fazer. Todas as cargas de trabalho instaladas no SDK local são excluídas junto com a .dotnet/ pasta.

Próximas Etapas 

  • Last updated on