https://github.com/shuttle/shuttle.nugetpackager
Visual Studio extension used to configure/build a C# class library as a NuGet package.
https://github.com/shuttle/shuttle.nugetpackager
Last synced: about 2 months ago
JSON representation
Visual Studio extension used to configure/build a C# class library as a NuGet package.
- Host: GitHub
- URL: https://github.com/shuttle/shuttle.nugetpackager
- Owner: Shuttle
- Created: 2020-06-17T11:07:31.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-10-06T06:54:12.000Z (8 months ago)
- Last Synced: 2025-02-02T07:28:52.997Z (4 months ago)
- Language: C#
- Homepage:
- Size: 145 KB
- Stars: 1
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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 extension from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=Shuttle.NuGetPackager).
## 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 `false` in order to make use of an ``AssemblyInfo.cs` file which is created from the `AssemblyInfo.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:
| Tag | Property / Value |
| --- | --- |
| #{SemanticVersionCore}# | $(SemanticVersionCore) |
| #{SemanticVersion}# | $(SemanticVersion) |
| #{Year}# | $([System.DateTime]::Now.ToString(`yyyy`)) |
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:
```
```
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.
| Parameter | Required | Description |
| --- | --- | --- |
| Text | yes | The text to display on the console. |
| UserInput | output | The value entered on the console. |
``` xml
```
### RegexFindAndReplace
Performs a regular expression find/replace on the given files.
| Parameter | Required | Description |
| --- | --- | --- |
| Files | yes | The files that the find/replace operation should be performed on. |
| FindExpression | yes | The Regex that should be used to find the text to be replaced. |
| ReplacementText | no | The text to replace the located expression with. |
| IgnoreCase | no | Defaults to false. |
| Multiline | no | Defaults to false. |
| Singleline | no | Defaults to false. |
``` xml
```
### 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}`.
| Parameter | Required | Description |
| --- | --- | --- |
| Files | yes | The files that contain package version tags. |
| PackageFolder | yes | The folder that contains all the packages. |
| OpenTag | no | Defaults to `{`. |
| CloseTag | no | Defaults to `}`. |
``` xml
```
### Zip
Creates an archive that contains the given files.
| Parameter | Required | Description |
| --- | --- | --- |
| Files | yes | The files that should be added to the zip archive. |
| RelativeFolder | yes | The 'base' folder that the zip entries should be created from. e.g. if there is a file `c:\folder\another\file.txt` and the `RelativeFolder` is `c:\folder\` then the entry in the zip archive will be `another\file.txt`. |
| ZipFilePath | yes | The path to the zip archive that will be created. Any existing file will be overwritten. |
``` xml
```