排查使用 Xamarin 生成的 tvOS 应用问题

本文介绍了在使用 Xamarin 的 tvOS 支持时可能会遇到的问题。

已知问题

Xamarin 的 tvOS 支持的当前版本存在以下已知问题：

• Mono Framework - Mono 4.3 Cryptography.ProtectedData 无法解密 Mono 4.2 中的数据。 因此，在配置受保护的 NuGet 源时，NuGet 包将无法还原并出现错误 Data unprotection failed。
  • 解决方法 - 在 Visual Studio for Mac 中，需要在重新尝试还原包之前重新添加使用密码身份验证的任何 NuGet 包源。
• Visual Studio for Mac w/ F# 加载项 - 在 Windows 上创建 F# Android 模板时出错。 这仍应在 Mac 上正常运行。
• Xamarin.Mac - 在运行目标框架设置为 Unsupported 的 Xamarin.Mac 统一模板项目时，可能会显示弹出窗口 Could not connect to the debugger。
  • 可能的解决方法 - 降级稳定频道中提供的 Mono 框架版本。
• Xamarin Visual Studio 和 Xamarin.iOS - 在 Visual Studio 中部署 WatchKit 应用程序时，可能会出现错误 The file ‘bin\iPhoneSimulator\Debug\WatchKitApp1WatchKitApp.app\WatchKitApp1WatchKitApp’ does not exist。

请在 GitHub 上报告发现的任何 bug。

疑难解答

以下部分列出了将 tvOS 9 与 Xamarin.tvOS 配合使用时可能发生的一些已知问题，以及这些问题的解决方案：

可执行文件无效 - 可执行文件不包含 bitcode

尝试将 Xamarin.tvOS 应用提交到 Apple TV App Store 时，可能会收到以下形式的错误消息“可执行文件无效 - 可执行文件不包含 bitcode”。

要解决此问题，请执行以下操作：

1. 在 Visual Studio for Mac 中，右键单击解决方案资源管理器中的 Xamarin.tvOS 项目文件，然后选择“选项”。

2. 选择“tvOS 内部版本”并确保你处于“发布”配置：

   

3. 将 --bitcode=asmonly 添加到“其他 mtouch 参数”字段，然后单击“确定”按钮。

4. 在“发布”配置中重新生成应用。

验证 tvOS 应用是否包含 Bitcode

要验证 Xamarin.tvOS 应用内部版本是否包含 Bitcode，请打开终端应用并输入以下内容：

otool -l /path/to/your/tv.app/tv

在输出中，查找以下内容：

Section
  sectname __bundle
   segname __LLVM
      addr 0x0000000100001000
      size 0x000000000000124f
    offset 4096
     align 2^0 (1)
    reloff 0
    nreloc 0
     flags 0x00000000
 reserved1 0
 reserved2 0

addr 和 size 会有所不同，但其他字段应相同。

你需要确保使用的任何第三方静态（.a）库都是针对 tvOS 库（而不是 iOS 库）构建的，并且它们还包括 Bitcode 信息。

对于包含有效 Bitcode 的应用或库，size 将大于 1。 在某些情况下，库可以具有 Bitcode 标记，但不包含有效的 Bitcode。 例如：

无效的 Bitcode

 $ otool -arch arm64 libLibrary.a | grep __bitcode -A 3
   sect name __bitcode
   segname __LLVM
      add 0x0000000000000670
      size 0x0000000000000001

有效的 Bitcode

$ otool -l -arch arm64 libDownloadableAgent-tvos.a |grep __bitcode -A 3
   sectname __bitcode
   segname __LLVM
      addr 0x000000000001d2d0
      size 0x0000000000045440

请注意上述示例中两个库之间 size 的差异。 必须根据启用了 Bitcode 的 Xcode 存档版本（Xcode 设置 ENABLE_BITCODE）生成该库，作为解决此大小问题的解决方案。

仅包含 arm64 切片的应用还必须在 Info.plist 的 UIRequiredDeviceCapabilities 列表中包含“arm64”

将应用提交到 Apple TV App Store 进行发布时，你可能会收到以下形式的错误：

“仅包含 arm64 切片的应用还必须在 Info.plist 的 UIRequiredDeviceCapabilities 列表中包含‘arm64’”

如果发生这种情况，请编辑 Info.plist 文件并确保其包含以下关键值：

<key>UIRequiredDeviceCapabilities</key>
<array>
  <string>arm64</string>
</array>

重新编译应用以发布并重新提交到 iTunes Connect。

任务“MTouch”执行 - 失败

如果使用的是第三方库（如 MonoGame），并且发布编译失败，而且出现大量以 Task "MTouch" execution -- FAILED 结尾的错误消息，请尝试将 -gcc_flags="-framework OpenAL" 添加到“其他触摸参数”：

还应在“其他触摸参数”中包含 --bitcode=asmonly，将链接器选项设置为“全部链接”并执行干净编译。

ITMS-90471 错误。 缺少大型图标

如果收到格式为“ITMS-90471 错误”的消息。 尝试将 Xamarin.tvOS 应用提交到 Apple TV App Store 以进行发布时，出现“大型图标缺失”，请检查以下内容：

1. 确保已将大型图标资产包含在使用应用图标文档创建的 Assets.car 文件中。
2. 请确保在最终的应用程序捆绑包中包含使用图标和图像文档中的 Assets.car 文件。

无效捆绑包 - 支持游戏控制器的应用还必须支持 Apple TV 遥控模式

或

无效捆绑包 - 具有 GameController 框架的 Apple TV 应用必须在应用的 Info.plist 中包含 GCSupportedGameControllers 键

游戏控制器可用于增强游戏玩法，并提供游戏中的沉浸感。 它们还可用于控制标准 Apple TV 接口，因此用户不必在遥控模式和控制器之间切换。

如果要向 Apple TV App Store 提交具有游戏控制器支持的 Xamarin.tvOS 应用，并且收到以下格式的错误消息：

我们发现了最近交付“应用名称”的一个或多个问题。 交付已成功，但你可能希望在下一次交付中更正以下问题：

无效捆绑包 - 支持游戏控制器的应用还必须支持 Apple TV 遥控模式。

或

无效捆绑包 - 具有 GameController 框架的 Apple TV 应用必须在应用的 Info.plist 中包含 GCSupportedGameControllers 键。

解决方案是将对 Siri Remote（GCMicroGamepad）的支持添加到应用的 Info.plist 文件中。 Apple 已添加了面向 Siri 遥控的 Micro Game Controller 配置文件。 例如，包括以下键：

<key>GCSupportedGameControllers</key>  
  <array>  
    <dict>  
      <key>ProfileName</key>  
      <string>ExtendedGamepad</string>  
    </dict>  
    <dict>  
      <key>ProfileName</key>  
      <string>MicroGamepad</string>  
    </dict>  
  </array>  
<key>GCSupportsControllerUserInteraction</key>  
<true/>

重要

蓝牙游戏控制器是最终用户可以购买的可选商品，你的应用无法强制用户购买一个。 如果你的应用支持游戏控制器，它还必须支持 Siri 遥控，以便游戏可由所有 Apple TV 用户使用。

有关详细信息，请参阅 Siri 遥控和蓝牙控制器文档的“使用游戏控制器”部分。

不兼容的目标框架：.NetPortable、Version=v4.5、Profile=Profile78

尝试将可移植类库 (PCL) 包含在 Xamarin.tvOS 项目中时，可能会收到以下形式的消息：

不兼容的目标框架：.NetPortable、Version=v4.5、Profile=Profile78

要解决此问题，请添加包含以下内容，名为 Xamarin.TVOS.xml 的 XML 文件：

<Framework Identifier="Xamarin.TVOS" MinimumVersion="1.0" Profile="*" DisplayName="Xamarin.TVOS"/>

指向以下路径：

/Library/Frameworks/Mono.framework/Versions/Current/lib/mono/xbuild-frameworks/.NETPortable/v4.5/Profile/Profile259/SupportedFrameworks/

请注意，路径中的配置文件编号必须与 PCL 的配置文件编号匹配。

借助此文件，你应该能够成功将 PCL 文件添加到 Xamarin.tvOS 项目。

相关链接

• tvOS
• tvOS 人机界面指南
• tvOS 的应用编程指南