Visão geral global.json

Artigo
07/05/2024

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

O arquivo global.json permite definir qual versão do SDK do .NET é usada quando você executa comandos da CLI do .NET. A seleção da versão do SDK do .NET é independente da especificação da versão de tempo de execução a que um projeto se destina. 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 em sua máquina, nenhum arquivo global.json será necessário. Em cenários de CI (integração contínua), no entanto, você normalmente deseja especificar um intervalo aceitável para a versão do SDK usada. O arquivo global.json tem um rollForward recurso que fornece maneiras flexíveis de especificar um intervalo aceitável de versões. Por exemplo, o seguinte arquivo de global.json seleciona 8.0.300 ou qualquer faixa de recurso ou patch posterior para 8.0 instalado na máquina:

{
  "sdk": {
    "version": "8.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 em um de seus diretórios pai.

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

global.json esquema

sdk

Tipo: object

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

versão

Tipo: string

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

Este campo:

Não tem suporte a curinga; ou seja, você deve especificar o número completo da versão.
Não suporta intervalos de versões.

permitirPré-lançamento

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

Indica se o resolvedor do SDK deve considerar as 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 a partir do 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é-lançamento solicitado. Ou seja, se você estiver usando uma versão de visualização do Visual Studio ou definir a opção Usar visualizações do SDK do .NET (em Ferramentas>Opções>de Recursos de Visualização do Ambiente>), o valor padrão será .true Caso contrário, o valor padrão é false.

rollAvançar

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

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 estiver ausente ou como uma diretiva para usar uma versão posterior. Uma versão deve ser especificada com um rollForward valor, a menos que você a esteja definindo como latestMajor. O comportamento padrão de roll forward é determinado pelas regras correspondentes.

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 banda de recurso.
nn é a versão do patch.

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

Value	Comportamento
`patch`	Usa a versão especificada. Se não for encontrado, avança para o nível de patch mais recente. Se não for encontrado, falha. Esse valor é o comportamento herdado das versões anteriores do SDK.
`feature`	Usa o nível de patch mais recente para a banda principal, secundária e de recursos especificada. Se não for encontrado, avança para a próxima banda de recursos superior dentro da mesma banda maior/secundária e usa o nível de patch mais recente para essa banda de recursos. Se não for encontrado, falha.
`minor`	Usa o nível de patch mais recente para a banda principal, secundária e de recursos especificada. Se não for encontrado, avança para a próxima banda de recursos superior dentro da mesma versão principal/secundária e usa o nível de patch mais recente para essa banda de recursos. Se não for encontrado, avança para a próxima banda secundária e de recursos superior dentro da mesma banda principal e usa o nível de patch mais recente para essa banda de recursos. Se não for encontrado, falha.
`major`	Usa o nível de patch mais recente para a banda principal, secundária e de recursos especificada. Se não for encontrado, avança para a próxima banda de recursos superior dentro da mesma versão principal/secundária e usa o nível de patch mais recente para essa banda de recursos. Se não for encontrado, avança para a próxima banda secundária e de recursos superior dentro da mesma banda principal e usa o nível de patch mais recente para essa banda de recursos. Se não for encontrado, avança para a próxima banda maior, secundária e de recursos superior e usa o nível de patch mais recente para essa banda de recursos. Se não for encontrado, falha.
`latestPatch`	Usa o nível de patch instalado mais recente que corresponde à banda principal, secundária e de recursos solicitada com um nível de patch maior ou igual ao valor especificado. Se não for encontrado, falha.
`latestFeature`	Usa a banda de recursos instalada mais alta e o nível de patch que corresponde ao major e minor solicitados com uma banda de recursos e nível de patch maior ou igual ao valor especificado. Se não for encontrado, falha.
`latestMinor`	Usa o menor instalado, a banda de recursos e o nível de patch mais alto que correspondem ao major solicitado com um menor, banda de recursos e nível de patch maior ou igual ao valor especificado. Se não for encontrado, falha.
`latestMajor`	Usa o SDK .NET instalado mais alto com uma versão maior ou igual ao valor especificado. Se não for encontrado, falhe.
`disable`	Não rola para a frente. É necessária uma correspondência exata.

msbuild-sdks

Tipo: object

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

Comentários em global.json

Comentários em arquivos global.json são suportados usando comentários no estilo JavaScript ou C#. Por exemplo:

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

Exemplos

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 banda de recursos e a versão de patch mais recentes instaladas de uma versão principal e secundária específica. O JSON mostrado não permite qualquer versão do SDK anterior à 8.0.302 e permite 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 qualquer versão do SDK anterior à 8.0.102 e permite 8.0.102 ou qualquer versão posterior da 8.0.1xx, como 8.0.103 ou 8.0.199.

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

global.json e a 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 sua máquina. 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 sua máquina, visite a página Baixar .NET .

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

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

Regras de correspondência

Nota

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

As regras a seguir se aplicam ao determinar qual versão do SDK usar:

Se nenhum arquivo global.json for encontrado, ou global.json não especificar uma versão do SDK e não especificar um allowPrerelease valor, a versão mais alta do SDK instalada será usada (equivalente à configuração 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é-lançamento solicitado. Ou seja, se você estiver usando uma versão de visualização do Visual Studio ou definir a opção Usar visualizações do SDK do .NET (em Recursos de visualização do ambiente>de opções>de ferramentas>), as versões de pré-lançamento serão consideradas, caso contrário, apenas as versões de lançamento serão consideradas.
Se for encontrado um arquivo global.json que não especifique uma versão do SDK, mas especifique um allowPrerelease valor, será usada a versão mais alta do SDK instalada (equivalente à configuração rollForward como latestMajor). Se a versão mais recente do SDK pode ser lançada ou pré-lançada depende do valor do allowPrerelease. true indica que as versões de pré-lançamento são consideradas; false indica que apenas as versões de lançamento são consideradas.
Se um arquivo global.json for encontrado e especificar uma versão do SDK:
- Se nenhum rollForward valor for definido, ele será usado latestPatch como a política padrão rollForward . 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 compilação

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 de visualização do .NET. Veja: https://aka.ms/dotnet-support-policy

As versões do SDK do .NET 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 máquinas que nunca tiveram um .NET Core 3.0 ou superior runtime 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 alvo o 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 arranque '{startupProject}' visa o quadro '. NETCoreApp' versão '{targetFrameworkVersion}'. Esta versão das Ferramentas de Linha de Comando do Entity Framework Core .NET suporta apenas a versão 2.0 ou superior. Para obter informações sobre como usar versões mais antigas das ferramentas, consulte https://go.microsoft.com/fwlink/?linkid=871254.

A partir do SDK do .NET Core 2.1 (versão 2.1.300), o dotnet ef comando vem incluído no SDK. Para compilar seu projeto, instale o SDK do .NET Core 2.0 (versão 2.1.201) ou anterior em sua máquina e defina a versão desejada do SDK usando o arquivo global.json . Para obter mais informações sobre o comando, consulte Ferramentas de linha de dotnet ef comando do EF Core .NET.
Se você estiver usando global.json para permanecer em uma versão específica do SDK do .NET, observe que o Visual Studio só instala uma única 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, instale o SDK do .NET autônomo na página de download. No entanto, se você fizer isso, você não obterá 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.

Consulte também

Como os SDKs de projeto são resolvidos

Partilhar via