.NET MAUI Xcode 27 Uyumu: Scene Lifecycle Geçişi

Xcode 27 ile derlenen bir.NET MAUI uygulaması iOS 27 çalıştıran bir iPhone’a kurulup açılış ekranını gösterdikten sonra kapanıyorsa, büyük ihtimalle elinizde bozuk bir yaşam döngüsü değil, bir uyumluluk gereksinimi var. Cihaz günlüğünde UIScene life cycle is required for apps built with this SDK. mesajını görüyorsanız, projenizin UIKit scene lifecycle modelini benimsemesi gerekiyor. Bu yazıda, Gerald Versluis’in.NET Blog’daki anlatımına dayanarak hem yapay zekâ ajanıyla otomatik geçişi hem de elle yapılacak adımları sırayla ele alıyoruz.

Sorunun kaynağı: scene lifecycle zorunluluğu

UIKit’in scene lifecycle modeli, uygulamanın her arayüz örneğini (pencereler, ön plan ve arka plan geçişleri) yönetir. Uygulama sürecinin tamamını yöneten application lifecycle ile birlikte çalışır. Apple bu modeli iOS 13 ile tanıttı ve.NET MAUI zaten destekliyor.

Mevcut projelerin hâlâ yalnızca eski application lifecycle’ı kullanıyor olmasının nedeni basit:.NET MAUI’yi veya workload’ları güncellemek, projenizdeki platform dosyalarını yeniden yazmaz. Bu gereksinim belirli bir cihaza özgü de değil; Xcode 27 ile derlenen her iOS uygulaması, hangi form faktöründe olursa olsun bu modeli benimsemek zorunda. Buna karşılık, eski bir SDK ile derlenmiş mevcut bir binary, kullanıcı telefonunu güncelledi diye birdenbire bu geçişe ihtiyaç duymaz.

Sade bir uygulamada değişiklik gerçekten küçük: bir scene delegate sınıfı ve bir Info.plist girdisi. Asıl dikkat isteyen kısım, yıllar içinde eklediğiniz kimlik doğrulama geri çağrıları, deep link’ler ve App Actions gibi entegrasyonlar.

Geçişi bir AI ajanına devretmek

.NET MAUI CLI, geliştirme ortamınıza agent skill kurabiliyor. Skill, ajan için hazırlanmış talimatlar ve destekleyici kaynaklardan oluşur; uygulamanıza eklenen yeni bir çalışma zamanı bağımlılığı değildir.

Xcode 27 geçiş skill’i Microsoft.Maui.Cli 0.1.0-preview.13.26512.5 veya üzerini gerektiriyor. Kurulum:

dotnet tool install --global Microsoft.Maui.Cli --version 0.1.0-preview.13.26512.5

Zaten kuruluysa güncelleyin:

dotnet tool update --global Microsoft.Maui.Cli --version 0.1.0-preview.13.26512.5

Burada bir uyarı var:.NET MAUI CLI ve bu skill deneyseldir, Microsoft Destek Politikası kapsamında değildir. CLI, skill’i genel dotnet/maui-labs kataloğundan indirdiği için katalog keşfi ve kurulumu ağ erişimi gerektirir.

Uygulamanızın deposundan, CLI’nin skill’i bulabildiğini doğrulayın ve GitHub Copilot CLI için kurun:

maui ai list skill
maui ai add skill maui-xcode27-migration --env CopilotCli --yes

Başka bir AI sağlayıcısı kullanıyorsanız maui ai add skill --help çıktısına bakıp --env değerini değiştirin. Komutu değiştirmek istediğiniz uygulama deposunda çalıştırın; skill o proje için kurulur.

Ajan oturumunuzu yeniden başlatın ya da yeniden yükleyin, ardından şu yönergeyi verin:

Prepare this.NET MAUI app for Xcode 27. Inspect the project
and toolchain first, preserve custom lifecycle behavior, and validate
the migration. Ask before changing the SDK or dropping support for
older OS versions.

İsteğinizde skill adını belirtmeniz şart değil; uyumlu bir ajan göreve göre kurulu skill’ler arasından maui-xcode27-migration‘ı seçebilmeli. Şüpheye yer bırakmak istemiyorsanız adını açıkça yazabilirsiniz. Bu akışta maui migrate diye bir komut yok; skill’i kurmak tek başına uygulamanıza dokunmaz, geçişi ajan yapar.

Skill’i doğrudan GitHub Copilot CLI ile yönetmeyi tercih ederseniz, resmî eklenti kurulum belgesini izleyip maui-labs marketplace’ini ekleyin ve dotnet-maui eklentisini kurun:

copilot plugin marketplace add dotnet/maui-labs
copilot plugin install dotnet-maui@dotnet-maui-labs

Kurulum yöntemlerinden yalnızca birini seçin; aksi hâlde skill’in mükerrer kopyalarıyla uğraşırsınız.

Skill neleri kontrol ediyor?

Skill, herhangi bir düzenleme yapmadan önce hangi projeyi, hangi.NET SDK’yı,.NET MAUI paketlerini, Apple workload’larını ve Xcode sürümünü kullandığınızı tespit etmeli. Bir global.json, merkezî paket sürümleri veya hâlihazırda var olan özel bir scene delegate doğru yaklaşımı değiştirebilir. Geçişin kapsamı şöyle özetlenebilir:

• Uyumlu sürümler: Apple workload’ını Xcode ile eşleştirmek, gerekli.NET MAUI paketlerini güncellemek ve eski işletim sistemi desteğini sessizce düşürmeden deployment target’ları denetlemek.
• Scene yapılandırması: iOS ve Mac Catalyst hedefleri için delegate ve manifest’i eklemek ya da mevcutla uzlaştırmak; yapılandırmaya özgü plist dosyaları dâhil. Var olan scene özelleştirmeleri, açılış ekranı ayarları ve çoklu pencere davranışı korunmalı.
• Özel davranış: App delegate override’ları, lifecycle kayıtları, kimlik doğrulama, sıcak ve soğuk link’ler, bildirim dokunuşları, pencere gerektiren başlangıç işleri ve App Actions gözden geçirilmeli.
• Doğrulama: Salt okunur bir lifecycle denetimi çalıştırmak, diff’i incelemek, etkilenen hedefleri derlemek ve geçişin değiştirebileceği davranışları test etmek. Denenemeyen her şey raporlanmalı.

Başlamadan önce mevcut çalışmanızı commit’leyin veya kaydedin, sonucu kabul etmeden önce diff’i baştan sona okuyun. Başarılı bir derleme, kimlik doğrulama yönlendirmesinin ya da ana ekran kısayolunun hâlâ çalıştığını kanıtlamaz.

Elle geçiş: önce araç zincirinizi doğrulayın

Scene lifecycle desteği Xcode 27’den önce de vardı; uygulamanız zaten kullanıyor olabilir. Projenizde bir MauiUISceneDelegate ve ona karşılık gelen scene manifest’i varsa aşağıdaki geçiş adımlarını atlayabilirsiniz. Yine de araç zinciri sürümlerini kontrol edip uygulamanızı iOS 27 üzerinde test etmelisiniz.

Yazının yazıldığı tarihte, yayınlanmış.NET 10 iOS ve Mac Catalyst workload’ları 27.0.10722 Xcode 27.0 gerektiriyor. Daha yeni bir Xcode kurmak onu otomatik olarak bu workload ile uyumlu hâle getirmez. SDK’nın Xcode denetimini devre dışı bırakmak yerine.NET for iOS ve Mac Catalyst sürüm notlarına bakıp eşleşen sürümleri kullanın.

Aktif.NET SDK’nızı,.NET MAUI workload’ınızı, seçili Xcode’u ve Apple SDK uyumluluğunu hızlıca denetlemek için maui doctor komutunu çalıştırın. Bu komut Xcode lisansı, komut satırı araçları ve kurulu iOS runtime’ları gibi destekleyici bileşenleri de kontrol eder.

.NET 10 uygulamalarında, scene’leri etkinleştirmeden önce.NET MAUI paketlerinizi 10.0.110 veya üzerine güncelleyin. İki dosyalık açılış düzeltmesi daha eski bir.NET MAUI sürümüyle de işe yarayabilir, çünkü MauiUISceneDelegate orada da mevcut. Ancak 10.0.110, scene tarafındaki App Actions dağıtımını ve ilgili WebAuthenticator yönlendirmesini de içeriyor. Paket güncellemesini geçişin bir parçası sayın; aksi hâlde uygulamanın açılışını düzeltip bu entegrasyonları sessizce bozabilirsiniz.

Şablon projeler $(MauiVersion) değerini çoğunlukla kurulu workload’dan alır. Minimum sürümü açıkça sabitlemek için .csproj dosyanıza şunu ekleyin:

<PropertyGroup>
<MauiVersion>10.0.110</MauiVersion>
</PropertyGroup>

Bu sürümü başka bir yerde yönetiyorsanız oradaki değeri güncelleyin ve daha yeni bir uyumlu sürümü geriye düşürmeyin..NET MAUI 10.0.110 şablonlarıyla oluşturulan uygulamalarda scene yapılandırması zaten hazır gelir; mevcut projeler paket veya workload güncellemesiyle bu yapıya kavuşmaz.

Scene delegate ve manifest eklemek

Mevcut uygulamanızda Platforms/iOS/SceneDelegate.cs dosyasını oluşturun. Dosya zaten varsa yeni bir delegate eklemek yerine mevcut sınıfın temel sınıfını ve kaydını kontrol edin:

using Foundation;
using Microsoft.Maui;
namespace MyMauiApp;
[Register("SceneDelegate")]
public class SceneDelegate : MauiUISceneDelegate
{
}

MyMauiApp yerine kendi namespace’inizi yazın. Varsayılan kurulumda sınıfı public, kayıt adını da SceneDelegate olarak bırakın. Uygulamanızda kayıtlı özel bir scene delegate varsa davranışını koruyup manifest içinde onun kayıt adını tutarlı biçimde kullanın; rakip bir delegate eklemeyin.

Evet, sınıfın tamamı bu kadar; pencere kurulumunu.NET MAUI sizin yerinize yapıyor. Mevcut AppDelegate : MauiUIApplicationDelegate sınıfınızı da olduğu yerde bırakın. Scene delegate onun yerine değil, onunla birlikte çalışır.

Ardından Platforms/iOS/Info.plist dosyasını XML olarak açın ve kök <dict> içine şunu ekleyin. Zaten bir UIApplicationSceneManifest varsa mükerrer anahtar eklemek yerine mevcut scene yapılandırmasını güncelleyin:

<key>UIApplicationSceneManifest</key>
<dict>
<key>UIApplicationSupportsMultipleScenes</key>
<false/>
<key>UISceneConfigurations</key>
<dict>
<key>UIWindowSceneSessionRoleApplication</key>
<array>
<dict>
<key>UISceneConfigurationName</key>
<string>__MAUI_DEFAULT_SCENE_CONFIGURATION__</string>
<key>UISceneDelegateClassName</key>
<string>SceneDelegate</string>
</dict>
</array>
</dict>
</dict>

Burada üç ayrıntı kritik:

• __MAUI_DEFAULT_SCENE_CONFIGURATION__ değerini tam olarak gösterildiği gibi bırakın;.NET MAUI bu adı bekliyor.
• plist içindeki delegate adı ile C# kaydı eşleşmeli: örnekte SceneDelegate ve [Register("SceneDelegate")].
• Uygulamanız gerçekten çoklu pencere desteklemiyorsa UIApplicationSupportsMultipleScenes değerini false bırakın.

UISceneStoryboardFile gerekmiyor;.NET MAUI pencereyi kodla oluşturuyor ve mevcut açılış ekranı yapılandırmanız olduğu gibi kalıyor. Özel scene yapılandırma adlarınız varsa ya da GetConfiguration veya WillConnect metotlarını override ediyorsanız, manifest’i topluca değiştirmek yerine bunları birlikte değerlendirin. Varsayılan MauiUISceneDelegate pencere oluşturma yolu __MAUI_DEFAULT_SCENE_CONFIGURATION__ adını bekler; farklı bir ad, pencere oluşturmayı üstlenen özel bir uygulama gerektirir.

Bazı uygulamalar Debug, Release, müşteri veya ortam derlemeleri için farklı plist dosyaları seçer. Manifest’i, yayına çıkabilecek her plist dosyasında ekleyin ya da uzlaştırın. Yalnızca varsayılan dosyayı güncellerseniz bir yapılandırma açılış ekranının hemen ardından yine çökebilir. Bu dosyaları düzenlerken mevcut MauiSplashScreen veya UILaunchStoryboardName kurulumunu koruyun.

Mac Catalyst için aynı iki adım

Projeniz Mac Catalyst’i de hedefliyorsa aynı değişiklikleri orada da yapın: Platforms/MacCatalyst/SceneDelegate.cs dosyasını ekleyin ve aynı UIApplicationSceneManifest bölümünü Platforms/MacCatalyst/Info.plist dosyasına taşıyın.

Minimum işletim sistemi sürümleri

.NET for iOS ve.NET for Mac Catalyst 27 SDK’ları desteklenen minimum sürümleri de yükseltiyor: iOS için en az 15.0, Mac Catalyst için en az 17.0 (macOS 14 Sonoma). Uygulamanızın .csproj dosyasındaki değerler daha düşükse güncelleyin:

<SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">15.0</SupportedOSPlatformVersion>
<SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'maccatalyst'">17.0</SupportedOSPlatformVersion>

Bu girdiler bir <PropertyGroup> içinde yer almalı. Mükerrer eklemek yerine mevcut değerleri değiştirin; sonradan gelen bir tanım değişikliğinizi ezebilir. Sürümleri XML etiketleri arasına, başta veya sonda boşluk bırakmadan yazın.

Uygulamanız zaten daha yüksek bir deployment target gerektiriyorsa onu koruyun. iOS 15 altı ya da macOS 12-13 desteğini sürdürmek zorundaysanız, bu SDK’lara geçiş bir destek politikası kararı demektir. Kullanıcıları sessizce dışarıda bırakmak yerine, karar verene kadar uyumlu bir 26.x SDK üzerinde kalın. Bu SDK minimumu scene benimsenmesinden ayrı bir konudur; şablonların deployment target rehberine bakabilirsiniz.

Özel yaşam döngüsü davranışlarını taşımak

Scene’ler etkinleştiğinde UIKit artık AppDelegate üzerindeki aktivasyon, arka plana geçiş, URL ve user activity geri çağrılarını çağırmaz. Bu hem ConfigureLifecycleEvents kayıtları hem de OpenUrl veya ContinueUserActivity gibi override ettiğiniz metotlar için geçerli. İlgili mantığı scene olaylarına taşıyın:

Mevcut olay	Scene karşılığı
OnActivated	SceneOnActivated
OnResignActivation	SceneOnResignActivation
DidEnterBackground	SceneDidEnterBackground
WillEnterForeground	SceneWillEnterForeground
OpenUrl	SceneOpenUrl
ContinueUserActivity	SceneContinueUserActivity

Geri çağrı argümanları farklı olduğu için kaydın adını değiştirmek yetmez, mantığı taşımanız gerekir. SceneDelegate içinde metot override ediyorsanız ilgili base uygulamasını çağırın; framework’ün pencere kurulumu, lifecycle olayları ve kimlik doğrulama yönlendirmesi buna bağlı.

Özel deep link’ler için SceneWillConnect olayını da ele alın: uygulamayı başlatan URL’ler ve user activity’ler UISceneConnectionOptions içinde gelir. Bu geri çağrı.NET MAUI pencereyi oluşturmadan önce çalıştığı için navigasyonu pencere hazır olana kadar erteleyin.

Uygulamanız bildirim dokunuşuyla içerik açıyorsa, soğuk başlangıç girdisi olarak connectionOptions.NotificationResponse değerini inceleyin. Bu yolu, uygulama düzeyinde kalmaya devam eden olağan push kaydı ve DidReceiveRemoteNotification akışından ayrı tutun.

Normal bir açılışta URL veya user activity yükü hiç olmayabilir. Binding’in nullability açıklaması bir değer geleceğini ima etse bile, UrlContexts ve UserActivities koleksiyonlarını dolaşmadan önce boş olma ihtimaline karşı koruma koyun.

FinishedLaunching çalışmaya devam eder, ancak standart.NET MAUI scene yolunda pencere daha sonra scene delegate üzerinden oluşturulur ve AppDelegate.Windownull kalır. base.FinishedLaunching sonrasında bu özelliğe erişen kodun, pencere hazır olduğunda uygun scene penceresini kullanması gerekir. Platformlar arası Window yaşam döngüsü olayları çalışmaya devam eder; o yönlendirmeyi tekrarlamayın.

App Actions ve kimlik doğrulama

.NET MAUI 10.0.110, scene tabanlı App Actions’ı işler ve ilgili URL ile user activity geri çağrılarını WebAuthenticator‘a yönlendirir. Bu kimlik doğrulama işleyişi genel deep link navigasyonu değildir ve soğuk başlangıçtaki link’leri sizin yerinize yeniden oynatmaz. Kimlik doğrulamayı ve kendi link’lerinizi hem uygulama açıkken hem de tamamen kapalıyken test edin.

App Actions kullanıyorsanız, özel her PerformActionForShortcutItem işleyicisinin completion geri çağrısını tam olarak bir kez çağırdığından emin olun. İşlem ele alındıysa true, alınmadıysa false geçin. İşleyici dönüşten sonra asenkron yanıt verebilir, ancak sadece geri dönmek eylemi onaylamaz. Yalnızca log yazan bir işleyicinin bile yanıt vermesi gerekir. Örnek olarak MauiProgram.cs dosyasına using Microsoft.Maui.LifecycleEvents; ekleyip şu gözlemciyi CreateMauiApp içinde, return builder.Build(); satırından önce kaydedebilirsiniz:

builder.ConfigureLifecycleEvents(events =>
{
#if IOS || MACCATALYST
events.AddiOS(ios => ios
.PerformActionForShortcutItem((application, shortcutItem, completion) =>
{
Console.WriteLine($"App Action received: {shortcutItem.Type}");
completion(false);
}));
#endif
});

Varsayılan.NET MAUI builder’ı App Actions’ı zaten Essentials’a yönlendiriyor. Bu log gözlemcisine isteğiniz dışında ihtiyacınız yok ve ayrıca ikinci bir Platform.PerformActionForShortcutItem kaydı eklememelisiniz. AppDelegate içinde PerformActionForShortcutItem override ediyorsanız, scene’ler etkinken o override artık çağrılmaz; özel mantığı completion geri çağrısıyla birlikte yukarıdaki gibi bir kayda taşıyın.

Yeniden derleyin ve test edin

iOS hedefini restore edip derleyin:

dotnet restore -p:TargetFramework=net10.0-ios
dotnet build -f net10.0-ios --no-restore

Simülatörde hâlâ uygulamanın eski sürümü görünüyorsa uygulamayı kaldırın, proje klasöründeki bin ve obj dizinlerini silin ve bu iki komutu yeniden çalıştırın.

Hem Debug hem Release derlemelerini, eşleşen workload ve Xcode ile iOS 27 çalıştıran normal bir iPhone veya iPad simülatöründe açın. iOS 26’da başarılı bir derleme ya da açılış, Xcode 27 ile derlenen uygulamanın iOS 27’de açılacağını kanıtlamaz. Soğuk başlangıcı, arka plan–ön plan geçişlerini, kimlik doğrulama akışınızı, uygulama açıkken ve kapalıyken link’leri ve bildirim dokunuşlarını, bir de App Actions’ı kontrol edin. Mac Catalyst hedefiniz varsa onu da derleyip test edin.

Bu geçişi doğrulamak için özel bir cihaz simülatörüne ihtiyacınız yok; cihaza özgü yerleşimler ve Xcode 27.1 araçları ayrı bir konu olarak ele alınacak.

Kaynaklar ve İleri Okuma

• devblogs.microsoft.com

• Get Your.NET MAUI App Ready for Xcode 27 —.NET Blog (Gerald Versluis)
• maui-xcode27-migration skill’inin deposundaki kaynak dizini
• dotnet/maui-labs katalog deposu
• GitHub Copilot CLI eklenti kurulum belgesi
• .NET for iOS ve Mac Catalyst 27.0.10722 sürüm notları
• .NET MAUI şablonları ve deployment target rehberi
• .NET Agent Skills: Üç Yöntem, Tek Sağlayıcı
• Agent Skills for.NET Kararlı Sürümde