Evitar el aviso de compilación "NETSDK1057: You are using a preview version of .NET" usando global.json

martes, 17 de junio de 2025

Pantalla de ordenador mostrando el aviso NETSDK1057 y global.json sugerido como solución del problema

Si os gusta trastear con las previews de .NET en el mismo equipo en el que estáis desarrollando proyectos que usan versiones estables, es posible que al compilar encontréis en la consola o ventana Output de vuestro IDE favorito un mensaje de error parecido al siguiente:

NETSDK1057: You are using a preview version of .NET. See: https://aka.ms/dotnet-support-policy

Básicamente, el sistema nos está informando de que estamos usando un SDK que aún está en fase de pruebas, o preview. Aunque esto no debería ser un problema porque el SDK debería ser totalmente compatible hacia atrás, simplemente es un recordatorio de que no es la versión estable y siempre podríamos encontrarnos algún problema.

Esto ocurre porque los comandos del SDK utilizan la última versión instalada en el equipo, por lo que, si hemos instalado una versión preliminar, será ésta la que se utilice. Podemos comprobarlo fácilmente ejecutando el siguiente comando en consola, que nos mostrará la versión del SDK que se está utilizando por defecto:

 C:\> dotnet --version
10.0.100-preview.5.25277.14

Normalmente, el mensaje NETSDK1057 podemos ignorarlo sin problema, pero si por cualquier motivo queremos eliminarlo o simplemente queremos forzar el uso de una versión determinada del SDK de .NET en algún proyecto o de forma global, podremos hacerlo usando un archivo llamado global.json.

Forzar la versión del SDK

Para forzar el uso de una versión específica del SDK de .NET, bien sea de forma global o bien en un proyecto concreto, lo primero que debemos hacer es determinar qué versiones del SDK tenemos instaladas en nuestro equipo. Para ello, podemos ejecutar el siguiente comando en la consola:

C:\> dotnet --list-sdks
2.1.818 [C:\Program Files\dotnet\sdk]
3.1.426 [C:\Program Files\dotnet\sdk]
6.0.301 [C:\Program Files\dotnet\sdk]
6.0.321 [C:\Program Files\dotnet\sdk]
7.0.120 [C:\Program Files\dotnet\sdk]
8.0.117 [C:\Program Files\dotnet\sdk]
8.0.206 [C:\Program Files\dotnet\sdk]
8.0.411 [C:\Program Files\dotnet\sdk]
9.0.301 [C:\Program Files\dotnet\sdk]
10.0.100-preview.5.25277.14 [C:\Program Files\dotnet\sdk]

Una vez sabemos qué versiones del SDK tenemos instaladas y cuál queremos forzar, lo siguiente es crear un archivo llamado global.json. Su ubicación es importante, porque su ámbito se extiende a todos los proyectos que estén en la misma carpeta o en sus subdirectorios a cualquier nivel de profundidad.

Es decir, si creamos el archivo global.json en la raíz de un proyecto, afectará únicamente a ese proyecto y a sus subproyectos. Si lo creamos en una carpeta superior, por ejemplo en la carpeta de una solución, afectará a todos sus proyectos, que típicamente se encontrarán en subdirectorios. Si lo creamos en la carpeta raíz de un disco duro, afectará a todos los proyectos guardados en él.

El archivo global.json es un archivo JSON con una estructura muy sencilla (podéis consultarla siguiendo este enlace). Básicamente en él indicaremos la versión del SDK que queremos forzar a los proyectos que se encuentren en su ámbito, así como algunas opciones adicionales para personalizar su comportamiento.

Veamos un ejemplo sencillo. Si queremos forzar el uso de la versión 9.0.301 en un proyecto, basta con crear el archivo global.json en su raíz con el siguiente contenido:

{
  "sdk": {
    "version": "9.0.301"
  }
}

La propia CLI de .NET también nos permite hacerlo usando el comando dotnet new global.json --sdk-version <version>, que creará el archivo global.json en la carpeta actual, forzando la versión del SDK que le indiquemos. El contenido del archivo creado será exactamente el mismo que el del ejemplo anterior:

C:\MyProject>dotnet new global.json --sdk-version 9.0.301
The template "global.json file" was created successfully.
C:\MyProject>type global.json
{
  "sdk": {
    "version": "9.0.301"
  }
}

En cualquiera de los casos, si sobre la misma carpeta o alguna de sus subcarpetas consultamos el SDK utilizado por defecto, obtendremos el valor esperado:

C:\MyProject>dotnet --version
9.0.301

C:\MyProject>md Test

C:\MyProject>cd Test

C:\MyProject\Test>dotnet --version
9.0.301

A partir de este momento, dado que ya no estamos usando la versión preview del SDK, el mensaje de aviso habrá desaparecido 😊

Posibles efectos secundarios

Sin duda, usara global.json es una forma muy sencilla de forzar una versión del SDK de .NET en un proyecto o en un conjunto de proyectos. Sin embargo, al hacerlo también podemos estar introduciendo algunos inconvenientes que debemos considerar.

En primer lugar, si forzamos una versión del SDK que no está instalada en el equipo, obtendremos un error al intentar compilar o ejecutar el proyecto. Normalmente no ocurrirá en casos de desarrolladores aislados o si se hace de forma global, pero pueden surgir problemas si trabajamos en un equipo de desarrollo y alguno de los miembros no tiene instalada la versión del SDK que hemos forzado, pues se encontrará con el error al intentar compilar el proyecto.

Por ejemplo, si forzamos en el global.json el uso del SDK 9.0.400, que no está instalado en el equipo, al intentar compilar el proyecto obtendremos un error similar al siguiente:

C:\MyProject>dotnet build
The command could not be loaded, possibly because:
  * You intended to execute a .NET application:
      The application 'build' does not exist or is not a managed .dll or .exe.
  * You intended to execute a .NET SDK command:
      A compatible .NET SDK was not found.

Requested SDK version: 9.0.400
global.json file: C:\MyProject\global.json

También debemos tener en cuenta que al forzar una versión específica del SDK, podemos estar limitando el uso de nuevas características o mejoras que se vayan introduciendo en versiones posteriores del SDK. Es decir, si la versión estable actual es la 9.0.301 y se lanza la 9.0.400, no pasaremos a usar esta última de forma automática, será necesario actualizar el global.json para referenciar la nueva versión.

Por último, a la hora de forzar una versión del SDK, sobre todo si se hace de forma global, también es importante tener en cuenta que cada versión del SDK admite un conjunto de versiones del runtime de .NET. Por ejemplo, si forzamos el uso del SDK 9.0.301, no podremos compilar o ejecutar proyectos cuyo <TargetFramework> en el archivo .csproj sea superior a net9.0, como net10.0 o posteriores:

C:\MyProject>dotnet build
C:\Program Files\dotnet\sdk\9.0.301\Sdks\Microsoft.NET.Sdk\targets\Microsoft.NET.TargetFrameworkInference.targets(166,5): error NETSDK1045: The current .NET SDK does not support targeting .NET 10.0.  Either target .NET 9.0 or lower, or use a version of the .NET SDK that supports .NET 10.0. Download the .NET SDK from https://aka.ms/dotnet/download

Cómo forzar la última versión estable

Afortunadamente, muchos de estos problemas podemos solucionarlos usando opciones adicionales en el archivo global.json.

Por ejemplo, si queremos que el SDK use la última versión estable instalada en el equipo, sea cual sea su número de versión, podemos usar la opción allowPrerelease. Dado que no usamos la propiedad version para especificar una versión concreta, el sistema simplemente buscará la más reciente que no sea preview:

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

El valor por defecto de allowPrerelease puede variar según el entorno. En la CLI suele ser true, pero si estamos en Visual Studio, depende de lo que hayamos configurado en la sección Herramientas>Opciones>Entorno>Características de versión preliminar.

Adicionalmente, existe la propiedad rollForward, que nos permite controlar cómo se comporta el SDK cuando no existe la versión del SDK que hemos especificado en la propiedad version, o cómo actuar si existen versiones posteriores a la especificada. Pero esto, si os interesa, lo veremos en un artículo posterior, y mientras tanto, podéis consultar la documentación oficial para más detalles.

Conclusión

En resumen, el uso de global.json nos permite tener un control preciso sobre la versión del SDK de .NET utilizada en nuestros proyectos, evitando sorpresas y mensajes de advertencia relacionados con versiones preliminares. Sin embargo, es importante conocer sus implicaciones y utilizarlo de forma consciente, especialmente en entornos colaborativos.

¡Espero que os resulte útil!