HgMetal

Automatic versioning of C# .NET assemblies based on Git or Mercurial commits

When you develop something using C#, either applications, shared libraries, ASP.NET websites or something else, most likely you use some Version Control System (ex. Git or Mercurial) to store source code and track changes within it. Your software grows up, new functionality appears, published releases remain on long-term support, and sooner or later you will need to distinguish versions of your software. Also, you may need to tell about backward compatibility and complexity of changes between releases in a simple way without forcing users to seek in release notes. And of course, you need to track those versions in your VCS. Now let's remember the DRY (don't repeat yourself) principle and make Version Control System responsible for the information required for versioning, at the same time automating this process.

HgMetal is licensed under its own License Terms.

How to use HgMetal?

1. Add HgMetal NuGet package to all projects for that you want to add auto-versioning.

2. Add HgMetalInfo.g.cs to your .gitignore or .hgignore file. For example, for Mercurial .hgignore with regular expressions syntax you can use (?i)(?<![^/])hgmetalinfo\.g\.cs$, and Mercurial will ignore any HgMetalInfo.g.cs in any directory.

3. Remove AssemblyVersion-kind attributes from AssemblyInfo.cs and other places and let HgMetal manage version numbers - those attributes will be defined automatically in HgMetalInfo.g.cs files.

   OR

4. Disable generation of AssemblyVersion-kind attributes by adding <HgMetalAssemblyAttributesTemplate>None</HgMetalAssemblyAttributesTemplate> property in *.csproj files and use constants from HgMetalInfo static class in your AssemblyInfo.cs files.

5. Rebuild your projects. You are done - now HgMetal is responsible for assembly version numbers updates.

What's next?

After installation of HgMetal you can:

• configure HgMetal with MSBuild properties;
• bind version numbers to VCS metadata (tags etc);
• choose a suitable version number template;
• compose your own versioning scheme with available fields;
• see examples of using HgMetal in different situations;
• forget about manual version number updating and celebrate it!

Troubleshooting

HgMetal caches obtained version metadata to not perform slow operations with the repository on every build. It invalidates its cache on project file or tip commit changes but sometimes you can encounter the wrong results. In this case, you can try to rebuild your project - HgMetal will delete the old HgMetalInfo.g.cs file and will recalculate its contents.