NuGet for Source Using Add As Link (Part 1)
Update: Projects using NuGet for Source with Add as Link. If you have a project using this please comment and let me know.
- https://github.com/rhyous/SimpleArgs
- https://github.com/rhyous/EasyXml
- https://github.com/rhyous/EasyCsv
- https://github.com/rhyous/SimplePluginLoader
- https://github.com/rhyous/StringLibrary
So I have a project on GitHub called SimpleArgs. This project makes command line arguments easy in a C# project. However, one of the requirements is to have an option to use the SimpleArgs dll or to have a single file executable. Yes, everything in one single exe, so referencing a dll is not an option.
So I created two separate NuGet packages from this project:
- SimpleArgs – This NuGet package uses a dll
- SimpleArgs.Sources – This NuGet package adds source
I use SimpleArgs.Sources the most. I quickly realized that NuGet for source does not scale. I have a Solution with four different projects where each project is a single file executable. The result was many copies of the SimpleArgs code.
MySolution
/Packages <-- Copy of SimpleArgs source
/SingleExe1 <-- Copy of SimpleArgs source
/SingleExe2 <-- Copy of SimpleArgs source
/SingleExe3 <-- Copy of SimpleArgs source
/SingleExe4 <-- Copy of SimpleArgs source
That is 5 copies of the SimpleArgs source. Now at first, this doesn’t seem to be a big problem, in fact, it seems little more than an annoyance. One of the first changes I made, was to exclude the duplicate copies of source from Git. This helped but not enough. There are still problems that occur with multiple copies of source. For example, I ran into a bug with SimpleArgs. I fixed it, and then some time later I ran into the same bug with another project in the same solution. Oh, yeah. I only fixed the bug in one copy of the SimpleArgs source.
I decided the best solution was to reference the source using Add as link. Add as link is the ability to include a file into your Visual Studio project but without making a copy of the file in your project.
See: How to Add As Link in Visual Studio
I quickly changed the projects so the source was included not as copies but using the Add As Link capability. I manually did this. Then I finally pushed my changes to SimpleArgs Git repository and released a new version of the SimpleArgs.Sources NuGet package. That basically wiped out my manual work to Add As Link.
I needed the NuGet packages include the source using Add As Link for me.
How to create NuGet package using Add As Source
Well, to my dismay, NuGet didn’t have this feature built in. At first I was exciting about the possibility that this feature would be added as part of NuGet 3.3 and the contentFiles feature, but unfortunately, this feature is for Universal Windows projects, and not for Console Application, Windows Forms, or WPF projects.
However, NuGet does run a PowerShell script on install and another on uninstall, called install.psi and uninstall.ps1. It took some work, I even gave up once, but eventually I found the right library and the documentation for it to help me solve this.
Step 1 – Create a NuGet Packager Project in Visual Studio
- Open Visual Studio and go to File | New Project.
Note: Steps 2 thru 7 installs the NuGet Packager project from online. If you have already done this, then you probably can create your project without these steps. 🙂 - At the bottom of the list on the right, click Online to expand it.
Note: For some reason, Visual Studio hung for about ten to twenty seconds when I clicked this. - In the search bar on the top right, enter NuGet.
- Select NuGet Packager.
- Give your project a Name.
Note: Mine is named SimpleArgs.Sources. - Give your solution a Name.
- Click Ok.
See steps 2 – 7 in this image:
When you click OK, the template will install. It will prompt you a few times but once installed, your project will be created.Note: From now on, you can find the NuGet Packager project in Installed | Templates | Visual C# | NuGet.
Step 2 – Fill out the Package.nuspec file metadata
The package.nusepc is an Xml file. It is created as follows:
<?xml version="1.0"?>
<package >
<metadata>
<id>SimpleArgs.Sources</id>
<version>1.0.0</version>
<title>SimpleArgs.Sources</title>
<authors>Jjbarneck</authors>
<owners></owners>
<description>A long description of the package. This shows up in the right pane of the Add Package Dialog as well as in the Package Manager Console when listing packages using the Get-Package command.</description>
<releaseNotes></releaseNotes>
<summary>A short description of the package. If specified, this shows up in the middle pane of the Add Package Dialog. If not specified, a truncated version of the description is used instead.</summary>
<language>en-US</language>
<projectUrl>https://nuget.org/packages/SimpleArgs.Sources</projectUrl>
<iconUrl>https://nuget.org/Content/Images/packageDefaultIcon-50x50.png</iconUrl>
<requireLicenseAcceptance>false</requireLicenseAcceptance>
<licenseUrl>http://opensource.org/licenses/Apache-2.0</licenseUrl>
<copyright>Copyright 2016</copyright>
<dependencies>
<group targetFramework="net40">
<dependency id="log4net" version="1.2.10" />
</group>
</dependencies>
<references></references>
<tags></tags>
</metadata>
<files>
<file src="lib\" target="lib" />
<file src="tools\" target="tools" />
<file src="content\" target="content" />
</files>
</package>
Package.nuspec Changes
I can’t go over every possible nuspec setting. That is in the Nuspec Reference. However, I’ll give you the basics of what I changed.
- id – Set this to your package name. If you named your project correctly, this is already named correctly. I’ll leave the above unchanged.
- version – This is your version. If this is your first release, 1.0.0 is perfect. I am changing mine to 1.1.0 as my last version was 1.0.9.
- title – Often the same as the id, but not always. I’ll leave mine as is.
- authors – This is me. I want something other than the Visual Studio username. I changed this to Jared Barneck (Rhyous)
- owners – This is me or my business. I’ll change this to Rhyous Publishing LLC
- description – Long description. This is defined in the Xml. Change it to describe your NuGet package.
- releaseNotes – I just put a link to the release notes in my GitHub repo: https://github.com/rhyous/SimpleArgs/blob/master/ReleaseNotes.txt
- summary – Short description. This is also defined in the xml. This is usually shorter than the description.
- language – This is the 5 digit language IETF language tag. I left mine at en-US.
- projectUrl – I changed this to my GitHub location: https://github.com/rhyous/SimpleArgs
- iconUrl – I changed this to the icon file in my GitHub source. Unlike the release notes and the license file, I used the raw GitHub link for the image: https://raw.githubusercontent.com/rhyous/SimpleArgs/master/Docs/Images/SimpleArgs.Logo.png
- requireLicenseAcceptance – I left this as false. Only set this to true if your license requires an agreement.
- licenseUrl – I set this to the license file in my GitHub repository:
https://github.com/rhyous/SimpleArgs/blob/master/Fork%20and%20Contribute%20License.txt - copyright – I set this to Copyright Rhyous Publishing LLC
- dependencies – This project has no dependencies, so I deleted this entire section.
- references – I deleted this tag. Source NuGet packages probably won’t have any references.
- tags – Since my project is for command line arguments, I set my tags to: args, arguments
- files – This was preconfigured, however, I replaced the libs\ with src\ because I didn’t have any libs but I have source.
You can see my final nuspec file in the GitHub repo: SimpleArgs.Sources Package.nuspec
Step 3 – Add Shared Source Files
In Visual Studio, in Solution Explorer, you should see that there are already four folders provided for you. See the image to your right. ———–>
- content – This is what is going to be copied to your project. Since we don’t want all our source copied, we aren’t going to put our source here.
Note: I would delete this folder, but it turns out, I have one source file that isn’t shared. ArgsHandler.cs will be customized in each project, which makes sense because each project will have different args and handle args differently. ArgsHandler.cs will go here. - libs – I have no libs. I can delete this folder and the associated xml for it in the nuspec.
- src – Stuff I put here isn’t copied to my projects. I am going to put all my shared source in this folder.
- tools – this has the PowerShell scripts: init.ps1, install.ps1, and uninstall.ps1
Now that we understand our folder structure, let’s get to work.
- In Visual Studio’s Solution Explorer, create a folder called App_Packages under the src directory.
Note: I was going to use App_Sources but NuGet recommends that we follow what other community members follow and others have already started putting source files under App_Packages, so I am following that community convention. Also, this is important for the PowerShell scripts, as this convention plays a part in them. If you don’t follow this convention, you will have to edit the and uninstall.psi PowerShell scripts, which I’ll be providing later. - In Visual Studio’s Solution Explorer, create a Folder with the project name and version. In my case, the folder name is this: SimpleArgs.Sources.1.1.0.
Note: Again, this was by community convention. Others were doing this. You don’t have to follow this exactly, again, If you don’t follow this convention, you will have to edit the install.ps1 and uninstall.psi PowerShell scripts, which I’ll be providing later. - In Windows Explorer, not in Visual Studio, put your source under the project name and version directory.
Note: In Visual Studio’s Solution Explorer, I only have these two directories: App_Packages/SimpleArgs.Sources.1.1.0.
Note: In Windows Explorer, My directory structure ended up as follows:\App_Packages \App_Packages\SimpleArgs.Sources.1.1.0\ \App_Packages\SimpleArgs.Sources.1.1.0\Business \App_Packages\SimpleArgs.Sources.1.1.0\Business\Args.cs \App_Packages\SimpleArgs.Sources.1.1.0\Business\ArgsHandlerCollection.cs \App_Packages\SimpleArgs.Sources.1.1.0\Business\ArgsManager.cs \App_Packages\SimpleArgs.Sources.1.1.0\Business\ArgsReader.cs \App_Packages\SimpleArgs.Sources.1.1.0\Business\ArgumentMessageBuilder.cs \App_Packages\SimpleArgs.Sources.1.1.0\Business\CommonAllowedValues.cs \App_Packages\SimpleArgs.Sources.1.1.0\Extensions \App_Packages\SimpleArgs.Sources.1.1.0\Extensions\ArgumentExtensions.cs \App_Packages\SimpleArgs.Sources.1.1.0\Extensions\StringExtensions.cs \App_Packages\SimpleArgs.Sources.1.1.0\Interfaces \App_Packages\SimpleArgs.Sources.1.1.0\Interfaces\IArgumentMessageBuilder.cs \App_Packages\SimpleArgs.Sources.1.1.0\Interfaces\IArgumentsHandler.cs \App_Packages\SimpleArgs.Sources.1.1.0\Interfaces\IReadArgs.cs \App_Packages\SimpleArgs.Sources.1.1.0\Model \App_Packages\SimpleArgs.Sources.1.1.0\Model\Argument.cs \App_Packages\SimpleArgs.Sources.1.1.0\Model\ArgumentAddedEventArgs.cs \App_Packages\SimpleArgs.Sources.1.1.0\Model\ArgumentDictionary.cs \App_Packages\SimpleArgs.Sources.1.1.0\Model\ArgumentList.cs \App_Packages\SimpleArgs.Sources.1.1.0\Model\ArgumentsHandlerBase.cs
Note: There is a good reason that I don’t include these in the NuGet Packager Visual Studio project, which I will explain later.
Step 4 – Add Source Files
As mentioned earlier, the ArgsHandler.cs file isn’t shared. Each project does need its own copy of this file. So we need to add it so that it supports Source Code Transformations.
- In Visual Studio’s Solution Explorer, copy any source files into the Content directory. You may put them in sub directories if you wish. I created an Arguments folder.
- Add .pp to the end of any source files.
- Change the namespace to $rootnamespace$ in any source files. You may also add a sub namespace to the end of $rootnamespace$ as I did.
using SimpleArgs;
using System;
using System.Collections.Generic;
namespace $rootnamespace$.Arguments
{
// Add this line of code to Main() in Program.cs
//
// ArgsManager.Instance.Start(new ArgsHandler(), args);
//
/// <summary>
/// A class that implements IArgumentsHandler where command line
/// arguments are defined.
/// </summary>
public sealed class ArgsHandler : ArgsHandlerBase
{
// content snipped see full file here: https://github.com/rhyous/SimpleArgs/blob/master/NuGet/SimpleArgs.NuGet/content/Arguments/ArgsHandler.cs.pp
}
}
Step 5 – Add As Link in NuGet using PowerShell scripts
There are three PowerShell scripts.
- init.ps1
- install.ps1
- uninstall.ps1
We are only going to modify install.ps1 and uninstall.ps1.
Note: The following are written to be very generic and have been tested in various Visual Studio projects, which means some common bugs are already fixed, such as not failing on creation of App_Packages just because it is already there.
- Update install.ps1.
Note: For the latest versions of install1.ps1 and uninstall.ps1, go to the tools directory on my GitHub repo.
# Runs every time a package is uninstalled param($installPath, $toolsPath, $package, $project) # $installPath is the path to the folder where the package is installed. # $toolsPath is the path to the tools directory in the folder where the package is installed. # $package is a reference to the package object. # $project is a reference to the project the package was installed to. # Variables $src = "src" $packageName = [System.IO.Path]::GetFileName($installPath) #logging write-host "project: " $project.FullName write-host "installPath: " $installPath write-host "toolsPath: " $toolsPath write-host "package: " $package write-host "project: " $project $srcPath = [System.IO.Path]::Combine($installPath, $src) write-host "srcPath: " $srcPath $solutionDir = [System.IO.Path]::GetDirectoryName($dte.Solution.FullName) $projectDir = [System.IO.Path]::GetDirectoryName($project.FullName) write-host "solutionDir: " $solutionDir write-host "projectDir: " $projectDir $areSameDir = $solutionDir -eq $projectDir write-host "areSameDir: " $areSameDir function AddLinkedFiles($path, $addLocation, $canLink) { write-host "path: " $path write-host "addLocation: " $addLocation.FullName write-host "canLink: " $canLink foreach ($item in Get-ChildItem $path) { write-host "item: " $item $item.FullName if (Test-Path $item.FullName -PathType Container) { if ( $canLink) { $addFolder = $project.ProjectItems|Where-Object {$_.FullName -eq $item.FullName} if (!$addFolder) { $addFolder = $addLocation.ProjectItems.AddFolder($item) } write-host "addFolder: " $addFolder.FullName AddLinkedFiles $item.FullName $addFolder $canLink } else { AddLinkedFiles $item.FullName $addLocation $canLink } } else { write-host "Adding " $item.FullName " to " $addLocation.FullName $addLocation.ProjectItems.AddFromFile($item.FullName) } } } write-host "Calling AddLinkedFiles" AddLinkedFiles $srcPath $project (!$areSameDir) - Update uninstall.ps1.
# Runs every time a package is uninstalled param($installPath, $toolsPath, $package, $project) # $installPath is the path to the folder where the package is installed. # $toolsPath is the path to the tools directory in the folder where the package is installed. # $package is a reference to the package object. # $project is a reference to the project the package was installed to. # Variables $packages = "Packages" $app_packages = "App_Packages" $src = "src" $packageName = [System.IO.Path]::GetFileName($installPath) #logging write-host "project: " $project.FullName write-host "installPath: " $installPath write-host "toolsPath: " $toolsPath write-host "package: " $package write-host "project: " $project $srcPath = [System.IO.Path]::Combine($installPath, $src) write-host "srcPath: " $srcPath $solutionDir = [System.IO.Path]::GetDirectoryName($dte.Solution.FullName) $projectDir = [System.IO.Path]::GetDirectoryName($project.FullName) write-host "solutionDir: " $solutionDir write-host "projectDir: " $projectDir $areSameDir = $solutionDir -eq $projectDir write-host "areSameDir: " $areSameDir if ($areSameDir) { $packagesItem = $project.ProjectItems|Where-Object {$_.Name -eq $packages} write-host "packageFolder: " $packagesItem.Name $item = $packagesItem.ProjectItems|Where-Object {$_.Name -eq [System.IO.Path]::GetFileName($installPath)} write-host "item: " $item.Name $item.Remove() if ($packagesItem.ProjectItems.Count -eq 0) { $packagesItem.Remove() } } else { $app_packagesItem = $project.ProjectItems|Where-Object {$_.Name -eq $app_packages} write-host "app_packagesItem: " $app_packagesItem.Name $app_packagesFolder = [System.IO.Path]::Combine($srcPath,$app_packages) foreach ($subDir in (Get-ChildItem $app_packagesFolder)) { $item = $app_packagesItem.ProjectItems|Where-Object {$_.Name -eq $subDir.Name} write-host "item: " $item.Name if ($item) { $item.Delete() } } if ($app_packagesItem.ProjectItems.Count -eq 0 -and (Get-ChildItem ([System.IO.Path]::Combine($projectDir, $app_packages))).Count -eq 0) { $app_packagesItem.Delete() } }Step 6 – Build the solution and NuGet package
The NuGet Packager project template is pretty awesome. When you use it, it builds the NuGet package for you on build. Also, if you build in release mode, it will try to upload the NuGet package to the public NuGet Package Gallary.
- In Visual Studio, make sure the Solution Configuration is set to Debug.
- Choose to Build | Build Solution.
- In your project directory, you should have a NuGet package built. Mine is called SimpleArgs.Sources.1.1.1.nupkg.
Stay Tuned
Stay tuned for NuGet for Source Using Add As Link (Part 2 – Testing & Deploying)
If you subscribe, you will never miss a post.
