Skip to content

Improved GitVersionTask documentation #792

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Feb 23, 2016
Merged

Improved GitVersionTask documentation #792

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ee78485
Improved GitVersionTask documentation
asbjornu Feb 22, 2016
602eaf3
Wrap all lines at 80 characters
asbjornu Feb 23, 2016
cb03a49
Fixed typos and errors
asbjornu Feb 23, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 87 additions & 40 deletions docs/usage/msbuild-task.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,36 +1,69 @@
# MSBuild Task

Available on [Nuget](https://www.nuget.org) under [GitVersionTask](https://www.nuget.org/packages/GitVersionTask/)
The MSBuild Task for GitVersion — **GitVersionTask** — a simple solution if you
want to version your assemblies without writing any command line scripts or
modifying your build process.

## TL;DR

### Install

It works simply by installing the [GitVersionTask NuGet
Package](https://www.nuget.org/packages/GitVersionTask/) into the project you
want to have versioned by GitVersion:

Install-Package GitVersionTask

The MSBuild task will wire GitVersion into the MSBuild pipeline of a project and perform several actions.
### Remove attributes

The next thing you need to do, is remove the `Assembly*Version` attributes from
your `Properties\AssemblyInfo.cs` files, so GitVersionTask can be in charge of
versioning your assemblies.

### Done!

The TL;DR section is now done and GitVersionTask should be working its magic,
versioning your assemblies like a champ. However, if you're interested in
knowing what more GitVersionTask does, or have any questions, please read on.

After being installed into a project, the MSBuild task will wire GitVersion into
the MSBuild pipeline of a project and perform several actions. These actions are
described below.

## Inject version metadata into the assembly
## How does it work?

Task Name: `GitVersionTask.UpdateAssemblyInfo`
### Inject version metadata into the assembly

### AssemblyInfo Attributes
The sub-task named `GitVersionTask.UpdateAssemblyInfo` will inject version
metadata into the assembly which GitVersionTask is added to. For each assembly
you want GitVersion to version, you need to install the GitVersionTask into it
via NuGet.

At build time a temporary AssemblyInfo.cs will be created that contains the appropriate SemVer information. This will will be included in the build pipeline.
#### AssemblyInfo Attributes

Ensure you remove the `Assembly*Version` attributes from your `Properties\AssemblyInfo.cs` file so as to not get duplicate attribute warnings. Sample default:
At build time a temporary `AssemblyInfo.cs` will be created that contains the
appropriate SemVer information. This will be included in the build pipeline.
Sample default:

[assembly: AssemblyVersion("1.0.0.0")]
[assembly: AssemblyFileVersion("1.0.0.0")]
[assembly: AssemblyInformationalVersion("1.1.0+Branch.master.Sha.722aad3217bd49a6576b6f82f60884e612f9ba58")]
```c#
[assembly: AssemblyVersion("1.0.0.0")]
[assembly: AssemblyFileVersion("1.0.0.0")]
[assembly: AssemblyInformationalVersion("1.1.0+Branch.master.Sha.722aad3217bd49a6576b6f82f60884e612f9ba58")]
```

Now when you build:

* `AssemblyVersion` will be set to the `AssemblySemVer` variable.
* `AssemblyFileVersion` will be set to the `MajorMinorPatch` variable with a appended `.0`.
* `AssemblyInformationalVersion` will be set to the `InformationalVersion` variable.
* `AssemblyFileVersion` will be set to the `MajorMinorPatch` variable with a
* appended `.0`. `AssemblyInformationalVersion` will be set to the
* `InformationalVersion` variable.

### Other injected Variables
#### Other injected Variables

All other [variables](../more-info/variables.md) will be injected into a internal static class.
All other [variables](../more-info/variables.md) will be injected into an
internal static class:

```
```c#
namespace AssemblyName
{
[CompilerGenerated]
Expand All @@ -44,11 +77,11 @@ namespace AssemblyName
}
```

### Accessing injected Variables
#### Accessing injected Variables

**All variables**
##### All variables

```
```c#
var assemblyName = assembly.GetName().Name;
var gitVersionInformationType = assembly.GetType(assemblyName + ".GitVersionInformation");
var fields = gitVersionInformationType.GetFields();
Expand All @@ -59,49 +92,63 @@ foreach (var field in fields)
}
```

**Specific variable**
##### Specific variable

```
```c#
var assemblyName = assembly.GetName().Name;
var gitVersionInformationType = assembly.GetType(assemblyName + ".GitVersionInformation");
var versionField = gitVersionInformationType.GetField("Major");
Trace.WriteLine(versionField.GetValue(null));
```

## Populate some MSBuild properties with version metadata
### Populate some MSBuild properties with version metadata

Task Name: `GitVersionTask.GetVersion`
The sub-task `GitVersionTask.GetVersion` will write all the derived
[variables](../more-info/variables.md) to MSBuild properties so the information
can be used by other tooling in the build pipeline.

At build time all the derived [variables](../more-info/variables.md) will be written to MSBuild properties so the information can be used by other tooling in the build pipeline.
The class for `GitVersionTask.GetVersion` has a property for each variable.
However at MSBuild time these properties are mapped to MSBuild properties that
are prefixed with `GitVersion_`. This prevents conflicts with other properties
in the pipeline.

The class for `GitVersionTask.GetVersion` has a property for each variable. However at MSBuild time these properties a mapped to MSBuild properties that are prefixed with `GitVersion_`. This prevents conflicts with other properties in the pipeline.
#### Accessing variable in MSBuild

### Accessing variable in MSBuild
After `GitVersionTask.GetVersion` has executed, the MSBuild properties can be
used in the standard way. For example:

After `GitVersionTask.GetVersion` has executed the properties can be used in the standard way. For example:

<Message Text="GitVersion_InformationalVersion: $(GitVersion_InformationalVersion)"/>
```xml
<Message Text="GitVersion_InformationalVersion: $(GitVersion_InformationalVersion)"/>
```

## Communicate variables to current Build Server
### Communicate variables to current Build Server

Task Name: `GitVersionTask.WriteVersionInfoToBuildLog`
The sub-task `GitVersionTask.WriteVersionInfoToBuildLog` will attempt to write
the version information to the current Build Server log.

If, at build time, it is detected that the build is occurring inside a Build Server server then the [variables](../more-info/variables.md) will be written to the build log in a format that the current Build Server can consume. See [Build Server Support](../build-server-support/build-server-support.md).
If, at build time, it is detected that the build is occurring inside a Build
Server then the [variables](../more-info/variables.md) will be written to the
Build Server log in a format that the current Build Server can consume. See
[Build Server Support](../build-server-support/build-server-support.md).

## Conditional control tasks

Properties `WriteVersionInfoToBuildLog`, `UpdateAssemblyInfo` and `GetVersion` are checked before running these tasks.
Properties `WriteVersionInfoToBuildLog`, `UpdateAssemblyInfo` and `GetVersion`
are checked before running these tasks.

If you, eg., want to disable `GitVersionTask.UpdateAssemblyInfo` just define `UpdateAssemblyInfo` to something other than `true` in your MSBuild script, like this:
If you, e.g. want to disable `GitVersionTask.UpdateAssemblyInfo` just define
`UpdateAssemblyInfo` to something other than `true` in your MSBuild script, like
this:

```
<PropertyGroup>
...
<UpdateAssemblyInfo>false</UpdateAssemblyInfo>
...
</PropertyGroup>
```xml
<PropertyGroup>
...
<UpdateAssemblyInfo>false</UpdateAssemblyInfo>
...
</PropertyGroup>
```

## My Git repository requires authentication. What do I do?

Set the environmental variables `GITVERSION_REMOTE_USERNAME` and `GITVERSION_REMOTE_PASSWORD` before the build is initiated.
Set the environmental variables `GITVERSION_REMOTE_USERNAME` and
`GITVERSION_REMOTE_PASSWORD` before the build is initiated.