Asignación de origen del paquete

La asignación de origen del paquete es una herramienta que se puede usar para mejorar la seguridad de la cadena de suministro, especialmente si usa una combinación de orígenes de paquetes públicos y privados.

De forma predeterminada, NuGet buscará todos los orígenes de paquetes configurados cuando necesite descargar un paquete. Cuando hay un paquete en varios orígenes, es posible que no sea determinista desde qué origen se descargará el paquete. Con la asignación de origen del paquete, puede filtrar por paquete qué orígenes debe buscar NuGet.

También tenemos sugerencias para otros procedimientos recomendados que le ayudarán a fortalecer su cadena de suministro contra ataques.

La asignación de origen del paquete se agregó en NuGet 6.0. A partir de Visual Studio 17.5, puede agregar y eliminar asignaciones de paquetes de origen con el cuadro de diálogo Opciones de Visual Studio.

Compatibilidad con Visual Studio

La característica está disponible en todas las herramientas integradas de NuGet.

• Visual Studio 2022 y versiones posteriores
• SDK de .NET 6.0.100 y versiones posteriores
• nuget.exe 6.0.0 y versiones posteriores

Las herramientas anteriores omitirán la configuración de asignación de origen del paquete. Para usar esta característica, asegúrese de que todos los entornos de compilación usan versiones de herramientas compatibles.

Las asignaciones de origen del paquete se aplicarán a todos los tipos de proyecto, incluido .NET Framework, siempre y cuando se utilicen herramientas compatibles.

Tutorial en vídeo

Si desea obtener información general en vídeo de la característica Asignación de origen del paquete, vea el vídeo Secure your NuGet packages with Package Source Mapping (Protección de los paquetes de NuGet con asignación de origen de paquetes) en YouTube.

Habilitación de la asignación de origen del paquete

Para participar en esta característica, debe tener un archivo nuget.config. Tener un solo nuget.config en la raíz del repositorio se considera un procedimiento recomendado. Consulte la documentación de nuget.config para obtener más información.

Habilitar mediante el cuadro de diálogo Opciones de Visual Studio

1. Abra su solución en Visual Studio.
2. Vaya al Package Source Mappings cuadro de diálogo Opciones.

Desde la interfaz de usuario del administrador de paquetes

• Seleccione un paquete de la lista para mostrarlo en el panel de detalles.
• Presione el botón Configure para abrir la página de opciones Asignaciones de origen de paquetes.

En el cuadro de diálogo Opciones de Visual Studio

• Vaya al menú Tools de la barra de herramientas principal de Visual Studio y elija NuGet Package Manager ->Package Manager Settings.
• Vaya a la página Package Source Mappings.

3. Presione el botón Add de la página Package Source Mappings para abrir el cuadro de diálogo Add Package Source Mappings.

4. Escriba un id. de paquete o un patrón de paquete y seleccione uno o varios orígenes de paquete alternando la casilla para los orígenes deseados.

5. La página de opciones Package Source Mapping mostrará la asignación de origen recién creada.

6. Presione OK en el cuadro de diálogo Opciones para guardar los cambios en el objeto aplicable nuget.config.
7. La ventana Administrador de paquetes NuGet se actualizará y reflejará el nuevo estado de las asignaciones de origen del paquete seleccionado.

Habilitación mediante la edición manual nuget.config

• Declare los orígenes de paquete deseados en el archivo nuget.config.
• Después de las declaraciones de origen, agregue un elemento <packageSourceMapping> que especifique las asignaciones deseadas para cada origen.
• Declare exactamente un elemento packageSource para cada origen en uso.
  • Agregue tantos patrones como sea necesario.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <!-- Define the package sources, nuget.org and contoso.com. -->
  <!-- `clear` ensures no additional sources are inherited from another config file. -->
  <packageSources>
    <clear />
    <!-- `key` can be any identifier for your source. -->
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="contoso.com" value="https://contoso.com/packages/" />
  </packageSources>
  
  <!-- Define mappings by adding package patterns beneath the target source. -->
  <!-- Contoso.* packages and NuGet.Common will be restored from contoso.com,
       everything else from nuget.org. -->
  <packageSourceMapping>
    <!-- key value for <packageSource> should match key values from <packageSources> element -->
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="contoso.com">
      <package pattern="Contoso.*" />
      <package pattern="NuGet.Common" />
    </packageSource>
  </packageSourceMapping>
</configuration>

La configuración de la asignación de origen del paquete se aplica siguiendo las reglas de prioridad de nuget.config cuando hay varios archivos nuget.config en varios niveles (nivel de máquina, nivel de usuario, nivel de repositorio).

Reglas de asignación de origen del paquete

Para obtener la máxima flexibilidad y control, NuGet requiere que todos los paquetes coincidan con un patrón de paquete mediante una prioridad bien definida.

Requisitos del patrón de paquete

Todos los paquetes solicitados deben asignarse a uno o varios orígenes coincidiendo con un patrón de paquete definido. En otras palabras, una vez que haya definido un elemento packageSourceMapping, debe definir explícitamente desde qué orígenes se restaurará cada paquete, incluidos los paquetes transitivos.

• Tanto los paquetes de nivel superior como los transitivos deben coincidir con los patrones definidos. No es necesario que un paquete de nivel superior y sus dependencias procedan del mismo origen.
• El mismo patrón de identificador se puede definir en varios orígenes, lo que permite restaurar los identificadores de paquete correspondientes desde cualquiera de las fuentes que definen el patrón. Sin embargo, esto no se recomienda debido al impacto en la previsibilidad de la restauración (un paquete determinado podría proceder de varios orígenes). Puede ser una configuración válida si confía en todos los orígenes respectivos.

Sintaxis del patrón de paquete

Prioridad del patrón de paquete

Cuando varios patrones únicos coinciden con un identificador de paquete, se prefiere el más específico. Los patrones de identificador de paquete siempre tienen la prioridad más alta, mientras que el * genérico siempre tiene la prioridad más baja. Para los patrones de prefijo de paquete, el más largo tiene prioridad.

Establecimiento de orígenes predeterminados

El patrón * se puede usar para declarar un origen predeterminado de facto, lo que significa que cualquier paquete que no coincida con otros patrones especificados se restaurará desde ese origen sin producir un error. Esta configuración es ventajosa si usa principalmente paquetes de, por ejemplo, nuget.org, y solo tiene algunos paquetes internos, o bien usa prefijos estándar para todos los paquetes internos, como Contoso.*.

Si su equipo no utiliza prefijos estándar para los identificadores de los paquetes internos o examina los paquetes nuget.org antes de su instalación, hacer que un origen privado sea el predeterminado se adaptará mejor a sus necesidades.

Introducción

Hay 2 maneras de incorporar completamente el repositorio, manualmente o mediante la herramienta NuGet.PackageSourceMapper.

Incorporación manual

Para la incorporación manual, puede realizar los pasos siguientes:

1. Declare una nueva carpeta de paquetes global para el repositorio.
2. Ejecute dotnet restore para restaurar las dependencias.
3. Ejecute dotnet list package --include-transitive para ver todos los paquetes de nivel superior y transitivos de la solución.
   • Para los proyectos de .NET Framework que usan packages.config, el archivo packages.config tendrá una lista plana de todos los paquetes directos y transitivos.
4. Defina asignaciones de forma que cada identificador de paquete de la solución (incluidos los paquetes transitivos) coincidan con un patrón para el origen de destino.
5. Ejecute dotnet nuget locals global-packages -c para borrar el directorio global-packages.
6. Ejecute la restauración para validar que ha configurado las asignaciones correctamente. Si sus asignaciones no cubren completamente cada identificador de paquete en su solución, los mensajes de error le ayudarán a identificar el problema.
7. Cuando la restauración se realice correctamente, ya habrá terminado. Opcionalmente, tenga en cuenta lo siguiente:
   • Simplificar la configuración a un menor número de declaraciones utilizando prefijos de identificador de paquetes más amplios o estableciendo una fuente predeterminada cuando sea posible.
   • Verificar el origen de cada paquete restaurado comprobando los archivos de metadatos en la carpeta de paquetes global o revisando los registros de restauración.

Incorporación automatizada mediante la herramienta

Muchos repositorios tienen un gran número de paquetes y el trabajo manualmente puede llevar mucho tiempo. La herramienta NuGet.PackageSourceMapper puede generar automáticamente un NuGet.config automáticamente, en función de los orígenes y paquetes conocidos del proyecto.

La herramienta del asignador de origen del paquete requiere que haya completado una restauración correcta del paquete en la que leerá cada archivo .nupkg.metadata respectivo generado como parte de la compilación para comprender mejor cómo se asignan los respectivos paquetes y orígenes. La herramienta no solo cubre las principales dependencias que también tiene en cuenta todas las dependencias transitivas al generar la asignación.

La herramienta tiene varias opciones para generar el patrón de asignación en función de sus necesidades, consulte la entrada de blog y la instrucción Léame de la herramienta para obtener más detalles.

Para obtener una idea del aspecto que pueden tener las asignaciones de origen, consulte nuestro repositorio de ejemplo.