通过

更新现有 Mac 应用

  • 项目

更新现有应用以使用 Unified API 需要更改项目文件本身以及应用程序代码中使用的命名空间和 API。

改为使用 64 位

需要新的 Unified API 才能从 Xamarin.Mac 应用程序支持 64 位设备体系结构。 截至 2015 年 2 月 1 日，Apple 要求向 Mac App Store 提交的所有新应用都支持 64 位体系结构。

Xamarin 为 Visual Studio for Mac 和 Visual Studio 提供工具，以自动执行从 Classic API 到 Unified API 的迁移过程，也可以手动转换项目文件。 虽然强烈建议使用自动工具，但本文将介绍这两种方法。

准备工作

在将现有代码更新到 Unified API 之前，强烈建议消除所有编译警告。 迁移到 Unified 后，Classic API 中的许多警告将成为错误。 在开始之前修复它们会更容易，因为 Classic API 中的编译器消息通常提供有关要更新的内容的提示。

自动更新

修复警告后，在 Visual Studio for Mac 或 Visual Studio 中选择现有 Mac 项目，并从“项目”菜单中选择“迁移到 Xamarin.Mac Unified API”。 例如：

Choose Migrate to Xamarin.Mac Unified API from the Project menu

在自动迁移运行之前，需要同意此警告（显然，在开始此冒险之前，应确保拥有备份/源代码管理）：

Agree to this warning before the automated migration will run

在 Xamarin.Mac 应用程序中使用 Unified API 时，可以选择两种受支持的目标框架类型：

  • Xamarin.Mac Mobile Framework - 这与 Xamarin.iOS 和 Xamarin.Android 使用的经过调整的 .NET 框架相同，支持完整桌面框架的子集。 这是建议的框架，因为它具有卓越的链接行为，进而可提供较小的平均二进制文件。
  • Xamarin.Mac .NET 4.5 Framework - 此框架也是桌面框架的子集。 但是，与移动框架相比，它对完整桌面框架的削减要少得多，并且应该“仅适用于”大多数 NuGet 包或第三方库。 这样，开发人员就可以使用标准桌面程序集，同时仍使用受支持的框架，但此选项会生成更大的应用程序捆绑包。 这是建议的框架，其中使用与 Xamarin.Mac 移动框架不兼容的第三方 .NET 程序集。 有关支持的程序集的列表，请参阅我们的程序集文档。

有关目标框架的详细信息以及为 Xamarin.Mac 应用程序选择特定目标的含义，请参阅我们的目标框架文档。

该工具其实就是自动执行以下“手动更新”部分中概述的所有步骤，并且是将现有 Xamarin.Mac 项目转换为 Unified API 的建议方法。

手动更新的步骤

同样，修复警告后，请按照以下步骤手动更新 Xamarin.Mac 应用以使用新的 Unified API：

1. 更新项目类型和生成目标

将 csproj 文件中的项目风格从 42C0BBD9-55CE-4FC1-8D90-A7348ABAFB23 更改为 A3F8F2AB-B479-4A4A-A458-A89E7DC349F1。 在文本编辑器中编辑 csproj 文件，替换 <ProjectTypeGuids> 元素中的第一项，如下所示：

Edit the csproj file in a text editor, replacing the first item in the ProjectTypeGuids element as shown

将包含 Xamarin.Mac.targets 的 Import 元素更改为 Xamarin.Mac.CSharp.targets，如下所示：

Change the Import element that contains Xamarin.Mac.targets to Xamarin.Mac.CSharp.targets as shown

在 <AssemblyName> 元素后面添加以下代码行：

<TargetFrameworkVersion>v2.0</TargetFrameworkVersion>
<TargetFrameworkIdentifier>Xamarin.Mac</TargetFrameworkIdentifier>

示例：

Add these lines of code after the <AssemblyName> element

2. 更新项目引用

展开 Mac 应用程序项目的“引用”节点。 它最初将显示类似于此屏幕截图的 *broken- XamMac 引用（因为我们刚刚更改了项目类型）：

It will initially show a broken- XamMac reference similar to this screenshot

单击 XamMac 项旁边的齿轮图标，然后选择“删除”以移除损坏的引用。

接下来，在 Solution Pad 中，右键单击“解决方案资源管理器”中的 References 文件夹，然后选择“编辑首选项”。 滚动到引用列表的底部，并在 Xamarin.Mac 旁边勾选对号。

Scroll to the bottom of the list of references and place a check besides Xamarin.Mac

按“确定”保存项目引用更改。

3. 从命名空间中移除 MonoMac

从 using 语句中的命名空间中移除 MonoMac 前缀，或者在类名已完全限定的位置进行此操作（例如 MonoMac.AppKit 直接变为 AppKit）。

4.重新映射类型

引入了本机类型，以替换以前使用的一些类型，例如带有 CoreGraphics.CGRect 的 System.Drawing.RectangleF 实例（示例）。 可以在本机类型页上找到类型的完整列表。

5.修复方法替代

某些 AppKit 方法的签名已更改，以使用新的本机类型（例如 nint）。 如果自定义子类重写这些方法，签名将不再匹配，并将导致错误。 通过更改子类以匹配使用本机类型的新签名，可以修复这些方法替代。

注意事项

将现有 Xamarin.Mac 项目从 Classic API 转换为新的 Unified API（如果该应用依赖于一个或多个组件或 NuGet 包）时，应考虑以下注意事项。

组件

应用程序中包含的任何组件也需要更新为 Unified API，否则在尝试编译时会出现冲突。 对于任何包含的组件，请将当前版本替换为支持 Unified API 的 Xamarin 组件存储中的新版本，并执行全新生成。 作者尚未转换的任何组件都将在组件存储中显示仅 32 位警告。

NuGet 支持

虽然我们贡献了 NuGet 的更改以使用 Unified API 支持，但尚未推出 NuGet 的新版本，因此我们正在评估如何让 NuGet 识别新 API。

在此之前，与组件一样，需要将项目中包含的任何 NuGet 包切换到支持 Unified API 的版本，然后执行干净生成。

重要

如果在将应用程序转换为 Unified API 之后收到以下形式的错误，这通常是因为项目中有组件或 NuGet 包尚未更新到 Unified API：“错误 3 无法在相同的 Xamarin.Mac 项目中同时包含 "monomac.dll" 和 "Xamarin.Mac.dll" - "Xamarin.Mac.dll" 被显式引用，而 "monomac.dll" 按 "xxx, Version=0.0.000, Culture=neutral, PublicKeyToken=null" 引用”。 需要删除现有组件/NuGet，更新到支持 Unified API 的版本并执行干净生成。

启用 Xamarin.Mac 应用的 64 位版本

对于已转换为 Unified API 的 Xamarin.Mac 移动应用程序，开发人员仍需要从应用的“选项”中为 64 位计算机启用应用程序生成。 有关启用 64 位版本的详细说明，请参阅 32/64 位平台注意事项文档中的启用 Xamarin.Mac 应用的 64 位版本。

完成

无论是选择使用自动方法还是手动方法将 Xamarin.Mac 应用程序从 Classic API 转换为 Unified API，都有几个实例需要进一步的手动干预。 有关已知问题和解决方法，请参阅文档将代码更新到 Unified API 的提示。