Xcode 26.6 Support

[dalexsoto]

Summary

Apple has shipped Xcode 26.6, but just like with Xcode 26.3 — the underlying SDK did not change. Xcode 26.6 ships the exact same iOS/tvOS/macOS/Mac Catalyst SDK (26.5) that we already support; the differences are in Xcode itself, not in the platform APIs.

Because there are no new APIs to bind, our most recent release already works with Xcode 26.6. The only thing standing in the way is the Xcode version validation we run at build time.

What you'll see

If you install Xcode 26.6 while using the currently released workloads, you'll get a build error similar to:

This version of .NET for iOS (26.5.10284) requires Xcode 26.5. The current version of Xcode is 26.6. Either install Xcode 26.5, or use a different version of .NET for iOS. See https://aka.ms/xcode-requirement for more information.

Recommended: install Xcode 26.5

The safest and fully and supported approach is to install Xcode 26.5, this is the version that matches the currently released workloads and build against it. You can keep Xcode 26.6 installed at the same time; multiple Xcode versions can coexist on the same machine, so there's no need to uninstall 26.6.

See Installing multiple versions of Xcode for the full step-by-step instructions. In short:

• Download the Xcode 26.5 .xip from the Apple Developer Downloads site.
• Extract it, rename the app to something descriptive (for example Xcode_26.5.app), and move it to /Applications/.
• Select it with xcode-select -s /Applications/Xcode_26.5.app (or the DEVELOPER_DIR environment variable, or your IDE's Apple SDK location setting).

This keeps you on a supported configuration and requires no changes to your project.

Alternative: skip the version check

If you'd rather stay on Xcode 26.6, you can skip the version check by setting the ValidateXcodeVersion property to false. This works for any Xcode version, it simply disables the validation:

<PropertyGroup>
  <ValidateXcodeVersion>false</ValidateXcodeVersion>
</PropertyGroup>

Once the check is disabled, projects should build just fine against Xcode 26.6, because the SDK is the same one our 26.5 workloads were built and tested against.

Important

Treat this as a temporary, local unblock, not a permanent setting. Plan to remove it once a workload that officially supports Xcode 26.6 is released.

Is it safe to use a "mismatched" Xcode?

• Using a version of Xcode that doesn't match the workload is not an officially supported configuration, even when it builds with no errors or warnings.
• That said, the impact of a mismatch depends entirely on the differences between the two Xcode versions, and that's impossible to predict in advance. In this specific case the SDK is identical to 26.5, so there is effectively nothing different for the build to trip over.
• Historically, a mismatched Xcode has only ever caused strange build failures, not an app that builds successfully but then misbehaves at runtime. If it builds, it's very unlikely to be subtly broken.

Why does the validation exist at all?

The only supported scenario is using a version of the workload that matches the installed version of Xcode. We enforce that because the matrix of "workload version × Xcode version" combinations grows very quickly, and validating/supporting every combination would consume time we'd rather spend on actual platform work. The check is intentionally strict so that unsupported combinations fail fast and visibly instead of producing hard-to-diagnose problems.

Recommendations

• Disable automatic updates in the macOS App Store so Xcode doesn't silently auto-update out from under your installed workload (https://aka.ms/xcode-requirement).
• Keep multiple Xcode versions installed side by side and select the one matching your workload (via xcode-select -s, the DEVELOPER_DIR environment variable, or your IDE's Apple SDK location setting) when you need to.
• CI / hosted agents: if you rely on Microsoft-hosted or other managed macOS agents, watch for the image moving to Xcode 26.6; pin the Xcode version your build expects until the matching workload ships.

---

Release Check List

This is a checklist for what to do for every release.

Copy this list into a new issue and then check off as the release progresses.

✅ Checklist

Xcode 26.6

• Create new milestone in GitHub.
• Create a new issue with a copy of this list, assign it to the milestone.

RC

• Update binding status in wiki (read instructions in the Makefile in the wiki's git repository)
• Create a new xcodeX[.Y] branch - this needs deciding where to branch from (which is outside the scope of this document). Push this branch to origin with no changes.
• Create PR with an Xcode bump. -> [xcode26.6] Bump to Xcode 26.6 Release Candidate #25659
  • Update the following values in Make.versions:
    • *_NUGET_OS_VERSION
  • Update the following values in Make.config:
    • XCODE_VERSION
    • XCODE_URL
    • XCODE_DEVELOPER_ROOT
  • Update the xcodeChannel value in tools/devops/automation/templates/variables/common.yml. Change to Beta if using an Xcode beta or release candidate, and switch back to Stable with the final (stable) Xcode release.
  • Add the new OS versions to the builds/Version-*.plist.in files.
  • Build and fix any issues.
  • Run the following tests locally, and fix any issues (these are the ones that typically fail in Xcode bumps, but there may be other failing tests as well - CI will report any such failures once the PR is created):
    • xtro
    • monotouch-test
    • introspection
    • cecil
    • bgen
• Bind APIs!

Pre-release process

This happens after the stable version of Xcode has been released and the xcodeX[.Y] branch has been updated according to the previous section(s).

• Make sure all the PRs targeting the xcodeX[.Y] branch have been merged and no more changes are desired for the release.
• Merge the xcodeX[.Y] branch into main.
• Merge main into the target release branch (for instance this was release/9.0.1xx for the Xcode 16.4 release).
• Review the API diff to make sure all api differences are expected.
• Make sure the release branch created packages after the merge and pushed them to maestro.
• Create VS insertion (this may not happen for all releases, sometimes we release only to NuGet).
• Let MAUI know about our new package names, so they can update their darc dependencies. For instance, these dependencies: https://github.com/dotnet/maui/blob/408a1cc69d6a120cafa4e75ae30411f1ec48fa3a/eng/Version.Details.xml#L15-L30 would have to be updated to net9.0_18.5 or net9.0_15.5 for our Xcode 16.4 release.

Release process

• Write release notes.
• Publish NuGets to nuget.org.
• Publish release notes.
• Update API diff (the STABLE_NUGET_VERSION_* variables in Make.config) for the main branch. Can only be done after the NuGets have been published to nuget.org.
  • Link to PR
• Update docs by executing docs/sync-mobile-docs.sh. Beware if docs were modified in the docs-mobile repository by somebody else, any such changes will have to be copied back first.
  • Link to dotnet/docs-mobile PR
• Update API / reference docs. See update-api-docs.md for instructions.
  • Create new monikers (add link to dev.azure.com ticket)
  • Add reference docs (add link to dotnet/macios-api-docs PR)
  • Flip the monikers from prerelease to live (add link to dev.azure.com ticket)
• Make sure all items in the milestone for the current release have been closed.
• Close this issue & close the milestone.
• Wonder about life as you consider the impossibility of actually reaching this point, because you can't close the milestone before all issues have been closed, and you can't close this issue until checking off all items, which you can't do until you've closed the milestone. Decide to schedule yet another viewing of Life of Brian to cope celebrate the release 🍾.