Selección de la versión de .NET Core que se va a usarSelect the .NET Core version to use

En este artículo se explican las directivas que usan las herramientas de .NET Core, el SDK y el runtime para la selección de versiones.This article explains the policies used by the .NET Core tools, SDK, and runtime for selecting versions. 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.These policies provide a balance between running applications using the specified versions and enabling ease of upgrading both developer and end-user machines. Estas directivas realizan las siguientes acciones:These policies perform the following actions:

  • La implementación sencilla y eficaz de .NET Core, incluidas las actualizaciones de seguridad y confiabilidad.Easy and efficient deployment of .NET Core, including security and reliability updates.
  • Usar las herramientas y los comandos más recientes independientemente del runtime de destino.Use the latest tools and commands independent of target runtime.

La selección de versiones se produce:Version selection occurs:

En el resto de este documento se examinan los cuatro escenarios.The rest of this document examines those four scenarios.

El SDK usa la versión instalada más recienteThe SDK uses the latest installed version

Los comandos de SDK incluyen dotnet new y dotnet run.SDK commands include dotnet new and dotnet run. La CLI de .NET Core debe elegir una versión del SDK para cada comando dotnet.The .NET Core CLI must choose an SDK version for every dotnet command. Usa el SDK más reciente instalado en el equipo de forma predeterminada, aunque:It uses the latest SDK installed on the machine by default, even if:

  • El proyecto tenga como destino una versión anterior del entorno de ejecución de .NET Core.The project targets an earlier version of the .NET Core runtime.
  • La versión mas reciente del SDK de .NET Core sea una versión preliminar.The latest version of the .NET Core SDK is a preview version.

Puede beneficiarse de las características y mejoras del SDK más reciente mientras selecciona como destino versiones anteriores del runtime de .NET Core.You can take advantage of the latest SDK features and improvements while targeting earlier .NET Core runtime versions. Puede tener como destino varias versiones del runtime de .NET Core en otros proyectos, con las mismas herramientas del SDK para todos los proyectos.You can target multiple runtime versions of .NET Core on different projects, using the same SDK tools for all projects.

En raras ocasiones, es posible que tenga que usar una versión anterior del SDK.On rare occasions, you may need to use an earlier version of the SDK. Esa versión se especifica en un archivo global.json.You specify that version in a global.json file. 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 Core anterior a la versión instalada más reciente.The "use latest" policy means you only use global.json to specify a .NET Core SDK version earlier than the latest installed version.

global.json se puede colocar en cualquier lugar de la jerarquía de archivos.global.json can be placed anywhere in the file hierarchy. La CLI busca el primer archivo global.json hacia arriba desde el directorio del proyecto.The CLI searches upward from the project directory for the first global.json it finds. Puede controlar a qué proyectos se aplica un archivo global.json determinado mediante su lugar en el sistema de archivos.You control which projects a given global.json applies to by its place in the file system. 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.The .NET CLI searches for a global.json file iteratively navigating the path upward from the current working directory. El primer archivo global.json que se encuentra especifica la versión que se usa.The first global.json file found specifies the version used. Si esa versión del SDK está instalada, es la que se usa.If that SDK version is installed, that version is used. 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.If the SDK specified in the global.json is not found, the .NET CLI uses matching rules to select a compatible SDK, or fails if none is found.

En el ejemplo siguiente se muestra la sintaxis de global.json:The following example shows the global.json syntax:

{
  "sdk": {
    "version": "3.0.0"
  }
}

El proceso de selección de una versión del SDK es la siguiente:The process for selecting an SDK version is:

  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.dotnet searches for a global.json file iteratively reverse-navigating the path upward from the current working directory.
  2. dotnet usa el SDK especificado en el primer archivo global.json que encuentra.dotnet uses the SDK specified in the first global.json found.
  3. dotnet usa el SDK instalado más reciente si no se encuentra ningún archivo global.json.dotnet uses the latest installed SDK if no global.json is found.

Puede obtener más información sobre cómo seleccionar una versión del SDK en la sección Reglas de coincidencia del artículo sobre global.json.You can learn more about selecting an SDK version in the Matching rules section of the article on global.json.

Los monikers de la plataforma de destino definen las API de tiempo de compilaciónTarget Framework Monikers define build time APIs

El proyecto se compila con las API definidas en un moniker de la plataforma de destino (TFM).You build your project against APIs defined in a Target Framework Moniker (TFM). La plataforma de destino se especifica en el archivo del proyecto.You specify the target framework in the project file. Establezca el elemento TargetFramework del archivo del proyecto como se muestra en el ejemplo siguiente:Set the TargetFramework element in your project file as shown in the following example:

<TargetFramework>netcoreapp3.0</TargetFramework>

Puede compilar el proyecto con varios TFM.You may build your project against multiple TFMs. Configurar varias plataformas de destino es más común para las bibliotecas, pero también se puede hacer con las aplicaciones.Setting multiple target frameworks is more common for libraries but can be done with applications as well. Especifique una propiedad TargetFrameworks (el plural de TargetFramework).You specify a TargetFrameworks property (plural of TargetFramework). Las plataformas de destino se delimitan por punto y coma, como se muestra en el ejemplo siguiente:The target frameworks are semicolon-delimited as shown in the following example:

<TargetFrameworks>netcoreapp3.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.A given SDK supports a fixed set of frameworks, capped to the target framework of the runtime it ships with. Por ejemplo, el SDK de .NET Core 3.0 incluye el runtime .NET Core 3.0, que es una implementación de la plataforma de destino netcoreapp3.0.For example, the .NET Core 3.0 SDK includes the .NET Core 3.0 runtime, which is an implementation of the netcoreapp3.0 target framework. El SDK de .NET Core 3.0 admite netcoreapp2.1, netcoreapp2.2 y netcoreapp3.0, pero no netcoreapp3.1 (o una versión posterior).The .NET Core 3.0 SDK supports netcoreapp2.1, netcoreapp2.2, netcoreapp3.0, but not netcoreapp3.1 (or higher). El SDK de .NET Core 3.1 se instala para compilar para netcoreapp3.1.You install the .NET Core 3.1 SDK to build for netcoreapp3.1.

Las plataformas de destino de .NET Standard también se limitan a la plataforma de destino del runtime con el que se incluye el SDK..NET Standard target frameworks are also capped to the target framework of the runtime the SDK ships with. El SDK de .NET Core 3.1 está limitado a netstandard2.1.The .NET Core 3.1 SDK is capped to netstandard2.1. Para más información, consulte .NET Standard.For more information, see .NET Standard.

Puesta al día de las aplicaciones dependientes de la plataformaFramework-dependent apps roll forward

Cuando una aplicación se ejecuta desde el origen con dotnet run, desde una implementación dependiente del marco con dotnet myapp.dll o desde un ejecutable dependiente del marco con myapp.exe, el ejecutable dotnet es el host de la aplicación.When you run an application from source with dotnet run, from a framework-dependent deployment with dotnet myapp.dll, or from a framework-dependent executable with myapp.exe, the dotnet executable is the host for the application.

El host elige la versión de revisión más reciente instalada en el equipo.The host chooses the latest patch version installed on the machine. Por ejemplo, si se especifica netcoreapp3.0 en el archivo de proyecto, y 3.0.2 es el runtime de .NET instalado más reciente, se usa el runtime 3.0.2.For example, if you specified netcoreapp3.0 in your project file, and 3.0.2 is the latest .NET runtime installed, the 3.0.2 runtime is used.

Si no se encuentra ninguna versión de 3.0.* aceptable, se usa una versión de 3.* nueva.If no acceptable 3.0.* version is found, a new 3.* version is used. Por ejemplo, si se especificó netcoreapp3.0 y solo está instalado 3.1.0, la aplicación se ejecuta con el runtime 3.1.0.For example, if you specified netcoreapp3.0 and only 3.1.0 is installed, the application runs using the 3.1.0 runtime. Este comportamiento se conoce como "puesta al día de versión secundaria".This behavior is referred to as "minor version roll-forward." Las versiones inferiores no se considerarán.Lower versions also won't be considered. Cuando no hay ningún runtime aceptable instalado, la aplicación no se ejecutará.When no acceptable runtime is installed, the application won't run.

Algunos ejemplos de uso muestran el comportamiento; si indica como destino la versión 3.0:A few usage examples demonstrate the behavior, if you target 3.0:

  • ✔️ Se especifica la versión 3.0.✔️ 3.0 is specified. 3.0.3 es la versión de revisión instalada más reciente.3.0.3 is the highest patch version installed. Se usa la versión 3.0.3.3.0.3 is used.
  • ❌ Se especifica la versión 3.0.❌ 3.0 is specified. No hay ninguna versión 3.0.* instalada.No 3.0.* versions are installed. 2.1.1 es la versión del runtime instalada más alta.2.1.1 is the highest runtime installed. Se muestra un mensaje de error.An error message is displayed.
  • ✔️ Se especifica la versión 3.0.✔️ 3.0 is specified. No hay ninguna versión 3.0.* instalada.No 3.0.* versions are installed. 3.1.0 es la versión del runtime instalada más alta.3.1.0 is the highest runtime version installed. Se usa la versión 3.1.0.3.1.0 is used.
  • ❌ Se especifica la versión 2.0.❌ 2.0 is specified. No hay ninguna versión 2.x instalada.No 2.x versions are installed. 3.0.0 es la versión del runtime instalada más reciente.3.0.0 is the highest runtime installed. Se muestra un mensaje de error.An error message is displayed.

La puesta al día de versión secundaria tiene un efecto secundario que puede afectar a los usuarios finales.Minor version roll-forward has one side-effect that may affect end users. Considere el caso siguiente:Consider the following scenario:

  1. La aplicación especifica que se requiere la versión 3.0.The application specifies that 3.0 is required.
  2. Cuando se ejecuta, la versión 3.0.* no está instalada, pero sí que lo está la 3.1.0.When run, version 3.0.* is not installed, however, 3.1.0 is. Se usará la versión 3.1.0.Version 3.1.0 will be used.
  3. Más adelante, el usuario instala la versión 3.0.3 y ejecuta de nuevo la aplicación. Ahora se usará la versión 3.0.3.Later, the user installs 3.0.3 and runs the application again, 3.0.3 will now be used.

Es posible que las versiones 3.0.3 y 3.1.0 se comporten de forma diferente, especialmente en escenarios como la serialización de datos binarios.It's possible that 3.0.3 and 3.1.0 behave differently, particularly for scenarios like serializing binary data.

Las implementaciones autocontenidas incluyen el runtime seleccionado.Self-contained deployments include the selected runtime

Puede publicar una aplicación como una distribución autocontenida.You can publish an application as a self-contained distribution. Este enfoque empaqueta el runtime y las bibliotecas de .NET Core con la aplicación.This approach bundles the .NET Core runtime and libraries with your application. Las implementaciones autocontenidas no tienen una dependencia de los entornos de runtime.Self-contained deployments don't have a dependency on runtime environments. 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.Runtime version selection occurs at publishing time, not run time.

El proceso de publicación selecciona la versión de revisión más reciente de la familia de runtime indicada.The publishing process selects the latest patch version of the given runtime family. Por ejemplo, dotnet publish seleccionará .NET Core 3.0.3 si es la versión de revisión más reciente de la familia de runtime de .NET Core 3.0.For example, dotnet publish will select .NET Core 3.0.3 if it is the latest patch version in the .NET Core 3.0 runtime family. La plataforma de destino (incluidas las revisiones de seguridad instaladas más recientes) se empaqueta con la aplicación.The target framework (including the latest installed security patches) is packaged with the application.

Es un error que no se cumpla la versión mínima especificada para una aplicación.It's an error if the minimum version specified for an application isn't satisfied. 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 binds to the latest runtime patch version (within a given major.minor version family). dotnet publish no es compatible con la semántica de puesta al día de dotnet run.dotnet publish doesn't support the roll-forward semantics of dotnet run. Para obtener más información sobre las revisiones y las implementaciones autocontenidas, vea el artículo sobre selección de revisión de runtime en la implementación de aplicaciones .NET Core.For more information about patches and self-contained deployments, see the article on runtime patch selection in deploying .NET Core applications.

Las implementaciones autocontenidas pueden requerir una versión de revisión específica.Self-contained deployments may require a specific patch version. 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:You can override the minimum runtime patch version (to higher or lower versions) in the project file, as shown in the following example:

<RuntimeFrameworkVersion>3.0.3</RuntimeFrameworkVersion>

El elemento RuntimeFrameworkVersion invalida la directiva de versión predeterminada.The RuntimeFrameworkVersion element overrides the default version policy. Para las implementaciones autocontenidas, RuntimeFrameworkVersion especifica la versión de la plataforma de runtime exacta.For self-contained deployments, the RuntimeFrameworkVersion specifies the exact runtime framework version. Para las aplicaciones dependientes de la plataforma, RuntimeFrameworkVersion especifica la versión de la plataforma de runtime mínima que se requiere.For framework-dependent applications, the RuntimeFrameworkVersion specifies the minimum required runtime framework version.

Vea tambiénSee also