QuickStart

Introduction

This is the quick guide to get started with Squirrel.

We'll touch on the basics of:

adding Squirrel into an existing application
defining the details for your application
how versioning works in Squirrel
creating a release for your application
installing this app on your local machine

Requirements

Visual Studio 2012 or better
NuGet 2.7 (might work on older versions, but I haven't tested thoroughly)
A WPF or WinForms application on .NET 4 or greater
Recommended: Enable NuGet Package Restore for your solution. It's neat.

Install Squirrel

This section should walk you through the steps necessary (with pictures because we're visual creatures) to add Squirrel into your application.

In the Package Manager Console in Visual Studio ( or View | Other Windows | Package Manager Console if you don't have it open) run this command:

Note: You only need to install this against your main application (my project is called TestApp).

Install-Package Squirrel.Client -Project TestApp

As part of the install, a script will do a few tasks to get you up and running:

set BuildPackage to true inside the project file to hook into the build system
add a NuSpec file to the project to define the metadata for your installer
open the NuSpec file inside Visual Studio, ready to edit it

Define the application details

Squirrel leverages many NuGet conventions instead of reinventing the wheel. One of these is the NuSpec file specification which defines some metadata for your application.

When you install Squirrel, you'll see a template like this (with your project name in place of TestApp):

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
  <metadata>
    <id>TestApp</id>
    <title>A human-friendly name for TestApp goes here</title>
    <version>$version$-beta</version>
    <authors>Your Name Here</authors>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>A description of TestApp goes here</description>
  </metadata>
</package>

Here's a quick explanation of the fields:

Id - a short identifier for the application
Title - the application name (will appear in the "Programs and Features" listing when it's been installed).
Description - a brief explanation of what the application does
Authors - put your name in there so you can get internet famous
Version - this is generated at build time. Don't remove the $version$ placeholder.

If you have values in your AssemblyInfo.cs file, you can specify those as placeholders in this file:

$id$ - the Assembly name
$version$ - the assembly version as specified in the assembly’s AssemblyVersionAttribute. If the assembly’s AssemblyInformationalVersionAttribute is specified, that one is used instead.
$author$ - the company as specified in the AssemblyCompanyAttribute.
$description$ - the description as specified in the AssemblyDescriptionAttribute.

You can read the full documentation about the nuspec reference for more information about how this all works.

Here's an example for Play for Windows:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
  <metadata>
    <id>Play-Windows</id>
    <title>Play for Windows</title>
    <version>$version$-beta</version>
    <authors>GitHub</authors>
    <description>A client for streaming Play music to your Windows machine</description>
  </metadata>
</package>

Once you've done that, save the file and build the solution.

Application dependencies and NuSpec files

If you've got a non-trivial application - which references other projects and they each have their own set of package.config files - you should read this guide on ensuring things are structured right (unfortunately the magic can only go so far).

Specifying the version of your application

Now when you build the project, NuGet will create a package with each build. This contains the build output from the project - which should be everything you need to run the application.

1>------ Build started: Project: TestApp, Configuration: Debug Any CPU ------
1>  All packages listed in packages.config are already installed.
1>  TestApp -> C:\Users\brendanforster\Documents\GitHub\TestApp\bin\Debug\TestApp.exe
1>  Attempting to build package from 'TestApp.csproj'.
1>  Packing files from 'C:\Users\brendanforster\Documents\GitHub\TestApp\bin\Debug'.
1>  Using 'TestApp.nuspec' for metadata.
1>  Found packages.config. Using packages listed as dependencies
1>  Successfully created package 'C:\Users\brendanforster\Documents\GitHub\TestApp\bin\Debug\TestApp.1.0.0-beta.nupkg'.
1>  
1>  Attempting to build symbols package for 'TestApp.csproj'.
1>  Packing files from 'C:\Users\brendanforster\Documents\GitHub\TestApp\bin\Debug'.
1>  Using 'TestApp.nuspec' for metadata.
1>  Found packages.config. Using packages listed as dependencies
1>  Successfully created package 'C:\Users\brendanforster\Documents\GitHub\TestApp\bin\Debug\TestApp.1.0.0-beta.symbols.nupkg'.
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

But where does that version come from? It's just the Properties\AssemblyInfo.cs file inside that project. Open up that file and ensure it has these three values.

[assembly: AssemblyVersion("1.0.0")]
[assembly: AssemblyFileVersion("1.0.0")]
[assembly: AssemblyInformationalVersion("1.0.0")]

You probably don't have AssemblyInformationalVersion - and this is one that NuGet prefers. Add that in if you don't have it.

Before you go any further, have a read of how NuGet versioning works as these are the same rules we use.

Some quick notes:

the nuspec template that Squirrel adds has a -beta flag in the version by default - this is Semantic Versioning's way of saying that it's a pre-release application. You can delete this if you don't care about having pre-release applications.
using the Major.Minor.Patch versioning conventions should be enough for most cases.

Publish a Release

So once you're application is ready to ship and you've got the version right, build the solution and then open the Package Manager Console again.

Inside, run this command: New-Release -Project TestApp

This process will:

find the NuGet .nupkg files in your build output
generate the Squirrel release packages
create a RELEASES file to the same folder - which lists all versions available
create a WiX installer for your application
put all these artifacts in the Releases folder in your solution directory

What's in a Release?

The contents of a release are just a few files.

RELEASES file

This file is a plain-text file containing lines like this:

361A52FD65D40D0A851850AF70D884C91287DB3F TestApp-1.0.0-beta-full.nupkg 2632148

This is a list of all the release packages in the Releases directory, capturing in each row:

a SHA1 hash of the file contents (to detect corrupt packages and not use them)
the file name
the file size (in bytes)

This file is downloaded by the Squirrel updater to determine what releases are available beyond it's current release.

.nupkg file

This file is a NuGet package containing the build artifacts necessary to get your application working. You don't need to understand how to install this - the Squirrel.Client library takes care of unpacking these bits and putting them somewhere.

Setup.exe

If you're lazy like me, just go and click this. This executable contains everything you need to get the application running on a given machine.

In particular, the default Squirrel installer takes care of:

unpacking your application bits from the .nupkg file
installing the application into %LOCALAPPDATA% folder for the current user
creating a shortcut on the desktop for your application
starting the application after the installer finishes

And there we go. Welcome to Squirrel.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly