Partilhar via

Suporte a várias versões .NET

Muitas bibliotecas destinam-se a uma versão específica do .NET Framework. Por exemplo, você pode ter uma versão da sua biblioteca específica para UWP e outra versão que aproveita os recursos do .NET Framework 4.6. Para acomodar isso, o NuGet suporta colocar várias versões da mesma biblioteca em um único pacote.

Este artigo descreve o layout de um pacote NuGet, independentemente de como o pacote ou assemblies são criados (ou seja, o layout é o mesmo, seja usando vários arquivos .csproj não no estilo SDK e um arquivo .nuspec personalizado ou um único .csproj no estilo SDK com vários destinos). Para um projeto no estilo SDK, os destinos do pacote NuGet sabem como o pacote deve ser disposto e automatizam a colocação dos assemblies nas pastas lib corretas e a criação de grupos de dependência para cada estrutura de destino (TFM). Para obter instruções detalhadas, consulte Suporte a várias versões do .NET Framework em seu arquivo de projeto.

Você deve dispor manualmente o pacote conforme descrito neste artigo ao usar o método de diretório de trabalho baseado em convenção descrito em Criando um pacote. Para um projeto no estilo SDK, o método automatizado é recomendado, mas você também pode optar por dispor manualmente o pacote conforme descrito neste artigo.

Estrutura de pastas da versão do Framework

Ao construir um pacote que contém apenas uma versão de uma biblioteca ou que visa vários frameworks, deve sempre criar subpastas sob lib usando diferentes nomes de frameworks que diferenciam maiúsculas de minúsculas, seguindo a seguinte convenção:

lib\{framework name}[{version}]

Para obter uma lista completa dos nomes suportados, consulte a referência Target Frameworks.

Você nunca deve ter uma versão da biblioteca que não seja específica para uma estrutura e colocada diretamente na pasta raiz lib . (Esta capacidade foi suportada apenas com packages.config). Isso tornaria a biblioteca compatível com qualquer estrutura de destino e permitiria que ela fosse instalada em qualquer lugar, provavelmente resultando em erros de tempo de execução inesperados. A adição de assemblies na pasta raiz (como lib\abc.dll) ou subpastas (como lib\abc\abc.dll) foi preterida e é ignorada ao usar o formato PackagesReference.

Por exemplo, a estrutura de pastas abaixo oferece suporte a quatro versões de um conjunto que são específicas do framework:

\lib
    \net46
        \MyAssembly.dll
    \net461
        \MyAssembly.dll
    \uap
        \MyAssembly.dll
    \netcore
        \MyAssembly.dll

Para incluir facilmente todos esses ficheiros ao construir o pacote, use um caracter curinga recursivo ** na seção do seu <files>:.nuspec

<files>
    <file src="lib\**" target="lib/{framework name}[{version}]" />
</files>

Pastas específicas de arquitetura

Se você tiver assemblies específicos da arquitetura, ou seja, assemblies separados destinados a ARM, x86 e x64, deverá colocá-los em uma pasta nomeada runtimes dentro de subpastas denominadas {platform}-{architecture}\lib\{framework} ou {platform}-{architecture}\native. Por exemplo, a seguinte estrutura de pastas acomodaria DLLs nativas e gerenciadas destinadas ao Windows 10 e à uap10.0 estrutura:

\runtimes
    \win10-arm
        \native
        \lib\uap10.0
    \win10-x86
        \native
        \lib\uap10.0
    \win10-x64
        \native
        \lib\uap10.0

Esses assemblies só estarão disponíveis em tempo de execução; portanto, se pretender fornecer também o assembly correspondente para o tempo de compilação, coloque o assembly de AnyCPU na pasta /ref/{tfm}.

Observe que o NuGet sempre escolhe esses ativos de compilação ou tempo de execução de uma pasta, portanto, se houver alguns ativos compatíveis de /ref, então /lib será ignorado para adicionar assemblies em tempo de compilação. Da mesma forma, se houver alguns ativos compatíveis a partir de /runtimes, então /lib será ignorado durante o tempo de execução.

Consulte Criar pacotes UWP para obter um exemplo de referência a esses arquivos no manifesto .nuspec .

Além disso, consulte Empacotando um componente de aplicativo da Windows Store com o NuGet

Correspondência de versões de assemblies e o framework de destino num projeto

Quando o NuGet instala um pacote que tem várias versões de assembly, ele tenta corresponder o nome da estrutura do assembly com a estrutura de destino do projeto.

Se uma correspondência não for encontrada, o NuGet copiará o assembly para a versão mais alta que seja menor ou igual à estrutura de destino do projeto, se disponível. Se nenhum assembly compatível for encontrado, o NuGet retornará uma mensagem de erro apropriada.

Por exemplo, considere a seguinte estrutura de pastas em um pacote:

\lib
    \net45
        \MyAssembly.dll
    \net461
        \MyAssembly.dll

Ao instalar este pacote num projeto destinado ao .NET Framework 4.6, o NuGet instala o assembly na pasta net45, porque essa é a versão mais alta disponível que é menor ou igual a 4.6.

Se o projeto tiver como destino o .NET Framework 4.6.1, por outro lado, o NuGet instalará o assembly na net461 pasta.

Se o projeto tiver como destino o .NET Framework 4.0 e versões anteriores, o NuGet lançará uma mensagem de erro apropriada por não encontrar o assembly compatível.

Agrupando assemblies por versão do framework

O NuGet copia assemblies de apenas uma única pasta de biblioteca no pacote. Por exemplo, suponha que um pacote tenha a seguinte estrutura de pastas:

\lib
    \net40
        \MyAssembly.dll (v1.0)
        \MyAssembly.Core.dll (v1.0)
    \net45
        \MyAssembly.dll (v2.0)

Quando o pacote é instalado em um projeto destinado ao .NET Framework 4.5, MyAssembly.dll (v2.0) é o único assembly instalado. MyAssembly.Core.dll (v1.0) não está instalado porque não está listado net45 na pasta. O NuGet se comporta dessa maneira porque MyAssembly.Core.dll pode ter sido mesclado na versão 2.0 do MyAssembly.dll.

Se pretender que MyAssembly.Core.dll seja instalado para o .NET Framework 4.5, coloque uma cópia na pasta net45.

Agrupando conjuntos por perfil de framework

O NuGet também oferece suporte para especificar um perfil de framework específico ao anexar um traço e o nome do perfil ao final da pasta.

lib{nome do framework}-{perfil}

Os perfis suportados são os seguintes:

  • client: Perfil do Cliente
  • full: Perfil completo
  • wp: Windows Phone
  • cf: Estrutura compacta

Declarando dependências (Avançado)

Ao empacotar um arquivo de projeto, o NuGet tenta gerar automaticamente as dependências do projeto. As informações nesta seção sobre como usar um arquivo .nuspec para declarar dependências geralmente são necessárias apenas para cenários avançados.

(Versão 2.0+) Você pode declarar dependências de pacote no .nuspec correspondentes à estrutura de destino do projeto de destino usando <group> elementos dentro do <dependencies> elemento . Para mais informações, consulte o elemento dependencies.

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. Consulte Estruturas de destino para obter os identificadores exatos da estrutura.

Recomendamos o uso de um grupo por Target Framework Moniker (TFM) para arquivos nas pastas lib/ e ref/ .

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

<dependencies>

    <group targetFramework="net472">
        <dependency id="jQuery" version="1.10.2" />
        <dependency id="WebActivatorEx" version="2.2.0" />
    </group>

    <group targetFramework="net20">
    </group>

</dependencies>

Determinando qual alvo do NuGet usar

Ao embalar bibliotecas destinadas à Biblioteca de Classes Portátil, pode ser complicado determinar qual alvo do NuGet se deve usar nos nomes das suas pastas e no ficheiro .nuspec, especialmente se o objetivo for apenas um subconjunto da PCL. Os seguintes recursos externos irão ajudá-lo com isso:

Arquivos de conteúdo e scripts do PowerShell

Advertência

Arquivos de conteúdo mutáveis e execução de script estão disponíveis apenas com o packages.config formato, são preteridos com todos os outros formatos e não devem ser usados para novos pacotes.

Com packages.config, os ficheiros de conteúdo e os scripts do PowerShell podem ser agrupados por framework de destino usando a mesma estrutura de pastas dentro das pastas content e tools. Por exemplo:

\content
    \net46
        \MyContent.txt
    \net461
        \MyContent461.txt
    \uap
        \MyUWPContent.html
    \netcore
\tools
    init.ps1
    \net46
        install.ps1
        uninstall.ps1
    \uap
        install.ps1
        uninstall.ps1

Se uma pasta de estrutura for deixada vazia, o NuGet não adicionará referências de assembly ou arquivos de conteúdo ou executará os scripts do PowerShell para essa estrutura.

Observação

Como init.ps1 é executado no nível da solução e não depende do projeto, ele deve ser colocado diretamente sob a tools pasta. Ele é ignorado se colocado numa pasta de framework.

  • Last updated on