Usar o LibMan com ASP.NET Core no Visual Studio

Por Scott Addie

O Visual Studio tem suporte interno para LibMan em projetos ASP.NET Core, incluindo:

• Suporte para configurar e executar operações de restauração LibMan na compilação.
• Itens de menu para acionar operações de restauração e limpeza do LibMan.
• Caixa de diálogo de pesquisa para localizar bibliotecas e adicionar os arquivos a um projeto.
• Suporte de edição para libman.json—o arquivo de manifesto LibMan.

Ver ou baixar código de exemplo(como baixar)

Prerequisites

• Visual Studio 2019 com a carga de trabalho de desenvolvimento ASP.NET e Web

Adicionar arquivos de biblioteca

Os arquivos de biblioteca podem ser adicionados a um projeto ASP.NET Core de duas maneiras diferentes:

1. Use a caixa de diálogo Adicionar Biblioteca Client-Side
2. Configurar manualmente as entradas do arquivo de manifesto do LibMan

Use a caixa de diálogo Adicionar Biblioteca Client-Side

Siga estas etapas para instalar uma biblioteca do lado do cliente:

• No Gerenciador de Soluções, clique com o botão direito do mouse na pasta do projeto na qual os arquivos devem ser adicionados. Escolha Adicionar>Client-Side Biblioteca. A caixa de diálogo Adicionar biblioteca Client-Side é exibida:

  

• Selecione o provedor de biblioteca na lista suspensa Provedor . CDNJS é o provedor padrão.

• Digite o nome da biblioteca a ser buscado na caixa de texto Biblioteca . O IntelliSense fornece uma lista de bibliotecas começando com o texto fornecido.

• Selecione a biblioteca na lista IntelliSense. Observe que o nome da biblioteca está sufixo com o @ símbolo e a versão estável mais recente conhecida pelo provedor selecionado.

• Decida quais arquivos incluir:

  • Selecione o botão de opção Incluir todos os arquivos da biblioteca para incluir todos os arquivos da biblioteca.
  • Selecione o botão de opção Escolher arquivos específicos para incluir um subconjunto dos arquivos da biblioteca. Quando o botão rádio é selecionado, o selector de ficheiros é ativado. Marque as caixas à esquerda dos nomes de arquivo para download.

• Especifique a pasta do projeto para armazenar os arquivos na caixa de texto Local de Destino . Como recomendação, armazene cada biblioteca em uma pasta separada.

  A pasta Local de Destino sugerida baseia-se no local a partir do qual a caixa de diálogo foi iniciada:

  • Se lançado a partir da raiz do projeto:
    • wwwroot/lib é usado se wwwroot existir.
    • lib é usado se wwwroot não existir.
  • Se iniciado a partir de uma pasta de projeto, o nome da pasta correspondente é usado.

  A sugestão de pasta tem o nome da biblioteca acrescentado. A tabela a seguir ilustra sugestões de pasta ao instalar o jQuery em um Razor projeto do Pages.

  Local de lançamento	Pasta sugerida
  raiz do projeto (se wwwroot existir)	wwwroot/lib/jquery/
  raiz do projeto (se wwwroot não existir)	lib/jquery/
  Pasta de Páginas no projeto	Pages/jquery/

• Clique no botão Instalar para baixar os arquivos, de acordo com a configuração em libman.json.

• Revise o feed do Gerenciador de bibliotecas da janela Saída para obter detalhes da instalação. Por exemplo:

  Restore operation started...
  Restoring libraries for project LibManSample
  Restoring library jquery@3.3.1... (LibManSample)
  wwwroot/lib/jquery/jquery.min.js written to destination (LibManSample)
  wwwroot/lib/jquery/jquery.js written to destination (LibManSample)
  wwwroot/lib/jquery/jquery.min.map written to destination (LibManSample)
  Restore operation completed
  1 libraries restored in 2.32 seconds
  

Configurar manualmente as entradas do arquivo de manifesto do LibMan

Todas as operações LibMan no Visual Studio são baseadas no conteúdo do manifesto LibMan da raiz do projeto (libman.json). Você pode editar libman.json manualmente para configurar arquivos de biblioteca para o projeto. Visual Studio restaura todos os arquivos de biblioteca depois que libman.json é salvo.

Para abrir libman.json para edição, existem as seguintes opções:

• Clique duas vezes no libman.json arquivo no Gerenciador de Soluções.
• Clique com o botão direito do mouse no projeto no Gerenciador de Soluções e selecione Gerenciar Client-Side Bibliotecas. †
• Selecione Gerenciar bibliotecas Client-Side no menu Projeto do Visual Studio. †

† Se o libman.json arquivo ainda não existir na raiz do projeto, ele será criado com o conteúdo do modelo de item padrão.

O Visual Studio oferece suporte avançado à edição JSON, como colorização, formatação, IntelliSense e validação de esquema. O esquema JSON do manifesto LibMan é encontrado em https://json.schemastore.org/libman.

Com o seguinte ficheiro de manifesto, o LibMan obtém ficheiros de acordo com a configuração definida na propriedade libraries. Uma explicação dos literais de objeto definidos em libraries segue:

• Um subconjunto do jQuery versão 3.3.1 é recuperado do provedor CDNJS. O subconjunto é definido na files propriedade—jquery.min.js, jquery.jse jquery.min.map. Os arquivos são colocados na pasta wwwroot/lib/jquery do projeto.
• A totalidade do Bootstrap versão 4.1.3 é recuperada e colocada em uma pasta wwwroot/lib/bootstrap . A propriedade provider do literal do objeto substitui o valor da propriedade defaultProvider. O LibMan recupera os arquivos Bootstrap do provedor unpkg.

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "libraries": [
    {
      "library": "jquery@3.7.1",
      "files": [
        "jquery.min.js",
        "jquery.js",
        "jquery.min.map"
      ],
      "destination": "wwwroot/lib/jquery/"
    },
    {
      "provider": "unpkg",
      "library": "bootstrap@5.3.6",
      "destination": "wwwroot/lib/bootstrap/"
    }
  ]
}

Restaurar arquivos da biblioteca

Para restaurar arquivos de biblioteca de dentro do Visual Studio, deve haver um arquivo válido libman.json na raiz do projeto. Os arquivos restaurados são colocados no projeto no local especificado para cada biblioteca.

Os arquivos de biblioteca podem ser restaurados em um projeto ASP.NET Core de duas maneiras:

1. Restaurar arquivos durante a compilação
2. Restaurar ficheiros manualmente

Restaurar arquivos durante a compilação

O LibMan pode restaurar os arquivos de biblioteca definidos como parte do processo de compilação. Por padrão, o comportamento de restauração na compilação está desabilitado.

Para habilitar e testar o comportamento de restauração na compilação:

• Clique com libman.json o botão direito do rato no Explorador de Soluções e selecione Ativar Restauração das Bibliotecas Client-Side durante a Compilação no menu de contexto.

• Clique no botão Sim quando solicitado a instalar um pacote NuGet. O pacote NuGet Microsoft.Web.LibraryManager.Build é adicionado ao projeto:

  <PackageReference Include="Microsoft.Web.LibraryManager.Build" Version="3.0.71" />
  

• Construa o projeto para confirmar que a restauração do arquivo LibMan ocorre. O Microsoft.Web.LibraryManager.Build pacote injeta um destino MSBuild que executa o LibMan durante a operação de compilação do projeto.

• Analise o feed Build da janela Output para um log de atividades do LibMan:

  1>------ Build started: Project: LibManSample, Configuration: Debug Any CPU ------
  1>
  1>Restore operation started...
  1>Restoring library jquery@3.3.1...
  1>Restoring library bootstrap@4.1.3...
  1>
  1>2 libraries restored in 10.66 seconds
  1>LibManSample -> C:\LibManSample\bin\Debug\netcoreapp2.1\LibManSample.dll
  ========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========
  

Quando o comportamento de restauração na compilação está habilitado, o menu de contexto exibe uma opção libman.jsonDesativar restauração de bibliotecas Client-Side durante a compilação. Selecionar esta opção remove a Microsoft.Web.LibraryManager.Build referência de pacote do ficheiro de projeto. Consequentemente, as bibliotecas do lado do cliente não são mais restauradas em cada compilação.

Independentemente da configuração de restauração na compilação, você pode restaurar manualmente a qualquer momento no libman.json menu de contexto. Para obter mais informações, consulte Restaurar arquivos manualmente.

Restaurar ficheiros manualmente

Para restaurar manualmente os ficheiros da biblioteca:

• Para todos os projetos da solução:
  • Clique com o botão direito do mouse no nome da solução no Gerenciador de Soluções.
  • Selecione a opção Restaurar Client-Side Bibliotecas.
• Para um projeto específico:
  • Clique com o botão direito do rato no libman.json ficheiro no Solution Explorer.
  • Selecione a opção Restaurar Client-Side Bibliotecas.

Enquanto a operação de restauração está em execução:

• O ícone do Centro de Status de Tarefas (TSC) na barra de status do Visual Studio será animado e lerá Operação de restauração iniciada. Clicar no ícone abre uma tooltip listando as tarefas em segundo plano conhecidas.

• As mensagens serão enviadas para a barra de status e para o feed do Gerenciador de bibliotecas da janela Saída . Por exemplo:

  Restore operation started...
  Restoring libraries for project LibManSample
  Restoring library jquery@3.3.1... (LibManSample)
  wwwroot/lib/jquery/jquery.min.js written to destination (LibManSample)
  wwwroot/lib/jquery/jquery.js written to destination (LibManSample)
  wwwroot/lib/jquery/jquery.min.map written to destination (LibManSample)
  Restore operation completed
  1 libraries restored in 2.32 seconds
  

Excluir arquivos de biblioteca

Para executar a operação de limpeza , que exclui arquivos de biblioteca restaurados anteriormente no Visual Studio:

• Clique com o botão direito do rato no libman.json ficheiro no Solution Explorer.
• Selecione a opção Limpar Client-Side bibliotecas .

Para evitar a remoção não intencional de arquivos que não são da biblioteca, a operação de limpeza não exclui diretórios inteiros. Ele remove apenas os arquivos que foram incluídos na restauração anterior.

Enquanto a operação de limpeza está em execução:

• O ícone TSC na barra de status do Visual Studio será animado e lerá Operação de bibliotecas de cliente iniciada. Clicar no ícone abre uma tooltip listando as tarefas em segundo plano conhecidas.
• As mensagens são enviadas para a barra de status e para o feed do Gerenciador de bibliotecas da janela Saída . Por exemplo:

Clean libraries operation started...
Clean libraries operation completed
2 libraries were successfully deleted in 1.91 secs

A operação de limpeza exclui apenas arquivos do projeto. Os arquivos da biblioteca permanecem no cache para recuperação mais rápida em futuras operações de restauração. Para gerenciar arquivos de biblioteca armazenados no cache da máquina local, use a CLI do LibMan.

Desinstalar arquivos da biblioteca

Para desinstalar ficheiros de biblioteca:

• Abra libman.json.

• Posicione o cursor dentro do objeto literal correspondente libraries.

• Clique no ícone da lâmpada que aparece na margem esquerda e selecione Desinstalar <library_name>@<library_version>:

  

Como alternativa, você pode editar e salvar manualmente o manifesto LibMan (libman.json). A operação de restauração é executada quando o arquivo é salvo. Os ficheiros de biblioteca que já não estão definidos em libman.json são removidos do projeto.

Atualizar versão da biblioteca

Para verificar se há uma versão atualizada da biblioteca:

• Abra libman.json.
• Posicione o cursor dentro do objeto literal correspondente libraries.
• Clique no ícone da lâmpada que aparece na margem esquerda. Passe o cursor sobre Verificar se há atualizações.

O LibMan verifica se há uma versão da biblioteca mais recente do que a versão instalada. Podem ocorrer os seguintes resultados:

• Uma mensagem Nenhuma atualização encontrada será exibida se a versão mais recente já estiver instalada.

• A versão estável mais recente é exibida se ainda não estiver instalada.

  

• Se um pré-lançamento mais recente do que a versão instalada estiver disponível, o pré-lançamento será exibido.

Para fazer o downgrade para uma versão mais antiga da biblioteca, edite manualmente o libman.json arquivo. Quando o ficheiro é salvo, a operação de restauração do LibMan:

• Remove arquivos redundantes da versão anterior.
• Adiciona arquivos novos e atualizados da nova versão.

Recursos adicionais

• Usar a CLI do LibMan com ASP.NET Core
• repositório GitHub LibMan