Compartir por

Actualización a una nueva versión de .NET

Las nuevas versiones de .NET se publican cada año. Varios desarrolladores inician el proceso de actualización en cuanto la nueva versión está disponible, mientras que otros esperan hasta que ya no se admita la versión que usan. El proceso de actualización tiene varios aspectos que se deben tener en cuenta.

Motivos comunes para actualizar a una nueva versión de .NET:

  • Ya no se admite la versión de .NET usada actualmente
  • La nueva versión admite un nuevo sistema operativo
  • La nueva versión tiene una característica importante de API, rendimiento o seguridad

Actualización del entorno de desarrollo

Para actualizar a una nueva versión de .NET, el SDK de .NET es el componente principal que se debe instalar. Este incluye una CLI de .NET actualizada, un sistema de compilación y una versión en tiempo de ejecución.

El sitio web de .NET ofrece instaladores y archivos que puede descargar y usar en cualquier sistema operativo y arquitectura compatibles.

Algunos sistemas operativos tienen un administrador de paquetes que también puede usar para instalar una nueva versión de .NET; podría preferir esto.

Visual Studio instala nuevas versiones del SDK de .NET automáticamente. Para los usuarios de Visual Studio, es suficiente actualizar a una versión más reciente de Visual Studio.

Actualización del código fuente

El único cambio necesario para actualizar una aplicación es actualizar la propiedad TargetFramework en un archivo de proyecto a la versión más reciente de .NET.

Siga este procedimiento:

  • Abra el archivo del proyecto (el archivo *.csproj, *.vbproj o *.fsproj).
  • Cambie el valor de propiedad <TargetFramework> de, por ejemplo, net6.0 a net8.0.
  • Si se usa, el mismo patrón se aplica a la propiedad <TargetFrameworks>.

Sugerencia

La funcionalidad de modernización - actualización de la aplicación GitHub Copilot puede realizar estos cambios automáticamente.

El siguiente paso es compilar el proyecto (o la solución) con el nuevo SDK. Si se necesitan cambios adicionales, el SDK proporcionará advertencias y errores que le guiarán.

Es posible que tenga que ejecutar dotnet workload restore para restaurar cargas de trabajo con la nueva versión del SDK.

Más recursos:

Anclaje de versiones

Al actualizar herramientas de desarrollo como el SDK de .NET, Visual Studio u otros componentes, es posible que encuentre nuevos comportamientos, advertencias de analizador o cambios importantes que afecten al proceso de compilación. Al anclar a una versión, puede actualizar el entorno de desarrollo mientras mantiene el control sobre cuándo se actualizan los componentes específicos en los proyectos.

El anclaje de versiones proporciona varias ventajas:

  • Compilaciones predecibles: garantiza resultados de compilación coherentes en diferentes máquinas y entornos de CI/CD.
  • Adopción gradual: permite adoptar nuevas características de forma incremental en lugar de todas a la vez.
  • Evitar cambios inesperados: impide que las nuevas reglas del analizador, los comportamientos del SDK o las versiones del paquete causen errores de compilación.
  • Coordinación del equipo: permite que los equipos se actualicen juntos en un momento planeado en lugar de individualmente cuando se actualicen las herramientas.
  • Depuración y solución de problemas: facilita el aislamiento de problemas al controlar qué versiones han cambiado.

En las secciones siguientes se describen varios mecanismos para controlar versiones de distintos componentes en los proyectos de .NET:

Control de la versión del SDK con global.json

Puede fijar la versión del SDK de .NET para un proyecto o solución usando un archivo global.json. Este archivo especifica la versión del SDK que se va a usar al ejecutar comandos de la CLI de .NET y es independiente de la versión en tiempo de ejecución que tiene como destino el proyecto.

Cree un archivo global.json en el directorio raíz de la solución:

dotnet new globaljson --sdk-version 9.0.100 --roll-forward latestFeature

Este comando crea el siguiente archivo global.json que ancla el SDK a la versión 9.0.100 o cualquier revisión o banda de características posterior dentro de la versión principal 9.0:

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

La rollForward directiva controla cómo se selecciona la versión del SDK cuando la versión exacta no está disponible. Esta configuración garantiza que, al actualizar Visual Studio o instalar un nuevo SDK, el proyecto seguirá usando SDK 9.0.x hasta que actualice explícitamente el archivo global.json .

Para obtener más información, consulte global.json información general.

Comportamiento del analizador de control

Los analizadores de código pueden introducir nuevas advertencias o cambiar el comportamiento entre versiones. Puede controlar las versiones del analizador para mantener compilaciones coherentes mediante la AnalysisLevel propiedad . Esta propiedad permite bloquear a una versión específica de las reglas del analizador, lo que impide que se introduzcan nuevas reglas al actualizar el SDK.

<PropertyGroup>
  <AnalysisLevel>9.0</AnalysisLevel>
</PropertyGroup>

Cuando se establece en 9.0, solo se habilitan las reglas del analizador que vienen con .NET 9, incluso si usa el SDK de .NET 10. Esto impide que las nuevas reglas del analizador de .NET 10 afecten a la compilación hasta que esté listo para abordarlas.

Para obtener más información, vea AnalysisLevel.

Control de versiones de paquetes NuGet

Al administrar las versiones de paquetes de forma coherente entre proyectos, puede evitar actualizaciones inesperadas y mantener compilaciones confiables.

Archivos de bloqueo de paquetes

Los archivos de bloqueo de paquetes garantizan que las operaciones de restauración de paquetes usen exactamente las mismas versiones de paquete en distintos entornos. El archivo de bloqueo (packages.lock.json) registra las versiones exactas de todos los paquetes y sus dependencias.

Habilite los archivos de bloqueo en el archivo del proyecto:

<PropertyGroup>
  <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
</PropertyGroup>

Para asegurarse de que se produce un error en las compilaciones si el archivo de bloqueo no está actualizado:

<PropertyGroup>
  <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
  <RestoreLockedMode>true</RestoreLockedMode>
</PropertyGroup>

Después de habilitar los archivos de bloqueo, ejecute dotnet restore para generar el archivo packages.lock.json . Confirme este archivo en el control de código fuente.

Administración central de paquetes

La administración central de paquetes (CPM) permite administrar las versiones de paquetes en una sola ubicación para todos los proyectos de una solución. Este enfoque simplifica la administración de versiones y garantiza la coherencia entre proyectos.

Cree un archivo Directory.Packages.props en la raíz de la solución:

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

  <ItemGroup>
    <PackageVersion Include="Azure.Identity" Version="1.17.0" />
    <PackageVersion Include="Microsoft.Extensions.AI" Version="9.10.1" />
  </ItemGroup>
</Project>

En los archivos del proyecto, haga referencia a paquetes sin especificar una versión:

<ItemGroup>
  <PackageReference Include="Azure.Identity" />
  <PackageReference Include="Microsoft.Extensions.AI" />
</ItemGroup>

Asignación de origen del paquete

La asignación de origen del paquete permite controlar qué orígenes de NuGet se usan para paquetes específicos, mejorando la seguridad y la confiabilidad.

Configure la asignación de origen en el archivo nuget.config:

<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="contoso" value="https://contoso.com/packages/" />
  </packageSources>

  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="contoso">
      <package pattern="Contoso.*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

Esta configuración garantiza que todos los paquetes que comienzan con Contoso. solo se restauren desde el origen contoso, mientras que otros paquetes proceden de nuget.org.

Para obtener más información, consulte Restauración de paquetes NuGet.

Control de la versión de MSBuild

Visual Studio admite la instalación en paralelo de varias versiones. Por ejemplo, puede instalar Visual Studio 2026 y Visual Studio 2022 en la misma máquina. Cada versión de Visual Studio incluye un SDK de .NET correspondiente. Al actualizar Visual Studio, también se actualiza la versión del SDK incluida. Sin embargo, puede seguir usando versiones anteriores del SDK instalándolas independientemente de la página de descarga de .NET.

Las versiones de MSBuild corresponden a las versiones de Visual Studio. Por ejemplo, Visual Studio 2022, versión 17.8, incluye MSBuild 17.8. El SDK de .NET también incluye MSBuild. Cuando se usa dotnet build, se usa la versión de MSBuild incluida con el SDK especificado por global.json o el SDK instalado más reciente.

Para usar una versión específica de MSBuild:

  • Use dotnet build con una versión del SDK anclada en global.json.
  • Inicie el símbolo del sistema de desarrolladores de Visual Studio que sea adecuado, el cual configura el entorno para la versión de MSBuild correspondiente a esa versión de Visual Studio.
  • Invoque directamente MSBuild desde una instalación específica de Visual Studio (por ejemplo, "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe").

Para obtener más información, vea SDK de .NET, MSBuild y control de versiones de Visual Studio.

Actualización de la integración continua (CI)

Las canalizaciones de CI siguen un proceso de actualización similar a los archivos de proyecto y de tipo Dockerfile. Por lo general, puede actualizar canalizaciones de CI cambiando solo los valores de versión.

Actualización del entorno de hospedaje

Hay muchos patrones que se usan para hospedar aplicaciones. Si el entorno de hospedaje incluye el entorno de ejecución de .NET, debe instalarse la nueva versión del entorno de ejecución de .NET. En Linux, las dependencias deben instalarse, pero no suelen cambiar entre versiones de .NET.

En el caso de los contenedores, se deben cambiar las instrucciones FROM para que incluyan nuevos números de versión.

En el siguiente ejemplo de Dockerfile se muestra cómo extraer una imagen de ASP.NET Core 9.0.

FROM mcr.microsoft.com/dotnet/aspnet:9.0

En un servicio en la nube como Azure App Service, se necesita un cambio de configuración.

Consulte también

  • Last updated on