OctoPack is an open source project that makes it easy to create Octopus Deploy-compatible NuGet packages.
Sounds confusing? Well, NuGet was originally designed for packaging up open-source code libraries for developers to use in Visual Studio. And it also happens to be the perfect format for packaging applications that you want to deploy. As we discuss on the packaging page, however, some of the default NuGet conventions and assumptions don't work quite so well for tools like Octopus. So to help you create Octopus-ready NuGet packages, we created a tool called OctoPack.
Please raise and track issues for this project here.
Assuming you have an ASP.NET web site or Windows Service C# (or VB.NET) project, creating a NuGet package that works with Octopus is easy.
- Ensure you have installed NuGet into your Visual Studio
- From the View menu, open Other Windows -> Package Manager Console
- In the Default Project drop down, choose the ASP.NET web site or Windows Service project that you would like to package
Install the OctoPack package by typing:
You will see output similar to this:
To have OctoPack create a NuGet package from your build, set the
RunOctoPack MSBuild property to
true. For example, if you are compiling from the command line, you might use:
msbuild MySolution.sln /t:Build /p:RunOctoPack=true
After the build completes, in the output directory you will find a NuGet package. This package is ready to be deployed using your Octopus Deploy server.
Adding a NuSpec
.nuspec file describes the contents of your NuGet package. OctoPack automatically creates one if you haven't provided one, by guessing some of the settings from your project. But you may wish to provide your own simple .nuspec file to your project. The file name should match the name of your C# project - for example, Sample.Web.nuspec if your ASP.NET project is named Sample.Web.
Here is an example of the .nuspec file contents:
<?xml version="1.0"?> <package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd"> <metadata> <id>Sample.Web</id> <title>Your Web Application</title> <version>1.0.0</version> <authors>Your name</authors> <owners>Your name</owners> <licenseUrl>http://yourcompany.com</licenseUrl> <projectUrl>http://yourcompany.com</projectUrl> <requireLicenseAcceptance>false</requireLicenseAcceptance> <description>A sample project</description> <releaseNotes>This release contains the following changes...</releaseNotes> </metadata> </package>
What is packaged?
OctoPack is smart enough to only package files required for deployment. If you are packaging a Windows Service or Console application, then it will package all of the output files in the
bin\Release folder (assuming you have done a release build).
If you need to include other files in your package for deployment, use the Visual Studio properties panel to set the Copy to Output Directory attribute to Copy always.
When web applications are packaged, only the binaries and content files are included:
(Note: OctoPack won't run web.config transformation files, because these will be run as part of the deployment instead)
If you need to go beyond this and include additional files, you can do so using the
<files> element in your custom NuSpec file. For example:
<files> <file src="bin\*.dll" target="bin" /> <file src="Content\*.css" target="Content" /> </files>
(Note: this only works in OctoPack >= 2.0.24)
<files> section exists, OctoPack by default won't attempt to automatically add any extra files to your package, so you'll need to be explicit about which files you want to include. You can override this behavior with /p:OctoPackEnforceAddingFiles=true
See the NuSpec files reference documentation for more examples on how to specify which files to include.
NuGet packages have version numbers. When you use OctoPack, the NuGet package version number will come from (in order of priority):
- The command line, if you pass
/p:OctoPackPackageVersion=<version>as an MSBuild parameter when building your project
- If the
[assembly: FileVersion]is the same as the
[assembly: AssemblyInformationalVersion](AKA ProductVersion), then we'll use the
[assembly: AssemblyVersion]attribute in your
- Otherwise we take the
Version Numbers are preserved as-is
NuGet 3 started removing leading zeros and the fourth digit if it is zero. These are affectionately known as "NuGet zero quirks" and can be surprising when working with tooling outside the NuGet ecosystem. We have made a choice to preserve the version as-is when working with Octopus tooling to create packages of any kind. Learn more about versioning in Octopus Deploy.
To make this work for NuGet packages we have forked NuGet
The fork of NuGet 3 available here: https://github.com/OctopusDeploy/NuGet.Client The build is available here: https://build.octopushq.com/project.html?projectId=OctopusDeploy_NuGet&tab=projectOverview The packages are available here: https://octopus.myget.org/feed/octopus-dependencies/package/nuget/NuGet.CommandLine
Adding release notes
NuSpec files can contain release notes, which show up on the Octopus Deploy release page. OctoPack can add these notes to your NuGet package if you pass a path to a file containing the notes. For example:
msbuild MySolution.sln /t:Build /p:RunOctoPack=true /p:OctoPackReleaseNotesFile=..\ReleaseNotes.txt
Note that the file path should always be relative to the C#/VB project file (not the solution file).
To publish your package to a NuGet feed, you can optionally use some extra MSBuild properties:
/p:OctoPackPublishPackageToFileShare=C:\MyPackages- copies the package to the path given
/p:OctoPackPublishPackageToHttp=http://my-nuget-server/api/v2/package- pushes the package to the NuGet server
/p:OctoPackPublishApiKey=ABCDEFGMYAPIKEY- API key to use when publishing
/p:OctoPackAppendProjectToFeed=true- Append the project name onto the feed so you can nest packages under folders on publish
/p:OctoPackAppendToPackageId=foo- Append the extra name to the package ID (e.g. for feature branch packages). MyApp.Foo.1.2.3.nupkg
Contributing to OctoPack
Read our contributing guidelines for information about contributing step templates and to the website.