Partilhar via

Referência .nuspec

Um ficheiro é um manifesto XML que contém metadados de .nuspec pacotes. Este manifesto é usado tanto para construir o pacote quanto para fornecer informações aos consumidores. O manifesto está sempre incluído num pacote.

Neste tópico:

Compatibilidade com tipos de projeto

Forma geral e esquema

Um nuspec.xsd ficheiro de esquema pode ser encontrado no repositório NuGet GitHub. Note que este ficheiro representa apenas o esquema mais recente de um .nuspec ficheiro. Não existem versões oficialmente publicadas e nenhuma versão desse ficheiro corresponde a qualquer versão específica do NuGet.

Dentro deste esquema, um .nuspec ficheiro tem a seguinte forma 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 uma representação visual clara do esquema, abra o ficheiro de esquema no Visual Studio em modo Design e clique no link XML Schema Explorer . Alternativamente, abre o ficheiro como código, clica com o botão direito no editor e seleciona Mostrar Explorador de Esquemas XML. De qualquer forma, obtém uma vista como a abaixo (quando maioritariamente expandida):

Visual Studio Schema Explorer with nuspec.xsd open

Todos os nomes de elementos XML no ficheiro .nuspec são sensíveis a maiúsculas e minúsculas, tal como acontece com XML em geral. Por exemplo, usar o elemento <description> de metadados está correto e <Description> não é correto. A carcaça adequada para cada nome de elemento está documentada abaixo.

Importante

Embora o .nuspec ficheiro contenha uma referência a um esquema (xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd"), O NuGet-Team nunca publicou um ficheiro de esquema que pudesse ser usado para validação automática de esquemas.

Elementos de metadados obrigatórios

Embora os seguintes elementos sejam os requisitos mínimos para um pacote, deve considerar adicionar os elementos opcionais de metadados para melhorar a experiência global que os programadores têm com o seu pacote.

Estes elementos devem aparecer dentro de um <metadata> elemento.

id

O identificador de pacote insensível a maiúsculas minúsculas, que deve ser único em nuget.org ou na galeria onde o pacote se encontra. Os IDs podem não conter espaços ou caracteres que não sejam válidos para uma URL, e geralmente seguem as regras do namespace .NET. Consulte Escolhendo um identificador de pacote exclusivo para obter orientações.

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

versão

A versão do pacote, seguindo o padrão major.minor.patch . Os números de versão podem incluir um sufixo pré-lançamento, conforme descrito em Versionamento de pacotes.

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

descrição

Uma descrição do pacote para a visualização da interface.

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

autores

Uma lista separada por vírgulas de autores de pacotes. O authors e o owners do nuspec são ignorados ao carregar o pacote para nuget.org. Para definir a propriedade de pacotes no nuget.org, veja Gerir proprietários de pacotes no nuget.org.

Elementos de metadados opcionais

proprietários

Importante

Owners está obsoleto. Usa autores em vez disso.

Uma lista separada por vírgulas de proprietários de pacotes. O owners from the nuspec é ignorado ao carregar o pacote para nuget.org. Para definir a propriedade de pacotes em nuget.org, veja Gestão de proprietários de pacotes em nuget.org.

projectUrl

Uma URL para a página inicial do pacote, frequentemente mostrada nas visualizações da interface, bem como em nuget.org.

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

licenseUrl

Importante

licenseUrl está obsoleto. Use a licença em vez disso.

Um URL para a licença do pacote, frequentemente mostrado em interfaces como nuget.org.

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

licença

Suportado com NuGet 4.9.0 e versões superiores

Uma expressão de licença SPDX ou um caminho para um ficheiro de licença dentro do pacote, frequentemente mostrado em interfaces como nuget.org. Se estiver a licenciar 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 aprovadas pela Open Source Initiative ou pela Free Software Foundation.

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

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

Se usares uma licença personalizada que não é suportada por expressões de licença, podes empacotar um .txt.md ou 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 o equivalente MSBuild, veja Packing a license expression ou a license file.

A sintaxe exata das expressões de licença do NuGet é descrita abaixo no 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 está obsoleto. Usa o ícone em vez disso.

Um URL para uma imagem de 128x128 com fundo de transparência para usar como ícone do pacote na visualização da interface. Certifique-se de que este elemento contém o URL direto da imagem e não o URL de uma página web que contenha a imagem. Por exemplo, para usar uma imagem do GitHub, use a URL do ficheiro raw como https://github.com/<nome> de utilizador/<repositório>/raw/<branch>/<logo.png>.

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

icon

Suportado com NuGet 5.3.0 e superiores

É um caminho para um ficheiro de imagem dentro do pacote, frequentemente mostrado em interfaces como nuget.org como o ícone do pacote. O tamanho do ficheiro de imagem está limitado a 1 MB. Os formatos de ficheiro suportados incluem JPEG e PNG. Recomendamos uma resolução de imagem de 128x128.

Por exemplo, 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 de nuspec de ícones de embalagem.

Para o equivalente ao MSBuild, veja Packing an icon image file.

Sugestão

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

readme

Suportado com o NuGet 5.10.0 preview 2 e superiores

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

Por exemplo, adicionaria o seguinte ao seu nuspec para poder incluir um ficheiro readme com o seu projeto:

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

Para o equivalente MSBuild, dá uma vista de olhos em Packing a readme file.

exigeLicençaAceitação

Um valor booleano que especifica se o cliente deve pedir ao consumidor que aceite a licença do pacote antes de instalar o pacote.

desenvolvimentoDependência

(2.8+) Um valor booleano que especifica se o pacote está marcado como dependência apenas de desenvolvimento, o que impede que o pacote seja incluído como dependência noutros pacotes. Com o PackageReference (NuGet 4.8+), esta flag também significa que excluirá os ativos em tempo de compilação da compilação. Ver suporte a DevelopmentDependency para PackageReference

resumo

Importante

summary está a ser depreciado. Utilize description em substituição.

Uma breve descrição do pacote para visualização da interface. Se for omitido, usa-se uma versão truncada de description .

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

notas de versão

(1,5+) Uma descrição das alterações feitas nesta versão do pacote, frequentemente usada na interface, como o separador Updates do Visual Studio Package Manager em vez da descrição do pacote.

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

(1,5+) Detalhes de direitos de autor do pacote.

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

linguagem

O ID da localização do pacote. Ver Criação de pacotes localizados.

tags

Uma lista delimitada por espaço de etiquetas e palavras-chave que descrevem o pacote e ajudam na descoberta dos pacotes através de pesquisa e filtragem.

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

Utilizável

(3.3+) Apenas para uso interno do NuGet.

repositório

Metadados do repositório, consistindo em quatro atributos opcionais: type e url(4.0+), e branch e commit(4.6+). Estes atributos permitem-lhe mapear para .nupkg o repositório que o construiu, com a possibilidade de obter tanto detalhe quanto o nome do ramo individual e/ou o commit SHA-1 hash que construiu o pacote. Esta deve ser uma URL disponível publicamente que pode ser invocada diretamente por um software de controlo de versões. Não deve ser uma página html, pois é para o computador. Para ligar à página do projeto, use o projectUrl campo, em vez disso.

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 type atributo está limitado a 100 caracteres e o url atributo a 4000 caracteres.

title

Um título amigável para o uso humano do pacote que pode ser usado em alguns ecrãs de interface. (nuget.org e o Gestor de Pacotes no Visual Studio não mostram o título)

Ao carregar um pacote para nuget.org, o title campo está limitado a 256 caracteres, mas não é usado para qualquer propósito de exibição.

Elementos da coleção

Tipos de pacotes

(3,5+) Uma coleção de zero ou mais <packageType> elementos que especificam o tipo do pacote se diferente de um pacote de dependência tradicional. Cada packageType tem atributos de nome e versão. Veja Definir um tipo de pacote.

dependências

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

Assemblies de estrutura

(1.2+) Uma coleção de zero ou mais <frameworkAssembly> elementos que identificam referências assembly do .NET Framework que este pacote exige, o que garante que as referências são adicionadas a projetos que consomem o pacote. Cada frameworkAssembly tem atributos assemblyName e targetFramework . Veja abaixo Especificar referências de montagem do framework GAC .

references

(1,5+) Uma coleção de zero ou mais <reference> elementos que nomeiam assemblies na pasta do lib pacote e que são adicionados como referências de projeto. Cada referência tem um atributo de ficheiro . <references> pode também conter um <group> elemento com um atributo TargetFramework , que depois contém <reference> elementos. Se forem omitidas, todas as referências são lib incluídas. Veja Especificar referências de montagem explícitas abaixo.

contentFiles

(3.3+) Uma coleção de <files> elementos que identificam ficheiros de conteúdo a incluir no projeto que consume. Estes ficheiros são especificados com um conjunto de atributos que descrevem como devem ser usados dentro do sistema do projeto. Veja Especificar ficheiros a incluir no pacote abaixo.

files

O <package> nó pode conter um <files> nó como irmão de <metadata>, e um <contentFiles> filho sob <metadata>, para especificar quais os ficheiros assembly e content a incluir no pacote. Consulte Incluir ficheiros assembly e Incluir ficheiros de conteúdo mais adiante neste tópico para mais detalhes.

Atributos de metadados

minClientVersion

Especifica a versão mínima do cliente NuGet que pode instalar este pacote, imposta pela nuget.exe e pelo Visual Studio Package Manager. Isto é usado sempre que o pacote depende de funcionalidades específicas do .nuspec ficheiro que foram adicionadas numa determinada versão do cliente NuGet. Por exemplo, um pacote que use o developmentDependency atributo deve especificar "2.8" para minClientVersion. De forma semelhante, um pacote que use o contentFiles elemento (ver a secção seguinte) deve definir minClientVersion para "3.3". Note também que, como os clientes NuGet anteriores à 2.5 não reconhecem esta bandeira, recusam-se sempre a instalar o pacote, independentemente do 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 nuget pack comando substitui tokens delimitados por $-delimitados nos .nuspec ficheiros <metadata> e <files> nós por valores que provêm de um ficheiro de projeto ou do pack switch do -properties comando.

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

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 abaixo (AssemblyInfo refere-se ao ficheiro em Properties como AssemblyInfo.cs ou AssemblyInfo.vb).

Para usar estes tokens, execute nuget pack com o ficheiro de projeto em vez de apenas com o .nuspecficheiro . Por exemplo, ao usar o seguinte comando, os $id$ tokens e $version$ num .nuspec ficheiro são substituídos pelos valores e AssemblyVersion do AssemblyName projeto:

nuget pack MyProject.csproj

Normalmente, quando se tem um projeto, cria-se o .nuspec inicialmente que nuget spec MyProject.csproj inclui automaticamente alguns destes tokens padrão. No entanto, se um projeto não tiver valores para os elementos necessários .nuspec , então nuget pack falha. Além disso, se alterar os valores do projeto, certifique-se de reconstruir antes de criar o pacote; Isto pode ser feito convenientemente com o interruptor do build comando Pack.

Com exceção de $configuration$, os valores no projeto são usados em preferência a qualquer valor atribuído ao mesmo token na linha de comandos.

Símbolo Fonte de valor Valor
$id$ Ficheiro de projeto AssemblyName (título) a partir do ficheiro do projeto
$version$ AssemblyInfo AssemblyInformationalVersion se presente, caso contrário AssemblyVersion
$author$ AssemblyInfo Companhia de Assembleia
$title$ AssemblyInfo Título da Assembleia
$description$ AssemblyInfo AssemblyDescription
$copyright$ AssemblyInfo Direitos de autor da Assembleia
$configuration$ Assembly DLL Configuração usada para construir o monte, por defeito para Depurar. Note que, para criar um pacote usando uma configuração Release, deve sempre usar -properties Configuration=Release na linha de comandos.

Os tokens também podem ser usados para resolver caminhos quando inclui ficheiros assembly e ficheiros de conteúdo. Os tokens têm os mesmos nomes das propriedades do MSBuild, tornando possível selecionar ficheiros a serem incluídos consoante a configuração atual da compilação. Por exemplo, se usar os seguintes tokens no .nuspec ficheiro:

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

E constróis um assembly cuja AssemblyName configuração está LoggingLibraryRelease no MSBuild, as linhas resultantes no .nuspec ficheiro no pacote são as seguintes:

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

Elemento Dependencies

O <dependencies> elemento dentro <metadata> contém qualquer número de <dependency> elementos que identificam outros pacotes dos quais o pacote de topo depende. Os atributos de cada um <dependency> são os seguintes:

Attribute Description
id (Obrigatório) O ID do pacote da dependência, como "EntityFramework" e "NUnit", que é o nome do pacote nuget.org aparece numa página de pacote.
version (Obrigatório) A gama de versões aceitável como dependência. Consulte Versionamento de pacotes para a sintaxe exata. Versões flutuantes não são suportadas.
include Uma lista delimitada por vírgulas de etiquetas de inclusão/exclusão (ver abaixo) indicando a dependência a incluir no pacote final. O valor predefinido é all.
excluir Uma lista delimitada por vírgulas de etiquetas inclusão/exclusão (ver abaixo) indicando a dependência a excluir no pacote final. O valor padrão é build,analyzers qual pode ser sobrescrito. Mas content/ ContentFiles também são implicitamente excluídos no pacote final, que não pode ser sobrescrito. As tags especificadas com exclude têm precedência sobre as especificadas com include. Por exemplo, include="runtime, compile" exclude="compile" é o mesmo que include="runtime".

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

Incluir/Excluir tag Pastas afetadas do destino
contentFiles Content
runtime Runtime, Recursos e FrameworkAssemblies
Compilar Lib
compilação build (props e alvos do MSBuild)
nativo nativo
nenhuma Sem pastas
all Todas as pastas

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

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

As linhas seguintes indicam dependências nos mesmos pacotes, mas especificam incluir as contentFiles pastas e build de PackageA e everything exceto as native pastas 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 a .nuspec partir de um projeto usando nuget spec, as dependências que existem nesse projeto não são automaticamente incluídas no ficheiro resultante .nuspec . Em vez disso, usa nuget pack myproject.csproj, e obtém o ficheiro .nuspec dentro do ficheiro .nupkg gerado. Este .nuspec contém as dependências.

Grupos de dependências

Versão 2.0+

Como alternativa a uma única lista plana, as dependências podem ser especificadas de acordo com o perfil de framework do projeto-alvo usando <group> elementos dentro <dependencies>de .

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

O <group> elemento sem atributo targetFramework é usado como lista de dependências por defeito ou de recurso. Consulte Estruturas de destino para obter os identificadores exatos da estrutura.

Importante

O formato de grupo não pode ser misturado com uma lista plana.

Observação

O formato do Target Framework Moniker (TFM) usado na lib/ref pasta é diferente quando comparado com o TFM usado em dependency groups. Se os frameworks de destino declarados na dependencies group pasta e lib/ref do .nuspec ficheiro não tiverem correspondências exatas, o pack comando irá abrir o NuGet Warning NU5128.

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

<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 explícitas de montagem

O <references> elemento é usado por projetos que o usam packages.config para especificar explicitamente as assemblies que o projeto alvo deve referenciar ao usar o pacote. Referências explícitas são tipicamente usadas para assemblies apenas em tempo de design. Para mais informações, consulte a página sobre seleção de assembleias referenciadas pelos projetos .

Por exemplo, o seguinte <references> elemento instrui o NuGet a adicionar referências apenas xunit.dll a e xunit.extensions.dll mesmo que existam 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 plana, as referências podem ser especificadas de acordo com o perfil de estrutura do projeto-alvo usando <group> elementos dentro <references>de .

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

O <group> elemento sem atributo targetFramework é usado como lista padrão ou de reserva de referências. Consulte Estruturas de destino para obter os identificadores exatos da estrutura.

Importante

O formato de grupo não pode ser misturado com uma lista plana.

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

<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 montagem de estruturas

Os assemblies de framework são aqueles que fazem parte do framework .NET e já devem estar na cache assembly global (GAC) de qualquer máquina. Ao identificar esses assemblies dentro do <frameworkAssemblies> elemento, um pacote pode garantir que as referências necessárias são adicionadas a um projeto caso este ainda não tenha tais referências. Tais montagens, naturalmente, não são incluídas diretamente num pacote.

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

Attribute Description
NomeDaMontagem (Obrigatório) O nome da assembleia totalmente qualificado.
targetFramework (Opcional) Especifica a estrutura alvo a que esta referência se aplica. Se omitido, indica que a referência se aplica a todos os frameworks. Consulte Estruturas de destino para obter os identificadores exatos da estrutura.

O exemplo seguinte mostra uma referência a System.Net para todos os frameworks 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 ficheiros assembly

Se seguir as convenções descritas em Criar um Pacote, não precisa de especificar explicitamente uma lista de ficheiros no .nuspec ficheiro. O nuget pack comando recolhe automaticamente os ficheiros necessários.

Importante

Quando um pacote é instalado num projeto, o NuGet adiciona automaticamente referências de montagem às DLLs do pacote, excluindo aquelas que são nomeadas .resources.dll porque se assume serem assemblagens de satélites localizadas. Por esse motivo, evite usar .resources.dll para arquivos que, de outra forma, contenham código de pacote essencial.

Para contornar este comportamento automático e controlar explicitamente quais os ficheiros incluídos num pacote, coloque um <files> elemento como filho de <package> (e irmão de <metadata>), identificando cada ficheiro com um elemento separado <file> . 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 projetos que usam packages.config, o <files> elemento também é usado para incluir ficheiros de conteúdo imutáveis quando um pacote é instalado. Com o NuGet 3.3+ e o PackageReference dos projetos, <contentFiles> o elemento é usado em vez disso. Consulte Incluir ficheiros de conteúdo abaixo para mais detalhes.

Atributos dos elementos do ficheiro

Cada <file> elemento especifica os seguintes atributos:

Attribute Description
src A localização do ficheiro ou ficheiros a incluir, sujeita a exclusões especificadas pelo exclude atributo. O caminho é relativo ao .nuspec ficheiro, a menos que seja especificado um caminho absoluto. O carácter * coringa é permitido, e o duplo curinga ** implica uma pesquisa recursiva em pastas.
alvo O caminho relativo para a pasta dentro do pacote onde os ficheiros fonte são colocados, que deve começar por lib, content, build, ou tools. Veja Criar um .nuspec a partir de um diretório de trabalho baseado em convenções.
excluir Uma lista delimitada por ponto e vírgula de ficheiros ou padrões de ficheiros a excluir da src localização. O carácter * coringa é permitido, e o duplo curinga ** implica uma pesquisa recursiva em pastas.

Examples

Conjunto único

Source file:
    library.dll

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

Packaged result:
    lib\library.dll

Montagem única específica para uma estrutura alvo

Source file:
    library.dll

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

Packaged result:
    lib\net40\library.dll

Conjunto de DLLs usando um coringa

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 para diferentes frameworks

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 ficheiros

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 ficheiros de conteúdo

Os ficheiros de conteúdo são ficheiros imutáveis que um pacote precisa de incluir num projeto. Sendo imutáveis, não se destinam a ser modificadas pelo projeto consumidor. Exemplos de ficheiros de conteúdo incluem:

  • Imagens que são incorporadas como recursos
  • Ficheiros fonte que já estão compilados
  • Scripts que precisam de ser incluídos na saída de build do projeto
  • Ficheiros de configuração para o pacote que precisam de ser incluídos no projeto, mas que não precisam de alterações específicas do projeto

Os ficheiros de conteúdo são incluídos num pacote usando o <files> elemento, especificando a content pasta no target atributo. No entanto, tais ficheiros são ignorados quando o pacote é instalado num projeto usando PackageReference, que em vez disso utiliza o <contentFiles> elemento.

Para máxima compatibilidade com projetos consumidores, um pacote idealmente especifica os ficheiros de conteúdo em ambos os elementos.

Utilização do elemento ficheiros para ficheiros de conteúdo

Para ficheiros de conteúdo, basta usar o mesmo formato que para ficheiros assembly, mas especificar content como pasta base no target atributo, como mostrado nos exemplos seguintes.

Ficheiros básicos de conteúdo

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

ficheiros de conteúdo com estrutura de diretórios

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

ficheiro de conteúdo específico para uma framework alvo

Source file:
    css\cool\style.css

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

Packaged result:
    content\style.css

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

Neste caso, o NuGet vê que a extensão em target não corresponde à extensão em src e, por isso, trata essa parte do nome em 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

Ficheiros de conteúdo sem extensões

Para incluir ficheiros sem extensão, use os * coringas ou:**

Source file:
    flags\installed

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

Packaged result:
    flags\installed

ficheiros de conteúdo com deep path e deep target

Neste caso, porque as extensões de ficheiro da fonte e do destino coincidem, o NuGet assume que o destino é um nome de ficheiro 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

Renomeação de um ficheiro 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 ficheiros

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)

Utilização do elemento contentFiles para ficheiros de conteúdo

NuGet 4.0+ com PackageReference

Por defeito, um pacote coloca conteúdo numa contentFiles pasta (ver abaixo) e nuget pack inclui todos os ficheiros dessa pasta usando atributos predefinidos. Neste caso, não é necessário incluir um contentFiles nó no .nuspec at de todo.

Para controlar quais os ficheiros incluídos, o <contentFiles> elemento especifica é uma coleção de <files> elementos que identificam exatamente os ficheiros incluídos.

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

Attribute Description
incluir (Obrigatório) A localização do ficheiro ou ficheiros a incluir, sujeita a exclusões especificadas pelo exclude atributo. O caminho é relativo à contentFiles pasta, a menos que seja especificado um caminho absoluto. O carácter * coringa é permitido, e o duplo curinga ** implica uma pesquisa recursiva em pastas.
excluir Uma lista delimitada por ponto e vírgula de ficheiros ou padrões de ficheiros a excluir da src localização. O carácter * coringa é permitido, e o duplo curinga ** implica uma pesquisa recursiva em pastas.
buildAction A ação de construção para atribuir ao item de conteúdo para MSBuild, como Content, None, Embedded Resource, Compile, etc. O padrão é Compile.
copyToOutput Um Booleano que indica se deve copiar os itens de conteúdo para a pasta de saída de construção (ou publicação). O padrão é "false".
achatar Um Booleano que indica se deve copiar os itens de conteúdo para uma única pasta na saída de build (verdadeiro), ou preservar a estrutura de pastas no pacote (falso). Esta flag só funciona quando a flag copyToOutput está definida como true. O padrão é "false".

Ao instalar um pacote, o NuGet aplica os elementos filhos de <contentFiles> de cima para baixo. Se várias entradas corresponderem ao mesmo ficheiro, todas as entradas são aplicadas. A entrada mais alta sobrepõe-se às entradas inferiores se houver um conflito pelo mesmo atributo.

Estrutura de pastas do pacote

O projeto de 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 minúsculo de um dado $(ProjectLanguage)
  • TxM é algum nome de framework alvo legal que o NuGet suporta (ver frameworks Target).
  • Qualquer estrutura de pasta pode ser anexada ao final desta 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

Pastas vazias podem ser usadas _._ para optar por não fornecer conteúdo para certas combinações de linguagem e TxM, por exemplo:

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

Exemplo da secçã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 quadro

Versão 5.1+ apenas com PackageReference

As Referências de Framework são um conceito do .NET Core que representa frameworks partilhados como WPF ou Windows Forms. Ao especificar um framework partilhado, o pacote assegura que todas as dependências do framework estão incluídas no projeto de referência.

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

O exemplo seguinte mostra um nuspec gerado para um projeto WPF .NET Core. Note que não é recomendado a autoria manual de nuspecs que contenham referências ao framework. Considera usar o pacote de alvos , que os irá 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>

Ficheiros nuspec de exemplo

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

<?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>

A .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>

A .nuspec com ficheiros

<?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>

A .nuspec com montagens 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, estão instalados os seguintes objetivos específicos do projeto:

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