共用方式為


對已知問題進行疑難排解

本文說明 .NET 多平臺應用程式 UI (.NET MAUI) 的一些已知問題,以及如何解決或解決它們。 .NET MAUI 存放 也會詳細說明一些已知問題。

找不到 .NET MAUI 工作負載

有兩個選項可用來安裝 .NET MAUI 工作負載:

  1. Windows 上的 Visual Studio 可以為每個工作負載套件安裝 .msi 檔案。
  2. dotnet workload install 命令。

在 Windows 上,如果您在透過 Visual Studio 安裝程式安裝 .NET MAUI 之後執行 dotnet workload install ,Visual Studio 可以進入無法找到 .NET MAUI 工作負載的狀態。 您將會收到建置錯誤,告知您安裝 .NET MAUI 工作負載,而且有可能進入無法修復或重新安裝工作負載的狀態。 如需詳細資訊,請參閱 GitHub 問題 dotnet/sdk#22388

Windows

Windows 上此問題的解決方案是透過 CLI 卸載 .NET MAUI 工作負載、卸載 控制台 中的任何 .NET SDK,以及卸載 Visual Studio 中的 .NET MAUI 工作負載。 這些卸載可透過下列程式來完成:

  1. 如果您曾經使用命令,dotnet workload install請執行 dotnet workload uninstall maui
  2. 從 控制台 卸載任何獨立 .NET SDK 安裝程式。 這些安裝程式名稱類似 Microsoft .NET SDK 6.0.300
  3. 在每個 Visual Studio 實例中,卸載 .NET 多平臺應用程式 UI 開發,以及 .NET 桌面開發 Visual Studio 工作負載。

然後,執行下列命令,檢查是否需要卸載其他 .msi 檔案:

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

此指令 reg query 會列出電腦上仍安裝的 .NET 6+ SDK,例如:

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

如果您收到類似的輸出,您應該複製每個套件的 GUID,並使用 msiexec 命令卸載套件:

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

然後,您應該繼續執行 reg query 命令,直到它未傳回任何結果為止。 一旦沒有任何結果,而且所有 .NET 6+ SDK 都卸載之後,您也應該考慮刪除下列資料夾:

  • 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.*C:\Program Files\dotnet\sdk\7.*
  • C:\Program Files\dotnet\host\fxr\6.*C:\Program Files\dotnet\host\fxr\7.*

遵循此程序之後,您應該能夠透過 Visual Studio 重新安裝 .NET MAUI,或安裝您選擇的 .NET SDK 版本並執行 dotnet workload install maui 命令。

平臺版本不存在

如果您嘗試編譯專案並收到類似下列文字的錯誤,Visual Studio 可能無法解決必要的工作負載:

一或多個目標架構沒有平臺版本,即使已指定平臺:net8.0-android、net8.0-ios、net8.0-maccatalyst

此問題通常是因為已安裝 x86 和 x64 SDK,且正在使用 x86 版本。 Visual Studio 和 .NET MAUI 需要 x64 .NET SDK。 如果您的作業系統有一個先解析 x86 SDK 的系統範圍 PATH 變數,您需要先從 PATH 變數中移除 x86 .NET SDK,或升級 x64 .NET SDK,以便先解析。 如需針對 x86 與 x64 SDK 解析進行疑難解答的詳細資訊,請參閱 在 Windows 上安裝 .NET - 疑難解答

類型或命名空間 『Default』 不存在

使用 Contacts API 時,您可能會看到下列與 iOS 和 macOS 相關的錯誤:

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

iOS 和 macOS 平臺包含名為 的 Contacts根命名空間。 此衝突會針對包含 型別的 Microsoft.Maui.ApplicationModel.Communication 命名空間 Contacts ,導致這些平台發生衝突。 命名空間 Microsoft.Maui.ApplicationModel.Communication 會自動由 <ImplicitUsings> 項目檔中的 設定匯入。

若要撰寫也針對iOS和macOS編譯的程式代碼,請完整限定 Contacts 類型。 或者,在程式代碼檔案頂端提供 using 指示詞來對應 Communication 命名空間:

using Communication = Microsoft.Maui.ApplicationModel.Communication;

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

目前未安裝 Xcode 或找不到

使用 xcode-select --install安裝 Xcode 命令行工具之後,當您嘗試建置以 iOS 或 Mac Catalyst 為目標的 .NET MAUI 應用程式時,Visual Studio Code 可能會顯示「目前未安裝 Xcode 或找不到」訊息。 在此案例中,請檢查您也已安裝來自 App Store 的 Xcode。 然後,啟動 Xcode 並移至 [Xcode > 喜好 > 設定位置 > ] 命令行工具 ,並檢查下拉式清單是否空白。 如果是空的,請選取下拉式清單,然後選取 Xcode 命令行工具的位置。 然後關閉 Xcode 並重新啟動 Visual Studio Code。

找不到有效的 Xcode 應用程式套件組合

如果您嘗試建置以 iOS 或 Mac Catalyst 為目標的 .NET MAUI 應用程式時,收到「在 『/Library/Developer/CommandLineTools』 找不到有效的 Xcode 應用程式套件組合」錯誤,請嘗試目前未安裝或找不到 Xcode 中所述的解決方案。 如果您仍然無法存取 Xcode > 喜好 > 設定位置 > 命令列工具 下拉式清單,請執行下列命令:

sudo xcode-select --reset

找不到 Xcode 版本

在某些情況下,在iOS或Mac Catalyst上建置 .NET MAUI 應用程式可能會嘗試使用電腦上不再安裝的 Xcode 版本。 發生這種情況時,您會收到類似下列的錯誤訊息:

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

建置應用程式時,適用於 iOS 的 .NET 和 .NET for Mac Catalyst 會使用下列程式來判斷要使用的 Xcode 版本:

  1. MD_APPLE_SDK_ROOT如果已設定環境變數,請使用其值。
  2. 如果 ~/Library/Preferences/Xamarin/Settings.plist 檔案存在,請使用其內定義的值。
  3. 使用的值 xcode-select -p
  4. 使用 /Applications/Xcode.app

因此,指定計算機上 Xcode 位置的建議方法是將環境變數設定 MD_APPLE_SDK_ROOT 為 Xcode 版本的路徑。 如需詳細資訊,請參閱 使用特定版本的 Xcode 建置。

然後,您可以從您的計算機安全地刪除 ~/Library/Preferences/Xamarin/Settings.plist

診斷 Blazor 混合式應用程式中的問題

BlazorWebView 內建記錄可協助您診斷 Blazor 混合式應用程式中的問題。 開啟此記錄有兩個步驟:

  1. 啟用 BlazorWebView 和相關元件來記錄診斷資訊。
  2. 設定記錄器,將記錄檔輸出寫入您可以檢視的位置。

如需詳細資訊,請參閱 診斷 Blazor 混合式應用程式中的問題。

停用映像封裝

為了進行疑難解答,您可以將建置屬性false設定$(EnableMauiImageProcessing)為項目檔中第一個<PropertyGroup>節點,以停用映像資源封裝:

<EnableMauiImageProcessing>false</EnableMauiImageProcessing>

停用啟動顯示畫面封裝

為了進行疑難解答,您可以在項目檔的第一個<PropertyGroup>節點中,將組建屬性設定$(EnableSplashScreenProcessing)false ,以停用啟動顯示畫面資源產生:

<EnableSplashScreenProcessing>false</EnableSplashScreenProcessing>

停用字型封裝

為了進行疑難解答,您可以在項目檔的第一個<PropertyGroup>節點中,將build屬性設定$(EnableMauiFontProcessing)false ,以停用字型資源封裝:

<EnableMauiFontProcessing>false</EnableMauiFontProcessing>

停用資產檔案封裝

為了進行疑難解答,您可以在項目檔的第一個<PropertyGroup>節點中,將組建屬性設定$(EnableMauiAssetProcessing)false ,以停用資產文件資源封裝:

<EnableMauiAssetProcessing>false</EnableMauiAssetProcessing>

產生空白啟動顯示畫面

為了進行疑難解答,如果您沒有 <MauiSplashScreen> 專案且沒有自定義啟動顯示畫面,則可以產生空白啟動顯示畫面。 若要達成此目的,請在項目檔的第一個<PropertyGroup>節點中將組建屬性設定$(EnableBlankMauiSplashScreen)true

<EnableBlankMauiSplashScreen>true</EnableBlankMauiSplashScreen>

產生空白啟動顯示畫面將會覆寫任何自定義啟動顯示畫面,並會導致 App Store 拒絕。 不過,在測試中,它可以是一種有用的方法,以確保您的應用程式 UI 正確無誤。

重複的影像檔名錯誤

您可能會遇到關於重複映像檔名的建置錯誤:

偵測到一或多個重複的檔名。 所有影像輸出檔名都必須是唯一的。

因為從 .NET 8,.NET MAUI 會檢查 ,以確保沒有重複的影像資源檔名,因此會發生此情況MauiIconMauiImage

當您在多個資料夾中有相同的檔名,而且在某些情況下,當您在不同的資料夾中有相同擴展名時,就會發生此錯誤。 例如,PNG 檔案會在 Resources/Images/PNG/dotnet_bot.png 和 RESOURCES/Images/SVG/dotnet_bot.svg 的 PNG 檔案發生建置錯誤,因為 SVG 檔案會在建置階段轉換成 PNG 檔案。

如果您在 Include 專案上使用 MauiImage 屬性來包含資料夾中的所有影像,然後同時包含特定的影像檔,也會發生錯誤:

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

如果您收到此建置錯誤,可以藉由確保您的項目檔不包含重複的影像來修正。 若要這樣做,請變更參考特定檔案的任何 MauiIconMauiImage ,以使用 Update 屬性,而不是 Include 屬性:

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

如需 MSBuild 專案專案屬性的相關信息,請參閱 Item 元素 (MSBuild): 屬性和元素