Bagikan melalui

Memecahkan masalah umum

  • Artikel

Artikel ini menjelaskan beberapa masalah yang diketahui dengan .NET Multi-platform App UI (.NET MAUI), dan bagaimana Anda dapat menyelesaikan atau mengatasinya. Repositori .NET MAUI juga merinci beberapa masalah yang diketahui.

Tidak dapat menemukan beban kerja .NET MAUI

Ada dua opsi untuk menginstal beban kerja .NET MAUI:

  1. Visual Studio di Windows dapat menginstal file .msi untuk setiap paket beban kerja.
  2. perintah dotnet workload install.

Di Windows, jika Anda menjalankan dotnet workload install setelah menginstal .NET MAUI melalui alat penginstal Visual Studio, Visual Studio dapat memasukkan status di mana ia tidak dapat menemukan beban kerja .NET MAUI. Anda akan menerima kesalahan build yang memberi tahu Anda untuk menginstal beban kerja .NET MAUI, dan dimungkinkan untuk memasukkan status di mana beban kerja tidak dapat diperbaiki atau diinstal ulang. Untuk informasi selengkapnya, lihat masalah GitHub dotnet/sdk#22388.

Windows

Solusi untuk masalah ini di Windows adalah menghapus instalan beban kerja .NET MAUI melalui CLI, menghapus instalasi .NET SDK apa pun di Panel Kontrol, dan menghapus instalan beban kerja .NET MAUI di Visual Studio. Penginstalan ini dapat dilakukan dengan proses berikut:

  1. Jalankan dotnet workload uninstall maui jika Anda pernah menggunakan dotnet workload install perintah.
  2. Hapus instalan penginstal .NET SDK mandiri dari Panel Kontrol. Alat penginstal ini memiliki nama yang mirip Microsoft .NET SDK 6.0.300dengan .
  3. Dalam setiap instans Visual Studio, hapus instalan pengembangan UI Aplikasi Multi-platform .NET, dan beban kerja Visual Studio pengembangan desktop .NET.

Kemudian, periksa apakah ada file tambahan .msi yang perlu dihapus instalasinya dengan menjalankan perintah berikut:

reg query HKLM\SOFTWARE\Microsoft\Windows\currentversion\uninstall\ -s -f manifest

Perintah ini reg query mencantumkan .NET 6+ SDK yang masih diinstal pada komputer Anda, seperti:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\currentversion\uninstall\{EEC1BB5F-3391-43C2-810E-42D78ADF3140}
    InstallSource    REG_SZ    C:\ProgramData\Microsoft\VisualStudio\Packages\Microsoft.MacCatalyst.Manifest-6.0.300,version=125.179.40883,chip=x64,productarch=neutral\
    DisplayName    REG_SZ    Microsoft.NET.Sdk.MacCatalyst.Manifest-6.0.300

Jika Anda menerima output serupa, Anda harus menyalin GUID untuk setiap paket dan menghapus instalan paket dengan msiexec perintah :

msiexec /x {EEC1BB5F-3391-43C2-810E-42D78ADF3140} /q IGNOREDEPENDENCIES=ALL

Kemudian, Anda harus terus menjalankan reg query perintah sampai tidak mengembalikan hasil apa pun. Setelah tidak ada hasil lagi dan semua .NET 6+ SDK dihapus instalasinya, Anda juga harus mempertimbangkan untuk menghapus folder berikut:

  • C:\Program Files\dotnet\sdk-manifests
  • C:\Program Files\dotnet\metadata
  • C:\Program Files\dotnet\packs
  • C:\Program Files\dotnet\library-packs
  • C:\Program Files\dotnet\template-packs
  • C:\Program Files\dotnet\sdk\6.* atau C:\Program Files\dotnet\sdk\7.*
  • C:\Program Files\dotnet\host\fxr\6.* atau C:\Program Files\dotnet\host\fxr\7.*

Setelah mengikuti proses ini, Anda harus dapat menginstal ulang .NET MAUI baik melalui Visual Studio, atau dengan menginstal versi .NET SDK yang Anda pilih dan menjalankan dotnet workload install maui perintah .

Versi platform tidak ada

Visual Studio mungkin tidak menyelesaikan beban kerja yang diperlukan jika Anda mencoba mengkompilasi proyek dan menerima kesalahan yang mirip dengan teks berikut:

Versi platform tidak ada untuk satu atau beberapa kerangka kerja target, meskipun mereka telah menentukan platform: net8.0-android, net8.0-ios, net8.0-maccatalyst

Masalah ini biasanya menghasilkan SDK x86 dan x64 yang diinstal, dan versi x86 sedang digunakan. Visual Studio dan .NET MAUI memerlukan x64 .NET SDK. Jika sistem operasi Anda memiliki variabel di seluruh PATH sistem yang menyelesaikan X86 SDK terlebih dahulu, Anda perlu memperbaikinya dengan menghapus x86 .NET SDK dari PATH variabel, atau mempromosikan x64 .NET SDK sehingga diselesaikan terlebih dahulu. Untuk informasi selengkapnya tentang pemecahan masalah resolusi X86 vs x64 SDK, lihat Menginstal .NET di Windows - Pemecahan Masalah.

Tipe atau namespace 'Default' tidak ada

Saat menggunakan Contacts API, Anda mungkin melihat kesalahan berikut yang terkait dengan iOS dan macOS:

The type or namespace name 'Default' does not exist in the namespace 'Contacts' (are you missing an assembly reference?)

Platform iOS dan macOS berisi namespace layanan akar bernama Contacts. Konflik ini menyebabkan konflik bagi platform tersebut Microsoft.Maui.ApplicationModel.Communication dengan namespace layanan, yang berisi Contacts jenis. Namespace Microsoft.Maui.ApplicationModel.Communication secara otomatis diimpor oleh <ImplicitUsings> pengaturan dalam file proyek.

Untuk menulis kode yang juga dikompilasi untuk iOS dan macOS, sepenuhnya memenuhi syarat jenisnya Contacts . Atau, berikan using direktif di bagian atas file kode untuk memetakan Communication namespace:

using Communication = Microsoft.Maui.ApplicationModel.Communication;

// Code that uses the namespace:
var contact = await Communication.Contacts.Default.PickContactAsync();

Xcode saat ini tidak diinstal atau tidak dapat ditemukan

Setelah Anda menginstal alat baris perintah Xcode menggunakan xcode-select --install, Visual Studio Code mungkin menampilkan pesan "Xcode saat ini tidak diinstal atau tidak dapat ditemukan" saat Anda mencoba membangun aplikasi .NET MAUI yang menargetkan iOS atau Mac Catalyst. Dalam skenario ini, periksa apakah Anda juga menginstal Xcode dari App Store. Kemudian, luncurkan Xcode dan buka Alat Baris Perintah Lokasi > Preferensi > Xcode > dan periksa apakah drop-down kosong. Jika kosong, pilih menu drop-down, lalu pilih lokasi alat baris perintah Xcode. Kemudian tutup Xcode dan mulai ulang Visual Studio Code.

Tidak dapat menemukan bundel aplikasi Xcode yang valid

Jika Anda menerima kesalahan "Tidak dapat menemukan bundel aplikasi Xcode yang valid di '/Library/Developer/CommandLineTools'" saat Anda mencoba membangun aplikasi .NET MAUI yang menargetkan iOS atau Mac Catalyst, coba solusi yang dijelaskan di Xcode saat ini tidak diinstal atau tidak dapat ditemukan. Jika Anda masih tidak dapat mengakses menu drop-down Alat Baris Perintah Lokasi > Preferensi > Xcode>, jalankan perintah berikut:

sudo xcode-select --reset

Versi Xcode tidak dapat ditemukan

Dalam beberapa skenario, membangun aplikasi .NET MAUI di iOS atau Mac Catalyst dapat mencoba menggunakan versi Xcode yang tidak lagi diinstal di komputer Anda. Ketika ini terjadi, Anda akan menerima pesan kesalahan yang mirip dengan:

xcodebuild: error: SDK "/Applications/Xcode_14.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk" cannot be located.
xcrun: error: sh -c '/Applications/Xcode_14.1.app/Contents/Developer/usr/bin/xcodebuild -sdk /Applications/Xcode_14.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk -find dsymutil 2> /dev/null' failed with exit code 16384: (null) (errno=Invalid argument)
xcrun: error: unable to find utility "dsymutil", not a developer tool or in PATH

Saat membuat aplikasi, .NET untuk iOS dan .NET untuk Mac Catalyst menggunakan proses berikut untuk menentukan versi Xcode mana yang akan digunakan:

  1. MD_APPLE_SDK_ROOT Jika variabel lingkungan diatur, gunakan nilainya.
  2. Jika file ~/Library/Preferences/Xamarin/Settings.plist ada, gunakan nilai yang ditentukan di dalamnya.
  3. Gunakan nilai xcode-select -p.
  4. Gunakan /Applications/Xcode.app.

Oleh karena itu, pendekatan yang direkomendasikan untuk menentukan lokasi Xcode pada komputer Anda adalah mengatur MD_APPLE_SDK_ROOT variabel lingkungan ke jalur versi Xcode. Untuk informasi selengkapnya, lihat Membangun dengan versi Xcode tertentu.

Anda kemudian dapat dengan aman menghapus ~/Library/Preferences/Xamarin/Settings.plist dari komputer Anda.

Mendiagnosis masalah di aplikasi Blazor Hybrid

BlazorWebView memiliki pengelogan bawaan yang dapat membantu Anda mendiagnosis masalah di aplikasi Blazor Hybrid Anda. Ada dua langkah untuk mengaktifkan pengelogan ini:

  1. Aktifkan BlazorWebView dan komponen terkait untuk mencatat informasi diagnostik.
  2. Konfigurasikan pencatat untuk menulis output log ke tempat Anda dapat melihatnya.

Untuk informasi selengkapnya, lihat Mendiagnosis masalah di aplikasi Blazor Hybrid.

Menonaktifkan kemasan gambar

Untuk tujuan pemecahan masalah, kemasan sumber daya gambar dapat dinonaktifkan dengan mengatur $(EnableMauiImageProcessing) properti build ke false di simpul pertama <PropertyGroup> dalam file proyek Anda:

<EnableMauiImageProcessing>false</EnableMauiImageProcessing>

Menonaktifkan kemasan layar percikan

Untuk tujuan pemecahan masalah, pembuatan sumber daya layar splash dapat dinonaktifkan dengan mengatur $(EnableSplashScreenProcessing) properti build ke false di simpul pertama <PropertyGroup> dalam file proyek Anda:

<EnableSplashScreenProcessing>false</EnableSplashScreenProcessing>

Menonaktifkan pengemasan font

Untuk tujuan pemecahan masalah, kemasan sumber daya font dapat dinonaktifkan dengan mengatur $(EnableMauiFontProcessing) properti build ke false di simpul pertama <PropertyGroup> dalam file proyek Anda:

<EnableMauiFontProcessing>false</EnableMauiFontProcessing>

Menonaktifkan pengemasan file aset

Untuk tujuan pemecahan masalah, kemasan sumber daya file aset dapat dinonaktifkan dengan mengatur $(EnableMauiAssetProcessing) properti build ke false di simpul pertama <PropertyGroup> dalam file proyek Anda:

<EnableMauiAssetProcessing>false</EnableMauiAssetProcessing>

Membuat layar percikan kosong

Untuk tujuan pemecahan masalah, layar splash kosong dapat dihasilkan jika Anda tidak memiliki <MauiSplashScreen> item dan Anda tidak memiliki layar splash kustom. Ini dapat dicapai dengan mengatur $(EnableBlankMauiSplashScreen) properti build ke true di simpul pertama <PropertyGroup> dalam file proyek Anda:

<EnableBlankMauiSplashScreen>true</EnableBlankMauiSplashScreen>

Membuat layar splash kosong akan mengambil alih layar splash kustom apa pun dan akan menyebabkan penolakan app store. Namun, ini bisa menjadi pendekatan yang berguna dalam pengujian untuk memastikan bahwa UI aplikasi Anda sudah benar.

Kesalahan nama file gambar duplikat

Anda mungkin mengalami kesalahan build tentang nama file gambar duplikat:

Satu atau beberapa nama file duplikat terdeteksi. Semua nama file output gambar harus unik.

Ini terjadi untuk MauiIcon item dan MauiImage karena dari .NET 8, .NET MAUI memeriksa untuk memastikan bahwa tidak ada nama file sumber daya gambar duplikat.

Kesalahan akan terjadi ketika Anda memiliki nama file yang identik di beberapa folder, dan dalam keadaan tertentu ketika Anda memiliki nama file yang identik dengan ekstensi yang berbeda di folder yang berbeda. Misalnya, kesalahan build akan terjadi untuk file PNG di Resources/Images/PNG/dotnet_bot.png dan file SVG di Resources/Images/SVG/dotnet_bot.svg karena file SVG dikonversi ke file PNG pada waktu build.

Kesalahan juga akan terjadi jika Anda menggunakan Include atribut pada MauiImage item untuk menyertakan semua gambar dalam folder, lalu juga menyertakan file gambar tertentu:

<MauiImage Include="Resources\Images\*" />
<MauiImage Include="Resources\Images\dotnet_bot.svg" BaseSize="168,208" />

Jika Anda menerima kesalahan build ini, kesalahan tersebut dapat diperbaiki dengan memastikan bahwa file proyek Anda tidak menyertakan gambar duplikat. Untuk melakukan ini, ubah salah satu MauiIcon atau MauiImage yang mereferensikan file tertentu untuk menggunakan Update atribut alih-alih Include atribut :

<MauiImage Include="Resources\Images\*" />
<MauiImage Update="Resources\Images\dotnet_bot.svg" BaseSize="168,208" />

Untuk informasi tentang atribut elemen item MSBuild, lihat Elemen item (MSBuild): Atribut dan elemen.