This page is for Octopus Deploy 3.0 and newer versions. You can view this page for Octopus 2.0

Skip to end of metadata
Go to start of metadata

The easiest way to package your applications from your continuous integration/automated build process is to use OctoPack. OctoPack adds a custom MSBuild target that hooks into the build process of your solution. When enabled, OctoPack will package your Windows Service and ASP.NET applications when MSBuild runs. This makes it easy to integrate OctoPack with your build server - as long as you can pass properties to MSBuild, you can use OctoPack. 

Icon

OctoPack is built and maintained by the Octopus Deploy team, but it is also open source. You can view the OctoPack project on GitHub.

This three minute video (with captions) will walk you through the process of installing and using OctoPack. 

Installing OctoPack

OctoPack is, itself, a NuGet package. You can install it using the NuGet package installer:

OctoPack should only be installed on projects that you are going to deploy - that means the console application projects, Windows Service projects, and ASP.NET web applications. Unit tests, class libraries, and other supporting projects wouldn't be selected. 

Building packages

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:

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

A .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. The nuspec file needs to be in the same directory as your csproj file.

Here is an example of the .nuspec file contents:

Sample NuSpec file
Icon

Learn more about the NuSpec file format.

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.

Web applications require additional files to run, such as Razor/ASPX files, configuration files, and assets such as images, CSS and JavaScript files. When packaging a web application, OctoPack will include any files marked with the Build Action set to Content in the Solution Explorer properties window:

When web applications are packaged, only binaries and the content files are included:

OctoPack determines whether a project is a web application or not based on whether it finds a web.config file.

Icon

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:

If the <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

Icon

See the NuSpec files reference documentation for more examples on how to specify which files to include.

Version numbers

NuGet packages have version numbers. When you use OctoPack, the NuGet package version number will come from (in order of priority):

  1. The command line, if you pass /p:OctoPackPackageVersion=<version> as an MSBuild parameter when building your project.
  2. If the [assembly: FileVersion] is the same as the [assembly: AssemblyInformationalVersion] (AKA ProductVersion), then we'll use the [assembly: AssemblyVersion] attribute in your AssemblyInfo.cs file
  3. Otherwise we take the [assembly: AssemblyInformationalVersion].

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:

Note that the file path should always be relative to the C#/VB project file (not the solution file).

Replacement tokens

You can make use of NuGet replacement tokens inside your NuSpec file:

Sample NuSpec file

To set a value for these parameters, use the MSBuild property OctoPackNuGetProperties:

Publishing

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

All supported parameters

In addition to the common arguments above, OctoPack has a number of other parameters. The full list is documented in the table below. 

ParameterExample valueDescription
RunOctoPackTrueSet to True for OctoPack to run and create packages during the build. Default: OctoPack won't run.
OctoPackPackageVersion1.0.0Version number of the NuGet package. By default, OctoPack gets the version from your assembly version attributes. Set this parameter to use an explicit version number.
OctoPackAppConfigFileOverrideFoo.configWhen packaging a project called YourApp, containing a file named App.config, OctoPack will automatically ignore it, and instead look for YourApp.exe.config. Provide this setting to have OctoPack select your specified config file, instead.
OctoPackAppendToPackageIdReleaseA fragment that will be appended to the NuGet package ID, allowing you to create different NuGet packages depending on the build configuration. E.g., if the ID element in the NuSpec is set to "MyApp", and this parameter is set to "Release", the final package ID will be "MyApp.Release".
OctoPackAppendToVersion beta025Define a pre-release tag to be appended to the end of your package version.
OctoPackEnforceAddingFilesTrueBy default, when your NuSpec file has a <files> element, OctoPack won't automatically add any of the other files that it would usually add to the package. Set this parameter to true to force OctoPack to add all the files it would normally add.
OctoPackIgnoreNonRootScriptsTrueOctopus Deploy only calls Deploy.ps1 files etc., that are at the root of the NuGet package. If your project emits Deploy.ps1 files that are not at the root, OctoPack will usually warn you when packaging these. Set this parameter to true to suppress the warning.
OctoPackIncludeTypeScriptSourceFilesTrueIf your project has TypeScript files, OctoPack will usually package the corresponding .js file produced by the TypeScript compiler, instead of the .ts file. Set this parameter to true to force OctoPack to package the .ts file instead.
OctoPackNuGetArguments-NoDefaultExcludesUse this parameter to specify additional command line parameters that will be passed to NuGet.exe pack. See the NuGet pack command description.
OctoPackNuGetExePathC:\Tools\NuGet.exeOctoPack comes with a bundled version of NuGet.exe. Use this parameter to force OctoPack to use a different NuGet.exe instead.
OctoPackNuGetPropertiesfoo=bar;baz=bingIf you use replacement tokens in your NuSpec file (e.g., $foo$, $bar$, $version$, etc.), this parameter allows you to set the value for those tokens. See the section above on replacement tokens, and see the NuSpec reference for details on replacement tokens.
OctoPackNuGetPushProperties-Timeout 500Additional arguments that will be passed to NuGet.exe push if you are pushing to an HTTP/HTTPS NuGet repository. See the NuGet push command description.
OctoPackNuSpecFileNameMyApp.nuspecThe NuSpec file to use. Defaults to "<C#/VB project name>.nuspec". If the file doesn't exist, OctoPack generates a NuSpec based on your project metadata.
OctoPackPublishApiKeyAPI-ABCDEFGMYAPIKEYYour API key to use when publishing to a HTTP/HTTPS based NuGet repository
OctoPackPublishPackagesToTeamCityFalseBy default, if OctoPack detects that the build is running under TeamCity, the NuGet package that is produced is registered as an artifact in TeamCity. Use this parameter to suppress this behavior.
OctoPackPublishPackageToFileShare\\server\packagesOctoPack can publish packages to a file share or local directory after packaging
OctoPackPublishPackageToHttphttp://my-nuget-server/api/v2/packageOctoPack can publish packages to a HTTP/HTTPS NuGet repository (or the Octopus server) after packaging.
OctoPackReleaseNotesFilemyreleasenotes.txtUse this parameter to have the package release notes read from a file.
OctoPackProjectName
YourProjectName
Use this parameter to override the name of your package so its not necessarily identical to your Visual Studio Project. This will only work when building a single Project/Package. For multiple projects you do not use this parameter and instead set the below property on your project's csproj file
<PropertyGroup>
    <OctoPackProjectName>Foo</OctoPackProjectName>
</PropertyGroup>
 

 

 

 

 

  • No labels