How to Upgrade ASP.NET Zero: Branch Strategy, Conflict Checklist, and .NET 10

How to upgrade ASP.NET Zero is a search people type after a package scare, a new hire who cannot restore the solution, or a backlog ticket that has slid three releases. Official docs are honest: ASP.NET Zero is a startup template. ASP.NET Zero upgrade is not automatic. You overlay a clean template on an aspnetzero branch and merge. Conflicts are expected.

This guide is for license holders and tech leads who need a walkthrough they can paste into a ticket. You will get the new-project vs existing-project paths, a conflict checklist, what ASP.NET Zero v15 actually changed (.NET 10, ABP 11), and when MVC-to-Angular is a different job than a version bump.

We do this as a service: Code Migration and Framework Upgradation. You still own the code. The point of this post is so Thursday-you stops treating the merge as a weekend hobby.

Key takeaways

• Zero is a template. You merge a new generated tree. That is the official path on Version Updating.
• Keep a clean aspnetzero branch. Never develop custom features on it.
• Existing apps that never kept that branch need more work: recreate the starting version, copy custom code onto a migrate branch, fight conflicts by hand.
• ASP.NET Zero v15.0 (December 2025) moved the stack to .NET 10 and ABP 11. Waiting adds your features on top of theirs. The diff grows.
• Do not mix an MVC-to-Angular rewrite and a version bump in the same panic sprint.

Why an ASP.NET Zero version update is not NuGet

ABP / module packages can move on NuGet. The Zero template (UI, AppServices, Power Tools output you customized) does not.

Volosoft’s own support threads repeat the same sentence: there is no simpler way. If your aspnetzero overlay is clean, a merge can be hours. If you skipped the branch for years, it is a project.

Check AppVersionHelper (usually *.Core/AppVersionHelper.cs). Write the from-version and the to-version in the ticket before anyone opens Visual Studio.

Path A: new projects (keep the overlay branch)

Use this if you set the repo up the way the docs describe.

1. Private git repo (license rule).
2. dev (or main) for your product.
3. aspnetzero branched from the clean template. No custom commits except overwriting with a new download.
4. Download the new Zero version from aspnetzero.com (same project name, same UI option).
5. Check out aspnetzero, overwrite files, commit, tag (aspnetzero-v15.4 or whatever you landed on).
6. Merge aspnetzero into dev. Resolve conflicts in dev.
7. Smoke tenant login, permissions, and one real AppService write.

That loop is how you upgrade ASP.NET Zero for the rest of the product’s life.

Path B: existing projects (rebuild the branch dance)

Use this if you never kept a clean overlay.

Official existing-project steps, compressed:

1. Note the version in AppVersionHelper (the version you started on, if you still know it).
2. Create a new private repo.
3. Generate a clean Zero project at that starting version, same name.
4. Push as master, branch dev, then branch aspnetzero and migrate from dev.
5. Copy your real codebase onto migrate.
6. Merge migrate into dev and resolve conflicts. You now have a repo that looks like Path A.
7. From there, overlay the target version on aspnetzero and merge into dev as in Path A.

Support thread #12472 walks the same idea for 13.2 → 14.1. The painful part is not git theory. It is a year of custom Metronic, Power Tools entities, and tenant rules versus a year of template changes.

File-scoped vs block-scoped namespaces (called out on the 14.1 merge) will inflate conflict counts if your tooling cannot normalize style first. Run IDE cleanup on one side before you merge, or you will fight formatting, not features.

What changed in v15 / .NET 10

ASP.NET Zero v15.0 (December 2025) moved the line to .NET 10 and ABP 11. Later 2026 releases (through 15.4 in July) kept stacking Angular, Mapperly, health UI, and package bumps.

If you are still on MVC + jQuery Zero, or an old AngularJS line, you are not one version behind. You are a migration. ASP.NET Zero .NET 10 is the current Core line. Microsoft’s support clocks on the underlying .NET version do not care that your product owner is busy.

Conflict and smoke-test checklist

Paste this into the ticket.

Before merge	During merge	After merge
From-version and to-version written down	Resolve conflicts in dev only	Tenant login works
Freeze non-urgent features	Do not “fix” tenancy in a god account	Permission grants still hold
aspnetzero is a clean overlay	Budget conflict days; believe the docs	Hosting and CI know the target TFM
Backup / tag current dev		One real AppService write succeeds
		Logs show the new AppVersionHelper

Pretty UI is not the test. A compile is not the test.

Upgrade vs migrate ASP.NET MVC to Angular

How to upgrade ASP.NET Zero (version-to-version on the same UI line) and migrate ASP.NET MVC to Angular are different jobs.

Our service page lists both, plus legacy .NET onto Zero, and AngularJS 1.x onto modern Angular. Mixing them in one panic sprint is how you get neither.

Stay on the jQuery line only if you accept that major features now land on Core + jQuery / Angular first. Do not hide a stack change inside “update the packages.”

We will not quote a fake “two-week upgrade for every app.” Size depends on how far you drifted.

Frequently Asked Questions

How do you upgrade ASP.NET Zero in one sentence?

Download a clean template, commit it on aspnetzero, merge into dev, resolve conflicts, smoke tenant login and one write.

Is an ASP.NET Zero upgrade just updating NuGet?

No. NuGet moves ABP libraries. The template is a merge.

Can we jump many versions at once?

Sometimes. It is usually uglier. A stepping-stone version can be cheaper if namespace and UI churn exploded in between (see the 14.1 file-scoped namespace pain).

We are on MVC and jQuery. Is that an upgrade or a rewrite?

It is a stack change if you want Angular. It is a version merge if you stay on the jQuery template. Name which one you are buying.

Do we need a dedicated team?

Not always. Someone who has done Zero merges, plus your people who know the domain, beats a generalist who has never seen ABP tenancy.

Conclusion

How to upgrade ASP.NET Zero gets worse in the drawer. Put the from-version and to-version in a ticket this week. Freeze a slice of features. Merge on purpose, not after the next CVE.

If you want help, that is one of our four services. If you want to do it in-house, use the official branch dance and budget the conflicts. Either way, stop pretending it is a Friday.

Sources: ASP.NET Zero, Version updating accessed 2026-08-31; ASP.NET Zero, Introducing v15 accessed 2026-08-31; ASP.NET Zero change logs accessed 2026-08-31; ASP.NET Zero Support, Upgrading from 13.2 to 14.1 accessed 2026-08-31.