Visão geral do global.json

Esso artigo se aplica a: ✔️ .NET SDK do Core 3.1 e versões posteriores

O arquivo global.json permite definir qual versão do SDK .NET é usada ao executar comandos da CLI .NET. Selecionar a versão do SDK .NET é independente de especificar a versão de runtime que um projeto visa. A versão do SDK .NET indica qual versão da CLI do .NET é usada. Este artigo explica como selecionar a versão do SDK usando global.json.

Se você sempre quiser usar a versão mais recente do SDK instalada no computador, nenhum arquivo global.json será necessário. Em cenários de CI (integração contínua), no entanto, normalmente a intenção é especificar um intervalo aceitável para a versão do SDK usada. O arquivo global.json tem um recurso rollForward que fornece maneiras flexíveis de especificar um intervalo aceitável de versões. Por exemplo, o arquivo global.json a seguir seleciona 10.0.100 ou qualquer feature band ou patch posterior para 10.0 instalado no computador:

{
  "sdk": {
    "version": "10.0.100",
    "rollForward": "latestFeature"
  }
}

Você depende de dois componentes no SDK do .NET para pesquisar um arquivo global.json. Cada componente começa em um local diferente e pesquisa por meio de diretórios ancestrais:

• O muxer do .NET SDK gerencia os comandos da CLI dotnet. Ele começa no diretório de trabalho atual, que não é necessariamente o mesmo que o diretório do projeto.
• .NET resolvedor do SDK do projeto MSBuild resolve os SDKs do projeto durante os builds. Ele começa no diretório que contém um arquivo de solução, se houver. Se nenhum arquivo de solução existir, ele será iniciado a partir do diretório que contém o arquivo de projeto atual. Se nenhum dos arquivos existir, ele usará o diretório de trabalho atual.

Para obter informações sobre como especificar a versão de runtime em vez da versão do SDK, confira Estruturas de destino.

Esquema do global.json

sdk

Tipo: object

Especifica informações sobre o SDK do .NET a ser selecionado.

version

• Tipo: string

A versão do SDK .NET a ser usada.

Este campo:

• Requer o número de versão completo, como 10.0.100.
• Não dá suporte a números de versão como 10, 10.0 ou 10.0.x.
• Não tem suporte curinga.
• Não dá suporte para intervalos de versão.

allowPrerelease

• Tipo: boolean
• Disponível desde: .NET Core SDK 3.0.

Indica se o resolvedor do SDK deve considerar versões de pré-lançamento ao selecionar a versão do SDK a ser usada.

Se você não definir esse valor explicitamente, o valor padrão dependerá se você estiver executando de Visual Studio:

• Se você não estiver no Visual Studio, o valor padrão é true.
• Se você estiver no Visual Studio, ele usará o status de pré-lançamento solicitado. Ou seja, se você estiver usando uma versão prévia do Visual Studio ou definir a opção Usar versões prévias do .NET SDK (em Tools>Options>Environment>Preview Features), o valor padrão é true. Caso contrário, o valor padrão será false.

rollForward

• Tipo: string
• Disponível desde: .NET Core SDK 3.0.

Indica a política de avanço gradual a ser usada ao selecionar uma versão do SDK, seja como uma alternativa quando uma versão específica do SDK está ausente, ou como uma diretiva para utilizar uma versão mais recente. Uma versão deve ser especificada com um valor rollForward, a menos que você a esteja definindo como latestMajor. O comportamento de roll forward padrão é determinado pelas regras de correspondência.

Para entender as políticas disponíveis e seu comportamento, considere as seguintes definições para uma versão do SDK no formato x.y.znn:

• x é a versão principal.
• y é a versão secundária.
• z é a faixa de recursos.
• nn é a versão do patch.

A tabela a seguir mostra os valores possíveis da chave rollForward:

paths

• Tipo: Matriz de string
• Disponível desde: .NET 10 SDK.

Especifica os locais que devem ser considerados ao pesquisar um SDK de .NET compatível. Os caminhos podem ser absolutos ou relativos ao local do arquivo global.json . O valor $host$ especial representa o local correspondente ao executável em execução dotnet .

Esses caminhos são pesquisados na ordem em que são definidos e o primeiro SDK correspondente é usado.

Esse recurso permite o uso de instalações locais do SDK (como SDKs relativas a uma raiz do repositório ou colocadas em uma pasta personalizada) que não são instaladas globalmente no sistema.

O recurso "caminhos" só funciona ao usar comandos que envolvem o SDK do .NET, como dotnet run. Ele NÃO afeta cenários como a execução do inicializador de apphost nativo (app.exe), executando com dotnet app.dll, ou executando com dotnet exec app.dll. Para usar o recurso "caminhos", você deve usar comandos do SDK como dotnet run.

errorMessage

• Tipo: string
• Disponível desde: .NET 10 SDK.

Especifica uma mensagem de erro personalizada exibida quando o resolvedor do SDK não consegue encontrar um SDK .NET compatível.

msbuild-sdks

Tipo: object

Permite controlar a versão do SDK do projeto em um único lugar em vez de em cada projeto individual. Para obter mais informações, confira Como os SDKs do projeto são resolvidos.

test

• Tipo: object

Especifica informações sobre testes.

runner

• Tipo: string
• Disponível desde: .NET SDK 10.0.

O executor de teste com o qual descobrir/executar testes.

Comentários em global.json

Há suporte para comentários em arquivos global.json usando do comentários de estilo JavaScript ou C#. Por exemplo:

{
   // This is a comment.
  "sdk": {
    "version": "8.0.300" /* This is comment 2*/
  /* This is a
  multiline comment.*/
  }
}

Examples

O exemplo a seguir mostra como não permitir o uso de versões de pré-lançamento:

{
  "sdk": {
    "allowPrerelease": false
  }
}

O exemplo a seguir mostra como usar a versão mais alta instalada que é maior ou igual à versão especificada. O JSON mostrado não permite qualquer versão do SDK anterior à 7.0.200 e permite 7.0.200 ou qualquer versão posterior, incluindo 8.0.xxx.

{
  "sdk": {
    "version": "7.0.200",
    "rollForward": "latestMajor"
  }
}

O exemplo a seguir mostra como usar a versão especificada exata:

{
  "sdk": {
    "version": "8.0.302",
    "rollForward": "disable"
  }
}

O exemplo a seguir mostra como usar a última faixa de recursos e a versão do patch instalada de uma versão principal e secundária específica. O JSON mostrado não permite nenhuma versão do SDK anterior à 8.0.302, e permite a 8.0.302 ou qualquer versão 8.0.xxx posterior, como 8.0.303 ou 8.0.402.

{
  "sdk": {
    "version": "8.0.302",
    "rollForward": "latestFeature"
  }
}

O exemplo a seguir mostra como usar a versão de patch mais alta instalada de uma versão específica. O JSON mostrado não permite nenhuma versão do SDK anterior à 8.0.102, e permite a 8.0.102 ou qualquer versão 8.0.1xx posterior, como 8.0.103 ou 8.0.199.

{
  "sdk": {
    "version": "8.0.102",
    "rollForward": "latestPatch"
  }
}

O exemplo a seguir mostra como especificar caminhos de pesquisa do SDK adicionais e uma mensagem de erro personalizada:

{
  "sdk": {
    "version": "10.0.100",
    "paths": [ ".dotnet", "$host$" ],
    "errorMessage": "The required .NET SDK wasn't found. Please run ./install.sh to install it."
  }
}

O exemplo a seguir mostra uma versão inválida especificada. A saída do comando dotnet --info mostra a mensagem de erro: "A versão '10.0' não é válida para o valor 'sdk/version'."

{
  "sdk": {
    "version": "10.0",
    "rollForward": "latestFeature"
  }
}

O exemplo a seguir mostra como especificar Microsoft.Testing.Platform como o executor de teste:

{
    "test": {
        "runner": "Microsoft.Testing.Platform"
    }
}

global.json e a CLI .NET

Para definir uma versão do SDK no arquivo global.json, é útil saber quais versões do SDK estão instaladas em seu computador. Para obter informações sobre como fazer isso, consulte Como verificar se o .NET já está instalado.

Para instalar versões adicionais do SDK do .NET em seu computador, visite a página Download .NET.

Você pode criar um arquivo global.json no diretório atual executando o comando dotnet new, como no exemplo a seguir:

dotnet new globaljson --sdk-version 8.0.302 --roll-forward latestFeature

Regras de combinação

As seguintes regras se aplicam ao determinar qual versão do SDK será usada:

• Se nenhum arquivo global.json for encontrado, ou global.json não especificar uma versão do SDK e não especificar um valor de allowPrerelease, a versão mais alta do SDK instalada é usada (equivalente a configurar rollForward como latestMajor). Se as versões do SDK de pré-lançamento são consideradas depende de como dotnet está sendo invocado:

  • Se você não estiver usando o Visual Studio, as versões de pré-lançamento serão consideradas.
  • Se você estiver no Visual Studio, ele usará o status de pré-lançamento solicitado. Ou seja, se você estiver usando uma versão prévia do Visual Studio ou definir a opção Usar prévias do .NET SDK (em Tools>Options>Environment>Preview Features), são consideradas as versões de pré-lançamento; caso contrário, somente versões estáveis são consideradas.

• Se um arquivo global.json for encontrado que não especifica uma versão do SDK, mas especifica um valor allowPrerelease, a versão mais alta do SDK instalada é usada (equivalente a configurar rollForward como latestMajor). Se a versão mais recente do SDK pode ser versão ou pré-lançamento depende do valor de allowPrerelease. true indica que as versões de pré-lançamento são consideradas; false indica que somente as versões de lançamento são consideradas.

• Se um arquivo global.json for encontrado e ele especificar uma versão do SDK:

  • Se nenhum valor rollForward for definido, ele usa patch como a política rollForward padrão. Caso contrário, verifique cada valor e seu comportamento na seção rollForward.
  • Se as versões de pré-lançamento são consideradas e qual é o comportamento padrão quando allowPrerelease não está definido é descrito na seção allowPrerelease.

Solucionar problemas de avisos de build

• Os avisos a seguir indicam que seu projeto foi compilado usando uma versão de pré-lançamento do SDK do .NET:

  Você está usando uma versão prévia do .NET. Confira: https://aka.ms/dotnet-support-policy

  .NET versões do SDK têm um histórico e um compromisso de alta qualidade. No entanto, se você não quiser usar uma versão de pré-lançamento, verifique as diferentes estratégias que você pode usar na seção allowPrerelease . Para computadores que nunca tiveram um .NET Core 3.0 ou runtime superior ou SDK instalado, você precisa criar um arquivo global.json e especificar a versão exata que deseja usar.

• O aviso a seguir indica que seu projeto tem como destino o EF Core 1.0 ou 1.1, que não é compatível com .NET SDK do Core 2.1 e versões posteriores:

  O projeto de inicialização '{startupProject}' tem como alvo o framework '.NETCoreApp' versão '{targetFrameworkVersion}'. Esta versão do Entity Framework Core .NET Ferramentas de Linha de Comando só dá suporte à versão 2.0 ou superior. Para obter informações de como usar as versões mais antigas das ferramentas, confira https://go.microsoft.com/fwlink/?linkid=871254

  Começando com o SDK do .NET Core 2.1 (versão 2.1.300), o comando dotnet ef vem incluído no SDK. Para compilar seu projeto, instale .NET SDK do Core 2.0 (versão 2.1.201) ou anterior no computador e defina a versão desejada do SDK usando o arquivo global.json. Para obter mais informações sobre o comando dotnet ef, consulte EF Core .NET Command-line Tools.

• Se você estiver usando global.json para permanecer em uma versão específica do SDK do .NET, observe que Visual Studio só instala uma única cópia do SDK do .NET. Portanto, se você atualizar sua versão Visual Studio, ela removerá a versão anterior do SDK do .NET usado para instalar a nova versão. Ele remove a versão antiga mesmo que seja uma versão de .NET principal diferente.

Para evitar a remoção de versões do SDK do .NET pelo Visual Studio, instale o SDK .NET autônomo da página de download. No entanto, se você fizer isso, não obterá mais atualizações automáticas para essa versão do SDK do .NET por Visual Studio e poderá estar em risco por problemas de segurança.

Consulte também

• Como os SDKs de projeto são resolvidos