Visão geral do global.json

Artigo
01/11/2024

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

O arquivo global.json permite que você defina qual versão do SDK do .NET é usada ao executar comandos de CLI do .NET. Selecionar a versão do SDK do .NET não depende da especificação da versão do runtime ao qual o projeto é direcionado. A versão do SDK do .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 seguinte arquivo global.json seleciona 6.0.300 ou qualquer faixa de recursos ou patch posterior para o 6.0 instalado no computador:

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

O SDK do .NET procura um arquivo global.json no diretório de trabalho atual (que não necessariamente é o mesmo que o diretório do projeto) ou um de seus diretórios pai.

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

Digite: object

Especifica as informações sobre o SDK do .NET que será selecionado.

version

Digite: string

A versão do SDK do .NET que será usada.

Este campo:

Não tem suporte curinga, ou seja, você deve especificar o número completo da versão.
Não dá suporte para intervalos de versão.

allowPrerelease

Digite: boolean
Disponível desde: SDK do .NET Core 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á da execução no Visual Studio:

Se você não estiver no Visual Studio, o valor padrão será true.
Se você estiver no Visual Studio, ele usará o status de pré-versão 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 SDK do .NET (em Ferramentas>Opções>ambiente>Recursos da versão prévia), o valor padrão será true. Caso contrário, o valor padrão será false.

rollForward

Digite: string
Disponível desde: SDK do .NET Core 3.0.

Indica a política de roll-forward a ser usada ao selecionar uma versão do SDK, seja como um fallback quando uma versão específica do SDK está ausente ou como uma diretiva para usar uma versão mais alta. 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:

Valor	Comportamento
`patch`	Usa a versão especificada. Se não for encontrado, será encaminhado para o nível de patch mais recente. Se não for encontrado, falhará. Esse valor é o comportamento herdado das versões anteriores do SDK.
`feature`	Usa o nível de patch mais recente para a faixa principal, secundária e de recursos especificada. Se não for encontrado, avançará para a próxima faixa de recursos superior dentro da mesma principal/secundária e usará o nível de patch mais recente para essa faixa de recursos. Se não for encontrado, falhará.
`minor`	Usa o nível de patch mais recente para a faixa principal, secundária e de recursos especificada. Se não for encontrado, será encaminhado para a próxima faixa de recursos superior dentro da mesma versão principal/secundária e usará o nível de patch mais recente para essa faixa de recursos. Se não for encontrado, efetuará roll forward para a próxima faixa de recursos superior dentro da mesma principal e usará o nível de patch mais recente para essa faixa de recursos. Se não for encontrado, falhará.
`major`	Usa o nível de patch mais recente para a faixa principal, secundária e de recursos especificada. Se não for encontrado, será encaminhado para a próxima faixa de recursos superior dentro da mesma versão principal/secundária e usará o nível de patch mais recente para essa faixa de recursos. Se não for encontrado, efetuará roll forward para a próxima faixa de recursos superior dentro da mesma principal e usará o nível de patch mais recente para essa faixa de recursos. Se não for encontrado, efetua roll forward para a próxima faixa principal, secundária e de recursos mais alta, e usa o nível de patch mais recente para essa faixa de recursos. Se não for encontrado, falhará.
`latestPatch`	Usa o nível de patch instalado mais recente que corresponde à faixa principal, secundária e de recurso solicitada com um nível de patch que é maior que ou igual ao valor especificado. Se não for encontrado, falhará.
`latestFeature`	Usa a faixa de recursos e o nível de patch mais alto instalados que correspondem aos principais e secundários solicitados com uma faixa de recursos e um nível de patch maior que ou igual ao valor especificado. Se não for encontrado, falhará.
`latestMinor`	Usa o nível secundário, de faixa de recursos e de patch mais alto instalado que corresponde ao principal solicitado com uma faixa de recursos secundária e um nível de patch maior que ou igual ao valor especificado. Se não for encontrado, falhará.
`latestMajor`	Usa o SDK do .NET mais alto instalado com uma versão maior que ou igual ao valor especificado. Se não for encontrado, falhará.
`disable`	Não efetua roll forward. Uma correspondência exata é necessária.

msbuild-sdks

Digite: 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.

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": "7.0.100" /* This is comment 2*/
  /* This is a
  multiline comment.*/
  }
}

Exemplos

O exemplo a seguir mostra como não usar 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 à 2.2.200 e permite 2.2.200 ou qualquer versão posterior, incluindo 3.0.xxx e 3.1.xxx.

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

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

{
  "sdk": {
    "version": "3.1.100",
    "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 à 3.1.102, e permite a 3.1.102 ou qualquer versão 3.1.xxx posterior, como 3.1.103 ou 3.1.200.

{
  "sdk": {
    "version": "3.1.102",
    "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 à 3.1.102, e permite a 3.1.102 ou qualquer versão 3.1.1.xx posterior, como 3.1.103 ou 3.1.199.

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

global.json e CLI do .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, confira 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 6.0.100

Regras de correspondência

Observação

As regras de correspondência são regidas pelo ponto de entrada dotnet.exe, que é comum em todos os runtimes instalados do .NET instalados. As regras correspondentes da versão mais recente instalada do Runtime do .NET são usadas quando você tem vários runtimes instalados lado a lado ou se está usando um arquivo global.json.

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 nem um valor 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 no Visual Studio, as versões de pré-lançamento serão consideradas.
- Se você estiver no Visual Studio, ele usará o status de pré-versão solicitado. Ou seja, se você estiver usando uma versão prévia do Visual Studio ou se configurar a opção Usar versões prévias do SDK do .NET (em Ferramentas>Opções>ambiente>Recursos da versão prévia), as versões de pré-visualização são consideradas; caso contrário, apenas versões de lançamento 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 versão 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 latestPatch 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á trabalhando com uma versão prévia do SDK do .NET Core. Você pode definir a versão do SDK por meio de um arquivo global.json no projeto atual. Saiba mais em https://go.microsoft.com/fwlink/?linkid=869452.

Você está usando uma versão de visualização do .NET. Confira: https://aka.ms/dotnet-core-preview

As versões do SDK do .NET têm um histórico e o compromisso de manter a 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 SDK ou runtime do .NET Core 3.0 ou superior instalado, você precisa criar um arquivo global.json e especificar a versão exata que deseja usar.
O aviso a seguir indica que o projeto é direcionado ao EF Core 1.0 ou 1.1, que não é compatível com o SDk do .NET Core 2.1 e versões posteriores:

O projeto de inicialização '{startupProject}' é direcionado à estrutura '.NETCoreApp' versão '{targetFrameworkVersion}'. Essa versão das ferramentas de linha de comando do .NET do Entity Framework Core são compatíveis apenas com a versão 2.0 ou superiores. Para obter informações de como usar as versões mais antigas das ferramentas, confira https://go.microsoft.com/fwlink/?linkid=871254

A partir do 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 o SDK do .NET Core 2.0 (versão 2.1.201) ou versões anteriores em seu computador e defina a versão do SDK desejada usando o arquivo global.json. Para saber mais sobre o comando dotnet ef, confira Ferramentas da linha de comando do .NET EF Core.
Se você estiver usando global.json para permanecer em uma versão específica do SDK do .NET, observe que o Visual Studio instala apenas uma cópia do SDK do .NET. Portanto, se você atualizar sua versão do Visual Studio, ele removerá a versão anterior do SDK do .NET que ele usou para instalar a nova versão. Ele remove a versão antiga, mesmo que seja uma versão principal diferente do .NET.

Para evitar que o Visual Studio remova versões do SDK do .NET, você precisará instalar o SDK do .NET autônomo a partir da página de download. Observe que, se você fizer isso, você não obterá mais atualizações automáticas para essa versão do SDK do .NET por meio do Visual Studio e poderá estar em risco de problemas de segurança.

Confira também

Como os SDKs de projeto são resolvidos