Fijar dependencias de NuGet: PackageReference, gestión central de paquetes y packages.lock.json

Objetivo

Que cada restore de una aplicación produzca la misma clausura de paquetes en cualquier máquina y en CI, y que cualquier cambio en las dependencias aparezca como un diff revisable.

Requisitos previos

Proyectos de estilo SDK que usen PackageReference en lugar de packages.config, una única raíz de repositorio y un job de CI que ejecute dotnet restore como paso independiente.

Pasos

1. Entender las reglas que enumera la documentación sobre resolución de dependencias: versión mínima aplicable (una referencia a 4.0.0 significa al menos 4.0.0, y NuGet elige la versión más baja que cumpla todas las restricciones), prevalencia de la dependencia directa (direct-dependency-wins) y dependencias primas (cousin dependencies). Las versiones flotantes, como 4.*, optan por la coincidencia más reciente en cada restore.
2. Concentrar las versiones en un solo lugar: crear Directory.Packages.props en la raíz del repositorio con <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally> y un <PackageVersion Include="..." Version="..." /> por cada paquete; los archivos de proyecto mantienen <PackageReference Include="..." /> sin versión. La documentación indica que solo se importa automáticamente el Directory.Packages.props más cercano, así que conviene tener uno solo, salvo que se importe el del directorio superior de forma explícita.
3. Activar el archivo de bloqueo: establecer <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile> (en Directory.Build.props para todos los proyectos) y ejecutar dotnet restore; NuGet escribe packages.lock.json en la raíz de cada proyecto, con la clausura completa, incluidos los paquetes transitivos.
4. Hacer commit del archivo de bloqueo de cada aplicación o ejecutable que esté al inicio de una cadena de dependencias. En el caso de un proyecto de biblioteca del que dependen otros proyectos del repositorio, la documentación indica no incluir el archivo de bloqueo en el control de versiones: el restore del proyecto consumidor no lo usa (la documentación añade que conservarlo no causa problemas).
5. Restaurar en CI con dotnet restore --locked-mode (o RestoreLockedMode=true): si las dependencias declaradas cambiaron sin que se actualizara el archivo de bloqueo, el restore falla en lugar de regenerarlo en silencio.
6. Para actualizar: cambiar la versión en Directory.Packages.props, ejecutar dotnet restore sin modo bloqueado (NuGet detecta que cambió la entrada y reescribe el archivo de bloqueo; --force-evaluate solo hace falta para mover una versión flotante), revisar el diff del archivo de bloqueo y hacer commit de ambos archivos juntos.
7. Fijar el SDK con global.json (la documentación menciona la política rollForward con el valor disable): advierte de que los elementos PackageReference implícitos que añade el SDK cambian con la versión del SDK y provocan fallos en modo bloqueado.

Resultado esperado

Un clon nuevo restaura exactamente las mismas versiones; el git diff de una actualización muestra con precisión qué paquetes cambiaron, incluidos los transitivos; un paquete transitivo nuevo no puede entrar en el build sin que se note.

Límites y base de verificación

Las versiones flotantes y el modo bloqueado se contraponen; hay que elegir uno. Si hay varios target frameworks, el archivo de bloqueo contiene varios conjuntos de dependencias. Los archivos de bloqueo no sustituyen la fijación de orígenes de paquetes en nuget.config ni la verificación de firmas. Se trata de un procedimiento documentado; no se afirma ninguna medición de tiempos de restore.