Background
Since my team started to work with Azure DevOps, we've been exploring its potential progressively : Boards, Repos, Pipelines ...
During the first phase we became accustomed to how each of these unitary services work and the entire team now feels confortable with the them.
At this moment, I consider that the team's efficiency is equal to what it was before using Azure except we are using different tools now.
Stopping our exploration there would have been too bad considering the amount of manual labor that can be automated with Azure. Our development process should ideally converge to what is commonly called a "software factory" where most of the steps from code commits to software package delivery are automated.
I am not saying CI/CD here but the philosophy is equivalent. The continuous deployment of our built system is (at the time of writing) incompatible with the business. The packages are deployed manually in production by running an installer from a USB key. There is no automatic update support and the machines connectivity is limited to workshop automation. Not the ideal situation for DevOps but I believe we will get there sooner or later.
Our first step toward continuous deployment is focused on how each of the system components are developped in the team. The source code now resides in Azure Repo but the integrator is still checking-out the code to build the entire solution at once on his computer which means : build scripts to be updated, versions to be bumped and all binaries packed into a single installer. There is no opening for code reusability between teams: our repositories are private and the components are never archived anywhere.
As I used to work with NuGet packages in the past, all my developments are always packed and published to Azure Artifact. These packages are automatically fetched by visual studio at build time and hence, consumed as binaries and not code. My team really wants to do the same but they have limited knowledge with NuGet, pipeline configuration and artifact management. Besides, the integrator complains about the versioning because he's the only one to know how to increment the versions. I seized that opportunity to think about a solution where my team would only focus on code without ever caring about versioning, packing and publishing of the artifact.
Automation stages
Automation = Azure pipeline and the steps listed below will need to be scripted in an azure-pipelines.yml file
Versioning
It is critical to have a consistent versioning strategy among the development team to easily dissociate a major (i.e. breaking) change from a minor (i.e. compatible) by looking at the version. Besides, the version plays a key role in maintainability as it shall point the developers to the right code snapshot in history to fix whatever bug is found on client site.
I have oriented my team to Semantic Versioning 2.0 (SemVer 2) which is compatible with our traditional versioning strategy.
The version is delimited by the classic 3 digits plus additional metadata as shown below.
Major.Minor.Path-PreRelease.Counter+Build
| Part | Reason for change | Nature |
|---|---|---|
| Major | Incompatible changes made to public API | Mandatory version number |
| Minor | New features added but backward compatibility preserved | Mandatory version number |
| Path | Bug fixes with backward compatibility preserved | Mandatory version number |
| PreRelease | Pre-release alphanumeric tag to denote the version | Optional build metadata |
| Counter | Pre-release version counter | Optional build metadata |
| Build | Build alphanumeric tag to denote the version | Optional build metadata |
This versioning pattern is already supported by Azure Artifacts service and NuGet packaging technology since NuGet 4.3.0+ and Visual Studio 2017.
Now that we have the strategy, we have to define how to stamp this version in the binaries.
GitVersion
GitVersion is one of the tools that promises to be an automated SemVer 2.0 versioning system which will generate the right version for your current code depending on the branch you are on and by looking back at the history of the code.
GitVersion comes as a command line tool that can be executed from any git repository. It works out-of-the-box with GitHubFlow and GitFlow branching strategies and will generate a version without ever modifying the code. The version can then be published as an environment variable or injected into AssemblyInfo.
Below is an overview of the versions generated by GitVersion with the default configuration.
On this diagram, each arrow represents a branching or merging operation. The black labels show the version that is returned by GitVersion when executed from each branch.
Here are the default metadata settings built into GitVersion.
| master | hotfix | releases | dev | features | |
|---|---|---|---|---|---|
| Versioning rule | Last tag used as base version | Patch incremented on creation | Branch name used as next version | Minor incremented when merging from master or release branch | |
| PreRelease | beta | beta | alpha | branch name | |
| Counter | Incremented and reset automatically by gitversion based on the references of a branch. Will keep incrementing until a higher digit gets incremented. | ||||
| Build | Incremented on each commit since last tag | ||||
Note: To be used in .NET projects, the attributes AssemblyVersion and AssemblyFileVersion shall be deleted from AssemblyInfo and a dependency shall be added to GitVersionTask package.
Build and unit tests
Nothing special to be said on that part.
My team was already using pipelines with that setup and nothing needs to be modified for continuous package delivery.
Pack
GitVersion published multiple versions as environment variables. The output usually looks like this when printed in a json format:
{
"Major":2,
"Minor":3,
"Patch":0,
"PreReleaseTag":"alpha.2",
"PreReleaseTagWithDash":"-alpha.2",
"PreReleaseLabel":"alpha",
"PreReleaseNumber":2,
"WeightedPreReleaseNumber":2,
"BuildMetaData":"",
"BuildMetaDataPadded":"",
"FullBuildMetaData":"Branch.dev.Sha.b5753b8ab047485908674e7a0c956009abff5528",
"MajorMinorPatch":"2.3.0",
"SemVer":"2.3.0-alpha.2",
"LegacySemVer":"2.3.0-alpha2",
"LegacySemVerPadded":"2.3.0-alpha0002",
"AssemblySemVer":"2.3.0.0",
"AssemblySemFileVer":"2.3.0.0",
"FullSemVer":"2.3.0-alpha.2",
"InformationalVersion":"2.3.0-alpha.2+Branch.dev.Sha.b5753b8ab047485908674e7a0c956009abff5528",
"BranchName":"dev",
"Sha":"b5753b8ab047485908674e7a0c956009abff5528",
"ShortSha":"b5753b8",
"NuGetVersionV2":"2.3.0-alpha0002",
"NuGetVersion":"2.3.0-alpha0002",
"NuGetPreReleaseTagV2":"alpha0002",
"NuGetPreReleaseTag":"alpha0002",
"VersionSourceSha":"0f42b52188fcda73f3e407063db85695ce4ace1a",
"CommitsSinceVersionSource":2,
"CommitsSinceVersionSourcePadded":"0002",
"CommitDate":"2020-02-28"
}
There is a version string especially dedicated to NuGet packages : NuGetVersion. So all there is to do here is to inject that value into the packing task :
# Package assemblies
- task: NuGetCommand@2
displayName: 'Packaging the artifact'
inputs:
command: 'pack'
packagesToPack: '**/*.csproj;!**/*Tests.csproj'
versioningScheme: 'byEnvVar'
versionEnvVar: GitVersion.NuGetVersion
includeReferencedProjects: true
configuration: 'Release'
Publish
When a build completes, the created package will reside in what Azure defines as the staging directory, which is where the repository has been cloned for the build. This location is not accessible and if the team wants to share the package within the organization, they have to publish the artifact.
In Azure, the artifacts are stored in Feeds. A Feed is a repository for specific types of packages (npm, pypi, NuGet,…). All teams in Azure are free to create one or several Feeds depending on their needs.
Each Feed can have several Views. A View acts as an overlay of the Feed and is intended to filter the content. This concept has been originally introduced to defined several stages before releasing an artifact. By default, each Feed comes with 3 Views : @Local, @PreRelease and @Release, which store respectively development, release candidates and production artifacts. The diagram below summarizes these concepts.
By default, all packages are published into @Local. This View shall only be visible by developers to avoid interlocks during development.
When a release candidate is ready, the integrator shall promote the package from @Local to @PreRelease. The package becomes visible to the testers for verification and validation.
When a package is finally validated, the integrator will generate a new package that he will promote to @Release. The package becomes visible to all stakeholders within the organization.
Each Feed can define a maximum retention time for the package it stores. When the delay expires, the package is deleted. This retention delay is only applied to @Local and promoted packages won't be deleted by the defined policy.
It is up to each team to configure the permission levels for each view.
After configuring our Azure Artifact feed with the proper permission levels and retention time, we were ready to rollout the first automated package publication.
It worked as expected for the test project. One of my input requirements was that my team needs to focus on code only which means that they should never configure the pipeline for their project. As the pipeline configuration file stands in the project repository, I looked for a way of reusing existing pipeline configuration files ...
Pipeline template
Since December 2019, Azure supports templating with the reuse of pipeline config files located in external repositories. My team and I arrived just in time ! :)
Below is the template that I have pushed to a 'TeamProcess' repository:
# File : base-netfull-pipeline.yml # # Azure pipeline configuration to build .NET Framework projects and publish # them as NuGet artifacts into GF.MS.LAS.Machine Azure feed parameters: # Solution path in repository - name: 'solution' default: '**/*.sln' type: string # Target build platform - name: 'buildPlatform' default: 'Any CPU' type: string # Build configuration - name: 'buildConfiguration' default: 'Release' type: string # Build virtual image - name: 'vmImage' default: 'windows-latest' type: string # Source feed - name: 'feed' default: '7ea4c5d0-fe57-441e-9fac-f026c9bb1207' type: string # Packages to pack - name: 'packagesToPack' default: '**/*.csproj;!**/*Tests.csproj' type: string # Packages to push - name: 'packagesToPush' default: '$(Build.ArtifactStagingDirectory)/**/*.nupkg;!$(Build.ArtifactStagingDirectory)/**/*.symbols.nupkg' type: string # Does NuGet shall include all dependencies as reference package and/or dlls in the artifact ? - name: packageAddReferences type: boolean default: true jobs: - job: Build pool: vmImage: ${{ parameters.vmImage }} steps: # Install NuGet utility - task: NuGetToolInstaller@1 displayName: 'Installing NuGet utility' # Generate SemVer version - task: DotNetCoreCLI@2 displayName: 'Install gitversion' inputs: command: 'custom' custom: 'tool' arguments: 'install -g gitversion.tool' - task: DotNetCoreCLI@2 displayName: 'Gitversion setup' inputs: command: 'custom' custom: 'gitversion' arguments: '/output buildserver' # Restore project dependencies - task: NuGetCommand@2 displayName: 'Restoring dependencies of the package' inputs: command: 'restore' restoreSolution: '${{ parameters.solution }}' feedsToUse: 'select' vstsFeed: '${{ parameters.feed }}' # Build - task: VSBuild@1 displayName: 'Building solution' inputs: solution: '${{ parameters.solution }}' platform: '${{ parameters.buildPlatform }}' configuration: '${{ parameters.buildConfiguration }}' # Execute unit tests - task: VSTest@2 displayName: 'Executing unit tests' inputs: platform: '${{ parameters.buildPlatform }}' configuration: '${{ parameters.buildConfiguration }}' # Package assemblies - task: NuGetCommand@2 displayName: 'Packaging the artifact' inputs: command: 'pack' packagesToPack: '${{ parameters.packagesToPack }}' versioningScheme: 'byEnvVar' versionEnvVar: GitVersion.NuGetVersion includeReferencedProjects: ${{ parameters.packageAddReferences }} configuration: '${{ parameters.buildConfiguration }}' # Publish assemblies - task: NuGetCommand@2 displayName: 'Publishing the artifact to feed' inputs: command: 'push' packagesToPush: '${{ parameters.packagesToPush }}' nuGetFeedType: 'internal' publishVstsFeed: '${{ parameters.feed }}'To reuse this template, a project will create its own azure-pipelines.yml file with the following content:
# File: azure-pipelines.yml resources: repositories: - repository: templates type: git name: TeamProcess # Template reference jobs: - template: Process/Pipelines/net/base-netfull-pipeline.yml@templates
Conclusion
With a few days invested in reading msdn and other literature about the setup of Azure, I managed to achieve the creation of a fully automated NuGet package continuous delivery flow. The automatic versioning of the code is something I never thought of in the past but it is a real game changer. Without it, creating this delivery flow would have been trickier with additional scripting and/or code commits prior to build. The only difficulty I face was related to GitVersion add-on(s) in Azure. Many of them co-exist in the marketplace and it's really confusing. My recommendation is to used DotNetCLI instead which is a robust workaround to the add-on.
