A version number consists of four parts separated by the '.' character. The four parts are:
- Major Version
- Minor Version
- Build Number
For example: 126.96.36.199 or 1.07.0345.6789
Each part of the version number has it's own rule and each rule part is also separated by the '.' character.
Rule parts are made up of predefined tags that are used to update the related version number part.
The available rule parts are:
* - leave the version number part unchanged
+ - increment the version number by one
Y - the current year (minus 2000; i.e. 2008 returns 8)
YY - same as Y except returns two characters
YYYY - returns four digit year
M - current month
MM - current month (two characters)
D - current day of month
DD - two character day of month
h - current hour
hh - current hour (two characters)
m - current minute
mm - current minute (two characters)
s - current second
ss - current second (two characters)
YYMM - two digit year and two digit month
MMDD - two digit month and two digit day
DDhh - two digit day and two digit hour
hhmm - two digit hour and two digit minute
mmss - two digit minute and two digit second
hhmmss - two digit hour, two digit minute, and two digit second
nY - number of years from the given date (default of 1/1/2000)
nM - number of months from the given date (default of 1/1/2000)
nW - number of weeks from the given date (default of 1/1/2000)
nD - number of days from the given date (default of 1/1/2000)
Note: date parts are upper-case and time parts are lower-case.
Specifying rule part length
A rule part can have a length specifier appended to force the rule part to have a minimum number of characters. The lenght specifier takes the form ":n" where n is the desired minimum length. If the resulting number is longer than the length specified, the result is NOT truncated.
M:2 - returns a two digit month with a leading zero if required 02 for February, etc.
nW:4 - returns the number of weeks from the given date (default of 1/1/2000)
Rules can be combiled with the ";" character to create composite rules.
h:2;m:2 - returns four characters; two for the hour and two for the minute (same as hhmm)
Creating the rule
Now that you know what a rule is made of, it might be nice to actually create one.
On the same line as the version you want to apply the rule to, append a comment in the following format:
[assembly: AssemblyVersion("1.00.0806.0007")] // Rule: *.*.YYMM.+
[assembly: AssemblyFileVersion("1.08.0627.1857")] // Rule: *.YY.MMDD.hhmm
<assembly: AssemblyVersion("1.00.0806.0007")> ' Rule: *.*.YYMM.+
<assembly: AssemblyFileVersion("1.08.0627.1857")> ' Rule: *.YY.MMDD.hhmm
Notice that the AssemblyVersion and the AssemblyFileVersion each have their own rule.
Specifying the base date
The default date (1/1/2000) used in calculations can be overridden with any date of your choosing. One option is to use the date that the project was started so that the rules such as "nD" will calculate from the project start date.
To specify a custom start date, add a StartDate: entry to the rule comment like this:
[assembly: AssemblyVersion("1.00.0806.0007")] // Rule: *.*.YYMM.+ StartDate: 1/1/2008
[assembly: AssemblyFileVersion("1.08.0627.1857")] // Rule: *.YY.MMDD.hhmm StartDate: 1/1/2008
<assembly: AssemblyVersion("1.00.0806.0007")> ' Rule: *.*.YYMM.+ StartDate: 1/1/2008
<assembly: AssemblyFileVersion("1.08.0627.1857")> ' Rule: *.YY.MMDD.hhmm StartDate: 1/1/2008
AssemblyVersion and the AssemblyFileVersion can have different dates specified if desired.
Any rule part that generates a number greater than 65535 will cause the build to be cancelled.
An error message will be written to the output window and an entry added to the error list window.
If you want to know why I'm doing this, see here.
You can now specify a global rule that will apply to all projects by editing the entries
in the EnvironmenEvents macro file.
Dim assemblyVersionRule As String = String.Empty ' replace with your rule; default is "*.*.*.+"
Dim assemblyFileVersionRule As String = String.Empty ' replace with your rule; default is "*.*.*.+"
The global rule will apply to all projects that do not have their own rule specified. Rules defined
at the project leve take precedence.
Lagging Version Numbers (HACK)
Since it appears that VS caches a copy of the AssemblyInfo file before the BuildEvents_OnBuildProjConfigBegin
event is triggered, the version assigned to the compiled output lags behind the version in the
AssemblyInfo file. If you are not using date/time rules, you may not care about this issue.
However, it may cause a problem for some people especially with date/time rules.
The workaround i have in place is to respone to the BuildEvents_OnBuildBegin event and process
all projects in the solution. This works fine for me, but it does mean that if you want to
build a single project in the solution, all projects will be processed by the version number
macro. Any projects that have modified files will get a new version number generated.
You can choose which method you prefer by editing the EnvironmentEvents macro file.