Criar um pacote usando a nuget.exe CLI

Não importa o que o seu pacote faça ou que código contém, usa uma das ferramentas de interface de linha de comandos (CLI), seja nuget.exe ou dotnet.exe, para empacotar essa funcionalidade num componente que pode ser partilhado e usado por outros programadores. Para instalar as ferramentas da CLI do NuGet, consulte Instalar ferramentas de cliente NuGet. O Visual Studio não inclui automaticamente uma ferramenta de CLI.

• Para projetos que não são do tipo SDK, tipicamente projetos do .NET Framework, siga os passos descritos neste artigo para criar um pacote. Para um quickstart que forneça instruções passo a passo para usar Visual Studio e a CLI nuget.exe, consulte Quickstart: Criar e publicar um pacote usando Visual Studio (.NET Framework, Windows).

• Para projetos .NET Core e .NET Standard que utilizam o formato SDK, e quaisquer outros projetos do estilo SDK, veja Criar um pacote NuGet com o dotnet CLI.

• Para projetos migrados de packages.config para PackageReference, use o msbuild -t:pack comando.

Tecnicamente, um pacote NuGet é um ficheiro ZIP que foi renomeado para ter a extensão .nupkg e cujo conteúdo corresponde a certas convenções. Este artigo descreve o processo detalhado de criação de um pacote que cumpra essas convenções.

O empacotamento começa com o código compilado (assemblies), símbolos e outros ficheiros que pretende entregar como pacote. Para uma visão geral do processo de embalagem, consulte Fluxo de trabalho de criação de pacotes. Este processo é independente da compilação ou geração dos ficheiros que entram no pacote. Mas podes utilizar informação contida num ficheiro de projeto para manter sincronizados os assemblies compilados e os pacotes.

Decidir quais componentes empacotar

A maioria dos pacotes de uso geral contém um ou mais assemblies que outros desenvolvedores podem usar em seus próprios projetos.

Em geral, é preferível ter um assembly por pacote NuGet, desde que cada assembly seja útil de forma independente. Por exemplo, considere os seguintes casos que envolvem um conjunto chamado Utilities.dll que depende de um conjunto chamado Parser.dll:

• Se Parser.dll for útil por si só, crie um pacote para Utilities.dll e outro para Parser.dll. Fazer isso permite aos programadores usar Parser.dll independentemente de Utilities.dll.

• Se Parser.dll contiver código usado apenas porUtilities.dll, não há problema em manterParser.dll no mesmo pacote. Em geral, se a sua biblioteca for composta por múltiplos conjuntos que não são úteis de forma independente, não há qualquer problema em uni-los num único pacote.

• Se Utilities.dll também depender de Utilities.resources.dlle Utilities.resources.dll não for útil por si só, coloca ambos no mesmo pacote.

Recursos, como a montagem Utilities.resources.dll no exemplo anterior, são um caso especial. Quando um pacote é instalado num projeto, o NuGet adiciona automaticamente referências assembly às DLLs do pacote, excluindo aquelas que são nomeadas .resources.dll, porque se assume que são assemblies satélite localizados. Para mais informações sobre versões localizadas de uma biblioteca, consulte Criação de pacotes NuGet localizados. Por esta razão, evite usar .resources.dll para ficheiros que contenham código essencial de pacote.

Se a sua biblioteca contiver assemblies de interoperabilidade do Modelo de Objetos Componentes (COM), siga as diretrizes adicionais em Criar pacotes NuGet que contenham assemblies de interoperabilidade COM.

A função e a estrutura do arquivo .nuspec

Quando souber que ficheiros quer empacotar, o passo seguinte é criar um manifesto de pacote num ficheiro XML .nuspec .

O manifesto:

• Descreve o conteúdo e está incluído no próprio pacote.
• Impulsiona a criação do pacote e indica ao NuGet como instalar o pacote num projeto. Por exemplo, o manifesto identifica outras dependências de pacotes para que o NuGet também possa instalar essas dependências quando o pacote principal estiver instalado.
• Contém propriedades obrigatórias e opcionais, conforme descrito no restante desta secção. Para informações detalhadas, incluindo outras propriedades não mencionadas aqui, consulte a referência .nuspec.

As seguintes propriedades são exigidas no manifesto:

• O identificador do pacote, que deve ser único em toda a galeria que aloja o pacote
• Um número de versão específico na forma Major.Minor.Patch[-Sufixo], onde -Sufixo identifica versões pré-lançamento
• O título do pacote como deve aparecer no host (como nuget.org)
• Informação sobre o autor
• Uma longa descrição da embalagem

As seguintes propriedades são opcionais comuns:

• Notas de lançamento.
• Informação de direitos de autor.
• Uma breve descrição da interface Gestor de Pacotes em Visual Studio.
• Um identificador local.
• Um URL de projeto.
• Uma licença como expressão ou ficheiro. A licenseUrl propriedade está obsoleta. Utilize o license elemento de metadados nuspec em vez disso.
• Um ficheiro de read-me.
• Um ficheiro de ícones. A iconUrl propriedade está obsoleta. Use o elemento de metadados nuspec icon em vez disso.
• Listas de dependências e referências.
• Etiquetas que ajudam nas pesquisas de galerias.

O código seguinte é um ficheiro .nuspec típico (mas fictício), com comentários que descrevem as propriedades:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
    <metadata>
        <!-- An identifier that must be unique within the hosting gallery -->
        <id>Contoso.Utility.UsefulStuff</id>

        <!-- A package version number that's used when resolving dependencies -->
        <version>1.8.3</version>

        <!-- A comma-separated list of package authors that sometimes appears directly on the gallery -->
        <authors>Dejana Tesic, Rajeev Dey</authors>

        <!-- A project URL that provides a link for the gallery -->
        <projectUrl>http://github.com/contoso/UsefulStuff</projectUrl>

        <!-- License information that's displayed on the gallery -->
        <license type="expression">Apache-2.0</license>
        
        <!-- The location of a read-me file that's displayed in the Visual Studio Package Manager UI -->
        <readme>readme.md</readme>

        <!-- An icon that's used in the Visual Studio Package Manager UI -->
        <icon>icon.png</icon>

        <!-- 
            A property that when true, prompts the user to accept the license when
            installing the package
        -->
        <requireLicenseAcceptance>false</requireLicenseAcceptance>

        <!-- Detailed information about a particular release -->
        <releaseNotes>Bug fixes and performance improvements</releaseNotes>

        <!-- 
            A description that can be used in the Package Manager UI. The
            nuget.org gallery uses information you add in the portal. 
        -->
        <description>Core utility functions for web applications</description>

        <!-- Copyright information -->
        <copyright>Copyright ©2026 Contoso Corporation</copyright>

        <!-- Tags that appear in the gallery and can be used for tag searches -->
        <tags>web utility http json url parsing</tags>

        <!-- Dependencies that are automatically installed when the package is installed -->
        <dependencies>
            <dependency id="Newtonsoft.Json" version="9.0" />
        </dependencies>
    </metadata>

    <!-- A read-me Markdown file that's displayed in the Package Manager UI -->
    <files>
        <file src="readme.md" target="" />
        <file src="icon.png" target="" />
    </files>
</package>

Para informações detalhadas sobre a declaração de dependências e especificação dos números de versão, consulte packages.config e Versionamento de pacotes. Também podes usar os include atributos e exclude no dependency elemento para especificar os ativos de dependência que queres incluir ou excluir no pacote. Para mais informações, consulte Referência .nuspec - Elemento de Dependências.

Como o manifesto está incluído no pacote criado a partir dele, pode encontrar exemplos examinando pacotes existentes. Uma boa fonte é a pasta global-packages no teu computador. Para encontrar a sua localização, use o seguinte comando:

nuget locals -list global-packages

Depois de saber a localização da pasta global-packages , siga os seguintes passos para encontrar um ficheiro manifest:

1. Vai à pasta global-packages .
2. Nessa pasta, vai à subpasta de qualquer pacote e depois a uma subpasta de qualquer versão desse pacote.
3. Na subpasta de versões, faça uma cópia do ficheiro .nupkg e altere a extensão da cópia para zip.
4. Abre o ficheiro.zip e examina o ficheiro .nuspec dentro dele.

Criar o arquivo .nuspec

Criar um manifesto completo normalmente começa com um ficheiro .nuspec básico gerado através de um dos seguintes métodos:

• Um diretório de trabalho baseado em convenção
• Uma DLL de conjunto
• Um projeto Visual Studio
• Um novo ficheiro com valores predefinidos

Em seguida, edite o arquivo manualmente para que ele descreva o conteúdo exato desejado no pacote final.

A partir de um diretório de trabalho estruturado por convenção

Como um pacote NuGet é um ficheiro ZIP que foi renomeado com a extensão .nupkg , muitas vezes é mais fácil criar a estrutura de pastas que deseja no seu sistema de ficheiros local e depois criar o ficheiro .nuspec diretamente a partir dessa estrutura. O nuget pack comando adiciona automaticamente todos os ficheiros dessa estrutura de pastas, mas exclui quaisquer pastas que comecem com um ponto final, para que possas manter os ficheiros privados na mesma estrutura.

A vantagem desta abordagem é que não precisa de especificar no manifesto quais os ficheiros que quer incluir no pacote, como explicado mais adiante nesta secção. Em vez disso, pode fazer com que o seu processo de compilação produza exatamente a estrutura de pastas que entra no pacote. Também pode facilmente incluir outros ficheiros que de outra forma poderiam não fazer parte de um projeto:

• Conteúdo e código-fonte que devem ser injetados no projeto alvo
• Scripts do PowerShell
• Transformações em ficheiros de configuração existentes e código-fonte num projeto

As pastas alinham-se com as seguintes convenções:

Como a sua estrutura de pastas pode conter assemblies para muitos frameworks de destino, este método é necessário quando cria pacotes que suportam múltiplos frameworks.

Quando tiveres a estrutura de pastas desejada, executa o seguinte comando nessa pasta para criar o ficheiro .nuspec :

nuget spec

O ficheiro .nuspec gerado não contém referências explícitas a ficheiros na estrutura de pastas. O NuGet inclui automaticamente todos os arquivos quando o pacote é criado. No entanto, você ainda precisa editar variáveis de espaço reservado em outras partes do manifesto.

De uma DLL de montagem

No caso básico de criar um pacote a partir de um assembly, pode gerar um ficheiro .nuspec a partir dos metadados no assembly usando o seguinte comando:

nuget spec <assembly-name>.dll

O uso desse formulário substitui alguns espaços reservados no manifesto por valores específicos do assembly. Por exemplo, a <id> propriedade é definida como o nome do assembly e <version> é definida como a versão do assembly. Outras propriedades no manifesto, no entanto, não têm valores correspondentes na assembleia. Essas propriedades ainda contêm marcadores de posição depois de executares o comando.

De um projeto do Visual Studio

Criar um ficheiro .nuspec a partir de um ficheiro .csproj ou .vbproj é conveniente, porque outros pacotes instalados no projeto são automaticamente referenciados como dependências. Para criar um manifesto a partir de um ficheiro de projeto, use o seguinte comando na pasta que contém o ficheiro do projeto:

# Use in a folder that contains a project file, such as <project-name>.csproj or <project-name>.vbproj.
nuget spec

O ficheiro project-name.nuspec< resultante> contém tokens que são substituídos no momento do empacotamento por valores do projeto, incluindo referências a quaisquer outros pacotes que já tenham sido instalados.

Se tiver dependências de pacotes para incluir no .nuspec, use nuget pack antes. Depois obtém o ficheiro .nuspec dentro do ficheiro .nupkg gerado. Por exemplo, use o seguinte comando:

# Use in a folder that contains a project file, such as <project-name>.csproj or <project-name>.vbproj.
nuget pack myproject.csproj

Um token é delimitado por símbolos $ em ambos os lados da propriedade de projeto. Por exemplo, o <id> valor num manifesto gerado desta forma normalmente assemelha-se à seguinte linha:

<id>$id$</id>

Esse token é substituído pelo valor AssemblyName do arquivo de projeto no momento de empacotamento. Para o mapeamento exato dos valores do projeto para os tokens do ficheiro .nuspec, consulte os Tokens de substituição.

Os tokens dispensam-te de precisar de atualizar valores cruciais como o número de versão no ficheiro .nuspec à medida que atualizas o projeto. Mas também podes substituir os tokens por valores literais.

Várias opções adicionais de embalagem estão disponíveis quando trabalha a partir de um projeto Visual Studio, conforme descrito no Execute o nuget pack para gerar o ficheiro .nupkg mais adiante neste artigo.

Pacotes de nível de solução

Apenas NuGet 2.x. Não disponível no NuGet 3.0+.

O NuGet 2.x suporta a noção de um pacote ao nível da solução que instala ferramentas ou comandos extra para a Gestor de Pacotes Console (o conteúdo da pasta tools), mas não adiciona referências, conteúdos ou personalizações de builds a quaisquer projetos da solução. Tais pacotes não contêm ficheiros nas suas pastas diretas de lib, conteúdo ou build, e nenhuma das suas dependências tem ficheiros nas respetivas pastas de lib, conteúdo ou build.

O NuGet acompanha pacotes instalados ao nível da solução num ficheiropackages.config na pasta .nuget , em vez do ficheiropackages.config do projeto.

A partir de um novo ficheiro com valores predefinidos

O comando seguinte cria um manifesto padrão com marcadores de posição, o que ajuda a garantir que começa com a estrutura de ficheiros correta:

nuget spec [<package-name>]

Se omitir <package-name>, o ficheiro resultante será nomeado Package.nuspec. Se fornecer um nome como Contoso.Utility.UsefulStuff, o ficheiro chama-se Contoso.Utility.UsefulStuff.nuspec.

O ficheiro .nuspec resultante contém espaços reservados para valores como projectUrl. Antes de usar o ficheiro para criar o ficheiro .nupkg final, substitua os marcadores de posição por valores apropriados.

Escolha um identificador de pacote exclusivo e defina o número da versão

O identificador do pacote (<id> elemento) e o número de versão (<version> elemento) são os dois valores mais importantes no manifesto, porque identificam de forma única o código exato contido no pacote.

Boas práticas para o identificador de embalagem

• Unicidade: O identificador deve ser único na galeria que aloja o pacote, como nuget.org. Antes de decidir um identificador, pesquise na galeria aplicável para verificar se o nome já está em uso. Para evitar conflitos, um bom padrão é usar o nome da sua empresa como a primeira parte do identificador, como Contoso.
• Nomes semelhantes a Namespace: Seguindo um padrão semelhante ao do namespace no .NET, usando notação de pontos em vez de hífens. Por exemplo, use Contoso.Utility.UsefulStuff em vez de Contoso-Utility-UsefulStuff ou Contoso_Utility_UsefulStuff. Os consumidores também acham útil quando o identificador do pacote corresponde aos namespaces usados no código.
• Pacotes de exemplo: Se produzir um pacote de código de exemplo que demonstra como usar outro pacote, anexe .Sample como sufixo ao identificador, como em Contoso.Utility.UsefulStuff.Sample. Um pacote de exemplo deste tipo tem uma dependência do pacote que demonstra como usar. Quando criar um pacote de exemplo, utilize o método de diretório de trabalho baseado em convenções descrito anteriormente. Na pasta de conteúdo , organize o código de exemplo numa pasta chamada \Samples\<identifier>, como em \Samples\Contoso.Utility.UsefulStuff.Sample.

Boas práticas para a versão do pacote

• Em geral, define a versão do pacote para corresponder à biblioteca. Esta orientação é recomendada, mas não estritamente obrigatória. Esta prática é simples quando se limita um pacote a um único assembly, como descrito anteriormente em Decidir quais assemblies empacotar. De um modo geral, lembre-se que o próprio NuGet lida com versões de pacotes ao resolver dependências, não com versões de assembly.
• Quando usar um esquema de versões não padrão, considere as regras de versionamento do NuGet explicadas em Versionamento de Pacotes.

Para outros recursos úteis para compreender a versionação, consulte a seguinte série de breves publicações no blogue:

• Parte 1: Enfrentando o inferno das DLLs
• Parte 2: O algoritmo central
• Parte 3: Unificação através de redirecionamentos vinculativos

Adicionar um ficheiro read-me e outros ficheiros

Para especificar diretamente os ficheiros a incluir no pacote, use o <files> nó no ficheiro .nuspec, que vem após a <metadata> etiqueta.

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
    <metadata>
        <!-- ... -->
    </metadata>
    <files>
        <!-- Add files from an arbitrary folder that's not necessarily in the project. -->
        <file src="..\..\SomeRoot\**\*.*" target="" />
    </files>
</package>

Para incluir um ficheiro read-me no pacote, use o readme elemento de metadados para especificar o caminho de destino para o ficheiro read-me. Usa também um file elemento de metadados para especificar o caminho de origem e a pasta de destino do ficheiro read-me. Para obter mais informações, veja readme.

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
    <metadata>
        <!-- ... -->
        <readme>docs\readme.md</readme>
        <!-- ... -->
    </metadata>
    <files>
        <!-- Add a read-me file. -->
        <file src="..\readme.md" target="docs\" />
    </files>
</package>

O Visual Studio mostra o conteúdo do ficheiro read-me na interface do Gestor de Pacotes. Por exemplo, a captura de ecrã seguinte mostra o ficheiro read-me do HtmlAgilityPack pacote:

Incluir suportes e alvos do MSBuild em um pacote

Em alguns casos, pode querer adicionar alvos de construção personalizados ou propriedades a projetos que consomem o seu pacote, como executar uma ferramenta ou processo personalizado durante a compilação. Para mais informações sobre alvos e propriedades de construção personalizadas, consulte MSBuild .props e .targets in a package.

Criar <ficheiros package-id.targets> ou <package-id.props>, como Contoso.Utility.UsefulStuff.targets, nas pastas de build do projeto.

Depois, no ficheiro .nuspec, faça referência a estes ficheiros no nó <files>:

<?xml version="1.0"?>
<package >
    <metadata minClientVersion="2.5">
    <!-- ... -->
    </metadata>
    <files>
        <!-- In the package build folder, include everything that's in the local build folder. -->
        <file src="build\**" target="build" />

        <!-- Other files -->
        <!-- ... -->
    </files>
</package>

Quando pacotes são adicionados a um projeto, o NuGet inclui automaticamente estas propriedades e alvos.

Execute nuget pack para gerar o arquivo .nupkg

Quando usar um assembly ou o diretório de trabalho baseado em convenções, crie um pacote executando o comando nuget pack com o seu ficheiro .nuspec. No comando seguinte, substitua <project-name> pelo nome do seu projeto:

nuget pack <project-name>.nuspec

Quando usares um projeto Visual Studio, executa nuget pack com o ficheiro do teu projeto. Este comando carrega automaticamente o ficheiro .nuspec do projeto e substitui quaisquer tokens nele pelos valores correspondentes no ficheiro do projeto:

nuget pack <project-name>.csproj

Em todos os casos, nuget pack exclui pastas que começam com um ponto, como .git ou .hg.

O NuGet indica se existem erros no ficheiro .nuspec que precisam de ser corrigidos, como valores provisórios no manifesto que precisam de ser atualizados.

Após nuget pack ser bem-sucedido, tem um ficheiro .nupkg que pode publicar numa galeria adequada, conforme descrito em Publish NuGet packages.

Opções adicionais

Você pode usar várias opções de linha de comando com o nuget pack para excluir arquivos, alterar o número da versão no manifesto e mudar a pasta de saída, entre outros recursos. Para uma lista completa, consulte o comando pack (NuGet CLI).

As seguintes opções são algumas comuns nos projetos Visual Studio:

• Projetos referenciados: Se o projeto fizer referência a outros projetos, você poderá adicionar os projetos referenciados como parte do pacote ou como dependências, usando a -IncludeReferencedProjects opção:

  nuget pack MyProject.csproj -IncludeReferencedProjects
  

  Este processo de inclusão é recursivo. Por exemplo, se o MyProject.csproj referenciar os projetos B e C, e esses projetos referenciarem D, E e F, ficheiros de B, C, D, E e F são incluídos no pacote.

  Se um projeto referenciado incluir um ficheiro .nuspec próprio, o NuGet adiciona esse projeto referenciado como dependência. Você precisa empacotar e publicar esse projeto separadamente.

• Configuração da compilação: Por defeito, o NuGet usa a configuração padrão da compilação definida no ficheiro do projeto, normalmente Debug. Para arquivar ficheiros de uma configuração de build diferente, como Release, use a opção -properties com a configuração:

  nuget pack MyProject.csproj -properties Configuration=Release
  

• Símbolos: Para incluir símbolos que permitam aos consumidores passar pelo código do seu pacote no depurador, utilize as opções -Symbols e -SymbolPackageFormat. Para a -SymbolPackageFormat opção, especifique um formato de snupkg:

  nuget pack MyProject.csproj -symbols -SymbolPackageFormat snupkg
  

Instalação do pacote de teste

Antes de publicar um pacote, normalmente quer testar o processo de instalação do pacote num projeto. Um teste ajuda a garantir que todos os ficheiros necessários acabam no lugar correto do projeto.

Pode testar as instalações manualmente no Visual Studio ou na linha de comandos; usando os passos padrão de instalação de pacotes.

Para testes automatizados, pode usar o seguinte processo básico:

1. Copie o ficheiro .nupkg para uma pasta local.
2. Adicione a pasta às fontes dos seus pacotes usando o nuget sources add -name <name> -source <path> comando. Para mais informações, consulte o comando sources (NuGet CLI). Precisas de definir esta fonte local apenas uma vez em cada computador.
3. Instale o pacote a partir dessa fonte usando nuget install <package-ID> -source <name>. Neste comando, <name> deve corresponder ao nome da fonte que usas no nuget sources comando. Ao especificar a fonte, indica-se ao NuGet que instale o pacote exclusivamente a partir dessa origem.
4. Examine seu sistema de arquivos para verificar se os arquivos estão instalados corretamente.

Conteúdo relacionado

Depois de criares um pacote, que é um ficheiro .nupkg , podes publicá-lo na galeria que escolheres. Para mais informações, consulte Publicar pacotes NuGet.

Também pode estender as capacidades do seu pacote ou suportar outros cenários. Para obter mais informações, consulte os seguintes artigos:

• Controle de versão do pacote
• Suporta múltiplas versões .NET
• Transformação do código-fonte e dos ficheiros de configuração
• Criação de pacotes NuGet localizados
• Construir pacotes de pré-lançamento
• Definir um tipo de pacote NuGet
• Criar pacotes NuGet que contenham assemblies de interoperabilidade COM

Para outros tipos de embalagens a conhecer, consulte os seguintes artigos:

• Criação de pacotes nativos
• Criação de pacotes de símbolos (.snupkg)