通过

排查已知问题

  • 项目

本文介绍 .NET Multi-platform App 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 SDK 版本并运行 dotnet workload install maui 命令重新安装 .NET 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 - 故障排除。

“默认”类型或命名空间不存在

使用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 的根命名空间。 此冲突会导致这些平台与包含 Contacts 类型的 Microsoft.Maui.ApplicationModel.Communication 命名空间发生冲突。 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

生成应用时，.NET for iOS 和 .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 Hybrid 应用中的问题

BlazorWebView 具有内置日志记录，可帮助诊断 Blazor Hybrid 应用中的问题。 启用此日志记录分为两个步骤：

  1. 启用 BlazorWebView 和相关组件来记录诊断信息。
  2. 配置记录器以将日志输出写入到可以查看的位置。

有关详细信息，请参阅诊断 Blazor Hybrid 应用中的问题。

禁用图像打包

出于故障排除目的，可以通过将 $(EnableMauiImageProcessing) 生成属性设置为项目文件中第一个 <PropertyGroup> 节点中的 false 禁用图像资源打包：

<EnableMauiImageProcessing>false</EnableMauiImageProcessing>

禁用初始屏幕打包

出于故障排除目的，可以通过将 $(EnableSplashScreenProcessing) 生成属性设置为项目文件中第一个 <PropertyGroup> 节点中的 false 禁用初始屏幕资源生成：

<EnableSplashScreenProcessing>false</EnableSplashScreenProcessing>

禁用字体打包

出于故障排除目的，可以通过将 $(EnableMauiFontProcessing) 生成属性设置为项目文件中第一个 <PropertyGroup> 节点中的 false 禁用字体资源打包：

<EnableMauiFontProcessing>false</EnableMauiFontProcessing>

禁用资产文件打包

出于故障排除目的，可以通过将 $(EnableMauiAssetProcessing) 生成属性设置为项目文件中第一个 <PropertyGroup> 节点中的 false 禁用资产文件资源打包：

<EnableMauiAssetProcessing>false</EnableMauiAssetProcessing>

生成空白初始屏幕

出于故障排除目的，如果没有 <MauiSplashScreen> 项且没有自定义初始屏幕，则可以生成空白初始屏幕。 这可以通过将 $(EnableBlankMauiSplashScreen) 生成属性设置为项目文件中第一个 <PropertyGroup> 节点中的 true 实现：

<EnableBlankMauiSplashScreen>true</EnableBlankMauiSplashScreen>

生成空白初始屏幕将替代任何自定义初始屏幕，并会导致 App Store 拒绝。 但是，在测试中，它可以是一种有用的方法，可确保应用 UI 正确。

图像文件名重复错误

可能会遇到有关图像文件名重复的生成错误：

检测到一个或多个重复的文件名。 所有图像输出文件名都必须是唯一的。

由于 .NET 8、.NET MAUI 检查，因此 MauiIcon 与 MauiImage 项会发生这种情况，以确保没有重复的图像资源文件名。

如果多个文件夹中存在相同文件名，以及在某些情况下，不同文件夹中存在具有不同扩展名的相同文件名，则将会发生此错误。 例如，Resources/Images/PNG/dotnet_bot.png 上的 PNG 文件以及 Resources/Images/SVG/dotnet_bot.svg 上的 SVG 文件将会发生生成错误，因为 SVG 文件在生成时转换为 PNG 文件。

如果在 MauiImage 项上使用 Include 特性将所有图像包括在文件夹中，然后还包括特定的图像文件，则也会发生此错误：

<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 项元素属性的信息，请参阅项元素 (MSBuild)：特性和元素。