Compartilhar via

Pacotes em modelos do Visual Studio

Os modelos de projeto e item do Visual Studio geralmente precisam garantir que determinados pacotes sejam instalados quando um projeto ou item é criado. Por exemplo, o modelo ASP.NET MVC 3 instala jQuery, Modernizr e outros pacotes.

Para dar suporte a isso, os autores de modelo podem instruir o NuGet a instalar os pacotes necessários, em vez de bibliotecas individuais. Os desenvolvedores podem atualizar facilmente esses pacotes posteriormente.

Para saber mais sobre como criar modelos em si, consulte Como criar modelos de projeto ou criar modelos de projeto e item personalizados.

O restante desta seção descreve as etapas específicas a serem tomadas ao criar um modelo para incluir corretamente pacotes NuGet.

Samples

O exemplo Preinstalled-Packages está disponível no repositório NuGet/Samples no GitHub.

Adicionando pacotes a um modelo

Quando um modelo é instanciado, um assistente de modelo é invocado para carregar a lista de pacotes a serem instalados junto com informações sobre onde encontrar esses pacotes. Os pacotes podem ser inseridos no VSIX, inseridos no modelo ou localizados no disco rígido local, nesse caso, você usa uma chave do Registro para referenciar o caminho do arquivo. Detalhes sobre esses locais são dados posteriormente nesta seção.

Os pacotes pré-instalados funcionam usando assistentes de modelo. Um assistente especial é invocado quando o modelo é instanciado. O assistente carrega a lista de pacotes que precisam ser instalados e passa essas informações para as APIs apropriadas do NuGet.

Etapas para incluir pacotes em um modelo:

  1. No arquivo vstemplate, adicione uma referência ao assistente de modelo do NuGet adicionando o elemento WizardExtension.

    <WizardExtension>
    <Assembly>NuGet.VisualStudio.Interop, Version=1.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a</Assembly>
    <FullClassName>NuGet.VisualStudio.TemplateWizard</FullClassName>
</WizardExtension>

    NuGet.VisualStudio.Interop.dll é um assembly que contém apenas a classe TemplateWizard, que é um simples wrapper que invoca a implementação real em NuGet.VisualStudio.dll. A versão do assembly nunca será alterada para que os modelos de projeto/item continuem funcionando com novas versões do NuGet.

  2. Adicione a lista de pacotes a serem instalados no projeto:

    <WizardData>
    <packages>
        <package id="jQuery" version="1.6.2" />
    </packages>
</WizardData>

    O assistente dá suporte a vários <package> elementos para dar suporte a várias fontes de pacote. Os atributos id e version são obrigatórios, o que significa que uma versão específica de um pacote será instalada mesmo que uma versão mais recente esteja disponível. Isso impede que as atualizações de pacote quebrem o modelo, deixando a decisão de atualizar o pacote para o desenvolvedor que utiliza o modelo.

  3. Especifique o repositório em que o NuGet pode encontrar os pacotes, conforme descrito nas seções a seguir.

Repositório de pacotes VSIX

A abordagem de implantação recomendada para modelos de projeto/item do Visual Studio é uma extensão VSIX , pois permite que você empacote vários modelos de projeto/item juntos e permite que os desenvolvedores descubram facilmente seus modelos usando o GERENCIADOr de Extensões do VS ou a Galeria do Visual Studio. As atualizações para a extensão também são fáceis de implantar usando o mecanismo de atualização automática do Gerenciador de Extensões do Visual Studio.

O VSIX em si pode servir como a origem dos pacotes exigidos pelo modelo:

  1. Modifique o elemento <packages> no arquivo .vstemplate da seguinte maneira:

    <packages repository="extension" repositoryId="MyTemplateContainerExtensionId">
    <!-- ... -->
</packages>

    O atributo repository especifica o tipo de repositório como extension, enquanto repositoryId é o identificador exclusivo do próprio VSIX (este é o valor do atributo ID no arquivo de extensão vsixmanifest, consulte Referência do Esquema de Extensão VSIX 2.0).

  2. Coloque seus nupkg arquivos em uma pasta chamada Packages no VSIX.

  3. Adicione os arquivos de pacote necessários como <Asset> no vsixmanifest arquivo (consulte referência do esquema de extensão VSIX 2.0):

    <Asset Type="Moq.4.0.10827.nupkg" d:Source="File" Path="Packages\Moq.4.0.10827.nupkg" d:VsixSubPath="Packages" />

  4. Observe que você pode entregar pacotes no mesmo VSIX que seus modelos de projeto ou colocá-los em um VSIX separado se isso fizer mais sentido para o seu cenário. No entanto, não faça referência a nenhum VSIX sobre o qual você não tenha controle, pois as alterações nessa extensão podem interromper seu modelo.

Repositório de pacotes de modelo

Se você estiver distribuindo apenas um modelo de projeto/item e não precisar empacotar vários modelos juntos, poderá usar uma abordagem mais simples, mas mais limitada, que inclui pacotes diretamente no arquivo ZIP do modelo de projeto/item:

  1. Modifique o elemento <packages> no arquivo .vstemplate da seguinte maneira:

    <packages repository="template">
    <!-- ... -->
</packages>

    O repository atributo tem o valor template e o repositoryId atributo não é necessário.

  2. Coloque pacotes na pasta raiz do arquivo ZIP do modelo de projeto/item.

Vale ressaltar que usar esta abordagem em um VSIX que contém vários modelos leva a um excesso desnecessário quando um ou mais pacotes são comuns aos modelos. Nesses casos, use o VSIX como o repositório , conforme descrito na seção anterior.

Caminho da pasta especificado pelo Registro

Os SDKs instalados usando uma MSI podem instalar pacotes NuGet diretamente no computador do desenvolvedor. Isso os torna imediatamente disponíveis quando um projeto ou modelo de item é usado, em vez de ter que extraí-los durante esse tempo. ASP.NET modelos usam essa abordagem.

  1. Fazer com que o MSI instale pacotes no computador. Você pode instalar apenas os .nupkg arquivos ou instalá-los junto com o conteúdo expandido, o que salva uma etapa adicional quando o modelo é usado. Nesse caso, siga a estrutura de pasta padrão do NuGet na qual os .nupkg arquivos estão na pasta raiz e, em seguida, cada pacote tem uma subpasta com o par id/version como o nome da subpasta.

  2. Escreva uma chave do Registro para identificar o local do pacote:

    • Localização da chave: para toda a máquina HKEY_LOCAL_MACHINE\SOFTWARE[\Wow6432Node]\NuGet\Repository; ou, se por usuário, os modelos e pacotes instalados, como alternativa, use HKEY_CURRENT_USER\SOFTWARE\NuGet\Repository
    • Nome da chave: use um nome exclusivo para você. Por exemplo, os modelos ASP.NET MVC 4 para o VS 2012 usam AspNetMvc4VS11.
    • Valores: o caminho completo para a pasta de pacotes.

  3. No elemento do .vstemplate arquivo, adicione o atributo repository="registry" e especifique o nome da chave do Registro no atributo keyName.

    • Se você tiver descompactado previamente seus pacotes, use o isPreunzipped="true" atributo.

    • (NuGet 3.2+) Se você quiser forçar uma compilação em tempo de design após a instalação do pacote, adicione o atributo forceDesignTimeBuild="true".

    • Como otimização, adicione skipAssemblyReferences="true" porque o próprio modelo já inclui as referências necessárias.

      <packages repository="registry" keyName="AspNetMvc4VS11" isPreunzipped="true">
    <package id="EntityFramework" version="5.0.0" skipAssemblyReferences="true" />
    <-- ... -->
</packages>

Práticas recomendadas

  1. Declare uma dependência no VSIX do NuGet adicionando uma referência a ela em seu manifesto VSIX:

    <Reference Id="NuPackToolsVsix.Microsoft.67e54e40-0ae3-42c5-a949-fddf5739e7a5" MinVersion="1.7.30402.9028">
    <Name>NuGet Package Manager</Name>
    <MoreInfoUrl>http://learn.microsoft.com/nuget/</MoreInfoUrl>
</Reference>
<!-- ... -->

  2. Exigir que modelos de projeto/item sejam salvos na criação, incluindo <PromptForSaveOnCreation>true</PromptForSaveOnCreation> no .vstemplate arquivo.

  3. Os modelos não incluem um arquivo packages.config e não incluem nenhuma referência ou conteúdo que seria adicionado quando os pacotes NuGet fossem instalados.

  • Last updated on