dotnet restore

Este artículo se aplica a: ✔️ SDK de .NET Core 3.1 y versiones posteriores

NOMBRE

dotnet restore: restaura las dependencias y las herramientas de un proyecto.

Sinopsis

dotnet restore [<ROOT>] [--configfile <FILE>] [--disable-build-servers]
    [--disable-parallel]
    [-f|--force] [--force-evaluate] [--ignore-failed-sources]
    [--interactive] [--lock-file-path <LOCK_FILE_PATH>] [--locked-mode]
    [--no-cache] [--no-dependencies] [--packages <PACKAGES_DIRECTORY>]
    [-r|--runtime <RUNTIME_IDENTIFIER>] [-s|--source <SOURCE>]
    [--tl:[auto|on|off]] [--use-current-runtime, --ucr [true|false]]
    [--use-lock-file] [-v|--verbosity <LEVEL>]

dotnet restore -h|--help

Descripción

Un proyecto de .NET suele hacer referencia a bibliotecas externas en paquetes NuGet que proporcionan funcionalidad adicional. Se hace referencia a estas dependencias externas en el archivo de proyecto (.csproj o .vbproj). Al ejecutar el comando dotnet restore, la CLI de .NET usa NuGet para buscar estas dependencias y descargarlas si es necesario. También garantiza que todas las dependencias requeridas por el proyecto sean compatibles entre sí y que no haya conflictos entre ellas. Una vez completado el comando, todas las dependencias requeridas por el proyecto están disponibles en una caché local y la CLI de .NET puede usarla para compilar y ejecutar la aplicación.

En la mayoría de los casos, no es necesario usar explícitamente el comando dotnet restore, ya que, en caso de que sea necesario realizar una restauración de NuGet, los comandos siguientes se ejecutan de forma implícita:

• dotnet new
• dotnet build
• dotnet build-server
• dotnet run
• dotnet test
• dotnet publish
• dotnet pack

A veces, puede que no sea conveniente ejecutar la restauración de NuGet implícita con estos comandos. Por ejemplo, algunos sistemas automatizados, como los sistemas de compilación, deben llamar a dotnet restore explícitamente para controlar cuándo se produce la restauración a fin de controlar el uso de la red. Para evitar la restauración implícita de NuGet, puede usar la marca --no-restore con cualquiera de estos comandos.

Nota

La comprobación del paquete firmado durante las operaciones de restauración requiere un almacén raíz de certificado válido para la firma de código y la marca de tiempo. Para obtener más información, consulte Comprobación del paquete firmado de NuGet.

Especificación de fuentes

Para restaurar las dependencias, NuGet necesita las fuentes donde se encuentran los paquetes. Las fuente se proporcionan normalmente mediante el archivo de configuración nuget.config. Cuando se instala el SDK de .NET, se proporciona un archivo de configuración predeterminado. Para especificar fuentes adicionales, realice una de las acciones siguientes:

• Cree su propio archivo nuget.config en el directorio del proyecto. Para obtener más información, vea Configuraciones comunes de NuGet y Diferencias de nuget.config más adelante en este artículo.
• Use comandos de dotnet nuget como dotnet nuget add source.

Puede invalidar las fuentes nuget.config con la opción -s.

Para obtener información sobre cómo usar las fuentes autenticadas, vea Consumir paquetes desde fuentes autenticadas.

Carpeta de paquetes globales

Para las dependencias, puede especificar dónde se colocan los paquetes restaurados durante la operación de restauración mediante el argumento --packages. Si no se especifica, se usa la caché de paquetes NuGet predeterminada, que se encuentra en el directorio .nuget/packages del directorio de inicio del usuario en todos los sistemas operativos. Por ejemplo, /home/usuario1 en Linux o C:\Usuarios\usuario1 en Windows.

Herramientas específicas del proyecto

Para herramientas específicas del proyecto, dotnet restore restaura primero el paquete en el que se empaqueta la herramienta y, a continuación, continúa con la restauración de las dependencias de la herramienta especificadas en su project.json.

Diferencias de nuget.config

El comportamiento del comando dotnet restore depende de las opciones de configuración del archivo nuget.config, si existe. Por ejemplo, establecer globalPackagesFolder en nuget.config coloca los paquetes NuGet restaurados en la carpeta especificada. Esta es una alternativa para especificar la opción --packages en el comando dotnet restore. Para más información, consulte la referencia de nuget.config.

Hay tres configuraciones específicas que dotnet restore omite:

• bindingRedirects

  Los redireccionamientos de enlace no funcionan con elementos de <PackageReference> y .NET solo admite elementos de <PackageReference> para los paquetes NuGet.

• solution

  Esta configuración es específica para Visual Studio y no se aplica a .NET. .NET no usa un archivo packages.config y, en su lugar, usa elementos de <PackageReference> para los paquetes NuGet.

• trustedSigners

  En el SDK 5.0.100 de .NET se ha agregado compatibilidad con la comprobación de la firma de paquetes multiplataforma.

Descargas de manifiestos de cargas de trabajo

Cuando se ejecuta, este comando inicia una descarga asincrónica en segundo plano de manifiestos de publicidad de cargas de trabajo. Si la descarga no ha terminado cuando finaliza el comando, se detiene. Para obtener más información, vea Manifiestos de publicidad.

Argumentos

• ROOT

  Ruta de acceso opcional del archivo de proyecto para restaurar.

Opciones

• -a|--arch <ARCHITECTURE>

  Especifica la arquitectura de destino. Se trata de una sintaxis abreviada para establecer el identificador del entorno de ejecución (RID), donde el valor proporcionado se combina con el RID predeterminado. Por ejemplo, en un equipo win-x64, al especificar --arch x86 se establece el RID en win-x86. Si usa esta opción, no use la opción -r|--runtime. Disponible a partir de .NET 6 (versión preliminar 7).

• --configfile <FILE>

  Archivo de configuración de NuGet (nuget.config) que se va a usar. Si se especifica, solo se usará la configuración de este archivo. Si no se especifica, se utilizará la jerarquía de archivos de configuración del directorio actual. Para más información, consulte Configuraciones comunes de NuGet.

• --disable-build-servers

  Obliga al comando a omitir los servidores de compilación persistentes. Esta opción proporciona una manera coherente de deshabilitar todo el uso del almacenamiento en caché de compilación, lo que fuerza una compilación desde cero. Una compilación que no se basa en memorias caché es útil cuando las memorias caché están dañadas o tienen un estado incorrecto por algún motivo. Disponible a partir del SDK de .NET 7.

• --disable-parallel

  Deshabilita la restauración de varios proyectos en paralelo.

• --force

  Fuerza la resolución de todas las dependencias, incluso si la última restauración se realizó correctamente. Especificar esta marca es lo mismo que eliminar el archivo project.assets.json.

• --force-evaluate

  Fuerza la restauración para volver a evaluar todas las dependencias aunque ya exista un archivo de bloqueo.

• -?|-h|--help

  Imprime una descripción de cómo usar el comando.

• --ignore-failed-sources

  Solo se advierte sobre los orígenes con error si hay paquetes que satisfagan el requisito de versión.

• --interactive

  Permite que el comando se detenga y espere una entrada o una acción del usuario. Por ejemplo, para completar la autenticación.

• --lock-file-path <LOCK_FILE_PATH>

  Ubicación de salida donde se escribe el archivo de bloqueo del proyecto. De forma predeterminada es PROJECT_ROOT\packages.lock.json.

• --locked-mode

  No permite actualizar el archivo de bloqueo del proyecto.

• --no-cache

  Especifica que no se almacenen en caché las solicitudes HTTP.

• --no-dependencies

  Al restaurar un proyecto con referencias de proyecto a proyecto (P2P), se restaura el proyecto raíz y no las referencias.

• --packages <PACKAGES_DIRECTORY>

  Especifica el directorio de los paquetes restaurados.

• -r|--runtime <RUNTIME_IDENTIFIER>

  Especifica un tiempo de ejecución para la restauración del paquete. Se usa para restaurar los paquetes con tiempos de ejecución que no se enumeran explícitamente en la etiqueta <RuntimeIdentifiers> del archivo .csproj. Para obtener una lista de identificadores de tiempo de ejecución (RID), consulte el catálogo de RID.

• -s|--source <SOURCE>

  Especifica el URI del origen del paquete NuGet que se usará durante la operación de restauración. Este valor invalida todos los orígenes especificados en los archivos nuget.config. Al especificar esta opción varias veces, se pueden proporcionar varios orígenes.

• --tl:[auto|on|off]

  Especifica si se debe usar el registrador de terminal para la salida de compilación. El valor predeterminado es auto, que primero comprueba el entorno antes de habilitar el registro de terminal. La comprobación del entorno comprueba que el terminal sea capaz de usar características de salida modernas y no usa una salida estándar redirigida antes de habilitar el nuevo registrador. La opción on omite la comprobación del entorno y habilita el registro de terminal. La opción off omite la comprobación del entorno y usa el registrador de consola predeterminado.

  El registrador de terminal muestra la fase de restauración seguida de la fase de compilación. Durante cada fase, los proyectos en compilación actuales aparecen en la parte inferior del terminal. Cada proyecto que se compila genera una salida del destino de MSBuild que se está compilando actualmente y la cantidad de tiempo invertido en ese destino. Puede buscar en esta información para obtener más información sobre la compilación. Cuando un proyecto termina de compilarse, se escribe una única sección "compilación completada" en la que se captura lo siguiente:

  • El nombre del proyecto compilado.
  • La plataforma de destino (si es de destino múltiple).
  • El estado de esa compilación.
  • La salida principal de esa compilación (con hipervínculo).
  • Los diagnósticos generados para ese proyecto.

  Esta opción está disponible a partir de .NET 8.

• --use-current-runtime, --ucr [true|false]

  Establece RuntimeIdentifier en una plataforma portátil RuntimeIdentifier, en función de la que haya en la máquina. Esto sucede implícitamente con propiedades que requieren un RuntimeIdentifier, como SelfContained, PublishAot, PublishSelfContained, PublishSingleFile, y PublishReadyToRun. Si la propiedad se establece en false, esa resolución implícita ya no se producirá.

• --use-lock-file

  Habilita la generación del archivo de bloqueo del proyecto y su uso con la restauración.

• -v|--verbosity <LEVEL>

  Establece el nivel de detalle del comando. Los valores permitidos son q[uiet], m[inimal], n[ormal], d[etailed] y diag[nostic]. De manera predeterminada, es minimal. Para obtener más información, vea LoggerVerbosity.

Ejemplos

• Restauración de dependencias y herramientas para el proyecto en el directorio actual:

  dotnet restore
  

• Restauración de dependencias y herramientas para el proyecto app1 encontrado en la ruta de acceso dada:

  dotnet restore ./projects/app1/app1.csproj
  

• Restaurar las dependencias y las herramientas para el proyecto en el directorio actual con la ruta de acceso de archivo proporcionada como origen:

  dotnet restore -s c:\packages\mypackages
  

• Restaurar las dependencias y las herramientas para el proyecto en el directorio actual mediante las dos rutas de acceso de archivo proporcionadas como orígenes:

  dotnet restore -s c:\packages\mypackages -s c:\packages\myotherpackages
  

• Restauración de dependencias y herramientas para el proyecto en el directorio actual que muestra una salida detallada:

  dotnet restore --verbosity detailed
  

Auditoría de vulnerabilidades de seguridad

A partir de .NET 8, puede participar en la auditoría de seguridad de NuGet para dotnet restore. Esta auditoría genera un informe de vulnerabilidades de seguridad con el nombre del paquete afectado, la gravedad de la vulnerabilidad y un vínculo a la advertencia para obtener más detalles.

Para participar en la auditoría de seguridad, establezca la propiedad <NuGetAudit> de MSBuild en true en el archivo del proyecto. Además, para recuperar el conjunto de datos de vulnerabilidades conocidas, asegúrese de que tiene el registro central de NuGet.org definido como uno de los orígenes del paquete:

<packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
</packageSources>

Puede configurar el nivel en el que se producirá un error en la auditoría estableciendo la propiedad <NuGetAuditLevel> de MSBuild. Los valores posibles son low, moderate, high y critical. Por ejemplo, si solo desea ver advertencias moderadas, altas y críticas, puede establecer la propiedad en moderate.