Visão geral do global.json

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 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"
  }
}

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 ancestrais.

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:

• 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

• 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 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: SDK do .NET 10.

Especifica os locais que devem ser considerados ao pesquisar um SDK do .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

• Digite: string
• Disponível desde: SDK do .NET 10.

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

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.

test

• Digite: object

Especifica informações sobre testes.

runner

• Digite: string
• Disponível desde: SDK do .NET 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 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 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 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 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 de visualização do .NET. Confira: https://aka.ms/dotnet-support-policy

  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}' tem como alvo o framework '.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. No entanto, 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.

Consulte também

• Como os SDKs de projeto são resolvidos