Jak spakować bibliotekę .NET Framework?

Question

Jak spakować bibliotekę .NET w nowoczesny sposób ogólnego zastosowania do publikowania przez NuGet? Załóżmy, że mam pojedynczy zestaw AnyCPU, który chcę udostępnić na platformie .NET Framework 4.6.

Jest to seria pytań i odpowiedzi, które dokumentują moje wnioski na temat nowoczesnego pakietu Nuget authoringu, koncentrując się przede wszystkim na zmianach wprowadzonych Nuget 3. Możesz być także zainteresowany w niektórych pokrewnych pytania:

• How to package a .NET library targeting the Universal Windows Platform?
• How to package a portable .NET library targeting .NET Core?
• How to package a .NET library targeting .NET Framework and Universal Windows Platform and include platform-specific functionality?
• How to package a multi-architecture .NET library that targets the Universal Windows Platform?
• How to package a .NET library that targets the Universal Windows Platform and depends on Visual Studio extension SDKs?

Answer 1

Będziemy chcieli, aby utworzyć i opublikować pakiet Nuget o następującej treści:

• Zespół zawierający kod (.dll).
• Plik symbolu debugowania (.pdb).
• Plik dokumentacji XML (.xml), zakładając, że włączyłeś go w ustawieniach projektu.

Chociaż powód do publikowania kodu jest oczywiste, pozostałe dwa są warte rozszerza się na:

• Plik debug symbol umożliwia czas pracy do wypełnienia ślady stosu z numerami lini kodu i może również dostarczyć dodatkowe informacje do dołączonego debuggera. Umieszczenie tego pliku w pakiecie NuGet jest bardzo prostym sposobem na zwiększenie możliwości rozwiązywania problemów związanych z biblioteką.
• Urządzenie Visual Studio służy do wyświetlania podpowiedzi, które udostępniają dokumentację dotyczącą metod i ich argumentów dla użytkowników biblioteki. Pozwala to uniknąć konieczności odwoływania się do zewnętrznej dokumentacji, zwiększając użyteczność twojej biblioteki.

Pakiet NuGet jest w istocie plikiem zip z zawartością oraz kilkoma metadanymi. Aby opublikować tej biblioteki .NET, trzeba będzie utworzyć pakiet o następującej strukturze (metadanych pominięta):

\---lib 
    \---net46 
      MyLibrary.dll 
      MyLibrary.pdb 
      MyLibrary.XML 

Krótko mówiąc, wszystko w lib \ net46 będą stosowane, gdy pakiet jest instalowany w .NET Projekt Framework 4.6 i dokładnie to, czego potrzebujesz. Wszystkie trzy pliki będą pochodzić z katalogu wyjściowego kompilacji twojego projektu w konfiguracji Release build.

Najprostszym sposobem na stworzenie takiego pakietu NuGet jest użycie pliku wykonywalnego NuGet. Utwórz katalog w swoim rozwiązaniu (np. MyLibrary \ NuGet) i skopiuj nuget.exe do tego katalogu. Aby zdefiniować strukturę Nuget pakietu biblioteki, należy utworzyć plik .nuspec w tym samym katalogu (np MyLibrary.nuspec), stosując następujące jako szablon:

<?xml version="1.0"?> 
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd"> 
    <metadata minClientVersion="3.2"> 
     <id>Example.MyLibrary</id> 
     <version>1.0.0</version> 
     <authors>Firstname Lastname</authors> 
     <description>Example of a simple .NET Framework 4.6 library.</description> 
     <dependencies> 
      <dependency id="Newtonsoft.Json" version="8.0.1" /> 
     </dependencies> 
    </metadata> 
    <files> 
     <file src="..\bin\Release\MyLibrary.*" target="lib\net46" /> 
    </files> 
</package> 

Upewnij się, aby ustawić akcję kompilacji Nuget. exe i.nuspec do None, aby uniknąć niepotrzebnego dotknięcia przez proces kompilacji.

Jeśli projekt jest skonfigurowany zgodnie ze standardowymi szablonami projektów Visual Studio, wszystkie trzy odpowiednie wyjścia projektu (MyLibrary.dll, MyLibrary.xml i MyLibrary.pdb) będą obecne w katalogu bin \ Release i symbolu wieloznacznego wzór w tym przykładzie skopiuje je wszystkie do odpowiednich lokalizacji w pakiecie NuGet.

Lista zależności powinna odzwierciedlać plik packages.config w katalogu projektu. Jeśli twoja biblioteka nie ma zależności od innych pakietów NuGet, możesz po prostu pominąć element <dependencies>.

Zanim przejdziesz dalej, rozwiń swoje rozwiązanie, używając konfiguracji Release.

Możesz utworzyć pakiet za pomocą polecenia nuget.exe pack MyLibrary.nuspec. Spowoduje to wygenerowanie pakietu o nazwie podanego w pliku .nuspec, np. Example.MyLibrary.1.0.0.nupkg. Możesz przesłać ten plik do swojego repozytorium pakietów NuGet i przejść bezpośrednio do używania go tak, jakbyś był w innym pakiecie NuGet.

Uważam, że korzystne jest użycie skryptu PowerShell, aby rozpocząć generowanie pakietów NuGet, zwłaszcza jeśli trzeba wykonać wstępne przetwarzanie zawartości, jak to często bywa w przypadku bardziej złożonych projektów. Oto przykład skryptu PowerShell, który będzie korzystał nuget.exe w tym samym katalogu, aby utworzyć pakiety dla wszystkich .nuspec plików w tym samym katalogu:

# Delete any existing output. 
Remove-Item *.nupkg 

# Create new packages for any nuspec files that exist in this directory. 
Foreach ($nuspec in $(Get-Item *.nuspec)) 
{ 
    .\NuGet.exe pack "$nuspec" 
} 

Jeśli uwzględni go w swoim projekcie, należy ustawić kompilacja akcji skryptu PowerShell do None, aby uniknąć niepotrzebnego dotknięcia przez proces budowania.

Przykładowa biblioteka i odpowiednie pliki opakowań to available on GitHub. Rozwiązaniem odpowiadającym tej odpowiedzi jest SimpleNetFrameworkLibrary.