用 Xamarin 构建的 tvOS 应用疑难解答Troubleshooting tvOS apps built with Xamarin

本文介绍了在使用 Xamarin 的 tvOS 支持时可能遇到的问题。This article covers know issues you might encounter while working with Xamarin's tvOS support.

已知问题Known Issues

Xamarin 的 tvOS 支持的当前版本具有以下已知问题:The current release of Xamarin's tvOS support has the following known issues:

  • Mono Framework –单声道 4.3 ProtectedData 无法解密 mono 4.2 中的数据。Mono Framework – Mono 4.3 Cryptography.ProtectedData fails to decrypt data from Mono 4.2. 因此,当配置受保护的 NuGet 源时,NuGet 包将无法还原,并 Data unprotection failed 错误。As a result, NuGet packages will fail to restore with the error Data unprotection failed when a protected NuGet source is configured.
    • 解决方法–在 Visual Studio for Mac 中,你将需要添加回使用密码身份验证的任何 NuGet 包源,然后再重新尝试还原包。Workaround – In Visual Studio for Mac you will need to add back any NuGet package sources that use password authentication before re-attempting to restore the packages.
  • Visual Studio for Mac w/ F#外接程序–在 Windows 上创建F# Android 模板时出错。Visual Studio for Mac w/ F# Add-in – Error when creating an F# Android template on Windows. 这仍应在 Mac 上正常运行。This should still function correctly on Mac.
  • Xamarin –运行包含目标框架且设置为 Unsupported的 Xamarin 统一模板项目时,可能会出现弹出 Could not connect to the debuggerXamarin.Mac – When running the Xamarin.Mac unified template project with the target Framework set to Unsupported, the popup Could not connect to the debugger may appear.
    • 可能的解决方法–降级稳定通道中可用的 Mono framework 版本。Potential Workaround – Downgrade the Mono framework version available in our Stable channel.
  • Xamarin Visual studio & xamarin –在 Visual Studio 中部署 WatchKit 应用程序时,可能会出现 The file ‘bin\iPhoneSimulator\Debug\WatchKitApp1WatchKitApp.app\WatchKitApp1WatchKitApp’ does not exist 错误。Xamarin Visual Studio & Xamarin.iOS – When deploying WatchKit applications in Visual studio, the error The file ‘bin\iPhoneSimulator\Debug\WatchKitApp1WatchKitApp.app\WatchKitApp1WatchKitApp’ does not exist may appear.

请在GitHub上报告你发现的任何错误。Please report any bugs you find on GitHub.

疑难解答Troubleshooting

以下部分列出了在将 tvOS 9 与 tvOS 结合使用时可能出现的一些已知问题,以及针对这些问题的解决方案:The following sections list some known issues that can occur when using tvOS 9 with Xamarin.tvOS and the solution to those issues:

可执行文件无效-可执行文件不包含 bitcodeInvalid Executable - The executable does not contain bitcode

尝试将 tvOS 应用提交到 Apple TV 应用商店时,可能会收到 "无效可执行文件-可执行文件不包含 bitcode" 格式的错误消息。When attempting to submit a Xamarin.tvOS app to the Apple TV App Store, you might get an error message in the form "Invalid Executable - The executable does not contain bitcode".

若要解决此问题,请执行以下操作:To solve this issue, do the following:

  1. 在 Visual Studio for Mac 中,右键单击解决方案资源管理器中的 TvOS 项目文件,然后选择 "选项"。In Visual Studio for Mac, right-click on your Xamarin.tvOS Project File in the Solution Explorer and select Options.

  2. 选择 " TvOS 生成",并确保你在 "发布" 配置上:Select tvOS Build and ensure that you are on the Release configuration:

  3. --bitcode=asmonly 添加到 "其他 mtouch 参数" 字段,然后单击 "确定" 按钮。Add --bitcode=asmonly to the Additional mtouch arguments field and click the OK button.

  4. 发布配置中重新生成应用。Rebuild your app in the Release configuration.

验证 tvOS 应用程序是否包含 BitcodeVerifying that your tvOS App Contains Bitcode

若要验证 tvOS 应用版本是否包含 Bitcode,请打开终端应用并输入以下内容:To verify that your Xamarin.tvOS App build contains Bitcode, open the Terminal app and enter the following:

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

在输出中,查找以下内容:In the output, look for the following:

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

addrsize 将有所不同,但其他字段应相同。addr and size will be different but other fields should be identical.

你将需要确保你使用的任何第三方静态(.a)库是针对 tvOS 库(而不是 iOS 库)构建的,并且它们还包括 bitcode 信息。You will need to make sure that any third party static (.a) libraries you're using were built against tvOS libraries (not iOS libraries) and that they also includes bitcode information.

对于包含有效 bitcode 的应用或库,size 将大于1。For apps or libraries that include valid bitcode the size will be greater than one. 在某些情况下,库可以具有 bitcode 标记,但不包含有效的 bitcode。There are some situations where a library can have the bitcode marker, yet not contain valid bitcode. 例如:For example:

无效的 BitcodeInvalid Bitcode

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

有效的 BitcodeValid Bitcode

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

请注意上面列出的示例中两个库之间 size 的差异。Note the difference in size between the two libraries in the listed example runs above. 必须从启用了 bitcode 的 Xcode 存档版本(Xcode 设置 ENABLE_BITCODE)生成库,作为此大小问题的解决方案。The library must be generated from a Xcode archive build with bitcode enabled (Xcode setting ENABLE_BITCODE) as a solution to this size problem.

仅包含 arm64 切片的应用还必须在信息 info.plist 中的 UIRequiredDeviceCapabilities 列表中包含 "arm64"。Apps that only contain the arm64 slice must also have “arm64” in the list of UIRequiredDeviceCapabilities in Info.plist

将应用提交到 Apple TV App Store 进行发布时,可能会出现以下格式的错误:When submitting an app to the Apple TV App Store for publication, you might get an error in the form:

"仅包含 arm64 切片的应用还必须在 info.plist 的 UIRequiredDeviceCapabilities 列表中包含" arm64 ""Apps that only contain the arm64 slice must also have “arm64” in the list of UIRequiredDeviceCapabilities in Info.plist"

如果出现这种情况,请编辑 Info.plist 文件,并确保其具有以下键:If this occurs, edit your Info.plist file and ensure that it has the following keys:

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

重新编译你的应用程序以进行发布,并重新提交到 iTunes Connect。Recompile your app for release and resubmit to iTunes Connect.

任务 "MTouch" 执行失败Task "MTouch" execution -- FAILED

如果你使用的是第三方库(如 MonoGame),并且你的发布编译失败,并在 Task "MTouch" execution -- FAILED结束的一系列长错误消息,请尝试将 -gcc_flags="-framework OpenAL" 添加到其他 touch 参数If you are using a 3rd party library (such as MonoGame) and your release compile failed with a long series of error messages ending in Task "MTouch" execution -- FAILED, try adding -gcc_flags="-framework OpenAL" to your Additional touch arguments:

还应将 --bitcode=asmonly 添加到其他 touch 参数中,将链接器选项设置为 "全部链接",并执行 "干净编译"。You should also include --bitcode=asmonly in the Additional touch arguments, have your linker options set to Link All and do a clean compile.

ITMS-90471 错误。ITMS-90471 error. 缺少大图标The Large icon is missing

如果收到消息,格式为 "ITMS-90471 error"。If you get a message in the form "ITMS-90471 error. 尝试将 tvOS 应用提交到 Apple TV 应用商店进行发布时,缺少大图标 ",请检查以下各项:The Large icon is missing" while attempting to submit a Xamarin.tvOS app to the Apple TV App Store for release, please check the following:

  1. 确保已在你使用应用程序图标文档创建的 Assets.car 文件中包含了大图标资产。Ensure that you have included the Large Icon assets in your Assets.car file that you created using the App Icons documentation.
  2. 确保在最终的应用程序捆绑包中包括使用图标和图像文档的 Assets.car 文件。Ensure that you included the Assets.car file from the Working with Icons and Images documentation in your final application bundle.

无效的捆绑–支持游戏控制器的应用还必须支持 Apple TV 远程Invalid bundle – An app that supports game controllers must also support the Apple TV remote

or

无效的捆绑包–带有 GameController 框架的 Apple 电视应用程序的信息中必须包括 GCSupportedGameControllers 键。 info.plistInvalid bundle – Apple TV apps with the GameController framework must include the GCSupportedGameControllers key in the app’s Info.plist

游戏控制器可用于增强游戏,并在游戏中提供浸入式。Game Controllers can be used to enhance gameplay and provide a sense of immersion in a game. 它们还可用于控制标准 Apple TV 界面,因此用户无需在远程和控制器之间切换。They can also be used to control the standard Apple TV interface so the user doesn't have to switch between the remote and the controller.

如果你要将具有游戏控制器支持的 Xamarin tvOS 应用提交到 Apple TV 应用商店,并且你将收到如下所示的错误消息:If you are submitting a Xamarin.tvOS app with Game Controller support to the Apple TV App store and you are getting an error message in the form of:

我们发现你最近的 "应用名称" 传递有一个或多个问题。你的交付已成功完成,但你可能希望在下一次传递时更正以下问题:We have discovered one or more issues with your recent delivery for “app name”. Your delivery was successful, but you may wish to correct the following issues in your next delivery:

无效的捆绑–支持游戏控制器的应用也必须支持 Apple TV 远程。Invalid bundle – An app that supports game controllers must also support the Apple TV remote.

or

无效的捆绑包–具有 GameController 框架的 Apple TV 应用必须在应用的 info.plist 中包含 GCSupportedGameControllers 键。Invalid bundle – Apple TV apps with the GameController framework must include the GCSupportedGameControllers key in the app’s Info.plist.

解决方法是将对 Siri 远程(GCMicroGamepad)的支持添加到应用的 Info.plist 文件中。The solution is to add support for the Siri Remote (GCMicroGamepad) to your app's Info.plist file. Apple 添加了微型游戏控制器配置文件以面向 Siri 远程。The Micro Game Controller profile has been added by Apple to target the Siri Remote. 例如,包括以下项:For example, include the following keys:

<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/>

重要

蓝牙游戏控制器是最终用户可能会进行的可选购买,你的应用程序无法强制用户购买一个。Bluetooth Game Controllers are an optional purchase that end users might make, your app cannot force the user to purchase one. 如果你的应用程序支持游戏控制器,则它还必须支持 Siri 远程,以便所有 Apple TV 用户都可以使用该游戏。If your app supports Game Controllers it must also support the Siri Remote so that the game is useable by all Apple TV users.

有关详细信息,请参阅我们的Siri 远程和蓝牙控制器文档中的使用游戏控制器部分。For more information, please see our Working with Game Controllers section of our Siri Remote and Bluetooth Controllers documentation.

目标框架不兼容:。NetPortable,Version = 5v,Profile = Profile78Incompatible target framework: .NetPortable, Version=v4.5, Profile=Profile78

尝试在 tvOS 项目中包含可移植类库(PCL)时,可能会在中看到一条消息:When trying to include a Portable Class Library (PCL) into a Xamarin.tvOS project you might get a message in to form:

目标框架不兼容:。NetPortable,Version = 5v,Profile = Profile78Incompatible target framework: .NetPortable, Version=v4.5, Profile=Profile78

若要解决此问题,请添加一个名为 Xamarin.TVOS.xml 的 XML 文件,其中包含以下内容:To solve this issue, add an XML file called Xamarin.TVOS.xml with the following content:

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

到以下路径:To the following path:

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

请注意,路径中的配置文件编号必须与 PCL 的配置文件编号匹配。Note that the profile number in the path must match the profile number of the PCL.

准备好此文件后,应该能够成功地将 PCL 文件添加到 tvOS 项目。With this file in place, you should be able to successfully add the PCL file to the Xamarin.tvOS project.