Compartir a través de


Tutorial: Instalación y uso de una herramienta local de .NET mediante la CLI de .NET

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

En este tutorial se explica cómo instalar y usar una herramienta local. Usará una herramienta que ha creado en el primer tutorial de esta serie.

Prerrequisitos

  • Complete el primer tutorial de esta serie.

  • Instale el entorno de ejecución de .NET Core 2.1.

    En este tutorial se instala y se usa una herramienta destinada a .NET Core 2.1, por lo que debe tener ese entorno de ejecución instalado en el equipo. Para instalar la versión 2.1 del entorno de ejecución, vaya a la página de descarga de .NET Core 2.1 y busque el vínculo de instalación del entorno de ejecución en la columna Ejecutar aplicaciones: entorno de ejecución.

Creación de un archivo de manifiesto

Para instalar una herramienta solo para el acceso local (para el directorio y subdirectorios actuales), debe agregarse a un archivo de manifiesto.

Desde la carpeta microsoft.botsay, suba un nivel hasta la carpeta del repositorio .

cd ..

Cree un archivo de manifiesto; para ello, ejecute el comando dotnet new:

dotnet new tool-manifest

La salida indica la creación correcta del archivo.

The template "Dotnet local tool manifest file" was created successfully.

El archivo .config/dotnet-tools.json aún no tiene herramientas:

{
  "version": 1,
  "isRoot": true,
  "tools": {}
}

Las herramientas enumeradas en un archivo de manifiesto están disponibles para el directorio y subdirectorios actuales. El directorio actual es el que contiene el directorio .config con el archivo de manifiesto.

Cuando se usa un comando de la CLI que hace referencia a una herramienta local, el SDK busca un archivo de manifiesto en el directorio actual y en los directorios primarios. Si encuentra un archivo de manifiesto, pero el archivo no incluye la herramienta a la que se hace referencia, continúa la búsqueda a través de directorios primarios. La búsqueda finaliza cuando encuentra la herramienta a la que se hace referencia o encuentra un archivo de manifiesto con isRoot establecido en true.

Instalación de botsay como una herramienta local

Instale la herramienta desde el paquete que creó en el primer tutorial:

dotnet tool install --add-source ./microsoft.botsay/nupkg microsoft.botsay

Este comando agrega la herramienta al archivo de manifiesto que creó en el paso anterior. La salida del comando muestra en qué archivo de manifiesto se encuentra la herramienta recién instalada:

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

El archivo .config/dotnet-tools.json ahora tiene una herramienta:

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "microsoft.botsay": {
      "version": "1.0.0",
      "commands": [
        "botsay"
      ]
    }
  }
}

Uso de la herramienta

Invoque la herramienta ejecutando el comando dotnet tool run desde la carpeta del repositorio de:

dotnet tool run botsay hello from the bot

Restauración de una herramienta local instalada por otros usuarios

Normalmente, se instala una herramienta local en el directorio raíz del repositorio. Después de registrar el archivo de manifiesto en el repositorio, otros desarrolladores pueden obtener la versión más reciente del archivo. Para instalar todas las herramientas enumeradas en el archivo de manifiesto, pueden ejecutar un solo comando dotnet tool restore.

  1. Abra el archivo .config/dotnet-tools.json y reemplace el contenido por el siguiente JSON:

    {
      "version": 1,
      "isRoot": true,
      "tools": {
        "microsoft.botsay": {
          "version": "1.0.0",
          "commands": [
            "botsay"
          ]
        },
        "dotnetsay": {
          "version": "2.1.3",
          "commands": [
            "dotnetsay"
          ]
        }
      }
    }
    
  2. Guarde los cambios.

    Realizar este cambio es el mismo que obtener la versión más reciente del repositorio después de que otra persona haya instalado el paquete dotnetsay para el directorio del proyecto.

  3. Ejecute el comando dotnet tool restore.

    dotnet tool restore
    

    El comando genera resultados como en el ejemplo siguiente:

    Tool 'microsoft.botsay' (version '1.0.0') was restored. Available commands: botsay
    Tool 'dotnetsay' (version '2.1.3') was restored. Available commands: dotnetsay
    Restore was successful.
    
  4. Compruebe que las herramientas están disponibles:

    dotnet tool list
    

    La salida es una lista de paquetes y comandos, similar al ejemplo siguiente:

    Package Id      Version      Commands       Manifest
    --------------------------------------------------------------------------------------------
    microsoft.botsay 1.0.0        botsay         /home/name/repository/.config/dotnet-tools.json
    dotnetsay        2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json
    
  5. Pruebe las herramientas:

    dotnet tool run dotnetsay hello from dotnetsay
    dotnet tool run botsay hello from botsay
    

Actualización de una herramienta local

La versión instalada de la herramienta local dotnetsay es 2.1.3. Utilice el comando dotnet tool update para actualizar la herramienta a la versión más reciente.

dotnet tool update dotnetsay

La salida indica el nuevo número de versión:

Tool 'dotnetsay' was successfully updated from version '2.1.3' to version '2.1.7'
(manifest file /home/name/repository/.config/dotnet-tools.json).

El comando update busca el primer archivo de manifiesto que contiene el identificador del paquete y lo actualiza. Si no hay ningún identificador de paquete de este tipo en ningún archivo de manifiesto que esté en el ámbito de la búsqueda, el SDK agrega una nueva entrada al archivo de manifiesto más cercano. El ámbito de búsqueda va hacia los directorios principales hasta que se encuentra un archivo de manifiesto con isRoot = true.

Eliminación de herramientas locales

Ejecute el comando dotnet tool uninstall para quitar las herramientas instaladas:

dotnet tool uninstall microsoft.botsay
dotnet tool uninstall dotnetsay

Solución de problemas

Si recibe un mensaje de error al seguir el tutorial, consulte Solución de problemas de uso de herramientas de .NET.

Consulte también

Para obtener más información, vea Herramientas de .NET.