Seleccione la versión de .NET que se va a usar.

Artículo
02/10/2025

En este artículo se explican las directivas que usan las herramientas de .NET, el SDK y el entorno de ejecución para seleccionar versiones. Estas directivas proporcionan un equilibrio entre las aplicaciones en ejecución mediante las versiones especificadas y la facilidad de actualización de máquinas de desarrollador y de usuario final. Estas directivas habilitan:

Implementación sencilla y eficaz de .NET, incluidas las actualizaciones de seguridad y confiabilidad.
Use las herramientas y comandos más recientes independientemente del entorno de ejecución de destino.

Se produce la selección de versión:

Al ejecutar un comando del SDK, el SDK usa la versión instalada más reciente.
Al compilar un ensamblado, los monikers de la plataforma de destino definen las API de tiempo de compilación.
Al ejecutar una aplicación .NET, las aplicaciones dependientes de la plataforma de destino se ponen al día.
Al publicar una aplicación autocontenida, las implementaciones autocontenidas incluyen el runtime seleccionado.

El resto de este documento examina esos cuatro escenarios.

El SDK usa la versión instalada más reciente.

Los comandos del SDK incluyen dotnet new y dotnet run. La CLI de .NET debe elegir una versión del SDK para cada comando dotnet. Usa el SDK más reciente instalado en la máquina de forma predeterminada, incluso si:

El proyecto tiene como destino una versión anterior del entorno de ejecución de .NET.
La versión más reciente del SDK de .NET es una versión preliminar.

Puede aprovechar las características y mejoras más recientes del SDK, al tiempo que tiene como destino versiones anteriores del entorno de ejecución de .NET. Puede tener como destino diferentes versiones en tiempo de ejecución de .NET mediante las mismas herramientas del SDK.

En algunas circunstancias, es posible que tenga que usar una versión específica del SDK. Especifique esa versión en un archivo global.json.

global.json se pueden colocar en cualquier lugar de la jerarquía de archivos. Puede controlar a qué proyectos se aplica un global.json determinado por su lugar en el sistema de archivos. La CLI de .NET busca iterativamente un archivo de global.json al navegar por la ruta de acceso hacia arriba desde el directorio de trabajo actual (que no es necesariamente igual que el directorio del proyecto). El primer archivo global.json encontrado especifica la versión usada. Si se instala esa versión del SDK, se usa esa versión. Si no se encuentra el SDK especificado en el global.json, la CLI de .NET usa reglas de coincidencia para seleccionar un SDK compatible o se produce un error si no se encuentra ninguno.

En el ejemplo siguiente se muestra la sintaxis global.json:

{
  "sdk": {
    "version": "5.0.0"
  }
}

El proceso para seleccionar una versión del SDK es:

dotnet busca un archivo de global.json de forma iterativa que desplaza hacia arriba la ruta de acceso desde el directorio de trabajo actual.
dotnet usa el SDK especificado en el primer global.json encontrado.
dotnet usa el SDK instalado más reciente si no se encuentra ningún global.json.

Para obtener más información sobre la selección de versiones del SDK, vea las secciones Reglas de coincidencia y rollForward del artículo Información general de global.json.

Actualización de la versión del SDK

Es importante actualizar a la versión más reciente del SDK periódicamente para adoptar las características, mejoras de rendimiento y correcciones de errores más recientes. Para comprobar fácilmente las actualizaciones del SDK, use el comando dotnet sdk check. Además, si selecciona una versión específica con global.json, considere la posibilidad de usar una herramienta como Dependabot para actualizar automáticamente la versión del SDK anclada a medida que estén disponibles las nuevas versiones.

Los monikers de la plataforma de destino definen las API de tiempo de compilación

El proyecto se compila con las API definidas en un moniker de la plataforma de destino (TFM). En el archivo del proyecto, especificas el marco de destino . Establezca el elemento TargetFramework en el archivo de proyecto como se muestra en el ejemplo siguiente:

<TargetFramework>net8.0</TargetFramework>

Puede compilar el proyecto con varios TFM. Establecer varias plataformas de destino es más común para las bibliotecas, pero también se puede realizar con aplicaciones. Especifique una propiedad TargetFrameworks (el plural de TargetFramework). Las plataformas de destino se delimitan por punto y coma, como se muestra en el ejemplo siguiente:

<TargetFrameworks>net8.0;net47</TargetFrameworks>

Un SDK determinado admite un conjunto fijo de frameworks, limitado al framework objetivo del entorno de ejecución con el que se distribuye. Por ejemplo, el SDK de .NET 8 incluye el entorno de ejecución de .NET 8, que es una implementación del marco de destino de net8.0. El SDK de .NET 8 admite net7.0, net6.0y net5.0, pero no net9.0 (o superior). El SDK de .NET 9 se instala a fin de compilar para net9.0.

.NET Standard

.NET Standard era una manera de tener como destino una superficie de API compartida por diferentes implementaciones de .NET. A partir de la versión de .NET 5, que es un estándar de API propio, .NET Standard tiene poca relevancia, excepto en un escenario: .NET Standard es útil cuando se quiere tener como destino .NET y .NET Framework. .NET 5 implementa todas las versiones de .NET Standard.

Para obtener más información, consulte .NET 5 y .NET Standard.

Puesta al día de aplicaciones dependientes de la plataforma

Cuando una aplicación se ejecuta desde el origen con dotnet run, desde una implementación dependiente del marco condotnet myapp.dll o desde un ejecutable dependiente del marco con myapp.exe, el ejecutable dotnet es el host de la aplicación.

El host elige la versión de revisión más reciente instalada en la máquina. Por ejemplo, si especificó net5.0 en el archivo de proyecto y 5.0.2 es el entorno de ejecución de .NET más reciente instalado, se usa el entorno de ejecución de 5.0.2.

Si no se encuentra ninguna versión de 5.0.* aceptable, se usa una nueva versión de 5.*. Por ejemplo, si especificó net5.0 y solo 5.1.0 está instalado, la aplicación se ejecuta mediante el entorno de ejecución de 5.1.0. Este comportamiento conoce como "puesta al día de versión secundaria". Tampoco se tendrán en cuenta versiones inferiores. Cuando no se instala ningún entorno de ejecución aceptable, la aplicación no se ejecutará.

Algunos ejemplos de uso muestran el comportamiento, si tiene como destino la versión 5.0:

✔️ Se especifica la versión 5.0. 5.0.3 es la versión de parche más alta instalada. Se usa 5.0.3.
❌ Se especifica la versión 5.0. No hay ninguna versión 5.0.* instalada. 3.1.1 es el tiempo de ejecución más alto instalado. Se muestra un mensaje de error.
✔️ Se especifica la versión 5.0. No hay ninguna versión 5.0.* instalada. 5.1.0 es la versión en tiempo de ejecución más alta instalada. Se usa 5.1.0.
❌ Se especifica la versión 3.0. No hay ninguna versión 3.x instalada. 5.0.0 es el tiempo de ejecución más alto instalado. Se muestra un mensaje de error.

La actualización de versiones menores tiene un efecto secundario que puede afectar a los usuarios finales. Tenga en cuenta el siguiente escenario:

La aplicación especifica que se requiere la versión 5.0.
Cuando se ejecuta, la versión 5.0.* no está instalada, pero 5.1.0 es. Se usará la versión 5.1.0.
Más adelante, el usuario instala 5.0.3 y ejecuta la aplicación de nuevo, ahora se usará la versión 5.0.3.

Es posible que 5.0.3 y 5.1.0 se comporten de forma diferente, especialmente en escenarios como la serialización de datos binarios.

Control del comportamiento de puesta al día

Antes de invalidar el comportamiento de puesta al día predeterminado, familiarícese con el nivel de compatibilidad del entorno de ejecución de .NET.

El comportamiento de avance de una aplicación se puede configurar de cuatro maneras diferentes:

Configuración de nivel de proyecto estableciendo la propiedad <RollForward>:
```
<PropertyGroup>
  <RollForward>LatestMinor</RollForward>
</PropertyGroup>
```
Archivo *.runtimeconfig.json.

Este archivo se genera al compilar la aplicación. Si la propiedad <RollForward> se estableció en el proyecto, se reproduce en el archivo *.runtimeconfig.json como el ajuste rollForward. Los usuarios pueden editar este archivo para cambiar el comportamiento de la aplicación.
```
{
  "runtimeOptions": {
    "tfm": "net5.0",
    "rollForward": "LatestMinor",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "5.0.0"
    }
  }
}
```
Propiedad --roll-forward <value> del comando dotnet.

Al ejecutar una aplicación, puede controlar el comportamiento de avance desde la línea de comandos.
```
dotnet run --roll-forward LatestMinor
dotnet myapp.dll --roll-forward LatestMinor
myapp.exe --roll-forward LatestMinor
```
Variable de entorno DOTNET_ROLL_FORWARD.

Precedencia

El comportamiento de avance se establece en el siguiente orden cuando se ejecuta la aplicación: los elementos numerados más altos tienen prioridad sobre los numerados menores.

En primer lugar, se evalúa el archivo de configuración de *.runtimeconfig.json.
A continuación, se tiene en cuenta la variable de entorno DOTNET_ROLL_FORWARD, reemplazando la comprobación anterior.
Por último, cualquier parámetro --roll-forward pasado a la aplicación en ejecución invalida todo lo demás.

Valores

Con independencia de cómo configure el valor de puesta al día, use uno de los valores siguientes para establecer el comportamiento:

Valor	Descripción
`Minor`	predeterminado si no se especifica. Puesta al día con la versión secundaria mínima superior, si no se encuentra la versión secundaria solicitada. Si la versión secundaria solicitada está presente, se usa la directiva `LatestPatch`.
`Major`	Puesta al día con la siguiente versión principal superior disponible, y con la versión secundaria mínima si no se encuentra la versión principal solicitada. Si la versión principal solicitada está presente, se usa la directiva `Minor`.
`LatestPatch`	Puesta al día con la versión de revisión más alta. Este valor deshabilita la puesta al día de versiones secundarias.
`LatestMinor`	Puesta al día con la versión secundaria más alta, aunque la versión secundaria solicitada esté presente.
`LatestMajor`	Puesta al día con la última versión principal y la última versión secundaria, aunque la versión principal solicitada esté presente.
`Disable`	No se realiza la puesta al día, solo se enlaza a la versión especificada. Esta política no se recomienda para uso general, ya que deshabilita la capacidad de aplicar los últimos parches. Este valor solo se recomienda para las pruebas.

Las implementaciones independientes incluyen el entorno de ejecución seleccionado.

Puede publicar una aplicación como una distribución independiente . Este enfoque agrupa el entorno de ejecución y las bibliotecas de .NET con la aplicación. Las implementaciones independientes no tienen dependencia de entornos de ejecución. La selección de la versión en tiempo de ejecución se produce en tiempo de publicación, no en tiempo de ejecución.

El evento restore que tiene lugar al realizar la publicación selecciona la versión de revisión más reciente de la familia de entorno de ejecución indicada. Por ejemplo, dotnet publish seleccionará .NET 5.0.3 si es el último parche de la familia de tiempo de ejecución de .NET 5. La plataforma de destino (incluidas las revisiones de seguridad instaladas más recientes) se empaqueta con la aplicación.

Se produce un error si no se cumple la versión mínima especificada para una aplicación. dotnet publish se vincula a la versión de parche en tiempo de ejecución más reciente (dentro de una determinada familia de versiones principales/secundarias). dotnet publish no es compatible con la semántica de puesta al día de dotnet run. Para más información sobre las revisiones e implementaciones autocontenidas, consulte el artículo sobre selección de revisión del tiempo de ejecución en la implementación de aplicaciones .NET.

Las implementaciones independientes pueden requerir una versión de parche específica. Puede invalidar la versión de revisión de runtime mínima (para versiones superiores o inferiores) en el archivo del proyecto, como se muestra en el ejemplo siguiente:

<PropertyGroup>
  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>

El elemento RuntimeFrameworkVersion invalida la directiva de versión predeterminada. Para las implementaciones autocontenidas, RuntimeFrameworkVersion especifica la versión de la plataforma de runtime exacta. Para las aplicaciones dependientes de la plataforma, RuntimeFrameworkVersion especifica la versión de la plataforma de runtime mínima que se requiere.

Compartir vía