Your existing .NET MAUI app builds with Xcode 27, installs on an iPhone running iOS 27, shows its splash screen, and then disappears. Not exactly the grand entrance you were hoping for.<\/p>\n
That symptom can have many causes. But if the only thing that changed is that you\u2019re now building with Xcode 27 and running the app on iOS 27, and you see the device log message below, your .NET MAUI app needs a few changes:<\/p>\n
UIScene life cycle is required for apps built with this SDK.<\/code><\/pre>\nUIKit\u2019s scene lifecycle manages each instance of an app\u2019s user interface, including its windows and transitions between foreground and background states. It works alongside the application lifecycle, which manages the app process as a whole. Apple introduced this model with iOS 13, and .NET MAUI already supports it.<\/p>\n
This is an Xcode 27 compatibility requirement, not a broken .NET MAUI lifecycle. Existing .NET MAUI projects might still use only the older application lifecycle because updating .NET MAUI or its workloads doesn\u2019t rewrite their platform files. It\u2019s not specific to the iPhone Duo. Every iOS app built with Xcode 27, on any form factor, needs to adopt this pattern. An existing binary built with an older SDK doesn\u2019t suddenly need this migration just because someone updates their phone.<\/p>\n
For a straightforward app, the change is small: a scene delegate and an Info.plist<\/code> entry. The part that deserves your attention is everything you\u2019ve added over the years, such as authentication callbacks, deep links, and App Actions.<\/p>\nThat\u2019s where the maui-xcode27-migration<\/code> agent skill comes in. It guides your coding agent through the project checks, the migration, and the verification. You still review the changes, and the manual steps below explain what it\u2019s doing.<\/p>\nLet an AI agent handle the migration<\/h2>\n
The .NET MAUI CLI<\/a> can install agent skills into your development environment. A skill is a set of instructions and supporting resources for the agent. It\u2019s not another runtime dependency in your app.<\/p>\nThe Xcode 27 migration skill requires Microsoft.Maui.Cli 0.1.0-preview.13.26512.5 or later<\/strong>. Install that preview release:<\/p>\ndotnet tool install --global Microsoft.Maui.Cli --version 0.1.0-preview.13.26512.5<\/code><\/pre>\nIf you already have it installed, update it instead:<\/p>\n
dotnet tool update --global Microsoft.Maui.Cli --version 0.1.0-preview.13.26512.5<\/code><\/pre>\n\n\n<\/i>Preview tooling<\/strong><\/p>\nThe .NET MAUI CLI and this skill are experimental and are not covered by the Microsoft Support Policy. The CLI downloads the skill from the public dotnet\/maui-labs<\/code> catalog, so catalog discovery and installation require network access.<\/p><\/div>\nFrom your app\u2019s repository, check that the CLI can find the skill and install it for GitHub Copilot CLI:<\/p>\n
maui ai list skill\nmaui ai add skill maui-xcode27-migration --env CopilotCli --yes<\/code><\/pre>\nIf you use another AI provider, check maui ai add skill --help<\/code> and change the --env<\/code> option accordingly. Run the command from the app repository you want to change, because the skill is installed for that project.<\/p>\nRestart or reload your agent session so it picks up the new skill, then ask:<\/p>\n
Prepare this .NET MAUI app for Xcode 27. Inspect the project\nand toolchain first, preserve custom lifecycle behavior, and validate\nthe migration. Ask before changing the SDK or dropping support for\nolder OS versions.<\/code><\/pre>\nYou don\u2019t need to name the skill in your request. A compatible agent should pick maui-xcode27-migration<\/code> from the installed skills based on the task. If you want to remove any doubt, feel free to name it explicitly.<\/p>\nThe CLI installs the skill, and your coding agent does the migration. There\u2019s no maui migrate<\/code> command in this workflow, and installing the skill on its own doesn\u2019t touch your app.<\/p>\nPrefer to manage the skill directly with GitHub Copilot CLI? Follow the official GitHub Copilot plugin installation documentation<\/a>, then add the maui-labs<\/code> marketplace and install the dotnet-maui<\/code> plugin:<\/p>\ncopilot plugin marketplace add dotnet\/maui-labs\ncopilot plugin install dotnet-maui@dotnet-maui-labs<\/code><\/pre>\nYou can also find the migration skill directly in the dotnet\/maui-labs<\/code> repository<\/a>. Pick one installation method so you don\u2019t end up with duplicate copies.<\/p>\nWhat the skill checks<\/h2>\n
Before editing anything, the skill should work out which project, .NET SDK, .NET MAUI packages, Apple workloads, and Xcode version you\u2019re actually using. A global.json<\/code>, shared package versions, or an existing custom scene delegate can all change the right approach.<\/p>\nThe migration covers:<\/p>\n
\n- Compatible versions.<\/strong> Match the Apple workload to Xcode, update the required .NET MAUI packages, and check deployment targets without silently dropping older OS support.<\/li>\n
- Scene configuration.<\/strong> Add or reconcile the delegate and manifest for the iOS and Mac Catalyst targets, including configuration-specific plist files. Preserve existing scene customizations, launch-screen settings, and multi-window behavior.<\/li>\n
- Custom behavior.<\/strong> Review app-delegate overrides as well as lifecycle registrations, authentication, warm and cold links, notification taps, startup work that needs a window, and App Actions.<\/li>\n
- Verification.<\/strong> Run a read-only lifecycle audit, review the diff, build the affected targets, and test launch and the behaviors the migration can change. Report anything that could not be exercised.<\/li>\n<\/ul>\n
Commit or otherwise save your current work before starting, and go through the resulting diff before accepting it. A successful build doesn\u2019t prove that an authentication redirect or a Home screen shortcut still works.<\/p>\n
If you\u2019d rather do things by hand, the instructions are below.<\/p>\n
Before you start: check your app and toolchain<\/h2>\n
Scene lifecycle support was available before Xcode 27, so your app might already use it. If you already have a MauiUISceneDelegate<\/code> and matching scene manifest, good news: you can skip the migration steps below. You should still check the toolchain versions and test your app on iOS 27.<\/p>\nAt the time of writing, the released .NET 10 iOS and Mac Catalyst workloads 27.0.10722 require Xcode 27.0<\/strong>. Installing a newer Xcode doesn\u2019t automatically make it compatible with that workload. Check the .NET for iOS and Mac Catalyst release notes<\/a> and use the matching versions rather than disabling the SDK\u2019s Xcode check.<\/p>\n\n\n<\/i>Check your setup<\/strong><\/p>\nRun maui doctor<\/code> for a quick check of your active .NET SDK, .NET MAUI workload, selected Xcode, and Apple SDK compatibility. It also checks supporting components such as the Xcode license, command-line tools, and installed iOS runtimes.<\/p><\/div>\nFor a .NET 10 app, update your .NET MAUI packages to 10.0.110 or higher<\/strong> before enabling scenes. The two-file launch fix can work with an older .NET MAUI version because MauiUISceneDelegate<\/code> already exists there. However, 10.0.110 also includes the scene-side App Actions dispatch and relevant WebAuthenticator<\/code> forwarding. Treat the package update as part of the migration, otherwise you might fix the launch and silently break those integrations.<\/p>\nTemplate projects often get $(MauiVersion)<\/code> from the installed workload. To pin the minimum version explicitly, add this to your .csproj<\/code>:<\/p>\n<PropertyGroup>\n <MauiVersion>10.0.110<\/MauiVersion>\n<\/PropertyGroup><\/code><\/pre>\nIf you already manage this version elsewhere, update that value instead. Don\u2019t downgrade a newer compatible version.<\/p>\n
Apps created with the .NET MAUI 10.0.110 templates already have the scene configuration. Existing projects aren\u2019t retrofitted by a package or workload update, so you\u2019ll need to do that part yourself.<\/p>\n
Add the scene delegate<\/h2>\n
In your existing app, create Platforms\/iOS\/SceneDelegate.cs<\/code> and paste in this code. If the file already exists, check its base class and registration instead of adding a second delegate:<\/p>\nusing Foundation;\nusing Microsoft.Maui;\n\nnamespace MyMauiApp;\n\n[Register(\"SceneDelegate\")]\npublic class SceneDelegate : MauiUISceneDelegate\n{\n}<\/code><\/pre>\nReplace MyMauiApp<\/code> with your app\u2019s namespace. For this default setup, keep the class public and the registration name as SceneDelegate<\/code>. If your app already has a custom registered scene delegate, preserve its behavior and use its registered name consistently in the manifest instead of adding a competing delegate.<\/p>\nYes, that\u2019s the whole class. .NET MAUI does the actual window setup for you. Leave your existing AppDelegate : MauiUIApplicationDelegate<\/code> exactly where it is too. The scene delegate works alongside it, not instead of it.<\/p>\nAdd the scene manifest<\/h2>\n
Open Platforms\/iOS\/Info.plist<\/code> as XML and add the following inside the root <dict><\/code>. If you already have a UIApplicationSceneManifest<\/code>, update its existing scene configuration instead of adding a duplicate key:<\/p>\n<key>UIApplicationSceneManifest<\/key>\n<dict>\n <key>UIApplicationSupportsMultipleScenes<\/key>\n <false\/>\n <key>UISceneConfigurations<\/key>\n <dict>\n <key>UIWindowSceneSessionRoleApplication<\/key>\n <array>\n <dict>\n <key>UISceneConfigurationName<\/key>\n <string>__MAUI_DEFAULT_SCENE_CONFIGURATION__<\/string>\n <key>UISceneDelegateClassName<\/key>\n <string>SceneDelegate<\/string>\n <\/dict>\n <\/array>\n <\/dict>\n<\/dict><\/code><\/pre>\nThree details matter here:<\/p>\n
\n- Keep
__MAUI_DEFAULT_SCENE_CONFIGURATION__<\/code> exactly as shown. That\u2019s the name .NET MAUI expects.<\/li>\n- Match the delegate name in the plist with the C# registration:
SceneDelegate<\/code> and [Register(\"SceneDelegate\")]<\/code> in this example.<\/li>\n- Leave
UIApplicationSupportsMultipleScenes<\/code> set to false<\/code> unless your app really supports multiple windows.<\/li>\n<\/ul>\nYou don\u2019t need a UISceneStoryboardFile<\/code>. .NET MAUI creates the window in code, and your existing splash screen configuration stays as it is.<\/p>\nIf you have custom scene configuration names or override GetConfiguration<\/code> or WillConnect<\/code>, review them together rather than replacing the manifest wholesale. The default MauiUISceneDelegate<\/code> window-creation path expects __MAUI_DEFAULT_SCENE_CONFIGURATION__<\/code>; a different name needs an existing custom implementation that handles window creation.<\/p>\nSome apps select a different plist for Debug, Release, customer, or environment builds. Add or reconcile the manifest in every plist that can produce a shipping app. If you only update the default file, one configuration can still crash right after the splash screen. Preserve the existing MauiSplashScreen<\/code> or UILaunchStoryboardName<\/code> setup while editing these files.<\/p>\nThat\u2019s the iOS scene configuration done. If you don\u2019t target Mac Catalyst, skip ahead to the minimum OS versions.<\/p>\n
Do the same for Mac Catalyst<\/h2>\n
If your project also targets Mac Catalyst, make the same two changes there:<\/p>\n
\n- Add
Platforms\/MacCatalyst\/SceneDelegate.cs<\/code>.<\/li>\n- Add the same
UIApplicationSceneManifest<\/code> section to Platforms\/MacCatalyst\/Info.plist<\/code>.<\/li>\n<\/ol>\nCheck your minimum OS versions<\/h2>\n
The .NET for iOS and .NET for Mac Catalyst 27 SDKs also raise the minimum supported versions: iOS needs at least 15.0<\/code>, and Mac Catalyst needs at least 17.0<\/code> (macOS 14 Sonoma). In your app\u2019s .csproj<\/code>, update the existing SupportedOSPlatformVersion<\/code> entries if yours are lower:<\/p>\n<SupportedOSPlatformVersion Condition=\"$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'\">15.0<\/SupportedOSPlatformVersion>\n<SupportedOSPlatformVersion Condition=\"$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'maccatalyst'\">17.0<\/SupportedOSPlatformVersion><\/code><\/pre>\nThese entries belong inside a <PropertyGroup><\/code>. Replace the existing values instead of adding duplicates, because a later definition can override your change. Keep each version directly between its XML tags, without leading or trailing whitespace.<\/p>\nKeep a higher deployment target if your app already requires one. If you must retain support for iOS versions below 15 or macOS 12 and 13, moving to these SDKs requires a support-policy decision. Stay on a compatible 26.x SDK while you decide, rather than silently dropping those users. This SDK minimum is separate from scene adoption; see the .NET MAUI template deployment-target guidance<\/a>.<\/p>\nCheck any custom app behavior<\/h2>\n
With scenes enabled, UIKit no longer calls the AppDelegate<\/code> activation, backgrounding, URL, and user-activity callbacks. That goes for both ConfigureLifecycleEvents<\/code> registrations and methods you override in AppDelegate<\/code>, such as OpenUrl<\/code> or ContinueUserActivity<\/code>. Move that logic to the corresponding scene events:<\/p>\n\n\n\nExisting event<\/th>\n Scene event<\/th>\n<\/tr>\n<\/thead>\n \n\nOnActivated<\/code><\/td>\nSceneOnActivated<\/code><\/td>\n<\/tr>\n\nOnResignActivation<\/code><\/td>\nSceneOnResignActivation<\/code><\/td>\n<\/tr>\n\nDidEnterBackground<\/code><\/td>\nSceneDidEnterBackground<\/code><\/td>\n<\/tr>\n\nWillEnterForeground<\/code><\/td>\nSceneWillEnterForeground<\/code><\/td>\n<\/tr>\n\nOpenUrl<\/code><\/td>\nSceneOpenUrl<\/code><\/td>\n<\/tr>\n\nContinueUserActivity<\/code><\/td>\nSceneContinueUserActivity<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\nThe callback arguments differ, so move the logic instead of just renaming the registration. If you instead override methods in your SceneDelegate<\/code>, call the corresponding base<\/code> implementation. The framework\u2019s window setup, lifecycle events, and authentication forwarding depend on that behavior.<\/p>\nFor custom deep links, also handle SceneWillConnect<\/code>: URLs and user activities that launch the app arrive in its UISceneConnectionOptions<\/code>. That callback runs before .NET MAUI creates the window, so defer navigation until the window is ready.<\/p>\nIf your app opens content from a notification tap, inspect connectionOptions.NotificationResponse<\/code> as another cold-start input. Preserve that route separately from ordinary push registration and DidReceiveRemoteNotification<\/code>, which remain application-level callbacks.<\/p>\nA regular launch may have no URL or user-activity payload. Guard against absent UrlContexts<\/code> and UserActivities<\/code> before enumerating them, even when the binding\u2019s nullability annotation suggests a value will be there.<\/p>\nFinishedLaunching<\/code> still runs, but the standard .NET MAUI scene path creates the window later through the scene delegate. AppDelegate.Window<\/code> stays null<\/code>. Code that accesses it after base.FinishedLaunching<\/code> needs to use the appropriate scene window when it is ready instead. The cross-platform Window<\/code> lifecycle events keep working; do not duplicate that forwarding.<\/p>\n.NET MAUI 10.0.110 handles scene-based App Actions and forwards the relevant URL and user-activity callbacks to WebAuthenticator<\/code>. That authentication handling is not general app deep-link navigation and does not replay cold-start links for you. Test authentication and your own links with the app both running and fully closed.<\/p>\nIf you use App Actions, make sure every custom PerformActionForShortcutItem<\/code> handler calls its completion callback exactly once<\/strong>. Pass true<\/code> when the action was handled and false<\/code> when it was not. A handler can respond asynchronously after returning, but returning alone does not acknowledge the action.<\/p>\nEven a handler that only writes a log message needs to respond. As an example, add using Microsoft.Maui.LifecycleEvents;<\/code> to MauiProgram.cs<\/code>, then register this observer inside CreateMauiApp<\/code>, before return builder.Build();<\/code>:<\/p>\nbuilder.ConfigureLifecycleEvents(events =>\n{\n#if IOS || MACCATALYST\n events.AddiOS(ios => ios\n .PerformActionForShortcutItem((application, shortcutItem, completion) =>\n {\n Console.WriteLine($\"App Action received: {shortcutItem.Type}\");\n completion(false);\n }));\n#endif\n});<\/code><\/pre>\nThe default .NET MAUI builder already forwards App Actions to Essentials. You don\u2019t need this logging observer unless you want it, and you shouldn\u2019t add another Platform.PerformActionForShortcutItem<\/code> registration. If your AppDelegate<\/code> overrides PerformActionForShortcutItem<\/code>, that override is no longer called with scenes enabled. Move its custom logic into a registration like the one above, completion callback included.<\/p>\nRebuild and try it<\/h2>\n
Restore and build the iOS target:<\/p>\n
dotnet restore -p:TargetFramework=net10.0-ios\ndotnet build -f net10.0-ios --no-restore<\/code><\/pre>\nIf the simulator still seems to have an old version of your app, uninstall it, delete the app project\u2019s bin<\/code> and obj<\/code> folders, and run those two commands again.<\/p>\nLaunch both Debug and Release builds on a regular iPhone or iPad simulator running iOS 27 with the matching workload and Xcode. A successful build or launch on iOS 26 doesn\u2019t prove that the app will launch on iOS 27 when built with Xcode 27. Check a cold launch, background and foreground transitions, your authentication flow, links and notification taps with the app both running and closed, and App Actions. If you target Mac Catalyst, build and exercise that target too.<\/p>\n
You don\u2019t need an iPhone Duo simulator to verify this migration. Device-specific layouts and the Xcode 27.1 tooling are a separate topic that we\u2019ll cover in a follow-up post soon.<\/p>\n
The post Get Your .NET MAUI App Ready for Xcode 27<\/a> appeared first on .NET Blog<\/a>.<\/p>","protected":false},"excerpt":{"rendered":"Your existing .NET MAUI app builds with Xcode 27, installs on an iPhone running iOS 27, shows its splash screen, […]<\/p>\n","protected":false},"author":1,"featured_media":94,"comment_status":"","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"site-sidebar-layout":"default","site-content-layout":"","ast-site-content-layout":"default","site-content-style":"default","site-sidebar-style":"default","ast-global-header-display":"","ast-banner-title-visibility":"","ast-main-header-display":"","ast-hfb-above-header-display":"","ast-hfb-below-header-display":"","ast-hfb-mobile-header-display":"","site-post-title":"","ast-breadcrumbs-content":"","ast-featured-img":"","footer-sml-layout":"","ast-disable-related-posts":"","theme-transparent-header-meta":"","adv-header-id-meta":"","stick-header-meta":"","header-above-stick-meta":"","header-main-stick-meta":"","header-below-stick-meta":"","astra-migrate-meta-layouts":"default","ast-page-background-enabled":"default","ast-page-background-meta":{"desktop":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"ast-content-background-meta":{"desktop":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"footnotes":""},"categories":[7],"tags":[],"class_list":["post-5288","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-dotnet"],"_links":{"self":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/posts\/5288","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/comments?post=5288"}],"version-history":[{"count":0,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/posts\/5288\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/media\/94"}],"wp:attachment":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/media?parent=5288"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/categories?post=5288"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/tags?post=5288"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}