Procedimiento para administrar herramientas de .NET

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. Una herramienta se puede instalar en el equipo de las siguientes maneras:

  • 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 o 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 con 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 que instale 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.

Búsqueda de una herramienta

Estas son algunas formas de encontrar herramientas:

Comprobar el autor y las estadísticas

Como las herramientas de .NET se ejecutan con plena confianza y las herramientas globales se agregan a la variable de entorno PATH, pueden ser muy eficaces. 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.

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

SO Ruta de acceso
Linux/macOS $HOME/.dotnet/tools
Windows %USERPROFILE%\.dotnet\tools

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

El acceso a las herramientas es específico del usuario, no de la máquina global. 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 una herramienta global, use la opción --tool-path del comando dotnet tool install, tal 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, tiene que 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.

Para instalar una herramienta solo para el acceso local (del directorio y los subdirectorios actuales), debe agregarse a un archivo de manifiesto de la 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 el archivo de manifiesto en el que 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 qué herramientas se han restaurado:

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

Tal como se muestra en este ejemplo, la lista muestra las herramientas locales. Para ver las herramientas globales, use la opción --global y, para ver herramientas de ruta de acceso de herramientas, use la opción --tool-path.

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, eso es lo que se usa para invocar el comando:

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 que se instala mediante la opción tool-path, asegúrese de que el comando está disponible, tal como se explicó anteriormente en este artículo.

Invocación de una herramienta local

Para invocar una herramienta local, tiene que usar el comando dotnet desde el 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>

En el caso de una herramienta local, el SDK encuentra el primer archivo de manifiesto que contiene el identificador de paquete mediante la búsqueda en el directorio actual y en los directorios principales. 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

Quite 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>

En el caso de una herramienta local, el SDK encuentra el primer archivo de manifiesto que contiene el identificador de paquete mediante la búsqueda en el directorio actual y en los directorios principales.

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