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

En este artículo se explican las directivas que usan las herramientas de .NET, el SDK y el entorno de ejecución para la selección de versiones. Estas directivas proporcionan un equilibrio entre la ejecución de aplicaciones con las versiones especificadas y facilitan la actualización de los equipos del desarrollador y el usuario final. Estas directivas permiten lo siguiente:

• La implementación sencilla y eficaz de .NET, incluidas las actualizaciones de seguridad y confiabilidad.
• Usar las herramientas y los comandos más recientes independientemente del runtime de destino.

La selección de versiones se produce:

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

En el resto de este documento se examinan los cuatro escenarios.

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

Los comandos de 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 el equipo de forma predeterminada, aunque:

• El proyecto tenga como destino una versión anterior del entorno de ejecución de .NET.
• La versión mas reciente del SDK de .NET sea una versión preliminar.

Puede beneficiarse de las características y mejoras del SDK más reciente mientras selecciona como destino versiones anteriores del entorno de ejecución de .NET. Puede seleccionar como destino diferentes versiones del entorno de ejecución de .NET mediante las mismas herramientas del SDK.

En raras ocasiones, es posible que tenga que usar una versión anterior del SDK. Esa versión se especifica en un archivo global.json. La directiva "usar la versión más reciente" significa que solo se usa global.json para especificar una versión del SDK de .NET anterior a la versión instalada más reciente.

global.json se puede colocar en cualquier lugar de la jerarquía de archivos. Puede controlar a qué proyectos se aplica un archivo global.json determinado mediante su lugar en el sistema de archivos. La CLI de .NET busca un archivo global.json de forma iterativa desplazándose hacia arriba en la ruta de acceso desde el directorio de trabajo actual (que no es necesariamente el mismo que el directorio del proyecto). El primer archivo global.json que se encuentra especifica la versión que se usa. Si esa versión del SDK está instalada, es la que se usa. Si no se encuentra el SDK especificado en global.json, la CLI de .NET usa reglas de coincidencia para seleccionar un SDK compatible, o bien se produce un error si no se encuentra ninguno.

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

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

El proceso de selección de una versión del SDK es la siguiente:

1. dotnet busca un archivo global.json de forma iterativa desplazándose hacia arriba de forma inversa en la ruta de acceso desde el directorio de trabajo actual.
2. dotnet usa el SDK especificado en el primer archivo global.json que encuentra.
3. dotnet usa el SDK instalado más reciente si no se encuentra ningún archivo 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.

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). La plataforma de destino se especifica en el archivo del proyecto. Establezca el elemento TargetFramework del archivo del proyecto como se muestra en el ejemplo siguiente:

<TargetFramework>net8.0</TargetFramework>

Puede compilar el proyecto con varios TFM. Configurar varias plataformas de destino es más común para las bibliotecas, pero también se puede hacer con las 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 plataformas, limitado a la plataforma de destino del runtime con el que se suministra. Por ejemplo, el SDK de .NET 8 incluye el entorno de ejecución de .NET 8, que es una implementación de la plataforma de destino net8.0. El SDK de .NET 8 admite net7.0, net6.0 y net5.0 pero no net9.0 (o una versión posterior). El SDK de .NET 9 se instala a fin de compilar para net9.0.

.NET Standard

.NET Standard ha sido una manera de seleccionar como destino una superficie de API compartida por distintas implementaciones de .NET. A partir de la publicación de .NET 5, que es un estándar de API propiamente dicho, .NET Standard tiene poca relevancia, excepto en un escenario: resulta útil cuando se quiere seleccionar como destino .NET y .NET Framework. .NET 5 implementa todas las versiones anteriores de .NET Standard.

Para obtener más información, vea .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 el equipo. Por ejemplo, si se especifica net5.0 en el archivo de proyecto, y 5.0.2 es el runtime de .NET instalado más reciente, se usa el runtime 5.0.2.

Si no se encuentra ninguna versión de 5.0.* aceptable, se usa una versión de 5.* nueva. Por ejemplo, si se especificó net5.0 y solo está instalado 5.1.0, la aplicación se ejecuta con el runtime 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 hay ningún runtime aceptable instalado, la aplicación no se ejecutará.

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

• ✔️ Se especifica la versión 5.0. 5.0.3 es la versión de revisión más alta instalada. Se usa la versión 5.0.3.
• ❌ Se especifica la versión 5.0. No hay ninguna versión 5.0.* instalada. 3.1.1 es la versión más alta instalada del entorno de ejecución. 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 más alta instalada del entorno de ejecución. Se usa la versión 5.1.0.
• ❌ Se especifica la versión 3.0. No hay ninguna versión 3.x instalada. 5.0.0 es la versión más alta instalada del entorno de ejecución. Se muestra un mensaje de error.

La puesta al día de versión secundaria tiene un efecto secundario que puede afectar a los usuarios finales. Considere el caso siguiente:

1. La aplicación especifica que se necesita la versión 5.0.
2. Cuando se ejecuta, la versión 5.0.* no está instalada, pero sí que lo está la 5.1.0. Se va a usar la versión 5.1.0.
3. Más adelante, el usuario instala la versión 5.0.3 y ejecuta de nuevo la aplicación. Ahora se usará la versión 5.0.3.

Es posible que las versiones 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 puesta al día de una aplicación se puede configurar de cuatro maneras diferentes:

1. Valor de nivel del proyecto si se establece la propiedad <RollForward>:

   <PropertyGroup>
     <RollForward>LatestMinor</RollForward>
   </PropertyGroup>
   

2. Archivo *.runtimeconfig.json.

   Este archivo se genera al compilar la aplicación. Si se establece la propiedad <RollForward> en el proyecto, se reproduce en el archivo *.runtimeconfig.json como el valor 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"
       }
     }
   }
   

3. Propiedad --roll-forward <value> del comando dotnet.

   Al ejecutar una aplicación, puede controlar el comportamiento de la puesta al día desde la línea de comandos:

   dotnet run --roll-forward LatestMinor
   dotnet myapp.dll --roll-forward LatestMinor
   myapp.exe --roll-forward LatestMinor
   

4. Variable de entorno DOTNET_ROLL_FORWARD.

Prioridad

El comportamiento de puesta al día se establece en el orden siguiente cuando se ejecuta la aplicación; los elementos de mayor numeración tienen prioridad sobre los de menor numeración:

1. En primer lugar, se evalúa el archivo de configuración *.runtimeconfig.json.
2. A continuación, se tiene en cuenta la variable de entorno DOTNET_ROLL_FORWARD, y se reemplaza la comprobación anterior.
3. 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:

Las implementaciones autocontenidas incluyen el runtime seleccionado.

Puede publicar una aplicación como una distribución autocontenida. Este enfoque empaqueta el entorno de ejecución y las bibliotecas de .NET con la aplicación. Las implementaciones autocontenidas no tienen una dependencia de los entornos de runtime. La selección de la versión del runtime se produce en el momento de la publicación, no en el 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 la versión de revisión más reciente de la familia de entorno 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 enlaza a la versión de revisión de runtime más reciente (dentro de una familia de versión principal.secundaria determinada). 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 autocontenidas pueden requerir una versión de revisión 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.

Vea también

• Descarga e instalación de .NET
• Procedimiento para quitar el entorno de ejecución y el SDK de .NET