Procedimiento para administrar herramientas de .NET

  • Artículo

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

Una herramienta de .NET es un paquete NuGet especial que contiene una aplicación de consola. Puede instalar una herramienta en la máquina de las maneras siguientes:

  • Como herramienta global.

    Los archivos binarios de la herramienta se instalan en un directorio predeterminado que se agrega a la variable de entorno PATH. Puede invocar la herramienta desde cualquier directorio del equipo sin especificar su ubicación. Una versión de una herramienta se usa para todos los directorios del equipo.

  • Como herramienta global en una ubicación personalizada (también conocida como herramienta de ruta de acceso de herramientas).

    Los archivos binarios de la herramienta se instalan en la ubicación especificada. Puede invocar la herramienta desde el directorio de instalación, proporcionando el directorio con el nombre del comando, o agregando el directorio a la variable de entorno PATH. Una versión de una herramienta se usa para todos los directorios del equipo.

  • Como herramienta local (se aplica al SDK de .NET Core 3.0 y versiones posteriores).

    Los archivos binarios de la herramienta se instalan en un directorio predeterminado. Puede invocar la herramienta desde el directorio de instalación o cualquiera de sus subdirectorios. Distintos directorios pueden usar versiones diferentes de la misma herramienta.

    La CLI de .NET usa archivos de manifiesto para realizar un seguimiento de las herramientas que se instalan como locales en un directorio. Cuando el archivo de manifiesto se guarda en el directorio raíz de un repositorio de código fuente, un colaborador puede clonar el repositorio e invocar un solo comando de la CLI de .NET para instalar todas las herramientas enumeradas en los archivos de manifiesto.

Importante

Las herramientas de .NET se ejecutan con plena confianza. No instale una herramienta de .NET a menos que confíe en el autor.

Es posible que las herramientas de .NET no funcionen correctamente si .NET fue instalado a través de Snap.

Búsqueda de una herramienta

Estas son algunas formas de encontrar herramientas:

Comprobar el autor y las estadísticas

Las herramientas de .NET pueden ser eficaces porque se ejecutan con plena confianza y las herramientas globales se agregan a la variable de entorno PATH. No descargue herramientas de personas en las que no confíe.

Si la herramienta está hospedada en NuGet, busque la herramienta para comprobar el autor y las estadísticas.

Instalación de una herramienta global

Para instalar una herramienta como una herramienta global, use la opción -g o --global del comando dotnet tool install, tal como se muestra en el ejemplo siguiente:

dotnet tool install -g dotnetsay

La salida muestra el comando que se usa para invocar la herramienta y la versión instalada, de forma similar al ejemplo siguiente:

You can invoke the tool using the following command: dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed.

Nota

De manera predeterminada, la arquitectura de los binarios .NET que se van a instalar representa la arquitectura del sistema operativo que se está ejecutando en ese momento. Para especificar una arquitectura de SO diferente, consulte instalación de la herramienta .NET, opción --arch.

La ubicación predeterminada de los archivos binarios de una herramienta depende del sistema operativo:

SO Path
Linux/macOS $HOME/.dotnet/tools
Ventanas %USERPROFILE%\.dotnet\tools

Esta ubicación se agrega a la ruta del usuario cuando se ejecuta el SDK por primera vez. Por lo tanto, las herramientas globales se pueden invocar desde cualquier directorio sin especificar la ubicación de la herramienta.

El acceso a la herramienta es específico del usuario, no global de la máquina. Una herramienta global solo está disponible para el usuario que ha instalado la herramienta.

Instalación de una herramienta global en una ubicación personalizada

Para instalar una herramienta como herramienta global en una ubicación personalizada, use la opción --tool-path de instalación de la herramienta dotnet, como se muestra en los ejemplos siguientes:

En Windows:

dotnet tool install dotnetsay --tool-path c:\dotnet-tools

En Linux o macOS:

dotnet tool install dotnetsay --tool-path ~/bin

El SDK de .NET no agrega esta ubicación automáticamente a la variable de entorno PATH. Para invocar una herramienta de ruta de acceso de herramientas, debe asegurarse de que el comando está disponible mediante uno de los métodos siguientes:

  • Agregue el directorio de instalación a la variable de entorno PATH.
  • Especifique la ruta de acceso completa a la herramienta al invocarla.
  • Invoque la herramienta desde el directorio de instalación.

Instalación de una herramienta local

Se aplica al SDK de .NET Core 3.0 y versiones posteriores.

Si desea instalar una herramienta solo para el acceso local (para el directorio actual y subdirectorios), debe agregar la herramienta a un archivo de manifiesto de herramienta. Para crear un archivo de manifiesto de herramienta, ejecute el comando dotnet new tool-manifest:

dotnet new tool-manifest

Este comando crea un archivo de manifiesto denominado dotnet-tools.json en el directorio .config. Para agregar una herramienta local al archivo de manifiesto, use el comando dotnet tool install y omita las opciones --global y --tool-path, tal como se muestra en el ejemplo siguiente:

dotnet tool install dotnetsay

En la salida del comando se muestra en qué archivo de manifiesto se encuentra la herramienta que acaba de instalar, de manera similar al siguiente ejemplo:

You can invoke the tool from this directory using the following command:
dotnet tool run dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed.
Entry is added to the manifest file /home/name/botsay/.config/dotnet-tools.json.

En el ejemplo siguiente se muestra un archivo de manifiesto con dos herramientas locales instaladas:

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "botsay": {
      "version": "1.0.0",
      "commands": [
        "botsay"
      ]
    },
    "dotnetsay": {
      "version": "2.1.3",
      "commands": [
        "dotnetsay"
      ]
    }
  }
}

Normalmente, una herramienta local se agrega al directorio raíz del repositorio. Después de insertar el archivo de manifiesto en el repositorio, los desarrolladores que extraen código del repositorio obtienen el archivo de manifiesto más reciente. Para instalar todas las herramientas enumeradas en el archivo de manifiesto, ejecutan el comando dotnet tool restore:

dotnet tool restore

La salida indica las herramientas restauradas:

Tool 'botsay' (version '1.0.0') was restored. Available commands: botsay
Tool 'dotnetsay' (version '2.1.3') was restored. Available commands: dotnetsay
Restore was successful.

Instalación de una versión específica de la herramienta

Para instalar una versión preliminar o una versión específica de la herramienta, especifique el número de versión con la opción --version, tal como se muestra en el ejemplo siguiente:

dotnet tool install dotnetsay --version 2.1.3

Para instalar una versión preliminar de la herramienta sin especificar el número de versión exacto, use la opción --version y proporcione un carácter comodín, como se muestra en el ejemplo siguiente:

dotnet tool install --global dotnetsay --version "*-rc*"

Uso de una herramienta

El comando que se usa para invocar una herramienta puede ser diferente del nombre del paquete que se instala. Para mostrar todas las herramientas instaladas actualmente en el equipo para el usuario actual, use el comando dotnet tool list:

dotnet tool list

La salida muestra la versión y el comando de cada herramienta, de forma similar al ejemplo siguiente:

Package Id      Version      Commands       Manifest
-------------------------------------------------------------------------------------------
botsay          1.0.0        botsay         /home/name/repository/.config/dotnet-tools.json
dotnetsay       2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

Como se muestra en el ejemplo anterior, la lista muestra herramientas locales. Para ver las herramientas globales, use la opción --global. Para ver las herramientas de ruta de acceso de herramientas, use la opción --tool-path.

Para enumerar una herramienta específica, use el comando dotnet tool list <PACKAGE_ID>:

dotnet tool list dotnetsay

La salida solo mostrará esa herramienta si está instalada, similar al ejemplo siguiente:

Package Id      Version      Commands       Manifest
-------------------------------------------------------------------------------------------
dotnetsay       2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

Invocación de una herramienta global

En el caso de las herramientas globales, use el comando de la herramienta por sí solo. Por ejemplo, si el comando es dotnetsay o dotnet-doc, es lo que usa para invocar la herramienta global:

dotnetsay
dotnet-doc

Si el comando comienza con el prefijo dotnet-, una manera alternativa de invocar la herramienta es usar el comando dotnet y omitir el prefijo del comando de la herramienta. Por ejemplo, si el comando es dotnet-doc, el siguiente comando invoca la herramienta:

dotnet doc

Sin embargo, en el siguiente escenario no se puede usar el comando dotnet para invocar una herramienta global:

  • Una herramienta global y una herramienta local tienen el mismo comando con el prefijo dotnet-.
  • Quiere invocar la herramienta global desde un directorio que está en el ámbito de la herramienta local.

En este escenario, dotnet doc y dotnet dotnet-doc invocan a la herramienta local. Para invocar la herramienta global, use el comando por sí solo:

dotnet-doc

Invocación de una herramienta de ruta de acceso de herramientas

Para invocar una herramienta global instalada mediante la opción tool-path, asegúrese de que el comando está disponible como ya se explicó en este artículo.

Invocación de una herramienta local

Para invocar una herramienta local, tiene que usar el comando dotnet desde dentro del directorio de instalación. Puede usar el formato largo (dotnet tool run <COMMAND_NAME>) o el formato abreviado (dotnet <COMMAND_NAME>), tal como se muestra en los ejemplos siguientes:

dotnet tool run dotnetsay
dotnet dotnetsay

Si el comando tiene el prefijo dotnet-, puede incluir u omitir el prefijo al invocar la herramienta. Por ejemplo, si el comando es dotnet-doc, cualquiera de los siguientes ejemplos invoca la herramienta local:

dotnet tool run dotnet-doc
dotnet dotnet-doc
dotnet doc

Actualización de una herramienta

La actualización de una herramienta implica desinstalarla y reinstalarla con la versión estable más reciente. Para actualizar una herramienta, use el comando dotnet tool update con la misma opción que usó para instalar la herramienta:

dotnet tool update --global <packagename>
dotnet tool update --tool-path <packagename>
dotnet tool update <packagename>

Para una herramienta local, el SDK busca en el directorio actual y directorios primarios para buscar el primer archivo de manifiesto que contiene el identificador del paquete. Si no hay ningún identificador del paquete en ningún archivo de manifiesto, el SDK agrega una nueva entrada al archivo de manifiesto más cercano.

Desinstalación de una herramienta

Desinstale una herramienta mediante el comando dotnet tool uninstall con la misma opción que usó para instalar la herramienta:

dotnet tool uninstall --global <packagename>
dotnet tool uninstall --tool-path <packagename>
dotnet tool uninstall <packagename>

Para una herramienta local, el SDK busca en el directorio actual y directorios primarios para buscar el primer archivo de manifiesto que contiene el identificador del paquete.

Ayuda y solución de problemas

Si una herramienta no se puede instalar o ejecutar, vea Solución de problemas de uso de herramientas de .NET Core. Puede obtener una lista de los comandos y parámetros de dotnet tool disponibles mediante el parámetro --help:

dotnet tool --help

Para obtener instrucciones sobre el uso de la herramienta, escriba uno de los siguientes comandos o vea el sitio web de la herramienta:

<command> --help
dotnet <command> --help

Vea también