Visão geral do global.json

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

O ficheiro global.json permite-te definir qual .NET versão do SDK é usada quando executas comandos .NET CLI. Selecionar a versão do SDK .NET é independente de especificar a versão de execução que um projeto pretende. A versão do SDK .NET indica qual a versão da CLI .NET utilizada. 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 ficheiro global.json seguinte seleciona a 10.0.100 ou qualquer banda de funcionalidades ou patch posterior para a 10.0 que esteja instalado na máquina:

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

Dependes de dois componentes no SDK .NET para procurar um ficheiro global.json. Cada componente começa numa localização diferente e pesquisa através de diretórios de antepassados:

• .NET SDK muxer trata dos comandos dotnet CLI. Começa no diretório de trabalho atual, que não é necessariamente o mesmo que o diretório do projeto.
• .NET MSBuild project SDK resolver resolve SDKs de projeto durante as compilações. Começa no diretório que contém um ficheiro de solução, caso exista. Se não existir ficheiro de solução, começa a partir do diretório que contém o ficheiro do projeto atual. Se nenhum dos ficheiros existir, utiliza o diretório de trabalho atual.

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.

esquema global.json

sdk

Tipo: object

Especifica informações sobre o SDK .NET a selecionar.

version

• Tipo: string

A versão do SDK .NET a usar.

Este campo:

• Requer o número de versão completo, como 10.0.100.
• Não suporta números de versão como 10, 10.0 ou 10.0.x.
• Não tem suporte para wildcard.
• Não suporta intervalos de versões.

allowPrerelease

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

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 não definires este valor explicitamente, o valor padrão depende de estares a correr a partir do Visual Studio:

• Se não estiveres em Visual Studio, o valor padrão é true.
• Se estiveres no Visual Studio, ele usa o estado de pré-lançamento solicitado. Isto é, se estiveres a usar uma versão Preview do Visual Studio ou definires a opção Usar pré-visualizações do SDK .NET (em Tools>Options>Environment>Feature Preview Features), O valor padrão é true. Caso contrário, o valor padrão é false.

rollForward

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

A política de atualização progressiva a ser utilizada ao selecionar uma versão do SDK, quer seja como um recurso alternativo 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 funcionalidades.
• nn é a versão do patch.

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

Value	Behavior
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 versão principal, menor e de funcionalidades especificada. Se não for encontrado, passa 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, falha.
minor	Usa o nível de patch mais recente para a versão principal, menor e de funcionalidades especificada. Se não for encontrado, prossegue para a próxima faixa de características superior dentro da mesma versão maior/menor e utiliza o nível de correções mais recente para essa faixa de características. Se não for encontrado, avança para a próxima banda menor e de funcionalidades superior dentro da mesma principal e usa o nível de patch mais recente para essa banda de funcionalidades. Se não for encontrado, falha.
major	Usa o nível de patch mais recente para a versão principal, menor e de funcionalidades especificada. Se não for encontrado, prossegue para a próxima faixa de características superior dentro da mesma versão maior/menor e utiliza o nível de correções mais recente para essa faixa de características. Se não for encontrado, avança para a próxima banda menor e de funcionalidades superior dentro da mesma principal e usa o nível de patch mais recente para essa banda de funcionalidades. Se não for encontrado, avança para o próximo nível superior de major, minor e banda de funcionalidades, utilizando o nível de patch mais recente para essa banda de funcionalidades. 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 faixa de funcionalidades instalada mais alta e o nível de patch que corresponde às versões principais e secundárias solicitadas, com uma faixa de funcionalidades e nível de patch maior ou igual ao valor especificado. Se não for encontrado, falha.
latestMinor	Usa o maior instalado, a banda de funcionalidades e o nível de patch que correspondem ao major solicitado com um menor, banda de funcionalidades e nível de patch que sejam maiores ou iguais 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. Caso não seja encontrado, falhar.
disable	Não rola para a frente. É necessária uma correspondência exata.

paths

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

Especifica as localizações que devem ser consideradas ao procurar um SDK .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 SDK locais (como SDKs relativos a uma raiz de repositório ou colocados em uma pasta personalizada) que não são instalados globalmente no sistema.

A funcionalidade "caminhos" só funciona quando se usam comandos que envolvem o SDK .NET, como dotnet run. Ele NÃO afeta cenários como executar o iniciador apphost nativo (app.exe), executar com dotnet app.dll, ou executar 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 só lugar, em vez de em cada projeto individual. Para obter mais informações, consulte Como os SDKs de projeto são resolvidos.

test

• Tipo: object

Especifica informações sobre testes.

runner

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

O executor de testes utilizado para descobrir e executar testes.

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.*/
  }
}

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 faixa de funcionalidades e a versão mais recente do patch instalada 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"
  }
}

O exemplo a seguir mostra como especificar caminhos de pesquisa 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 seguinte 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 o .NET CLI

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 informações sobre como fazer isso, veja Como verificar se o .NET já está instalado.

Para instalar versões adicionais de SDK .NET na sua máquina, visite a página Download .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

Note

As regras de correspondência são regidas pelo ponto de entrada dotnet.exe, que é comum a todos os runtimes instalados do .NET. As regras de correspondência para a versão mais recente instalada do .NET Runtime são usadas quando tens vários runtimes instalados lado a lado ou se estiveres a usar um ficheiro 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 não estiveres no Visual Studio, serão consideradas as versões pré-lançamento.
  • Se estiveres no Visual Studio, ele usa o estado de pré-lançamento solicitado. Isto é, se estiveres a usar uma versão Preview do Visual Studio ou definires a opção Usar pré-visualizações do SDK .NET (em Tools>Options>Environment>Feature Preview Features), são consideradas versões pré-lançamento; caso contrário, apenas as versões de lançamento sã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 ficheiro global.json for encontrado e especificar uma versão do SDK:

  • Se nenhum valor rollForward for definido, será usado patch 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 seguintes avisos indicam que o seu projeto foi compilado usando uma versão pré-lançamento do SDK .NET:

  Estás a usar uma versão de pré-visualização do .NET. Veja: https://aka.ms/dotnet-support-policy

  As versões do .NET SDK têm uma história e 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 instalado um runtime ou SDK .NET Core 3.0 ou superior, precisa de criar um ficheiro global.json e especificar a versão exata que pretende usar.

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

  O projeto inicial '{startupProject}' destina-se ao framework '.NETCoreApp' versão '{targetFrameworkVersion}'. Esta versão das Ferramentas de Linha de Comandos Entity Framework Core .NET só suporta 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 .NET SDK Core 2.1 (versão 2.1.300), o comando dotnet ef vem incluído no SDK. Para compilar o seu projeto, instale .NET SDK Core 2.0 (versão 2.1.201) ou anterior na sua máquina e defina a versão desejada do SDK usando o ficheiro global.json. Para mais informações sobre o comando dotnet ef, consulte EF Core .NET Ferramentas de linha de comandos.

• Se estiveres a usar global.json para ficares numa versão específica do .NET SDK, nota que Visual Studio só instala uma única cópia do .NET SDK. Por isso, se atualizares a versão do Visual Studio, ele remove a versão anterior do SDK .NET que usou para instalar a nova versão. Remove a versão antiga, mesmo que seja uma versão .NET principal diferente.

Para evitar que o Visual Studio remova versões do .NET SDK, instale o .NET SDK autónomo a partir da página de download. No entanto, se o fizer, já não receberá atualizações automáticas dessa versão do .NET SDK através do Visual Studio e poderá estar em risco de problemas de segurança.

Ver também

• Como os SDKs de projeto são resolvidos