Shuttle.NuGetPackager

This VS2022+ extension is used to configure a C# class library project for NuGet packaging allowing you to manage the versioning package.

Note: This extension should only be applied to Visual Studio files that are in the new SDK format.

Installation

You can download this extntion from the Visual Studio Marketplace.

Usage

By accessing the context menu of a C# class library project you select Configure NuGet Project which will create a .package folder containing:

• package.msbuild
• Shuttle.NuGetPackager.targets
• Shuttle.NuGetPackager.MSBuild.dll
• AssemblyInfo.cs.template
• package.nuspec.template
• package.nuspec

In addition your projects's .csproj file will be updated to include a property <GenerateAssemblyInfo>false</GenerateAssemblyInfo> in order to make use of an ``AssemblyInfo.csfile which is created from theAssemblyInfo.cs.template`.

You explicitly set the version of your package using the package.msbuild file. When you commit you changes that version will be commited and any CI automation can build the package using the configured version.

In order to effect any changes you should execute the package.msbuild with the relevant target the default being Version. Each target is explained in the following sections.

Version

msbuild package.msbuild [/t:Version] [/p:SemanticVersion=major.minor.patch[-prerelease[+buildmetadata]]]

You will be prompted for the SemanticVersion if not specified. This is parsed and produces the following output parameters:

• SemanticVersionCore: major.minor.patch
• SemanticVersionPrerelease: prerelease
• SemanticVersionBuildMetadata: buildmetadata

These parameters are replacement values for tags in the AssemblyInfo.cs.template and package.nuspec.template files:

The package.nuspec file will also update #{Dependencies}# with all the dependencies located in the .csproj file.

Should you require more control over the dependencies the following structure may be used:

<dependencies>
	<dependency id="Shuttle.Core.Contract" version="{Shuttle.Core.Contract-version}" />
	<dependency id="Shuttle.Core.Data" version="{Shuttle.Core.Data-version}" />
</dependencies>

All {PackageName-version} tags will be replaced by the version referenced in the .csproj file.

Build

msbuild package.msbuild [/t:build]

Build both the Debug as well as the Release configurations of the project.

Pack (depends on Build)

msbuild package.msbuild [/t:pack]

Uses NuGet to pack the output using the package.nuspec file. The package.nuspec file is generated by the Version target.

The created {PackageName}.{SemanticVersion}.nupkg file will be in the .package\release folder.

Push

msbuild package.msbuild [/t:push]

Will push the .package\release\{PackageName}.{SemanticVersion}.nupkg package to a provided PackageSource NuGet source.

If PackageSource is not provided the default https://www.nuget.org will be used.

Bump (depends on Version)

msbuild package.msbuild [/t:bump] 

Will set the semantic version, build the project, and copy the package file to $(NuGetPackageSourceFolder).

If no $(NuGetPackageSourceFolder) property exists then the file isn't copied. As per normal MSBuild functionality you can also define an environment variable called NuGetPackageSourceFolder.

A useful workflow is to create a local package folder abd have the NuGetPackageSourceFolder environment variable point to that folder. You then bump the package and test is locally. Once you are happy with the package you can then commit the changes.

Flush

Removes the folder package (%UserProfile%\.nuget\packages\{PackageName}) from the NuGet cache.

This is useful during development when you wish to stick on the same version and have your dependent project make use of the latest build.

Shuttle.NuGetPackager.MSBuild

This assembly contains the following MSBuild tasks:

Prompt

Prompts the user for input that is saved in the given output parameter.

<Prompt Text="Enter semantic version:" Condition="$(SemanticVersion) == ''">
	<Output TaskParameter="UserInput" PropertyName="SemanticVersion" />
</Prompt>

RegexFindAndReplace

Performs a regular expression find/replace on the given files.

<RegexFindAndReplace Files="@(Files)" FindExpression="regex" ReplacementText="new-text" />

SetNuGetPackageVersions

Retrieves the package names and version from the given package folder and replaces all tags with the relevant version number. A tag has to be in the format {OpenTag}{PackageName}-version{CloseTag}.

<SetNuGetPackageVersions Files="@(Files)" PackageFolder="nuget-package-folder" />

Zip

Creates an archive that contains the given files.

<Zip Files="@(Files)" RelativeFolder="$(OutputPath)" ZipFilePath="$(OutputPath).zip" />