Skip to content
  • English Deutsch

benjamin-abt.com

Performance is a feature | Cloud - AI - Azure - .NET - Sustainability

  • Home
  • Blog
  • Portfolio
    • Overview
    • Workshops & Training
    • Publications
  • Contact
  • Home
  • Blog
  • Modern versioning for ASP.NET Core and web apps and how to produce idempotent artifacts

Modern versioning for ASP.NET Core and web apps and how to produce idempotent artifacts

Modern versioning for ASP.NET Core and web apps and how to produce idempotent artifacts
July 3, 2026 7 min read BEN ABT
C# .NET ASP.NET Core DevOps

ASP.NET Core applications are usually released often enough that versioning stops being a documentation concern and turns into delivery infrastructure. Once an application moves through CI, staging, production, containers, rollback procedures and incident response, the version number is no longer just a label. It becomes part of the operational model.

That changes the real question. It is not mainly whether a release should be called 6.4.0. The more important question is whether the identity of that release survives intact from Git commit to published output, deployment artifact and running process. If those layers disagree, a rollout may still succeed, but understanding the system later becomes needlessly expensive.

If the repository still lives on duplicated AssemblyInfo.cs values, wildcard auto increment or a public x.x.x.x release contract, start with How to migrate .NET versioning from x.x.x.x to SemVer . This article assumes that baseline is already in place and focuses only on the web-specific part afterwards: published output, artifact promotion and runtime-visible build identity. For Windows executables, installers and MSIX-specific constraints, the companion article Modern versioning for .NET desktop apps and how to produce idempotent artifacts covers the desktop side.

For ASP.NET Core, a useful versioning strategy therefore has to do two things at once:

  • express release intent clearly
  • produce artifacts that remain traceable as they move through environments

Nerdbank.GitVersioning is a strong fit because it anchors build identity in Git history while integrating directly into the .NET build.

Web delivery has more than one version surface

An ASP.NET Core application usually participates in several overlapping version conversations:

  • product release version
  • deployment artifact version
  • API compatibility version
  • database rollout compatibility
  • static-asset cache identity
  • container image tag

Those are related, but they are not interchangeable.

An API might ship product version 6.4.0 while still exposing v1 and v2 routes. Static assets may be cache-busted with hashes. A staged schema change may require temporary compatibility across two adjacent application versions. This is exactly why web versioning becomes brittle when the repository tries to express everything through one manually edited string.

Git should own version identity, not the pipeline

One of the most common failure patterns in web delivery is that the CI system quietly becomes the real source of version truth. A pipeline run number gets appended, a branch name is parsed, a tag may or may not be present and a build emits something that looks version-like.

That works right up to the point when the same commit has to be rebuilt, a release branch changes shape or a hotfix comes from a different line. At that point the version turns out to describe pipeline circumstances more than source state.

Git-aware versioning is stronger because it derives identity from the repository itself. That means the same commit can be traced consistently even when builds run on different agents or at different times. In web systems, where debugging often depends on exact source-to-runtime traceability, that is a significant operational improvement.

The baseline release policy becomes operational during publish

The migration article covers how NBGV is introduced, why Git has to own version identity and what belongs in version.json. Once that baseline exists, the web-specific concern is how published artifacts opt into clean public release formatting without losing internal traceability.

In practice, publicReleaseRefSpec in version.json defines when public formatting should apply and many teams make that explicit during publish:

PowerShell
dotnet publish -c Release -p:PublicRelease=true

That keeps commit-rich internal builds available where they help, while ensuring the formal deployment artifact is emitted in the representation that downstream tooling and operators expect.

Auto increment should follow repository history

Web systems still benefit from auto increment. The weak version of that idea is build-based incrementing, where every CI execution nudges a number forward. The stronger version is repository-based incrementing, where the version moves because source history moved.

That is the model NBGV provides. The declared release line stays stable in version.json, while Git history supplies version height and traceability. That makes the computed version meaningful in ways a pipeline counter never really is.

It also helps separate internal and public output. Internal builds often need commit-rich metadata. Public artifacts usually need a cleaner representation. NBGV supports that split through publicReleaseRefSpec and, when necessary, explicitly through the build property:

PowerShell
dotnet publish -c Release -p:PublicRelease=true

Stable artifact identity starts before deployment

The most important rule in ASP.NET Core delivery is still simple: build once, promote many.

That rule only works when the artifact itself has a trustworthy identity. If the application is rebuilt for each environment, the version number may remain similar while the actual payload changes. At that point the release process has already lost its strongest guarantee.

This matters regardless of packaging format:

  • publish directory zipped for deployment
  • App Service package
  • container image
  • Kubernetes deployment artifact

The shape can change. The requirement does not.

Deterministic publish output depends on more than compilation

It is common to discuss determinism as if it only concerned the compiler. For web applications, dotnet publish depends on more than that:

  • selected SDK
  • restored dependency graph
  • publish settings
  • static-asset manifests
  • packaging or containerization steps

That is why global.json belongs in the repository:

JSON
1{
2  "sdk": {
3    "version": "10.0.100"
4  }
5}

Without an SDK pin, rebuilding the same commit months later may produce different publish output simply because the agent moved to another feature band.

Runtime configuration must stay outside the artifact

Immutable artifacts only remain useful if the deployment model avoids environment-specific rebuilds. In ASP.NET Core that usually means configuration stays external and is injected at runtime instead of being baked into the compiled output.

That separation is easy to state and surprisingly easy to violate. The artifact needs to be the same in test, staging and production, with only configuration changing around it.

At the application level that means relying on the normal configuration stack rather than compile-time customization per environment:

C#
 1using Microsoft.AspNetCore.Builder;
 2using Microsoft.Extensions.Configuration;
 3using Microsoft.Extensions.DependencyInjection;
 4using Microsoft.Extensions.Hosting;
 5
 6WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
 7
 8builder.Configuration.AddEnvironmentVariables();
 9builder.Services.AddControllers();
10
11WebApplication app = builder.Build();
12
13if (app.Environment.IsDevelopment())
14{
15    app.UseDeveloperExceptionPage();
16}
17
18app.UseAuthorization();
19app.MapControllers();
20app.Run();

The principle is more important than the exact snippet: the runtime host supplies environment-specific behavior, not a fresh compilation.

Version reporting should be available from the running process

Deployment dashboards are useful, but they are not always enough during an incident. A running ASP.NET Core application should be able to report its own stamped identity.

NBGV’s generated ThisAssembly class makes that easy:

C#
 1WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
 2WebApplication app = builder.Build();
 3
 4app.MapGet("/version", () =>
 5{
 6    VersionResponse response = new VersionResponse(
 7        ThisAssembly.AssemblyInformationalVersion,
 8        ThisAssembly.AssemblyFileVersion,
 9        ThisAssembly.AssemblyVersion);
10
11    return Results.Ok(response);
12});
13
14app.Run();
15
16public sealed record VersionResponse(
17    string InformationalVersion,
18    string FileVersion,
19    string AssemblyVersion);

The endpoint itself is intentionally small. What matters is that the response comes from build-stamped metadata and not from a duplicated configuration value.

Monorepos benefit from pathFilters

Many ASP.NET Core repositories are not single-product repositories anymore. They may include APIs, workers, frontend assets, shared libraries and infrastructure code. In that layout, not every commit should advance every deployable unit.

pathFilters helps keep version height tied to relevant changes. A documentation-only commit or a frontend-only adjustment does not have to affect the identity of a backend API artifact. That keeps version numbers informative instead of merely busy.

The common failure modes are usually release-discipline problems

The most expensive versioning issues in web apps are rarely exotic MSBuild bugs. More often they come from weak release habits:

  • rebuilding the same commit separately for each environment
  • treating latest as the only meaningful container tag
  • exposing no runtime-visible build identity
  • letting pipeline run numbers define public versions
  • pretending API version, product release and artifact identity are the same thing

NBGV does not solve those problems by magic, but it removes one of the main reasons they persist: a missing source of truth.

Conclusion

Good ASP.NET Core versioning is ultimately about preserving identity from source control to runtime. The commit, the build output, the deployment artifact and the running process should all tell the same story.

That is where NBGV earns its place. It gives the repository a practical workflow through nbgv, stamps build output directly and keeps release behavior in version.json instead of scattering it across pipelines and tribal memory. Combined with pinned SDKs and a build-once-promote-many deployment model, that produces web artifacts that are easier to trust under pressure.

Related articles

Managed Identity in .NET: Stop Using Connection Strings

Nov 17, 2026 - 12 min read

Managed Identity in .NET: Stop Using Connection Strings

A credential-bearing connection string makes the first Azure request easy and every later security task harder. The same account key or …

Production Rate Limiting in ASP.NET Core

Nov 3, 2026 - 16 min read

Production Rate Limiting in ASP.NET Core

Most ASP.NET Core rate-limiting examples stop after registering a fixed window. That is enough to demonstrate the middleware, but it is not …

Problem Details in ASP.NET Core and .NET 11

Oct 5, 2026 - 12 min read

Problem Details in ASP.NET Core and .NET 11

builder.Services.AddProblemDetails() registers infrastructure. It does not create an error contract. An ASP.NET Core request can fail during …


BEN ABT

BEN ABT

Ben is Chief Engineering Officer and Principal Software Engineer at Medialesson.de, with a strong focus on .NET and Microsoft Azure. In his professional role, he designs and builds highly scalable platforms for hybrid and cloud-based scenarios. He also advises companies and C-levels on migrating to the sovereign cloud.

He runs myCSharp.de, the largest and most active German-speaking C# community forum, actively contributes to both his own and external open-source projects and regularly shares his knowledge through his blog, at community events, conferences and as a writer for technical magazines.

Let's Work Together

Looking for an experienced Platform Architect or Engineer for your next project? Whether it's cloud migration, platform modernization or building new solutions from scratch - I'm here to help you succeed.

New Platforms

Modernization

Training & Consulting

Contact Me
X Facebook LinkedIn WhatsApp
Back Next Blog Post

Open for work!

Contact Me
BEN ABT BEN ABT Software Engineer · Microsoft MVP Passionate about .NET, Azure, performance optimization and sustainable software engineering.

Medialesson GmbH Logo

Microsoft MVP Logo

Recent posts

View all
NuGet Staged Publishing with .NET 11 and GitHub Actions

NuGet Staged Publishing with .NET 11 and GitHub Actions

Nov 18, 2026
Managed Identity in .NET: Stop Using Connection Strings

Managed Identity in .NET: Stop Using Connection Strings

Nov 17, 2026
Automating Microsoft Entra External ID: CIAM Provisioning and Branding

Automating Microsoft Entra External ID: CIAM Provisioning …

Nov 10, 2026
Production Rate Limiting in ASP.NET Core

Production Rate Limiting in ASP.NET Core

Nov 3, 2026
The Big Decimal Bugfix with .NET 11

The Big Decimal Bugfix with .NET 11

Nov 2, 2026

Tags

.NET (197) C# (102) ASP.NET Core (50) Azure (43) DevOps (17) Docker (15) Microsoft (14) Security (14) EF Core (11) Microsoft MVP (11) AI (10) GitHub (10) GitHub Copilot (10) Architecture (9) ASP.NET (9) Synology (9) .NET 11 (8) Raspberry (8) Azure Functions (7) Cloudflare (7)
benjamin-abt.com

About BEN

Benjamin Abt is a Software Engineer, Platform Architect and Microsoft MVP specializing in .NET, Azure, cloud architecture, performance optimization and sustainable software development.

Connect

  • Follow me on GitHub
  • Follow me on LinkedIn
  • Follow me on Mastodon
  • Microsoft MVP profile
  • Follow SchwabenCode on GitHub
  • Follow me on X

Quick Links

  • Portfolio
  • Blog
  • Workshops & Training
  • Publications
  • Get in Touch
  • Sitemap
Open for Work

© Copyright Benjamin Abt & SchwabenCode | 2011 - 2026

Content licensed under CC BY 4.0 unless otherwise noted.

  • Impressum
  • Privacy
  • Contact