Xamarin.Forms UWP proje geçişi

Makale
05/14/2024

Xamarin.Forms UWP projenizi bir WinUI 3 projesine güncelleştirmek için şunları yapmalısınız:

Proje dosyanızı SDK stilinde olacak şekilde güncelleştirin.
Ad alanlarını güncelleştirme
TÜM API değişikliklerini ele alma
Uyumsuz bağımlılıkları .NET 8 sürümleriyle güncelleştirin veya değiştirin.
Uygulamanızı derleyin ve test edin.

SDK stili proje dosyasına güncelleştirme

Mevcut Xamarin.Forms UWP projeniz SDK stilindeki bir WinUI 3 projesine güncelleştirilebilir. .NET MAUI WinUI 3 uygulaması için SDK stilindeki bir proje aşağıdaki örneğe benzer:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType> <!-- in Xamarin.Forms this was AppContainerExe -->
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    <RootNamespace>YOUR_NAMESPACE_HERE.WinUI</RootNamespace>
    <ApplicationManifest>app.manifest</ApplicationManifest>
    <Platforms>x86;x64;ARM64</Platforms>
    <RuntimeIdentifiers>win10-x86;win10-x64;win10-arm64</RuntimeIdentifiers>
    <UseWinUI>true</UseWinUI>
    <EnableMsixTooling>true</EnableMsixTooling>
    <UseMaui>true</UseMaui>
    <!-- We do not want XAML files to be processed as .NET MAUI XAML -->
    <EnableDefaultMauiItems>false</EnableDefaultMauiItems>
  </PropertyGroup>
  ...
</Project>

Önemli

Hedef çerçeve takma adı (TFM), projeyi .NET kullanarak (bu örnekte .NET 8) olarak belirtir. SDK stili projelerdeki hedef çerçeveler hakkında bilgi için bkz . SDK stili projelerde hedef çerçeveler.

.NET MAUI desteğini etkinleştirmek için proje dosyanıza eklemeniz <UseMaui>true</UseMaui> gerekir. Ayrıca, proje dosyasına eklediğinizden <EnableDefaultMauiItems>false</EnableDefaultMauiItems> emin olun. Bu, zaten tanımlanmış olan yöntemle ilgili InitializeComponent derleme hataları almanızı durdurur.

MSBuild özelliklerindeki değişiklikler

Projenizi yükseltirken aşağıdaki UWP MSBuild özelliklerini proje dosyanızdan kaldırmanız önerilir:

WindowsXamlEnableOverview
AppxPackageSigningEnabled
GenerateAssemblyInfo

Hedef projedeki platform mimarilerinin aşağıdaki .NET çalışma zamanı tanımlayıcılarıyla belirtildiğinden de emin olmanız gerekir:

<PropertyGroup>
   <!-- Used in .NET MAUI WinUI projects -->
   <Platforms>x86;x64;ARM64</Platforms>
</PropertyGroup>

Çalışma zamanı tanımlayıcıları hakkında daha fazla bilgi için bkz . .NET RID Kataloğu.

Ad alanı değişiklikleri

UWP ve WinUI 3 arasındaki ad alanlarının adlarında farklılıklar vardır. Çoğu durumda ad alanı adını değiştirmek kadar kolaydır ve kodunuz derlenir. Örneğin, ad alanını Windows.UI.Xaml ad alanıyla Microsoft.UI.Xaml değiştirmeniz gerekir. Benzer şekilde, ad alanını Windows.UI.Xaml.Controls ad alanıyla Microsoft.UI.Xaml.Controls değiştirmeniz gerekir.

Diğer durumlarda, eşleme biraz daha fazla iş alır ve nadir durumlarda yaklaşımda bir değişiklik gerektirir. Daha fazla bilgi için bkz . UWP API'lerini ve kitaplıklarını Windows Uygulama SDK'sına eşleme.

API değişiklikleri

Uygulamanızı etkileyebilecek API değişikliklerini ele almanız gerekir. Örneğin, bazı türler, yöntemler ve özellikler yeniden adlandırılmış, kullanım dışı bırakılmış veya kaldırılmış olabilir. UWP projenizi WinUI 3'e yükseltirken desteklenenler hakkında bilgi için bkz . UWP'den WinUI 3'e geçiş yaparken desteklenenler. UWP özelliklerini ve API'lerini WinUI 3'e eşleme hakkında bilgi için bkz . UWP özelliklerini Windows Uygulama SDK'sına eşleme ve UWP API'lerini ve kitaplıklarını Windows Uygulama SDK'sına eşleme.

Proje dosyanızda özelliği ayarlanarak $(SupportedOSPlatformVersion) projeniz önceki işletim sistemi sürümleriyle uyumlu hale getirilebilir:

<PropertyGroup>
   <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">10.0.19041.0</SupportedOSPlatformVersion>
</PropertyGroup>

özelliği, $(SupportedOSPlatformVersion) uygulamanızı veya kitaplığınızı çalıştırmak için gereken en düşük işletim sistemi sürümünü gösterir. Projenizde bu en düşük çalışma zamanı işletim sistemi sürümünü açıkça belirtmezseniz, varsayılan olarak Hedef Çerçeve Takma Adı'ndan (TFM) platform sürümüne ayarlanır.

Projeniz yalnızca Windows'u hedeflediyse, platform denetimi koşulunu atlayıp özelliği doğrudan ayarlamak $(SupportedOSPlatformVersion) yeterlidir:

<PropertyGroup>
   <SupportedOSPlatformVersion>10.0.19041.0</SupportedOSPlatformVersion>
</PropertyGroup>

Özelliği hakkında $(SupportedOSPlatformVersion) daha fazla bilgi için bkz . Eski işletim sistemi sürümlerini destekleme.

Bir uygulamanın eski bir işletim sistemi sürümünde doğru şekilde çalışması için, işletim sisteminin bu sürümünde mevcut olmayan API'leri çağıramaz. Ancak, daha yeni API'lere yapılan çağrıların çevresine korumalar ekleyebilirsiniz, böylece bunlar yalnızca onları destekleyen bir işletim sistemi sürümünde çalıştırılırken çağrılır. Bu yöntemle IsWindowsVersionAtLeast elde edilebilir:

if (OperatingSystem.IsWindowsVersionAtLeast(10))
{
    // Use the API here
}

Dosyaları kaldırma

Xamarin.Forms UWP projelerinde bulunan aşağıdaki dosyalar WinUI 3 projelerinde yoktur:

MainPage.xaml ve MainPage.xaml.cs
Assemblyınfo.cs
Default.rd.xml

Bu nedenle, WinUI 3 projenizde yer alan bu dosyaları kaldırmanız gerekir. Bu dosyalarda yer alan tüm gerekli iş mantığı başka bir yere taşınmalıdır.

Package.appxmanifest değişiklikleri

Geçirilen projenizin Package.appxmanifest dosyasında aşağıdaki değişiklikler yapılmalıdır:

Uygulama giriş noktasını olarak $targetentrypoint$ ayarlayın. Daha fazla bilgi için bkz . Hedef giriş noktası.
runFullTrust Özelliği ekleyin. Daha fazla bilgi için bkz . Tam güven özelliğini çalıştırma.
Windows.Universal ve Windows.Desktop hedef cihaz ailelerini ekleyin. Daha fazla bilgi için bkz . Evrensel hedef cihaz ailesi ve Masaüstü hedef cihaz ailesi.

Bu değişikliklerin yapılması, Windows'ta uygulamanız için yaygın dağıtım hatalarını düzeltir.

Uyumlu bir Package.appxmanifest dosyası örneği için bkz. Package.appxmanifest.

Çalışma zamanı davranışı

Farklı platformlarda .NET 5+'ta yönteminde davranış değişiklikleri String.IndexOf() vardır. Daha fazla bilgi için bkz . .NET genelleştirme ve ICU.

Sonraki adımlar

Uygulamanızı önyükleme

Aracılığıyla paylaş