Skip to content

Commit 68adb68

Browse files
gep13gep13
committed
Merge pull request #792 from okb/feature/msbuild-task-documentation
Improved GitVersionTask documentation
2 parents 704bdfa + cb03a49 commit 68adb68

File tree

1 file changed

+87
-40
lines changed

1 file changed

+87
-40
lines changed

‎docs/usage/msbuild-task.md

Lines changed: 87 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,69 @@
11
# MSBuild Task
22

3-
Available on [Nuget](https://www.nuget.org) under [GitVersionTask](https://www.nuget.org/packages/GitVersionTask/)
3+
The MSBuild Task for GitVersion — **GitVersionTask** — a simple solution if you
4+
want to version your assemblies without writing any command line scripts or
5+
modifying your build process.
6+
7+
## TL;DR
8+
9+
### Install
10+
11+
It works simply by installing the [GitVersionTask NuGet
12+
Package](https://www.nuget.org/packages/GitVersionTask/) into the project you
13+
want to have versioned by GitVersion:
414

515
Install-Package GitVersionTask
616

7-
The MSBuild task will wire GitVersion into the MSBuild pipeline of a project and perform several actions.
17+
### Remove attributes
18+
19+
The next thing you need to do, is remove the `Assembly*Version` attributes from
20+
your `Properties\AssemblyInfo.cs` files, so GitVersionTask can be in charge of
21+
versioning your assemblies.
22+
23+
### Done!
24+
25+
The TL;DR section is now done and GitVersionTask should be working its magic,
26+
versioning your assemblies like a champ. However, if you're interested in
27+
knowing what more GitVersionTask does, or have any questions, please read on.
28+
29+
After being installed into a project, the MSBuild task will wire GitVersion into
30+
the MSBuild pipeline of a project and perform several actions. These actions are
31+
described below.
832

9-
## Inject version metadata into the assembly
33+
## How does it work?
1034

11-
Task Name: `GitVersionTask.UpdateAssemblyInfo`
35+
### Inject version metadata into the assembly
1236

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

15-
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.
42+
#### AssemblyInfo Attributes
1643

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

19-
[assembly: AssemblyVersion("1.0.0.0")]
20-
[assembly: AssemblyFileVersion("1.0.0.0")]
21-
[assembly: AssemblyInformationalVersion("1.1.0+Branch.master.Sha.722aad3217bd49a6576b6f82f60884e612f9ba58")]
48+
```c#
49+
[assembly: AssemblyVersion("1.0.0.0")]
50+
[assembly: AssemblyFileVersion("1.0.0.0")]
51+
[assembly: AssemblyInformationalVersion("1.1.0+Branch.master.Sha.722aad3217bd49a6576b6f82f60884e612f9ba58")]
52+
```
2253

2354
Now when you build:
2455

2556
* `AssemblyVersion` will be set to the `AssemblySemVer` variable.
26-
* `AssemblyFileVersion` will be set to the `MajorMinorPatch` variable with a appended `.0`.
27-
* `AssemblyInformationalVersion` will be set to the `InformationalVersion` variable.
57+
* `AssemblyFileVersion` will be set to the `MajorMinorPatch` variable with a
58+
* appended `.0`. `AssemblyInformationalVersion` will be set to the
59+
* `InformationalVersion` variable.
2860

29-
### Other injected Variables
61+
#### Other injected Variables
3062

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

33-
```
66+
```c#
3467
namespace AssemblyName
3568
{
3669
[CompilerGenerated]
@@ -44,11 +77,11 @@ namespace AssemblyName
4477
}
4578
```
4679

47-
### Accessing injected Variables
80+
#### Accessing injected Variables
4881

49-
**All variables**
82+
##### All variables
5083

51-
```
84+
```c#
5285
var assemblyName = assembly.GetName().Name;
5386
var gitVersionInformationType = assembly.GetType(assemblyName + ".GitVersionInformation");
5487
var fields = gitVersionInformationType.GetFields();
@@ -59,49 +92,63 @@ foreach (var field in fields)
5992
}
6093
```
6194

62-
**Specific variable**
95+
##### Specific variable
6396

64-
```
97+
```c#
6598
var assemblyName = assembly.GetName().Name;
6699
var gitVersionInformationType = assembly.GetType(assemblyName + ".GitVersionInformation");
67100
var versionField = gitVersionInformationType.GetField("Major");
68101
Trace.WriteLine(versionField.GetValue(null));
69102
```
70103

71-
## Populate some MSBuild properties with version metadata
104+
### Populate some MSBuild properties with version metadata
72105

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

75-
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.
110+
The class for `GitVersionTask.GetVersion` has a property for each variable.
111+
However at MSBuild time these properties are mapped to MSBuild properties that
112+
are prefixed with `GitVersion_`. This prevents conflicts with other properties
113+
in the pipeline.
76114

77-
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.
115+
#### Accessing variable in MSBuild
78116

79-
### Accessing variable in MSBuild
117+
After `GitVersionTask.GetVersion` has executed, the MSBuild properties can be
118+
used in the standard way. For example:
80119

81-
After `GitVersionTask.GetVersion` has executed the properties can be used in the standard way. For example:
82-
83-
<Message Text="GitVersion_InformationalVersion: $(GitVersion_InformationalVersion)"/>
120+
```xml
121+
<Message Text="GitVersion_InformationalVersion: $(GitVersion_InformationalVersion)"/>
122+
```
84123

85-
## Communicate variables to current Build Server
124+
### Communicate variables to current Build Server
86125

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

89-
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).
129+
If, at build time, it is detected that the build is occurring inside a Build
130+
Server then the [variables](../more-info/variables.md) will be written to the
131+
Build Server log in a format that the current Build Server can consume. See
132+
[Build Server Support](../build-server-support/build-server-support.md).
90133

91134
## Conditional control tasks
92135

93-
Properties `WriteVersionInfoToBuildLog`, `UpdateAssemblyInfo` and `GetVersion` are checked before running these tasks.
136+
Properties `WriteVersionInfoToBuildLog`, `UpdateAssemblyInfo` and `GetVersion`
137+
are checked before running these tasks.
94138

95-
If you, eg., want to disable `GitVersionTask.UpdateAssemblyInfo` just define `UpdateAssemblyInfo` to something other than `true` in your MSBuild script, like this:
139+
If you, e.g. want to disable `GitVersionTask.UpdateAssemblyInfo` just define
140+
`UpdateAssemblyInfo` to something other than `true` in your MSBuild script, like
141+
this:
96142

97-
```
98-
<PropertyGroup>
99-
...
100-
<UpdateAssemblyInfo>false</UpdateAssemblyInfo>
101-
...
102-
</PropertyGroup>
143+
```xml
144+
<PropertyGroup>
145+
...
146+
<UpdateAssemblyInfo>false</UpdateAssemblyInfo>
147+
...
148+
</PropertyGroup>
103149
```
104150

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

107-
Set the environmental variables `GITVERSION_REMOTE_USERNAME` and `GITVERSION_REMOTE_PASSWORD` before the build is initiated.
153+
Set the environmental variables `GITVERSION_REMOTE_USERNAME` and
154+
`GITVERSION_REMOTE_PASSWORD` before the build is initiated.

0 commit comments

Comments
 (0)