Referência do .nuspec

  • Artigo

Um arquivo .nuspec é um manifesto XML que contém metadados do pacote. Esse manifesto é usado para compilar o pacote e fornecer informações aos consumidores. O manifesto sempre é incluído em um pacote.

Neste tópico:

Compatibilidade de tipo de projeto

Formato e esquema geral

O arquivo de esquema nuspec.xsd atual pode ser encontrado no repositório GitHub do NuGet.

Dentro desse esquema, um arquivo .nuspec tem o seguinte formato geral:

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <!-- Required elements-->
        <id></id>
        <version></version>
        <description></description>
        <authors></authors>

        <!-- Optional elements -->
        <!-- ... -->
    </metadata>
    <!-- Optional 'files' node -->
</package>

Para obter uma representação visual do esquema, abra o arquivo de esquema no Visual Studio no modo de Design e clique no link Gerenciador de Esquema XML. Como alternativa, abra o arquivo como código, clique com o botão direito do mouse no editor e selecione Mostrar Gerenciador de Esquema XML. De qualquer forma, você receberá uma exibição como a mostrada abaixo (quando expandido):

Visual Studio Schema Explorer with nuspec.xsd open

Todos os nomes de elementos XML no arquivo .nuspec diferenciam maiúsculas de minúsculas, como é o caso do XML em geral. Por exemplo, o uso do elemento <description> de metadados está correto e <Description> não está correto. O invólucro apropriado para cada nome de elemento está documentado abaixo.

Elementos de metadados necessários

Embora os elementos a seguir sejam os requisitos mínimos para um pacote, considere adicionar os elementos de metadados opcionais para melhorar a experiência geral que os desenvolvedores têm com o pacote.

Esses elementos precisam aparecer dentro de um elemento <metadata>.

ID

O identificador de pacote que não diferencia maiúsculas de minúsculas, o qual deve ser exclusivo no nuget.org ou em qualquer galeria na qual o pacote reside. IDs podem não conter espaços nem caracteres que não sejam válidos para uma URL e geralmente seguem as regras de namespace do .NET. Consulte Escolhendo um identificador de pacote exclusivo para ver diretrizes.

Ao carregar um pacote para nuget.org, o campo id é limitado a 128 caracteres.

version

A versão do pacote, seguindo o padrão principal.secundária.patch. Os números de versão podem incluir um sufixo de pré-lançamento, conforme descrito em Controle de versões de pré-lançamento.

Ao carregar um pacote para nuget.org, o campo version é limitado a 64 caracteres.

descrição

Uma descrição do pacote para exibição na interface do usuário.

Ao carregar um pacote para nuget.org, o campo description é limitado a 4000 caracteres.

authors

Uma lista separada por vírgulas de autores de pacotes, correspondendo aos nomes de perfil em nuget.org. Eles são exibidos na Galeria NuGet no nuget.org e são usados para fazer referência cruzada de pacotes pelos mesmos autores.

Ao carregar um pacote para nuget.org, o campo authors é limitado a 4000 caracteres.

Elementos de metadados opcionais

owners

Importante

proprietários é preterido. Em vez disso, use autores.

Uma lista separada por vírgulas dos criadores de pacotes usando nomes de perfil em nuget.org. Geralmente, é a mesma lista que existe em authors, e é ignorada ao carregar o pacote para nuget.org. Consulte Gerenciar proprietários de pacotes em nuget.org.

projectUrl

Uma URL para a home page do pacote, geralmente mostrada em exibições de interface do usuário, bem como em nuget.org.

Ao carregar um pacote para nuget.org, o campo projectUrl é limitado a 4000 caracteres.

licenseUrl

Importante

licenseUrl é preterido. Em vez disso, use a licença.

Uma URL para a licença do pacote, geralmente mostrada em IUs como nuget.org.

Ao carregar um pacote para nuget.org, o campo licenseUrl é limitado a 4000 caracteres.

license

Compatível com NuGet 4.9.0 e superior

Uma expressão de licença SPDX ou caminho para um arquivo de licença no pacote, geralmente mostrado em interfaces do usuário como nuget.org. Se você estiver licenciando o pacote sob uma licença comum, como MIT ou BSD-2-Clause, use o identificador de licença SPDX associado. Por exemplo:

<license type="expression">MIT</license>

Observação

NuGet.org só aceita expressões de licença que são aprovadas pela Open Source Initiative ou pela Free Software Foundation.

Se o pacote estiver licenciado sob várias licenças comuns, você poderá especificar uma licença composta usando a sintaxe de expressão SPDX versão 2.0. Por exemplo:

<license type="expression">BSD-2-Clause OR MIT</license>

Se você usar uma licença personalizada que não tem suporte por expressões de licença, poderá empacotar um arquivo .txt ou .md com o texto da licença. Por exemplo:

<package>
  <metadata>
    ...
    <license type="file">LICENSE.txt</license>
    ...
  </metadata>
  <files>
    ...
    <file src="licenses\LICENSE.txt" target="" />
    ...
  </files>
</package>

Para obter o equivalente do MSBuild, consulte Empacotar uma expressão de licença ou um arquivo de licença.

A sintaxe exata das expressões de licença do NuGet é descrita abaixo em ABNF.

license-id            = <short form license identifier from https://spdx.org/spdx-specification-21-web-version#h.luq9dgcle9mo>

license-exception-id  = <short form license exception identifier from https://spdx.org/spdx-specification-21-web-version#h.ruv3yl8g6czd>

simple-expression = license-id / license-id”+”

compound-expression =  1*1(simple-expression /
                simple-expression "WITH" license-exception-id /
                compound-expression "AND" compound-expression /
                compound-expression "OR" compound-expression ) /                
                "(" compound-expression ")" )

license-expression =  1*1(simple-expression / compound-expression / UNLICENSED)

iconUrl

Importante

iconUrl é preterido. Use o ícone. em vez disso.

Um URL para uma imagem de 128x128 com fundo transparente para usar como ícone do pacote na exibição da IU. Verifique se esse elemento contém a URL direta da imagem e não a URL de uma página da Web que contém a imagem. Por exemplo, para usar uma imagem do GitHub, use a URL do arquivo raw como https://github.com/<username>/<repository>/raw/<branch>/<logo.png>.

Ao carregar um pacote para nuget.org, o campo iconUrl é limitado a 4000 caracteres.

ícone

Compatível com NuGet 5.3.0 e superior

É um caminho para um arquivo de imagem dentro do pacote, geralmente mostrado em interfaces do usuário como nuget.org como o ícone do pacote. O tamanho do arquivo de imagem é limitado a 1 MB. Os formatos de arquivo com suporte incluem JPEG e PNG. Recomendamos uma resolução de imagem de 128x128.

Por exemplo, você adicionaria o seguinte ao seu nuspec ao criar um pacote usando nuget.exe:

<package>
  <metadata>
    ...
    <icon>images\icon.png</icon>
    ...
  </metadata>
  <files>
    ...
    <file src="..\icon.png" target="images\" />
    ...
  </files>
</package>

Exemplo nuspec do ícone do pacote.

Para o equivalente do MSBuild, consulte Compactar um arquivo de imagem de ícone.

Dica

Para manter a compatibilidade com versões anteriores de clientes e fontes que ainda não oferecem suporte a icon, especifique icon e iconUrl. O Visual Studio oferece suporte a icon para pacotes provenientes de uma fonte baseada em pasta.

readme

Compatível com o NuGet 5.10.0 versão preliminar 2 e superior

Ao empacotar um arquivo Leiame, você precisa usar o elemento readme para especificar o caminho do pacote, relativo à raiz do pacote. Além disso, você precisa certificar-se de que o arquivo está incluído no pacote. Os formatos de arquivo suportados incluem apenas Markdown (.md).

Por exemplo, você adicionaria o seguinte ao seu nuspec para empacotar um arquivo Leiame com seu projeto:

<package>
  <metadata>
    ...
    <readme>docs\readme.md</readme>
    ...
  </metadata>
  <files>
    ...
    <file src="..\readme.md" target="docs\" />
    ...
  </files>
</package>

Para o equivalente do MSBuild, consulte Compactar um arquivo readme.

requireLicenseAcceptance

Um valor booliano que especifica se o cliente precisa solicitar que o consumidor aceite a licença do pacote antes de instalá-lo.

developmentDependency

(2.8 ou superior) Um valor booliano que especifica se o pacote está marcado como uma dependência somente de desenvolvimento, que impede que o pacote seja incluído como uma dependência em outros pacotes. Com PackageReference (NuGet 4.8+), esse sinalizador também significa que ele excluirá os recursos em tempo de compilação. Para obter mais informações, confira Suporte deDevelopmentDependency para PackageReference.

summary

Importante

summary está sendo preterido. Use description em vez disso.

Uma breve descrição do pacote para exibição de interface do usuário. Se omitido, uma versão truncada do description é usada.

Ao carregar um pacote para nuget.org, o campo summary é limitado a 4000 caracteres.

releaseNotes

(1.5 ou superior) Uma descrição das alterações feitas nesta versão do pacote, frequentemente usado na interface do usuário como a guia Atualizações do Gerenciador de Pacotes do Visual Studio em vez da descrição do pacote.

Ao carregar um pacote para nuget.org, o campo releaseNotes é limitado a 35.000 caracteres.

(1.5 ou superior) Detalhes sobre direitos autorais do pacote.

Ao carregar um pacote para nuget.org, o campo copyright é limitado a 4000 caracteres.

linguagem

A identificação de localidade para o pacote. Consulte Criando pacotes localizados.

marcas

Uma lista delimitada por espaço de marcas e palavras-chave que descrevem o pacote e auxiliam na descoberta de pacotes por meio de pesquisa e filtragem.

Ao carregar um pacote para nuget.org, o campo tags é limitado a 4000 caracteres.

serviceable

(3.3 ou superior) Somente para uso interno do NuGet.

repository

Metadados do repositório, consistindo em quatro atributos opcionais: type e url(4.0+) e branch e commit(4.6+). Esses atributos permitem mapear o para o repositório que o criou, com o potencial de obter detalhes tão detalhados quanto o nome da ramificação individual e/ou confirmar o hash SHA-1 que criou o pacote .nupkg. Essa deve ser uma URL disponível publicamente que pode ser invocada diretamente por um software de controle de versão. Não deve ser uma página html, pois isso é destinado ao computador. Para vincular à página do projeto, use o campo projectUrl.

Por exemplo:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        ...
        <repository type="git" url="https://github.com/NuGet/NuGet.Client.git" branch="dev" commit="e1c65e4524cd70ee6e22abe33e6cb6ec73938cb3" />
        ...
    </metadata>
</package>

Ao carregar um pacote para nuget.org, o atributo type é limitado a 100 caracteres e o atributo url é limitado a 4000 caracteres.

title

Um título amigável para humanos do pacote que pode ser usado em algumas exibições de interface do usuário. (nuget.org e o Gerenciador de pacotes no Visual Studio não mostram título)

Ao carregar um pacote para o nuget.org, o campo title é limitado a 256 caracteres, mas não é usado para fins de exibição.

Elementos de coleção

packageTypes

(3.5 ou superior) Uma coleção de zero ou mais elementos <packageType> que especificam o tipo do pacote se for diferente de um pacote de dependência tradicional. Cada packageType tem os atributos de name e version. Consulte Definindo um tipo de pacote.

dependencies

Uma coleção de zero ou mais elementos <dependency> que especificam as dependências do pacote. Cada dependência tem atributos de id, version, include (3.x ou superior) e exclude (3.x ou superior). Consulte Dependências abaixo.

frameworkAssemblies

(1.2 ou superior) Uma coleção de zero ou mais elementos <frameworkAssembly> identifica as referências de assembly do .NET Framework que este pacote requer, o que garante que elas sejam adicionadas aos projetos que consomem o pacote. Cada frameworkAssembly tem os atributos assemblyName e targetFramework. Consulte Especificando as referências GAC de assembly do framework abaixo.

referências

(1.5 ou superior) Uma coleção de zero ou mais assemblies de nomenclatura de elementos <reference> na pasta lib do pacote que são adicionados como referências de projeto. Cada referência tem um atributo file. <references> também pode conter um elemento <group> com um atributo targetFramework, que contém elementos <reference>. Se omitido, todas as referências no lib são incluídas. Consulte Especificando referências de assembly explícitas abaixo.

contentFiles

(3.3 ou superior) Uma coleção de elementos <files> que identificam os arquivos de conteúdo para incluir o projeto consumidor. Esses arquivos são especificados com um conjunto de atributos que descrevem como eles devem ser usados dentro do sistema de projeto. Consulte Especificando arquivos a serem incluídos no pacote abaixo.

arquivos

O nó <package> pode conter um nó <files> como um irmão de <metadata> e um filho <contentFiles> em <metadata>, para especificar quais assembly e arquivos de conteúdo são incluídos no pacote. Consulte Incluindo arquivos do assembly e Incluindo arquivos de conteúdo mais adiante neste tópico para obter detalhes.

Atributos de metadados

minClientVersion

Especifica a versão mínima do cliente NuGet que pode instalar esse pacote, imposta pelo nuget.exe e pelo Gerenciador de Pacotes do Visual Studio. Isso é usado sempre que o pacote depender de recursos específicos do arquivo .nuspec que foram adicionados em uma versão específica do cliente do NuGet. Por exemplo, um pacote usando o atributo developmentDependency deve especificar “2.8” para minClientVersion. Da mesma forma, um pacote usando o elemento contentFiles (consulte a próxima seção) deve definir minClientVersion para “3.3”. Observe também que, como os clientes do NuGet antes de 2.5 não reconhecem esse sinalizador, eles sempre recusam instalar o pacote, não importando o que minClientVersion contém.

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata minClientVersion="100.0.0.1">
        <id>dasdas</id>
        <version>2.0.0</version>
        <title />
        <authors>dsadas</authors>
        <owners />
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>My package description.</description>
    </metadata>
    <files>
        <file src="content\one.txt" target="content\one.txt" />
    </files>
</package>

Tokens de substituição

Ao criar um pacote, o comando nuget pack substitui tokens delimitados por $ nos nós <metadata> e <files> do arquivo .nuspec com valores que vêm de um arquivo de projeto ou a opção pack do comando -properties.

Na linha de comando, você especifica os valores de token com nuget pack -properties <name>=<value>;<name>=<value>. Por exemplo, você pode usar um token como $owners$ e $desc$ no .nuspec e fornecer os valores no tempo de empacotamento da seguinte maneira:

nuget pack MyProject.csproj -properties
    owners=janedoe,harikm,kimo,xiaop;desc="Awesome app logger utility"

Para usar valores de um projeto, especifique os tokens descritos na tabela a seguir (AssemblyInfo refere-se ao arquivo em Properties como AssemblyInfo.cs ou AssemblyInfo.vb).

Para usar esses tokens, execute nuget pack com o arquivo de projeto em vez de apenas o .nuspec. Por exemplo, ao usar o comando a seguir, os tokens $id$ e $version$ em um arquivo .nuspec são substituídos pelos valores AssemblyName e AssemblyVersion do projeto:

nuget pack MyProject.csproj

Normalmente, quando você tem um projeto, você cria o .nuspec inicialmente usando nuget spec MyProject.csproj, o que inclui alguns desses tokens padrão automaticamente. No entanto, se um projeto não tiver valores para os elementos .nuspec necessários, nuget pack falhará. Além disso, se você alterar os valores de projeto, lembre-se de recompilá-lo antes de criar o pacote. Isso pode ser feito convenientemente com a opção build do comando do pacote.

Com exceção de $configuration$, os valores do projeto são usados como preferenciais sobre qualquer um com o mesmo token na linha de comando.

Token Origem do valor Valor
$id$ Arquivo de projeto AssemblyName (título) do arquivo do projeto
$version$ AssemblyInfo AssemblyInformationalVersion se existir, caso contrário AssemblyVersion
$author$ AssemblyInfo AssemblyCompany
$title$ AssemblyInfo AssemblyTitle
$description$ AssemblyInfo AssemblyDescription
$copyright$ AssemblyInfo AssemblyCopyright
$configuration$ DLL de assembly Configuração usada para compilar o assembly, com Depuração como padrão. Observe que, para criar um pacote usando uma configuração de Versão, você sempre usará -properties Configuration=Release na linha de comando.

Tokens também podem ser usados para resolver caminhos quando você incluir arquivos do assembly e arquivos de conteúdo. Os tokens têm os mesmos nomes que as propriedades do MSBuild, tornando possível selecionar os arquivos a serem incluídos, dependendo da configuração de build atual. Por exemplo, se você usar os seguintes tokens no arquivo .nuspec:

<files>
    <file src="bin\$configuration$\$id$.pdb" target="lib\net40" />
</files>

E você compila um assembly cujo AssemblyName é LoggingLibrary com a configuração Release no MSBuild, as linhas resultantes no arquivo .nuspec do pacote são as seguintes:

<files>
    <file src="bin\Release\LoggingLibrary.pdb" target="lib\net40" />
</files>

Elemento de dependências

O elemento <dependencies> dentro do <metadata> contém diversos elementos <dependency> que identificam os outros pacotes dos quais o pacote de nível superior depende. Os atributos para cada <dependency> são os seguintes:

Atributo Descrição
id (Obrigatório) A ID do pacote de dependência, como "EntityFramework" e "NUnit", que é o nome do pacote nuget.org mostrado em uma página do pacote.
version (Obrigatório) O intervalo de versões aceitáveis como uma dependência. Consulte Controle de versão do pacote para ver a sintaxe exata. Versões flutuantes não têm suporte.
include Uma lista delimitada por vírgulas de marcas de inclusão/exclusão (veja abaixo) que indicam a dependência a ser incluída no pacote final. O valor padrão é all.
excluir Uma lista delimitada por vírgulas de marcas de inclusão/exclusão (veja abaixo) que indicam a dependência a ser excluída do pacote final. O valor padrão é build,analyzers, que pode ser substituído. Porém, content/ ContentFiles também é implicitamente excluído no pacote final que não pode ser substituído. Marcas especificadas com exclude têm precedência sobre aquelas especificadas com include. Por exemplo, include="runtime, compile" exclude="compile" é o mesmo que include="runtime".

Ao carregar um pacote para nuget.org, o atributo id de cada dependência é limitado a 128 caracteres e o atributo version é limitado a 256 caracteres.

Marca Incluir/Excluir Pastas afetadas do destino
contentFiles Sumário
runtime Runtime, Resources e FrameworkAssemblies
compilar lib
compilar build (objetos e destinos do MSBuild)
nativa nativa
nenhum Nenhuma pasta
all Todas as pastas

Por exemplo, as linhas a seguir indicam as dependências no PackageA versão 1.1.0 ou superior e PackageB versão 1.x.

<dependencies>
    <dependency id="PackageA" version="1.1.0" />
    <dependency id="PackageB" version="[1,2)" />
</dependencies>

As linhas a seguir indicam dependências nos mesmos pacotes, mas especificam a inclusão de pastas contentFiles e build de PackageA tudo, mas as pastas native e compile de PackageB"

<dependencies>
    <dependency id="PackageA" version="1.1.0" include="contentFiles, build" />
    <dependency id="PackageB" version="[1,2)" exclude="native, compile" />
</dependencies>

Importante

Ao criar um .nuspec de um projeto usando nuget spec, as dependências que existem no projeto não são incluídas automaticamente no arquivo .nuspec resultante. Em vez disso, use o nuget pack myproject.csproj e obtenha o arquivo .nuspec de dentro do arquivo .nupkg gerado. Este .nuspec contém as dependências.

Grupos de dependência

Versão 2.0 ou superior

Como alternativa a uma única lista simples, as dependências podem ser especificadas de acordo com o perfil da estrutura do projeto de destino usando elementos <group> dentro de <dependencies>.

Cada grupo tem um atributo chamado targetFramework e contém zero ou mais elementos <dependency>. Essas referências são instaladas juntas quando a estrutura de destino é compatível com o perfil da estrutura do projeto.

O elemento <group> sem um atributo targetFramework será usado como a lista de dependências padrão ou de fallback. Consulte Estruturas de destino para ver os identificadores de estrutura exatos.

Importante

O formato do grupo não pode ser combinado com uma lista simples.

Observação

O formato do Target Framework Moniker (TFM) usado na pasta lib/ref é diferente quando comparado ao TFM usado no dependency groups. Se as estruturas de destino declaradas nas pastas dependencies group e lib/ref no arquivo .nuspec não tiverem correspondências exatas, o comando pack gerará o Aviso NuGet NU5128.

O exemplo a seguir mostra diferentes variações do elemento <group>:

<dependencies>
    <group>
        <dependency id="RouteMagic" version="1.1.0" />
    </group>

    <group targetFramework=".NETFramework4.7.2">
        <dependency id="jQuery" version="1.6.2" />
        <dependency id="WebActivator" version="1.4.4" />
    </group>

    <group targetFramework="netcoreapp3.1">
    </group>
</dependencies>

Referências de assembly explícitas

O elemento <references> é usado por projetos usando packages.config para especificar explicitamente os assemblies aos quais o projeto de destino deve fazer referência ao usar o pacote. Referências explícitas são geralmente usadas apenas para assemblies de tempo de design. Para obter mais informações, consulte a página sobre como selecionar assemblies referenciados por projetos.

Por exemplo, o elemento <references> a seguir instrui o NuGet a adicionar referências a apenas xunit.dll e xunit.extensions.dll, mesmo se houver assemblies adicionais no pacote:

<references>
    <reference file="xunit.dll" />
    <reference file="xunit.extensions.dll" />
</references>

Grupos de referência

Como alternativa a uma única lista simples, as referências podem ser especificadas de acordo com o perfil da estrutura do projeto de destino usando elementos <group> dentro de <references>.

Cada grupo tem um atributo chamado targetFramework e contém zero ou mais elementos <reference>. Essas referências são adicionadas a um projeto quando a estrutura de destino é compatível com o perfil de estrutura do projeto.

O elemento <group> sem um atributo targetFramework será usado como a lista de referências padrão ou de fallback. Consulte Estruturas de destino para ver os identificadores de estrutura exatos.

Importante

O formato do grupo não pode ser combinado com uma lista simples.

O exemplo a seguir mostra diferentes variações do elemento <group>:

<references>
    <group>
        <reference file="a.dll" />
    </group>

    <group targetFramework="net45">
        <reference file="b45.dll" />
    </group>

    <group targetFramework="netcore45">
        <reference file="bcore45.dll" />
    </group>
</references>

Referências de assembly de estrutura

Assemblies do Framework são aqueles que fazem parte do .NET Framework e já devem estar no GAC (cache de assembly global) para qualquer computador especificado. Ao identificar assemblies dentro do elemento <frameworkAssemblies>, um pacote pode garantir que as referências necessárias sejam adicionadas a um projeto caso este já não tenha essas referências. Tais assemblies, obviamente, não são incluídos em um pacote diretamente.

O elemento <frameworkAssemblies> contém zero ou mais elementos <frameworkAssembly>, cada um deles especifica os seguintes atributos:

Atributo Descrição
assemblyName (Obrigatório) O nome totalmente qualificado do assembly.
targetFramework (Opcional) Especifica a estrutura de destino à qual esta referência se aplica. Se omitido, indica que a referência se aplica a todas as estruturas. Consulte Estruturas de destino para ver os identificadores de estrutura exatos.

O exemplo a seguir mostra uma referência a System.Net todas as estruturas de destino e uma referência a System.ServiceModel apenas para o .NET Framework 4.0:

<frameworkAssemblies>
    <frameworkAssembly assemblyName="System.Net"  />

    <frameworkAssembly assemblyName="System.ServiceModel" targetFramework="net40" />
</frameworkAssemblies>

Incluindo arquivos do assembly

Se você seguir as convenções descritas em Criando um pacote, não será necessário especificar explicitamente uma lista de arquivos no arquivo .nuspec. O comando nuget pack escolherá automaticamente os arquivos necessários.

Importante

Quando um pacote é instalado em um projeto, o NuGet adiciona automaticamente as referências de assembly às DLLs do pacote, excluindo aquelas que são nomeados .resources.dll porque são considerados assemblies satélites. Por esse motivo, evite usar .resources.dll para arquivos que contêm código de pacote essencial.

Para ignorar esse comportamento automático e controlar explicitamente quais arquivos são incluídos em um pacote, coloque uma elemento <files> como um filho de <package> (e um irmão de <metadata>), identificando cada arquivo com um elemento <file> separado. Por exemplo:

<files>
    <file src="bin\Debug\*.dll" target="lib" />
    <file src="bin\Debug\*.pdb" target="lib" />
    <file src="tools\**\*.*" exclude="**\*.log" />
</files>

Com o NuGet 2.x e anteriores, e em projetos que usam packages.config, o elemento <files> também é usado para incluir arquivos de conteúdo imutáveis quando um pacote é instalado. Com o NuGet 3.3 ou superior e projetos PackageReference, o elemento <contentFiles> é usado. Consulte Incluindo arquivos de conteúdo abaixo para ver os detalhes.

Atributos do elemento de arquivo

Cada elemento <file> especifica os seguintes atributos:

Atributo Descrição
src O local do arquivo ou arquivos a serem incluídos, sujeito a exclusões especificadas pelo atributo exclude. O caminho é relativo ao arquivo .nuspec, a menos que um caminho absoluto seja especificado. O caractere curinga * é permitido e o caractere curinga duplo ** sugere uma pesquisa de pastas recursiva.
destino O caminho relativo para a pasta dentro do pacote em que os arquivos de origem são colocados, os quais devem começar com lib, content, build ou tools. Consulte Criando um .nuspec de um diretório de trabalho baseado em convenção.
exclude Uma lista separada por ponto-e-vírgula de arquivos ou padrões de arquivo para excluir o local src. O caractere curinga * é permitido e o caractere curinga duplo ** sugere uma pesquisa de pastas recursiva.

Exemplos

Assembly único

Source file:
    library.dll

.nuspec entry:
    <file src="library.dll" target="lib" />

Packaged result:
    lib\library.dll

Assembly único específico para uma estrutura de destino

Source file:
    library.dll

.nuspec entry:
    <file src="assemblies\net40\library.dll" target="lib\net40" />

Packaged result:
    lib\net40\library.dll

Conjunto de DLLs que usam um caractere curinga

Source files:
    bin\release\libraryA.dll
    bin\release\libraryB.dll

.nuspec entry:
    <file src="bin\release\*.dll" target="lib" />

Packaged result:
    lib\libraryA.dll
    lib\libraryB.dll

DLLs de estruturas diferentes

Source files:
    lib\net40\library.dll
    lib\net20\library.dll

.nuspec entry (using ** recursive search):
    <file src="lib\**" target="lib" />

Packaged result:
    lib\net40\library.dll
    lib\net20\library.dll

Excluindo arquivos

Source files:
    \tools\fileA.bak
    \tools\fileB.bak
    \tools\fileA.log
    \tools\build\fileB.log

.nuspec entries:
    <file src="tools\*.*" target="tools" exclude="tools\*.bak" />
    <file src="tools\**\*.*" target="tools" exclude="**\*.log" />

Package result:
    (no files)

Incluindo arquivos de conteúdo

Arquivos de conteúdo são arquivos imutáveis que um pacote incluir em um projeto. Sendo imutáveis, eles não foram projetados para serem modificados pelo projeto consumidor. Alguns exemplos de arquivos de conteúdo:

  • Imagens que são inseridas como recursos
  • Arquivos de origem que já são compilados
  • Scripts que precisam ser incluídos na saída de build do projeto
  • Arquivos de configuração para o pacote que precisam ser incluídos no projeto, mas não precisam de nenhuma alteração específica do projeto

Arquivos de conteúdo são incluídos em um pacote usando o elemento <files>, especificando a pasta content no atributo target. No entanto, esses arquivos são ignorados quando o pacote é instalado em um projeto usando PackageReference, que usa o elemento <contentFiles>.

Para máxima compatibilidade com projetos de consumo, é ideal que um pacote especifique os arquivos de conteúdo em ambos os elementos.

Usando o elemento de arquivos para arquivos de conteúdo

Para arquivos de conteúdo, basta usar o mesmo formato que os arquivos do assembly, porém especifique content como a pasta base no atributo target conforme mostrado nos exemplos a seguir.

Arquivos de conteúdo básico

Source files:
    css\mobile\style1.css
    css\mobile\style2.css

.nuspec entry:
    <file src="css\mobile\*.css" target="content\css\mobile" />

Packaged result:
    content\css\mobile\style1.css
    content\css\mobile\style2.css

Arquivos de conteúdo com a estrutura de diretório

Source files:
    css\mobile\style.css
    css\mobile\wp7\style.css
    css\browser\style.css

.nuspec entry:
    <file src="css\**\*.css" target="content\css" />

Packaged result:
    content\css\mobile\style.css
    content\css\mobile\wp7\style.css
    content\css\browser\style.css

Arquivo de conteúdo específico para uma estrutura de destino

Source file:
    css\cool\style.css

.nuspec entry
    <file src="css\cool\style.css" target="Content" />

Packaged result:
    content\style.css

Arquivo de conteúdo copiado para uma pasta com ponto no nome

Nesse caso, o NuGet vê que a extensão em target não corresponde à extensão em src e, portanto, trata essa parte do nome no target como uma pasta:

Source file:
    images\picture.png

.nuspec entry:
    <file src="images\picture.png" target="Content\images\package.icons" />

Packaged result:
    content\images\package.icons\picture.png

Arquivos de conteúdo sem extensões

Para incluir arquivos sem extensão, use os curingas * ou **:

Source file:
    flags\installed

.nuspec entry:
    <file src="flags\**" target="flags" />

Packaged result:
    flags\installed

Arquivos de conteúdo com caminho e destino profundos

Nesse caso, como as extensões de arquivo de origem e de destino correspondem, o NuGet pressupõe que o destino é um nome de arquivo e não uma pasta:

Source file:
    css\cool\style.css

.nuspec entry:
    <file src="css\cool\style.css" target="Content\css\cool" />
    or:
    <file src="css\cool\style.css" target="Content\css\cool\style.css" />

Packaged result:
    content\css\cool\style.css

Renomeando um arquivo de conteúdo no pacote

Source file:
    ie\css\style.css

.nuspec entry:
    <file src="ie\css\style.css" target="Content\css\ie.css" />

Packaged result:
    content\css\ie.css

Excluindo arquivos

Source file:
    docs\*.txt (multiple files)

.nuspec entry:
    <file src="docs\*.txt" target="content\docs" exclude="docs\admin.txt" />
    or
    <file src="*.txt" target="content\docs" exclude="admin.txt;log.txt" />

Packaged result:
    All .txt files from docs except admin.txt (first example)
    All .txt files from docs except admin.txt and log.txt (second example)

Usando o elemento contentFiles para arquivos de conteúdo

NuGet 4.0 e posteriores com PackageReference

Por padrão, um pacote coloca o conteúdo em uma pasta contentFiles (veja abaixo) e nuget pack incluiu todos os arquivos nessa pasta usando os atributos padrão. Nesse caso, não é necessário incluir um nó contentFiles no .nuspec.

Para controlar quais arquivos são incluídos, o elemento <contentFiles> especifica uma coleção de elementos <files> que identificam as inclusões dos arquivos exatos.

Esses arquivos são especificados com um conjunto de atributos que descrevem como eles devem ser usados dentro do sistema de projeto:

Atributo Descrição
include (Obrigatório) O local do arquivo ou arquivos a serem incluídos, sujeito a exclusões especificadas pelo atributo exclude. O caminho é relativo à pasta contentFiles, a menos que um caminho absoluto seja especificado. O caractere curinga * é permitido e o caractere curinga duplo ** sugere uma pesquisa de pastas recursiva.
exclude Uma lista separada por ponto-e-vírgula de arquivos ou padrões de arquivo para excluir o local src. O caractere curinga * é permitido e o caractere curinga duplo ** sugere uma pesquisa de pastas recursiva.
buildAction A ação de build para atribuir ao item de conteúdo para o MSBuild, como Content, None, Embedded Resource, Compile etc. O padrão é Compile.
copyToOutput Um booliano que indica se os itens de conteúdo devem ser copiados para a pasta de saída de compilação (ou publicação). O padrão é false.
flatten Um valor booliano que indica se os itens de conteúdo devem ser copiados para uma única pasta na saída do build (verdadeiro) ou preservar a estrutura de pasta no pacote (falso). Esse sinalizador só funciona quando o sinalizador copyToOutput está definido como true. O padrão é false.

Ao instalar um pacote, o NuGet aplicará os elementos filho de <contentFiles> de cima para baixo. Se várias entradas corresponderem ao mesmo arquivo, todas as entradas serão aplicadas. A entrada superior substitui as entradas mais baixas em caso de conflito para o mesmo atributo.

Estrutura de pastas do pacote

O projeto do pacote deve estruturar o conteúdo usando o seguinte padrão:

/contentFiles/{codeLanguage}/{TxM}/{any?}
  • codeLanguages pode ser cs, vb, fs, any ou o equivalente em letras minúsculas de determinado $(ProjectLanguage)
  • TxM é qualquer moniker da estrutura de destino legal compatível com o NuGet (consulte Estruturas de destino).
  • Qualquer estrutura de pasta pode ser acrescentada ao final dessa sintaxe.

Por exemplo:

Language- and framework-agnostic:
    /contentFiles/any/any/config.xml

net45 content for all languages
    /contentFiles/any/net45/config.xml

C#-specific content for net45 and up
    /contentFiles/cs/net45/sample.cs

As pastas vazias podem usar . para recusar o fornecimento de conteúdo para certas combinações de idioma e TxM, por exemplo:

/contentFiles/vb/any/code.vb
/contentFiles/cs/any/.

Exemplo da seção contentFiles

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        ...
        <contentFiles>
            <!-- Embed image resources -->
            <files include="any/any/images/dnf.png" buildAction="EmbeddedResource" />
            <files include="any/any/images/ui.png" buildAction="EmbeddedResource" />

            <!-- Embed all image resources under contentFiles/cs/ -->
            <files include="cs/**/*.png" buildAction="EmbeddedResource" />

            <!-- Copy config.xml to the root of the output folder -->
            <files include="cs/uap/config/config.xml" buildAction="None" copyToOutput="true" flatten="true" />

            <!-- Copy run.cmd to the output folder and keep the directory structure -->
            <files include="cs/commands/run.cmd" buildAction="None" copyToOutput="true" flatten="false" />

            <!-- Include everything in the scripts folder except exe files -->
            <files include="cs/net45/scripts/*" exclude="**/*.exe"  buildAction="None" copyToOutput="true" />
        </contentFiles>
        </metadata>
</package>

Grupos de referência do Framework

Versão 5.1+ somente com PackageReference

As referências do Framework são um conceito do .NET Core que representa estruturas compartilhadas, como WPF ou Windows Forms. Ao especificar uma estrutura compartilhada, o pacote garante que todas as suas dependências de estrutura sejam incluídas no projeto de referência.

Cada elemento <group> requer um atributo targetFramework e zero ou mais elementos <frameworkReference>.

O exemplo a seguir mostra um nuspec gerado para um projeto WPF .NET Core. Observe que a criação manual de nuspecs que contêm referências de estrutura não é recomendada. Em vez disso, considere usar o pacote de destinos, que os inferirá automaticamente do projeto.

<package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
  <metadata>
    <dependencies>
      <group targetFramework=".NETCoreApp3.1" />
    </dependencies>
    <frameworkReferences>
      <group targetFramework=".NETCoreApp3.1">
        <frameworkReference name="Microsoft.WindowsDesktop.App.WPF" />
      </group>
    </frameworkReferences>
  </metadata>
</package>

Exemplo de arquivos nuspec

Um simples .nuspec que não especifica dependências ou arquivos

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>sample</id>
        <version>1.2.3</version>
        <authors>Kim Abercrombie, Franck Halmaert</authors>
        <description>Sample exists only to show a sample .nuspec file.</description>
        <language>en-US</language>
        <projectUrl>http://xunit.codeplex.com/</projectUrl>
        <license type="expression">MIT</license>
    </metadata>
</package>

Um .nuspec com dependências

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>sample</id>
        <version>1.0.0</version>
        <authors>Microsoft</authors>
        <dependencies>
            <dependency id="another-package" version="3.0.0" />
            <dependency id="yet-another-package" version="1.0.0" />
        </dependencies>
    </metadata>
</package>

Um .nuspec com arquivos

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>routedebugger</id>
        <version>1.0.0</version>
        <authors>Jay Hamlin</authors>
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>Route Debugger is a little utility I wrote...</description>
    </metadata>
    <files>
        <file src="bin\Debug\*.dll" target="lib" />
    </files>
</package>

Um .nuspec com assemblies de estrutura

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>PackageWithGacReferences</id>
        <version>1.0</version>
        <authors>Author here</authors>
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>
            A package that has framework assemblyReferences depending
            on the target framework.
        </description>
        <frameworkAssemblies>
            <frameworkAssembly assemblyName="System.Web" targetFramework="net40" />
            <frameworkAssembly assemblyName="System.Net" targetFramework="net40-client, net40" />
            <frameworkAssembly assemblyName="Microsoft.Devices.Sensors" targetFramework="sl4-wp" />
            <frameworkAssembly assemblyName="System.Json" targetFramework="sl3" />
        </frameworkAssemblies>
    </metadata>
</package>

Neste exemplo, os seguintes itens são instalados em destinos específicos do projeto:

  • .NET4 ->System.Web, System.Net
  • Perfil de Cliente do .NET4 ->System.Net
  • Silverlight 3 ->System.Json
  • WindowsPhone ->Microsoft.Devices.Sensors