Visão geral do global.json

Este artigo aplica-se a: ✔️ SDK do .net Core 2,0 e versões posteriores

O arquivo global. JSON permite que você defina qual versão do SDK do .net é usada quando você executa comandos da CLI do .net. Selecionar o SDK do .NET é independente de especificar o tempo de execução de destino do projeto. A versão do SDK do .NET indica quais versões da CLI do .NET são usadas.

Em geral, você deseja usar a versão mais recente das ferramentas do SDK, portanto, nenhum arquivo global. JSON é necessário. Em alguns cenários avançados, talvez você queira controlar a versão das ferramentas do SDK, e este artigo explica como fazer isso.

Para obter mais informações de como especificar o runtime nesse caso, confira Estruturas de destino.

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.

Esquema do global.json

sdk

Digite: object

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

version

  • Digite: string

  • Disponível desde: SDK do .NET Core 1,0.

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

Este campo:

  • Não tem suporte a curinga, ou seja, o número de versão completo deve ser especificado.
  • 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á se você estiver executando a partir de Visual Studio:

  • se você não estiver em Visual Studio, o valor padrão será true .
  • se você estiver em 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 da SDK do .NET Core (em ferramentas > opções > > recursos de visualização do ambiente), o valor padrão será true ; caso contrário, false .

Avanço

  • Digite: 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 superior. Uma versão deve ser especificada com um rollForward valor, a menos que você esteja definindo-a 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 para a rollForward chave:

Valor Comportamento
patch Usa a versão especificada.
Se não for encontrado, roll forward para o último nível de patch.
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 primária, secundária e de recurso especificada.
Se não for encontrado, roll forward para a próxima faixa de recursos mais alta dentro do mesmo principal/secundário e usa o nível de patch mais recente para essa faixa de recurso.
Se não for encontrado, falhará.
minor Usa o nível de patch mais recente para a faixa primária, secundária e de recurso especificada.
Se não for encontrado, roll forward para a próxima faixa de recursos mais alta na mesma versão principal/secundária e usa o nível de patch mais recente para essa faixa de recurso.
Se não for encontrado, roll forward para a próxima faixa secundária e de recurso na mesma principal e usa o nível de patch mais recente para essa faixa de recurso.
Se não for encontrado, falhará.
major Usa o nível de patch mais recente para a faixa primária, secundária e de recurso especificada.
Se não for encontrado, roll forward para a próxima faixa de recursos mais alta na mesma versão principal/secundária e usa o nível de patch mais recente para essa faixa de recurso.
Se não for encontrado, roll forward para a próxima faixa secundária e de recurso na mesma principal e usa o nível de patch mais recente para essa faixa de recurso.
Se não for encontrado, rola para a próxima faixa mais alta, secundária e de recurso e usa o nível de patch mais recente para essa faixa de recurso.
Se não for encontrado, falhará.
latestPatch Usa o nível de patch mais recente instalado que corresponde à faixa principal, secundária e de recursos solicitada com um nível de patch e maior 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 corresponde ao principal e secundário solicitados com uma faixa de recursos e um nível de patch que é maior ou igual ao valor especificado.
Se não for encontrado, falhará.
latestMinor Usa a maior versão instalada, a faixa de recursos e o nível de patch que corresponde à principal solicitada com um nível secundário, de faixa de recursos e de patch que é maior 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 ou igual à do valor especificado.
Se não for encontrado, falha.
disable Não rola para frente. 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, consulte como os SDKs do projeto são resolvidos.

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 recente 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 o 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 faixa de recursos e a versão de patch mais recentes instalados de uma versão principal e secundária específica. O JSON mostrado não permite qualquer versão do SDK anterior à 3.1.102 e permite o 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 qualquer versão do SDK anterior à 3.1.102 e permite 3.1.102 ou qualquer versão mais recente do 3.1.1 XX, como 3.1.103 ou 3.1.199.

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

global. JSON e a CLI do .NET

É útil saber quais versões do SDK estão instaladas em seu computador para definir uma no arquivo global. JSON . Para obter mais 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 baixar o .net .

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

dotnet new globaljson --sdk-version 3.0.100

Regras de correspondência

Observação

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

A partir do .NET Core 3,0, as seguintes regras 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 nem um allowPrerelease valor, a versão mais recente do SDK instalada será usada (equivalente a definir rollForward como latestMajor ). Se as versões de pré-lançamento do SDK são consideradas depende de como o dotnet está sendo invocado.

    • se você não estiver em Visual Studio, as versões de pré-lançamento serão consideradas.
    • se você estiver em 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 da SDK do .NET Core (em ferramentas > opções > recursos de visualização do ambiente > ), as versões de pré-lançamento serão consideradas; caso contrário, apenas as versões de lançamento serão consideradas.
  • Se um arquivo global. JSON for encontrado e não especificar uma versão do SDK, mas especificar um allowPrerelease valor, a versão mais recente do SDK instalada será usada (equivalente a definir rollForward como latestMajor ). Se a versão mais recente do SDK pode ser Release 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 apenas 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 rollForward valor for definido, ele será usado latestPatch como a rollForward política padrão. Caso contrário, verifique cada valor e seu comportamento na seção avanço .
    • 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

  • O seguinte aviso indica que seu projeto foi compilado usando uma versão de pré-lançamento do SDK do .NET Core:

    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. Mais em https://go.microsoft.com/fwlink/?linkid=869452 .

    As versões do SDK do .NET Core 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 com o SDK do .NET Core 3,0 ou uma versão posterior na seção allowPrerelease . Para computadores que nunca tinham um .NET Core 3,0 ou um tempo de execução ou SDK superior 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 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 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 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 anterior 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.

Confira também