Información general de global.json

Artículo
06/05/2023

Este artículo se aplica a: ✔️ SDK de .NET Core 3.1 y versiones posteriores

El archivo global.json permite definir qué versión del SDK de .NET se usa al ejecutar comandos de la CLI de .NET. Seleccionar la versión del SDK de .NET es independiente de especificar el entorno de ejecución que el proyecto tiene como destino. La versión del SDK de .NET indica qué versión de la CLI de .NET se usa. En este artículo se explica cómo seleccionar la versión del SDK mediante global.json.

Si siempre quiere usar la versión más reciente del SDK instalada en la máquina, no necesita ningún archivo global.json. Sin embargo, en escenarios de CI (integración continua), es habitual que se quiera especificar un intervalo aceptable para la versión del SDK que se usa. El archivo global.json tiene una característica rollForward que proporciona formas flexibles de especificar un intervalo de versiones aceptable. Por ejemplo, en el siguiente archivo global.json se selecciona 6.0.300 o cualquier banda de características o revisión posterior para la versión 6.0 instalada en la máquina:

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

El SDK de .NET busca un archivo global.json en el directorio de trabajo actual (que no es necesariamente el mismo que el directorio del proyecto) o en uno de sus directorios principales.

Para obtener información sobre cómo especificar la versión del entorno de ejecución en lugar de la versión del SDK, consulte Marcos de destino.

Esquema de global.JSON

sdk

Tipo: object

Especifica información sobre el SDK de .NET que se va a seleccionar.

version

Tipo: string

La versión del SDK de .NET que se va a usar.

Este campo:

No admite caracteres comodín; es decir, debe especificar el número de versión completo.
No admite intervalos de versiones.

allowPrerelease

Tipo: boolean
Disponible a partir del SDK de .NET Core 3.0.

Indica si la resolución del SDK debe tener en cuenta las versiones preliminares a la hora de seleccionar la versión del SDK que se va a usar.

Si no se establece este valor de forma explícita, el valor predeterminado depende de si se está ejecutando desde Visual Studio:

Si no se está en Visual Studio, el valor predeterminado es true.
Si se está en Visual Studio, se usa el estado de versión preliminar solicitado. Es decir, si se usa una versión preliminar de Visual Studio o se establece la opción Usar versiones preliminares del SDK de .NET (en Herramientas>Opciones>Entorno>Características en versión preliminar), el valor predeterminado es true. De lo contrario, el valor predeterminado es false.

rollForward

Tipo: string
Disponible a partir del SDK de .NET Core 3.0.

Directiva de puesta al día que se va a usar al seleccionar una versión del SDK, ya sea como reserva si falta una versión específica del SDK o como una directiva para usar una versión superior. Se debe especificar una versión con un valor rollForward, a menos que se esté estableciendo en latestMajor. El comportamiento predeterminado de puesta al día lo determinan las reglas de coincidencia.

Para comprender las directivas disponibles y su comportamiento, tenga en cuenta las siguientes definiciones de una versión del SDK en el formato x.y.znn:

x es la versión principal.
y es la versión secundaria.
z es la banda de características.
nn es la versión de la revisión.

En la siguiente tabla se muestran los posibles valores de la clave rollForward:

Valor	Comportamiento
`patch`	Usa la versión especificada. Si no se encuentra, se pone al día hasta el nivel de revisión más reciente. Si no se encuentra, se produce un error. Este valor es el comportamiento heredado de las versiones anteriores del SDK.
`feature`	Usa el nivel de revisión más reciente para las versiones principal y secundaria y la banda de características especificadas. Si no se encuentra, se pone al día hasta la siguiente banda de características superior dentro de la misma versión principal/secundaria y usa el nivel de revisión más reciente para esa banda de características. Si no se encuentra, se produce un error.
`minor`	Usa el nivel de revisión más reciente para las versiones principal y secundaria y la banda de características especificadas. Si no se encuentra, se pone al día hasta la siguiente banda de características superior dentro de la misma versión principal/secundaria y usa el nivel de revisión más reciente para esa banda de características. Si no se encuentra, se pone al día hasta la siguiente versión secundaria y banda de características superiores dentro de la misma versión principal y usa el nivel de revisión más reciente para esa banda de características. Si no se encuentra, se produce un error.
`major`	Usa el nivel de revisión más reciente para las versiones principal y secundaria y la banda de características especificadas. Si no se encuentra, se pone al día hasta la siguiente banda de características superior dentro de la misma versión principal/secundaria y usa el nivel de revisión más reciente para esa banda de características. Si no se encuentra, se pone al día hasta la siguiente versión secundaria y banda de características superiores dentro de la misma versión principal y usa el nivel de revisión más reciente para esa banda de características. Si no se encuentra, se pone al día hasta la siguiente versión principal, secundaria y banda de características superiores y usa el nivel de revisión más reciente para esa banda de características. Si no se encuentra, se produce un error.
`latestPatch`	Usa el nivel de revisión instalado más reciente que coincide con la versión principal, secundaria y banda de características solicitadas con un nivel de revisión mayor o igual que el valor especificado. Si no se encuentra, se produce un error.
`latestFeature`	Usa la banda de características instalada superior y el nivel de revisión que coincide con la versión principal y secundaria solicitadas con una banda de características y un nivel de revisión que es mayor o igual que el valor especificado. Si no se encuentra, se produce un error.
`latestMinor`	Usa la versión secundaria y la banda de características instaladas superiores y el nivel de revisión que coincide con la versión principal solicitada con una versión secundaria, banda de características y nivel de revisión que es mayor o igual que el valor especificado. Si no se encuentra, se produce un error.
`latestMajor`	Usa el SDK de .NET más reciente que se haya instalado con una versión que es mayor o igual que el valor especificado. Si no se encuentra, se produce un error.
`disable`	No se pone al día. Se necesita una coincidencia exacta.

msbuild-sdks

Tipo: object

Permite controlar la versión del SDK del proyecto en un lugar, en vez de hacerlo en cada proyecto individual. Para más información, vea Resolución de los SDK de proyecto.

Comentarios en global.json

Los comentarios en global.json se admiten mediante comentarios de estilo de JavaScript o C#. Por ejemplo:

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

Ejemplos

En el ejemplo siguiente se muestra cómo no usar versiones preliminares:

{
  "sdk": {
    "allowPrerelease": false
  }
}

En este ejemplo se muestra cómo usar la versión superior instalada que es mayor o igual que la versión especificada. El JSON mostrado no permite ninguna versión del SDK anterior a 2.2.200 y permite 2.2.200 o cualquier versión posterior, incluidos 3.0.xxx y 3.1.xxx.

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

En el ejemplo siguiente se muestra cómo usar la versión exacta especificada:

{
  "sdk": {
    "version": "3.1.100",
    "rollForward": "disable"
  }
}

En este ejemplo se muestra cómo usar la versión de revisión y banda de características más reciente instalada de una versión principal y secundaria concreta. El JSON mostrado no permite ninguna versión del SDK anterior a 3.1.102 y permite 3.1.102 o cualquier versión 3.1.xxx posterior, como 3.1.103 o 3.1.200.

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

En este ejemplo se muestra cómo usar la versión de revisión superior instalada de una versión específica. El JSON mostrado no permite ninguna versión del SDK anterior a 3.1.102 y permite 3.1.102 o cualquier versión 3.1.1xx posterior, como 3.1.103 o 3.1.199.

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

global.json y la CLI de .NET

Para establecer una versión del SDK en el archivo global.json, resulta útil saber qué versiones del SDK están instaladas en el equipo. Para obtener información sobre cómo hacerlo, consulte Cómo comprobar que .NET ya está instalado.

Para instalar otras versiones del SDK de .NET en el equipo, visite la página Descargas de .NET.

Puede crear un archivo global.json en el directorio actual ejecutando el comando dotnet new, similar al ejemplo siguiente:

dotnet new globaljson --sdk-version 6.0.100

Reglas de coincidencia

Nota:

Las reglas de coincidencia se rigen por el punto de entrada de dotnet.exe, que es común en todos los entornos de ejecución instalados de .NET. Se usan las reglas de coincidencia de la última versión instalada del entorno de ejecución de .NET cuando se tienen varios instalados en paralelo o si usa un archivo global.json.

A la hora de determinar qué versión del SDK se usará, se aplican las reglas siguientes:

Si no se encuentra ningún archivo global.json o en global.json no se especifica una versión del SDK ni un valor allowPrerelease, se usa la versión del SDK instalada más reciente (lo que equivale a establecer rollForward en latestMajor). Según cómo se invoque dotnet, se tendrán en cuenta o no las versiones preliminares del SDK:
- Si no se está en Visual Studio, se tienen en cuenta las versiones preliminares.
- Si se está en Visual Studio, se usa el estado de versión preliminar solicitado. Es decir, si se usa una versión preliminar de Visual Studio o se establece la opción Usar versiones preliminares del SDK de .NET (en Herramientas>Opciones>Entorno>Características en versión preliminar), se tienen en cuenta las versiones preliminares; de lo contrario, solo se consideran las versiones publicadas.
Si se encuentra un archivo global.json que no especifica una versión del SDK pero sí un valor allowPrerelease, se usa la versión del SDK instalada superior (lo que equivale a establecer rollForward en latestMajor). El que la versión más reciente del SDK pueda ser publicada o preliminar, depende del valor de allowPrerelease. true indica que se tienen en cuenta las versiones preliminares; false indica que solo se tienen en cuenta las versiones publicadas.
Si se encuentra un archivo global.json y especifica una versión del SDK:
- Si no hay ningún valor rollForward establecido, se usa latestPatch como directiva de rollForward predeterminada. De lo contrario, vea cada valor y su comportamiento en la sección rollForward.
- En la sección allowPrerelease se explica si se tienen en cuenta las versiones preliminares y cuál es el comportamiento predeterminado cuando allowPrerelease no está establecido.

Solución de problemas de advertencias de compilación

Las advertencias siguientes indican que el proyecto se ha compilado con una versión preliminar del SDK de .NET:

Trabaja con una versión preliminar del SDK de .NET Core. Puede definir la versión del SDK a través de un archivo global.json en el proyecto actual. Más información en https://go.microsoft.com/fwlink/?linkid=869452.

Está usando una versión preliminar de .NET. Consulte: https://aka.ms/dotnet-core-preview

Las versiones del SDK de .NET tienen un historial y el compromiso de ser de alta calidad. Pero si no quiere usar una versión preliminar, vea las distintas estrategias que puede aplicar en la sección allowPrerelease. En el caso de los equipos que nunca han tenido instalado un SDK o un runtime de .NET Core 3.0 o superior, debe crear un archivo global.json y especificar la versión exacta que quiere usar.
La advertencia siguiente indica que el proyecto tiene como destino EF Core 1.0 ó 1.1, que no es compatible con el SDK de .NET Core 2.1 y versiones posteriores:

El proyecto de inicio "{proyectoDeInicio}" está destinado a la versión "{versiónPlataformaDeDestino}" de ".NETCoreApp". Esta versión de las herramientas de línea de comandos de Entity Framework Core .NET solo admite la versión 2.0 o superior. Para obtener información sobre el uso de versiones anteriores de las herramientas, vea https://go.microsoft.com/fwlink/?linkid=871254.

A partir del SDK de .NET Core 2.1 (versión 2.1.300), el comando dotnet ef se incluye en el SDK. Para compilar el proyecto, instale el SDK de .NET Core 2.0 (versión 2.1.201) o versiones anteriores en el equipo y defina la versión del SDK deseada mediante el archivo global.json. Para obtener más información sobre el comando dotnet ef, vea EF Core .NET Command-line Tools (Herramientas de línea de comandos de EF Core .NET).
Si usa global.json para mantenerse en una versión específica del SDK de .NET, tenga en cuenta que Visual Studio solo instala una sola copia del SDK de .NET. Por lo tanto, si actualiza la versión de Visual Studio, quita la versión anterior del SDK de .NET que había usado para instalar la nueva versión. Quita la versión anterior incluso si es una versión principal diferente de .NET.

Para evitar que Visual Studio quite las versiones del SDK de .NET, deberá instalar el SDK de .NET independiente desde la página de descarga. Tenga en cuenta que, si lo hace, ya no obtendrá actualizaciones automáticas de esa versión del SDK de .NET a través de Visual Studio y puede correr el riesgo de sufrir problemas de seguridad.

Consulte también

Resolución de los SDK de proyecto