Usar a CLI do LibMan com ASP.NET Core

Por Scott Addie

A CLI do LibMan é uma ferramenta multiplataforma com suporte em todos os lugares com suporte do .NET Core.

Pré-requisitos

Instalação

Para instalar a CLI do LibMan:

dotnet tool install -g Microsoft.Web.LibraryManager.Cli

Uma Ferramenta Global do .NET Core é instalada no pacote NuGet Microsoft.Web.LibraryManager.Cli.

Para instalar a CLI do LibMan de uma fonte de pacote NuGet específica:

dotnet tool install -g Microsoft.Web.LibraryManager.Cli --version 1.0.94-g606058a278 --add-source C:\Temp\

No exemplo anterior, uma Ferramenta Global do .NET Core é instalada do arquivo C:\Temp\Microsoft.Web.LibraryManager.Cli.1.0.94-g606058a278.nupkg do computador Windows local.

Uso

Após a instalação bem-sucedida da CLI, o seguinte comando pode ser usado:

libman

Para exibir a versão da CLI instalada:

libman --version

Para exibir os comandos da CLI disponíveis:

libman --help

O comando anterior exibe uma saída semelhante à seguinte:

 1.0.163+g45474d37ed

Usage: libman [options] [command]

Options:
  --help|-h  Show help information
  --version  Show version information

Commands:
  cache      List or clean libman cache contents
  clean      Deletes all library files defined in libman.json from the project
  init       Create a new libman.json
  install    Add a library definition to the libman.json file, and download the 
             library to the specified location
  restore    Downloads all files from provider and saves them to specified 
             destination
  uninstall  Deletes all files for the specified library from their specified 
             destination, then removes the specified library definition from 
             libman.json
  update     Updates the specified library

Use "libman [command] --help" for more information about a command.

As seções a seguir descrevem os comandos da CLI disponíveis.

Inicializar o LibMan no projeto

O libman init comando criará um libman.json arquivo se um não existir. O arquivo é criado com o conteúdo do modelo de item padrão.

Sinopse

libman init [-d|--default-destination] [-p|--default-provider] [--verbosity]
libman init [-h|--help]

Opções

As opções a seguir estão disponíveis para o comando libman init:

  • -d|--default-destination <PATH>

    Um caminho relativo à pasta atual. Os arquivos de biblioteca serão instalados nesse local se nenhuma destination propriedade for definida para uma biblioteca em libman.json. O <PATH> valor é gravado na defaultDestination propriedade de libman.json.

  • -p|--default-provider <PROVIDER>

    O provedor a ser usado se nenhum provedor for definido para uma determinada biblioteca. O <PROVIDER> valor é gravado na defaultProvider propriedade de libman.json. Substitua <PROVIDER> por um dos seguintes valores:

    • cdnjs
    • filesystem
    • jsdelivr
    • unpkg
  • -h|--help

    Mostrar informações de ajuda.

  • --verbosity <LEVEL>

    Defina a verbosidade da saída. Substitua <LEVEL> por um dos seguintes valores:

    • quiet
    • normal
    • detailed

Exemplos

Para criar um libman.json arquivo em um projeto ASP.NET Core:

  • Navegue até a raiz do projeto.

  • Execute o comando a seguir:

    libman init
    
  • Digite o nome do provedor padrão ou pressione Enter para usar o provedor CDNJS padrão. Os valores válidos incluem:

    • cdnjs
    • filesystem
    • jsdelivr
    • unpkg

    libman init command - default provider

Um libman.json arquivo é adicionado à raiz do projeto com o seguinte conteúdo:

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "libraries": []
}

Adicionar arquivos de biblioteca

O libman install comando baixa e instala arquivos de biblioteca no projeto. Um libman.json arquivo será adicionado se um não existir. O libman.json arquivo é modificado para armazenar detalhes de configuração para os arquivos de biblioteca.

Sinopse

libman install <LIBRARY> [-d|--destination] [--files] [-p|--provider] [--verbosity]
libman install [-h|--help]

Argumentos

LIBRARY

O nome da biblioteca a ser instalada. Esse nome pode incluir notação de número de versão (por exemplo, @1.2.0).

Opções

As opções a seguir estão disponíveis para o comando libman install:

  • -d|--destination <PATH>

    O local para instalar a biblioteca. Se não for especificado, o local padrão será usado. Se nenhuma defaultDestination propriedade for especificada, libman.jsonessa opção será necessária.

  • --files <FILE>

    Especifique o nome do arquivo a ser instalado na biblioteca. Se não for especificado, todos os arquivos da biblioteca serão instalados. Forneça uma --files opção por arquivo a ser instalada. Também há suporte para caminhos relativos. Por exemplo: --files dist/browser/signalr.js.

  • -p|--provider <PROVIDER>

    O nome do provedor a ser usado para a aquisição da biblioteca. Substitua <PROVIDER> por um dos seguintes valores:

    • cdnjs
    • filesystem
    • jsdelivr
    • unpkg

    Se não for especificado, a defaultProvider propriedade in libman.json será usada. Se nenhuma defaultProvider propriedade for especificada, libman.jsonessa opção será necessária.

  • -h|--help

    Mostrar informações de ajuda.

  • --verbosity <LEVEL>

    Defina a verbosidade da saída. Substitua <LEVEL> por um dos seguintes valores:

    • quiet
    • normal
    • detailed

Exemplos

Considere o seguinte libman.json arquivo:

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "libraries": []
}

Para instalar o arquivo jQuery versão 3.2.1 jquery.min.js na pasta wwwroot/scripts/jquery usando o provedor CDNJS:

libman install jquery@3.2.1 --provider cdnjs --destination wwwroot/scripts/jquery --files jquery.min.js

O libman.json arquivo se assemelha ao seguinte:

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "libraries": [
    {
      "library": "jquery@3.2.1",
      "destination": "wwwroot/scripts/jquery",
      "files": [
        "jquery.min.js"
      ]
    }
  ]
}

Para instalar os calendar.js arquivos e calendar.cssde C:\temp\contosoCalendar\ usando o provedor do sistema de arquivos:

libman install C:\temp\contosoCalendar\ --provider filesystem --files calendar.js --files calendar.css

O seguinte prompt é exibido por dois motivos:

  • O libman.json arquivo não contém uma defaultDestination propriedade.
  • O libman install comando não contém a opção -d|--destination .

libman install command - destination

Depois de aceitar o destino padrão, o libman.json arquivo se assemelha ao seguinte:

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "libraries": [
    {
      "library": "jquery@3.2.1",
      "destination": "wwwroot/scripts/jquery",
      "files": [
        "jquery.min.js"
      ]
    },
    {
      "library": "C:\\temp\\contosoCalendar\\",
      "provider": "filesystem",
      "destination": "wwwroot/lib/contosoCalendar",
      "files": [
        "calendar.js",
        "calendar.css"
      ]
    }
  ]
}

Restaurar arquivos de biblioteca

O libman restore comando instala arquivos de biblioteca definidos em libman.json. As seguintes regras se aplicam:

  • Se nenhum libman.json arquivo existir na raiz do projeto, um erro será retornado.
  • Se uma biblioteca especificar um provedor, a defaultProvider propriedade in libman.json será ignorada.
  • Se uma biblioteca especificar um destino, a defaultDestination propriedade em libman.json será ignorada.

Sinopse

libman restore [--verbosity]
libman restore [-h|--help]

Opções

As opções a seguir estão disponíveis para o comando libman restore:

  • -h|--help

    Mostrar informações de ajuda.

  • --verbosity <LEVEL>

    Defina a verbosidade da saída. Substitua <LEVEL> por um dos seguintes valores:

    • quiet
    • normal
    • detailed

Exemplos

Para restaurar os arquivos de biblioteca definidos em libman.json:

libman restore

Excluir arquivos de biblioteca

O libman clean comando exclui arquivos de biblioteca restaurados anteriormente por meio do LibMan. Pastas que ficam vazias depois que essa operação é excluída. As configurações associadas dos arquivos de libman.json biblioteca na libraries propriedade não são removidas.

Sinopse

libman clean [--verbosity]
libman clean [-h|--help]

Opções

As opções a seguir estão disponíveis para o comando libman clean:

  • -h|--help

    Mostrar informações de ajuda.

  • --verbosity <LEVEL>

    Defina a verbosidade da saída. Substitua <LEVEL> por um dos seguintes valores:

    • quiet
    • normal
    • detailed

Exemplos

Para excluir arquivos de biblioteca instalados por meio do LibMan:

libman clean

Desinstalar arquivos de biblioteca

O comando libman uninstall:

  • Exclui todos os arquivos associados à biblioteca especificada do destino em libman.json.
  • Remove a configuração de biblioteca associada de libman.json.

Ocorre um erro quando:

  • Nenhum libman.json arquivo existe na raiz do projeto.
  • A biblioteca especificada não existe.

Se mais de uma biblioteca com o mesmo nome estiver instalada, você deverá escolher uma.

Sinopse

libman uninstall <LIBRARY> [--verbosity]
libman uninstall [-h|--help]

Argumentos

LIBRARY

O nome da biblioteca a ser desinstalado. Esse nome pode incluir notação de número de versão (por exemplo, @1.2.0).

Opções

As opções a seguir estão disponíveis para o comando libman uninstall:

  • -h|--help

    Mostrar informações de ajuda.

  • --verbosity <LEVEL>

    Defina a verbosidade da saída. Substitua <LEVEL> por um dos seguintes valores:

    • quiet
    • normal
    • detailed

Exemplos

Considere o seguinte libman.json arquivo:

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "libraries": [
    {
      "library": "jquery@3.3.1",
      "files": [
        "jquery.min.js",
        "jquery.js",
        "jquery.min.map"
      ],
      "destination": "wwwroot/lib/jquery/"
    },
    {
      "provider": "unpkg",
      "library": "bootstrap@4.1.3",
      "destination": "wwwroot/lib/bootstrap/"
    },
    {
      "provider": "filesystem",
      "library": "C:\\temp\\lodash\\",
      "files": [
        "lodash.js",
        "lodash.min.js"
      ],
      "destination": "wwwroot/lib/lodash/"
    }
  ]
}
  • Para desinstalar o jQuery, qualquer um dos seguintes comandos tem êxito:

    libman uninstall jquery
    
    libman uninstall jquery@3.3.1
    
  • Para desinstalar os arquivos Lodash instalados por meio do filesystem provedor:

    libman uninstall C:\temp\lodash\
    

Atualizar versão da biblioteca

O libman update comando atualiza uma biblioteca instalada por meio do LibMan para a versão especificada.

Ocorre um erro quando:

  • Nenhum libman.json arquivo existe na raiz do projeto.
  • A biblioteca especificada não existe.

Se mais de uma biblioteca com o mesmo nome estiver instalada, você deverá escolher uma.

Sinopse

libman update <LIBRARY> [-pre] [--to] [--verbosity]
libman update [-h|--help]

Argumentos

LIBRARY

O nome da biblioteca a ser atualizada.

Opções

As opções a seguir estão disponíveis para o comando libman update:

  • -pre

    Obtenha a versão de pré-lançamento mais recente da biblioteca.

  • --to <VERSION>

    Obtenha uma versão específica da biblioteca.

  • -h|--help

    Mostrar informações de ajuda.

  • --verbosity <LEVEL>

    Defina a verbosidade da saída. Substitua <LEVEL> por um dos seguintes valores:

    • quiet
    • normal
    • detailed

Exemplos

  • Para atualizar o jQuery para a versão mais recente:

    libman update jquery
    
  • Para atualizar o jQuery para a versão 3.3.1:

    libman update jquery --to 3.3.1
    
  • Para atualizar o jQuery para a versão de pré-lançamento mais recente:

    libman update jquery -pre
    

Gerenciar cache de biblioteca

O libman cache comando gerencia o cache da biblioteca LibMan. O filesystem provedor não usa o cache de biblioteca.

Sinopse

libman cache clean [<PROVIDER>] [--verbosity]
libman cache list [--files] [--libraries] [--verbosity]
libman cache [-h|--help]

Argumentos

PROVIDER

Usado apenas com o clean comando. Especifica o cache do provedor para limpar. Os valores válidos incluem:

  • cdnjs
  • filesystem
  • jsdelivr
  • unpkg

Opções

As opções a seguir estão disponíveis para o comando libman cache:

  • --files

    Listar os nomes dos arquivos armazenados em cache.

  • --libraries

    Liste os nomes das bibliotecas armazenadas em cache.

  • -h|--help

    Mostrar informações de ajuda.

  • --verbosity <LEVEL>

    Defina a verbosidade da saída. Substitua <LEVEL> por um dos seguintes valores:

    • quiet
    • normal
    • detailed

Exemplos

  • Para exibir os nomes de bibliotecas armazenadas em cache por provedor, use um dos seguintes comandos:

    libman cache list
    
    libman cache list --libraries
    

    Uma saída semelhante à apresentada a seguir será exibida:

    Cache contents:
    ---------------
    unpkg:
        knockout
        react
        vue
    cdnjs:
        font-awesome
        jquery
        knockout
        lodash.js
        react
    
  • Para exibir os nomes de arquivos de biblioteca armazenados em cache por provedor:

    libman cache list --files
    

    Uma saída semelhante à apresentada a seguir será exibida:

    Cache contents:
    ---------------
    unpkg:
        knockout:
            <list omitted for brevity>
        react:
            <list omitted for brevity>
        vue:
            <list omitted for brevity>
    cdnjs:
        font-awesome
            metadata.json
        jquery
            metadata.json
            3.2.1\core.js
            3.2.1\jquery.js
            3.2.1\jquery.min.js
            3.2.1\jquery.min.map
            3.2.1\jquery.slim.js
            3.2.1\jquery.slim.min.js
            3.2.1\jquery.slim.min.map
            3.3.1\core.js
            3.3.1\jquery.js
            3.3.1\jquery.min.js
            3.3.1\jquery.min.map
            3.3.1\jquery.slim.js
            3.3.1\jquery.slim.min.js
            3.3.1\jquery.slim.min.map
        knockout
            metadata.json
            3.4.2\knockout-debug.js
            3.4.2\knockout-min.js
        lodash.js
            metadata.json
            4.17.10\lodash.js
            4.17.10\lodash.min.js
        react
            metadata.json
    

    Observe que a saída anterior mostra que as versões jQuery 3.2.1 e 3.3.1 são armazenadas em cache no provedor CDNJS.

  • Para esvaziar o cache de biblioteca para o provedor CDNJS:

    libman cache clean cdnjs
    

    Depois de esvaziar o cache do provedor CDNJS, o libman cache list comando exibe o seguinte:

    Cache contents:
    ---------------
    unpkg:
        knockout
        react
        vue
    cdnjs:
        (empty)
    
  • Para esvaziar o cache para todos os provedores com suporte:

    libman cache clean
    

    Depois de esvaziar todos os caches do provedor, o libman cache list comando exibe o seguinte:

    Cache contents:
    ---------------
    unpkg:
        (empty)
    cdnjs:
        (empty)
    

Recursos adicionais