對已知問題進行疑難排解

  • 發行項

本文說明 .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 命令。

Mac：

Visual Studio for Mac 的安裝程式和更新程式會使用 dotnet workload install 命令來安裝 .NET MAUI .pkg 檔案。

由於 無法卸載.pkg 檔案，在 Mac 上卸載工作負載最簡單的方法是執行下列命令來刪除指定的資料夾：

rm -r ~/.dotnet/
sudo rm -r /usr/local/share/dotnet/

執行這些命令之後，您應該能夠透過 Visual Studio for Mac 重新安裝 .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 for Mac 可能會顯示「目前未安裝 Xcode 或找不到」訊息。 在此案例中，請檢查您也已安裝來自 App Store 的 Xcode。 然後，啟動 Xcode 並移至 [Xcode > 喜好 > 設定位置 > ] 命令行工具 ，並檢查下拉式清單是否空白。 如果是空的，請選取下拉式清單，然後選取 Xcode 命令行工具的位置。 然後關閉 Xcode 並重新啟動 Visual Studio for Mac。

找不到有效的 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

建置應用程式時，.NET iOS 和 .NET Mac Catalyst 會使用下列程式來判斷要使用的 Xcode 版本：

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

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

然後，您可以從您的計算機安全地刪除 ~/Library/Preferences/Xamarin/設定.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" />

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

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

如需 MSBuild 專案專案屬性的相關信息，請參閱 Item 元素 （MSBuild）： 屬性和元素。