dotnet/android, and why the version number tracks Android rather than .NET

What this repository is: bindings and tooling, not a framework

The repository description is precise and worth reading closely, because the distinction it draws is the one that determines what you can expect. .NET for Android provides open-source bindings of the Android SDK and tooling for use with .NET managed languages such as C#.

Bindings, not a framework. That means the project exposes the Android SDK to .NET rather than replacing it. When you write against it, the types in your code are the Android types, with .NET conventions layered over them, and the shape of the API you learn is the shape of the Android platform API. There is no separate object model, no cross-platform abstraction, and no set of design decisions that differ from Android's own.

That is a real constraint on how you should evaluate the project, and it cuts both ways. In its favour, documentation and behaviour transfer directly from Android documentation, and there is no second layer of concepts to hold in your head. Against it, a change in the Android SDK shows up in your code as a change in the platform API, and a design decision you would make against a framework is not available to you because there is no framework to decide against.

The tooling is the other half. This is not just a set of type forwards and wrappers; it is the build integration, the packaging into an application package, the resource handling and the deployment pipeline, which is what makes a binding layer usable in practice. The README's stated purpose, bindings and tooling, covers both.

Two facts frame everything else. It is part of .NET MAUI, so its support lifetime follows the MAUI support policy rather than its own. And it may also be used independently for native Android development using .NET, which is the path for a team that wants C# on Android without adopting a cross-platform UI framework. That second option is the more interesting one for a large codebase, because it lets an existing .NET library be reused on Android without the whole application becoming MAUI.

Why it ships as a workload, which is the whole architectural idea

The delivery mechanism is not an implementation detail, and this is the part of the project that most affects your upgrade decisions.

The README says .NET for Android ships as an optional .NET workload for .NET 6 and later, and that it can be updated independently from .NET in order to respond to external dependency updates like a new Android platform and tooling.

Put the two release cadences next to each other. Microsoft's .NET releases on a fixed schedule with a long support window for each major version. Google ships a new Android platform version every year, with new APIs, new build tools and new behaviour changes, on a schedule Microsoft does not control. A binding layer sits directly on top of that second cadence, and its whole job is to be current with it.

Under a conventional model, taking a new Android API level would mean waiting for a .NET version that carried the updated bindings, which would mean waiting for the next .NET release, and then everyone on the previous .NET version would be stuck on an old Android API until they upgraded the runtime as well. The workload model breaks that coupling. The binding layer gets its own version, its own release, and its own update path, so a team can move to a new Android API level without moving its runtime.

The cost of that independence is that you now have two version numbers to reason about, and the second one is not obvious from the repository name. That is what the next section is about, because the release tags encode the Android side of the equation in their most significant digit.

The workload mechanism also has a practical consequence for installation. Workloads are a .NET 6 and later concept, so there is no meaningful way to install this into an earlier runtime, and the earlier product under a different name is a different thing entirely. The README covers that transition, and it is worth reading rather than assuming continuity.

Reading the version number, where 37 is an API level rather than a .NET version

The three most recent tags are the clearest evidence of how this project versions itself, and the format is worth learning before you look at any release.

They are `37.0.0-rc.1.2257` described as .NET 11 RC 1, `37.0.0-preview.7.2131` described as .NET 11 Preview 7, and `37.0.0-preview.6.59` described as .NET 11 Preview 6.

Read the number in four parts. The leading 37 is the Android API level the bindings target, and it is the part that matters to an Android developer. The middle zero tracks the .NET major version, which here is zero because the .NET version is expressed in the suffix instead. The suffix carries the .NET release train, so `rc.1` is the first release candidate of .NET 11 and `preview.7` is the seventh preview. The trailing number is a build counter, and it is scoped to that train rather than running continuously: preview 6 has build 59 and preview 7 has build 2131, so the counter restarted or jumped when the release train advanced.

The practical consequence is that two numbers in one tag are about the runtime and one is about the platform, and the platform one comes first. If you are targeting a specific Android API level, the leading digit is what tells you whether a given build is usable. A build tagged 37 binds an API level your application does not target yet, and a build tagged something lower is the one that matches an older target.

The cadence is visible in the three dates. Preview 6 in July 2026, preview 7 in August, release candidate 1 in September, which is roughly monthly and tracks the .NET release train rather than Android's. That apparent contradiction, Android bindings on a .NET schedule, is resolved by the workload design: the binding layer ships continuously and the release train is just when a particular build is designated as a preview or release candidate for a given .NET version.

So the rule for an operator is simple. Track the leading API level for your target, treat the suffix as informational about the runtime it was built against, and read the release policy rather than the tag list when deciding whether a build is supported.

Installing it, and the Classic Xamarin installers that are still there

Installation is one command, and the README keeps it short on purpose.

dotnet workload install android

The README says that in its simplest form that is the whole install, and points to the .NET workload documentation for additional installation commands and options. That is the correct level of detail for the simple case, and the workload documentation is where the pinning and version-selection questions live.

One line in the downloads section deserves attention because it is the kind of thing that gets deleted. The README says that while no longer supported, Classic Xamarin.Android installers are still available, with a link to a document in the repository's own documentation directory listing previous releases.

Keeping the installers available is a deliberate and unusually considerate decision. The alternative is a dead link and a support burden with no upside, whereas leaving the binaries reachable costs almost nothing and saves anyone with an air-gapped build environment, or with a pinned base image, from a dead end. The link is in the repository rather than on a personal page, which means it survives a change of maintainer.

It is worth being clear about what that link is and is not. Those installers are frozen. They target the final Android and Xcode versions the Xamarin SDKs ever shipped, and they will not receive a fix for anything. They are an exit ramp for reading and building, not a place to stay.

The repository's own documentation directory also holds a build-and-run-from-source page and a development workflow page for people working on the bindings themselves rather than consuming them, which is the standard arrangement for a repository that doubles as a product and a development site.

Xamarin.Android ended on May 1, 2024, with a specific list of final versions

The support section of this README is short, and it is the most consequential part for anyone arriving from Xamarin.

The facts it states are these. Support for Xamarin.Android ended on May 1, 2024, as per the Xamarin Support Policy. .NET for Android is part of .NET MAUI, having been introduced in May 2022 as part of .NET 6, and is currently supported as described in the .NET MAUI Support Policy.

The quoted policy text is more specific than the summary, and the specifics are what a migration plan needs. It says Xamarin support ended on May 1, 2024 for all Xamarin SDKs including Xamarin.Forms, and that Android API 34 and Xcode 15 SDKs, covering iOS and iPadOS 17 and macOS 14, are the final versions Xamarin targets from the existing SDKs, with no new APIs planned.

Three things follow. First, the date is absolute and has passed, so any Xamarin project is now running on an unsupported toolchain by the vendor's own statement. Second, there is a defined ceiling: API 34 for Android and Xcode 15 for Apple platforms, which tells you exactly how far behind the platform you are, and API 34 is a specific number you can compare against your app's target. Third, and most usefully, the ceiling is a fixed target rather than a moving one, which means a migration to .NET for Android is a step change rather than an indefinite chase.

The README points to the official upgrade guidance for bringing Xamarin applications to the latest version of .NET, and that is the right next document. The important thing to carry away is that there is no supported path forward on Xamarin, and the destination is either .NET for Android on its own or .NET MAUI depending on whether you want a cross-platform UI framework.

The support policy links matter for a second reason. Because this repository is part of MAUI, its own support lifetime is the MAUI support policy rather than anything stated here. A team planning a long-lived Android application should read that policy to find out how long the current band is supported, because that is the real constraint and the repository's tag list will not tell them.

Building from source, and a coding standards page older than the product

The contributing section is where a project reveals what it thinks its own standards are, and there is one detail in this repository that is worth more than the rest of the section combined.

The links given are a page on how to build and run from source, a page on the development workflow and using your build, a page on submitting pull requests, and a coding guidelines link. The coding guidelines point goes to a domain under the Mono project.

Mono. The Mono project was the basis on which Xamarin was built, which was in turn the basis on which .NET for Android was built, and the community coding guidelines published by that project are still the standards reference for this codebase. That is a genuine piece of institutional memory: the conventions in the source are the conventions that were established when the code was first written for a runtime that predates .NET entirely, and they have been carried forward rather than reinvented.

It also means a contributor reading the guidelines is reading a document written for a very different ecosystem, and needs to judge which parts still apply. That is a small cost next to the benefit of not having a hundred style disagreements in review, and it is the kind of continuity that is easy to lose and hard to notice is valuable until it is gone.

The other two links describe a workflow most open source projects at this size would not have, which is what a repository that ships a product rather than a library needs. Building from source is not a nice-to-have when the project is itself the thing that produces the workload everyone installs; a developer who cannot build it cannot fix it. The development workflow page exists for the same reason, and its description, that it covers using your build, implies the workflow of pointing a local install at a locally built workload rather than at the released one. That is a two-layer build and a two-layer trust model, and having it documented is what makes a contribution to the bindings themselves practical.

The pull request guidance being in the wiki rather than in the repository is unremarkable and common, and it is the one link in that list whose content is not versioned alongside the code.

dotnet/android against Kotlin, and against plain interop from a shared codebase

Two comparisons, and the honest answer depends on what your organisation already has.

Against writing the Android app in Kotlin, the difference is not language quality. Kotlin is the platform language, it has first-class support in the Android toolchain, and anything you write in it compiles against the SDK without an interop layer. What .NET for Android offers is the ability to share code with an existing .NET codebase: business logic, domain models, networking and data access written once and running on both a server and an Android client.

That shared-code benefit is real and it is the entire argument. It is also bounded, and the bound is worth stating: the sharing works for logic, not for the platform. Your Android UI, your lifecycle handling and your interaction with Android-specific services are still Android code, reached through the bindings. A team that assumes it can share its application layer and find itself rewriting the presentation layer has misjudged the ratio, and the ratio is usually worse than expected for anything with a non-trivial interface.

The alternative that sometimes gets skipped is interop rather than migration. If you have a .NET server and an Android client and you are deciding what to share, a shared library compiled for .NET Standard and consumed from Kotlin is a different architecture from porting the client to .NET. The bindings are irrelevant in that case, because the client is not written in .NET at all, and the only thing you need is a .NET Standard library the JVM side can reference. For a team whose Android app is already written and working, that is usually the cheaper answer, and the .NET for Android workload is not part of it.

The third comparison is with the sibling product. .NET for Android used to be Xamarin.Android, and the two are not the same thing with a new name. One is frozen at API 34 with no future, the other is part of a supported product with an active release train. The README makes the transition unambiguous, which is more than many migrations get.

So the decision is not primarily technical. If your Android client is new and your organisation is a .NET shop, the workload is a reasonable default. If the client already exists in Kotlin, share a .NET Standard library and leave the bindings alone. If you are on Xamarin, the migration is not optional, and the pinned final version tells you exactly what you are leaving behind.

Editorial conclusion

Use .NET for Android if you are building Android from C# and want the SDK bindings to track new platform releases without waiting for a .NET version bump, which is exactly what the workload mechanism provides. Do not treat it as a framework with its own abstractions, because it is bindings plus tooling, and the design surface you depend on is Android's. If you are migrating from Xamarin, check the pinned API level of the workload you install against the API level you build for, because the two move independently. Verify first by running dotnet workload list after installation, confirming the installed version's API level matches your target, and reading the support policy page the README links rather than assuming the project's own cadence covers your release.

Frequently asked questions

Official sources

1. dotnet/android on GitHub
2. Issues
3. License: MIT
4. README
5. Releases