Use of local NuGet packages
Version 6.1.0
In this article
This article describes how to create your own local NuGet packages of PDFsharp or MigraDoc if you want to make changes to the source code in the PDFsharp solution and use these modified packages in your projects.
Local NuGet packages under Windows
Starting with PDFsharp 6, all Visual Studio solutions use a Directory.Packages.props
file. This concept for centralized package management was introduced many years ago but not officially supported by Microsoft for a long time.
When you download e.g. the PDFsharp.Samples
repository, the props file of this solution contains the required references to PDFsharp packages on NuGet.org
.
So there is nothing to do if you just want to compile and run the sample code.
But if you want to make modifications to the PDFsharp solution and compile examples in the PDFsharp.Samples
solution that should use these changes, you need to use these newer NuGet packages.
Each time the PDFsharp solution is built, NuGet packages for PDFsharp and MigraDoc are automatically created.
The names of these packages depend on the latest git tag, the name of the current branch, and the number of commits your private branch is ahead of the develop branch.
We use the following technique to manage these packages in a NuGet package store on our local developer machines.
The PDFsharp
solution itself uses project references, so nothing has to be done if we modify source code in this solution. But e.g. the PDFsharp.Samples
solution relies on NuGet packages of PDFsharp. We use private NuGet packages from a machine-local NuGet package store to resolve these references.
Do the following steps on your developer machine:
Create a folder
.nuget-local
in your user directory%USERPROFILE%
(on Windows) beside the.nuget
folder. Use $env:USERPROFILE in PowerShell.Add this folder (
%USERPROFILE%\.nuget-local
or$env:USERPROFILE/.nuget-local
, e.g.C:\Users\YOUR-NAME\.nuget-local
) to the NuGet package sources and name itnuget-local
.
You can do this with Visual StudioTools/Options/NuGet Package Manager/Package Sources
or add manually<add key="nuget-local" value="C:\Users\YOUR-NAME\.nuget-local" />
to thenuget.config
file somewhere inAppData
.When you compile PDFsharp, either with Visual Studio or with
dotnet build
, all NuGet packages are automatically created.Execute either the PowerShell script
.\dev\update-local-nuget-packages-debug.ps1
or.\dev\update-local-nuget-packages-release.ps1
, depending on what you have built.
This copies the NuGet packages to your local package source folder and deletes all folders with these package names from the.nuget\packages
folder. The last step is required because during development the package version does not change und the build system otherwise would later use the cached packages from the.nuget\packages
folder.The script shows the version number of the copied packages, e.g.
6.1.0-your-branch-42
Change the following line in the
Directory.Packages.props
file in the e.g. PDFsharp.Samples solution by inserting this new package version number.<PDFsharp_PackageVersion Condition=" '$(PDFsharp_PackageVersion)'=='' ">6.0.0-your-branch-42</PDFsharp_PackageVersion>
This is good enough if you work alone. If you work in a team and your colleagues want to use another branch of PDFsharp, you should create a
Local.Packages.props
file. UseLocal.Packages.props - template
to create this file. Insert the package version into this file. If this file exists, the PDFsharp package version is used from it. Because this file is private to your developer machine, i.e. not part of the repository, your colleagues can work with a different version of the PDFsharp packages.
Local NuGet packages under WSL2
Use the same technique if you test your code under WSL2. To consume NuGet packages created under Windows, run this command under WSL2:
dotnet nuget add source -n nuget-local /mnt/c/Users/YOUR-NAME/.nuget-local
Alternatively edit the NuGet.Config
file directly.
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
<add key="nuget-local" value="/mnt/c/Users/YOUR-NAME/.nuget-local" />
</packageSources>
</configuration>
This creates a NuGet source referring to the folder C:\Users\YOUR-NAME\.nuget-local
you created and filled under Windows using the instructions above.
PackageSourceMapping
PDFsharp repositories include nuget.config
files with PackageSourceMapping entries for the sources nuget.org and nuget-local. Without this config file the .NET SDK will not use your packages.