Xamarin.iOS 中的 IPA 支持IPA Support in Xamarin.iOS

本文介绍如何创建可通过 Ad Hoc 分发用来部署应用程序的 IPA 文件,用于内部应用程序的测试或内部分发。 This article covers how to create an IPA file that can be used to deploy an application using Ad Hoc distribution, either for testing, or for In-House distribution of internal applications.

除了通过 iTunes App Store 发布应用程序进行出售,还可部署它用于以下用途:In addition to releasing an application for sale through the iTunes App Store, it can be deployed for the following uses:

  • Ad Hoc 测试 - iOS 应用程序最多可向 100 名用户(由特定 iOS 设备 UUID 标识)部署,用于 Alpha 和 Beta 测试目的。Ad Hoc Testing — An iOS application can be deployed to up to 100 users (identified by specific iOS device UUIDs) for Alpha and Beta testing purposes. 请参阅预配用于开发的 iOS 设备文档,了解向 Apple 开发人员帐户添加测试 iOS 设备的相关详细信息,并请参阅 Ad-Hoc 指南,了解如何以此方法进行分发的相关详细信息。See our Provisioning an iOS Device for Development documentation for detailed information on adding test iOS devices to your Apple developer account, and the Ad-Hoc guide, for more information on how to distribute in this way.
  • 内部/企业部署 - 可在公司内部部署 iOS 应用程序,这需要 Apple 开发人员企业计划的成员身份。In House / Enterprise Deployment — An iOS application can be deployed internally, within a company, which requires membership of Apple's Developer Enterprise program. 内部分发指南中详细介绍了内部分发的相关详细信息。More information on In House Distribution is detailed in the In House Distribution guide.

在任一情况下,都必须创建 IPA 包(特殊类型的 zip 文件),并使用正确的分发配置文件进行数码签名。In either case, an IPA package (a special type of zip file) must be created and digitally signed with the correct Distribution Provisioning Profile. 本文介绍在 Mac 或 Windows 电脑上使用 iTunes 生成 IPA 包,并在 iOS 设备上进行安装的所需步骤。This article covers the steps required to build the IPA package and install the package on an iOS device using iTunes on a Mac or Windows PC.

iTunesMetadata.plist 文件The iTunesMetadata.plist File

在 iTunes Connect 中创建 iOS 应用程序(无论是用于在 iTunes App Store 中销售还是免费发布)时,开发人员可指定应用程序类型、子类型、版权声明、支持的 iOS 设备和必需设备功能等信息。When an iOS application is created in iTunes Connect (either for sale or free release from the iTunes App Store), the developer can specify information such as the application's genre, sub genre, copyright notice, supported iOS devices and required device capabilities.

通过 Ad Hoc 分发或 In-House 分发传递的 iOS 应用程序需以某种方式支持此信息,使它在 iTunes 和用户设备上可见。iOS applications that are delivered either via Ad Hoc or In-House distribution, need to have some way to support this information so that it can be visible on iTunes and the user's device. 默认情况下,每次生成项目时都会创建小型 iTunesMetadata.plist 文件,并保存在项目目录中。By default, a small iTunesMetadata.plist file is created every time you build your project and is stored in the project directory.

也可创建自定义 iTunesMetadata.plist 提供分发的其他信息。A custom iTunesMetadata.plist can also be created to supply the additional information to a distribution. 若要了解有关此文件内容以及如何创建该文件的详细信息,请参阅 iTunesMetadata.plist 内容创建 iTunesMetadata.plist 文件文档。To find out more about the content of this file and how to create it, please see our The iTunesMetadata.plist Contents and Creating an iTunesMetadata.plist File documentation.

iTunes 图稿iTunes Artwork

通过非 App Store 方式传递应用时,还需要包括在 iTunes 中用于表示应用程序的 512x512 和 1024x1024 图像。When delivering your app through non-App Store means, you also need to include a 512x512 and a 1024x1024 image that will be used to represent your application in iTunes.

若要指定 iTunes 图稿,请执行以下操作:To specify the iTunes Artwork, do the following:

  1. 在“解决方案资源管理器” 中,双击 Info.plist 文件,打开它进行编辑。Double-click the Info.plist file in the Solution Explorer to open it for editing.
  2. 滚动到编辑器的“iTunes 图稿” 分区。Scroll to the iTunes Artwork section of the editor.
  3. 若有任何图像缺失,请单击编辑器中的缩略图,从“打开文件” 对话框中选择所需 iTunes 图稿的图像文件,然后单击“确定” 或“打开” 按钮。For any missing image, click on the thumbnail in the editor, select the image file for the desired iTunes artwork from the Open File dialog box and click the OK or Open button.
  4. 重复此步骤,直到已为应用程序指定所需的所有图像。Repeat this step until all needed images have been specified for your application.

请参阅 iTunes 图稿文档,了解详细信息。Please see the iTunes Artwork documentation for more details.

创建 IPACreating an IPA

创建 IPA 现已内置于新的发布工作流。Creating an IPA is now built into the new publishing workflow. 为此,请按照下面的指示存档应用、对其签名并保存 IPA。To do this, follow the instructions below to archive your app, sign it, and save your IPA.

在开始针对跨平台解决方案创建 IPA 之前,确保已选择 iOS 项目作为启动项目:Before starting to create an IPA for a cross-platform solution, ensure that you have selected the iOS project as your startup project:

生成存档Build your Archive

若要生成 IPA,需要创建应用程序发布版本的存档 。To build an IPA, an archive of a release build of our application needs to be created. 该存档包含应用及其相关标识信息。This Archive contains our app and identifying information about it.

  1. 在 Visual Studio for Mac 中选择“发布 | 设备” 配置: !Select the Release | Device configuration in Visual Studio for Mac: !

  2. 在“生成” 菜单中,选择“存档以供发布” :From the Build menu, select Archive for Publishing:

  3. 存档创建完成后,将显示“存档” 视图:Once the archive has been created, the Archives view will be displayed:

签名和分发应用Sign and Distribute your App

每次生成用于存档的应用程序时,都会自动打开“存档视图” ,显示所有已存档的项目(按解决方案分组)。Each time you build your application for Archive, it will automatically open the Archives View, displaying all archived projects; grouped by solution. 默认情况下,此视图只显示当前打开的解决方案。By default, this view only shows the current, open solution. 若要查看拥有存档的所有解决方案,请单击“显示所有存档” 选项。To see all solutions that have archives, click on the Show all archives option.

建议保留部署到客户(Ad-Hoc 或 In-House 部署)的存档,以便之后可代表生成的任何调试信息。It is recommended that archives deployed to customers (either Ad-Hoc or In-House deployments) be kept, so that any debug information that is generated can be symbolized at a later date.

请注意,对于非 App Store 版本,iTunesMetadata.plist 文件和 iTunes 图稿集将自动包含在 IPA 中(如果在存档中找到)。Note that for non-App Store builds the iTunesMetadata.plist file, and iTunes artwork set will automatically be included in your IPA if they are found in the archive.

对应用进行签名并准备分发:To sign your app and prepare it for distribution:

  1. 选择“签名并分发...” 按钮,如下所示:Select the Sign and Distribute... button, illustrated below:

  2. 这将打开发布向导。This will open the publishing wizard. 选择 Ad-Hoc 或“企业” (In-House) 分发渠道来创建包:Select the Ad-Hoc or Enterprise(In-House) distribution channel to create a package:

  3. 在“配置文件”屏幕上,选择签名标识和对应的配置文件,或使用其他标识重新签名:On the Provisioning Profile screen, select your signing identity and corresponding provisioning profile, or re-sign with another identity:

  4. 验证包的详细信息,然后单击“发布” :Verify the details of your package, and click Publish:

  5. 最后,将 IPA 保存到计算机:Finally, save your IPA to your machine:

(在 Mac 上)通过命令行生成Building via the Command Line (On Mac)

在某些情况下,如在 CI 环境中,可能需要通过命令行生成 IPA。In certain cases, such as in a CI environment, it may be necessary to build you IPA via the command line. 为此,请按照以下步骤进行操作:Follow the steps below to achieve this:

  1. 确保已选中“项目选项”>“iOS IPA 选项”>“包含 iTunes 图稿图像” ,并且已选中“生成 Ad-Hoc/企业包 (IPA)” :Ensure Project Options > iOS IPA Options > Include iTunesArtwork images is checked and Build ad-hoc/enterprise package (IPA) is checked:

    如果愿意,可转而在文本编辑器中编辑 .csproj 文件,并向将用于生成应用的配置的 PropertyGroup 手动添加两个对应属性:If you prefer, you can instead edit the .csproj file in a text editor and manually add the two corresponding properties to the PropertyGroup for the configuration that will be used to build the app:

    <BuildIpa>true</BuildIpa>
    <IpaIncludeArtwork>false</IpaIncludeArtwork>
    
  2. 如果要包含可选的 iTunesMetadata.plist 文件,请单击“...” 选项,从列表选择它,然后单击“确定” 按钮:If you are including an optional iTunesMetadata.plist file, click the ... button, select it from the list and click the OK button:

  3. 直接调用 msbuild 并在命令行上传递此属性:Call msbuild directly and pass this property on the command line:

    /Library/Frameworks/Mono.framework/Commands/msbuild YourSolution.sln /p:Configuration=Ad-Hoc /p:Platform=iPhone /p:BuildIpa=true
    

自定义 IPA 位置Customizing the IPA Location

已添加新的 MSBuild 属性 IpaPackageDir,使自定义 .ipa 文件输出位置更加轻松。A new MSBuild property IpaPackageDir has been added to make it easy to customize the .ipa file output location. 如果将 IpaPackageDir 设为自定义位置,则 .ipa 文件将放入该位置,而不是默认时间戳的子目录中。If IpaPackageDir is set to a custom location, the .ipa file will be placed in that location instead of the default timestamped subdirectory. 创建依赖特定目录路径才能正常工作的自动生成,如用于持续集成 (CI) 生成的生成,此操作会很有帮助。This can be useful when creating automated builds that rely on a specific directory path to work correctly, such as those used for Continuous Integration (CI) builds.

通过几种可能的方法使用新属性:There are several possible ways to use the new property:

例如,若要将 .ipa 文件输出到旧的默认目录(正如在 Xamarin.iOS 9.6 和更低版本中),可以使用以下其中一种方法将 IpaPackageDir 属性设为 $(OutputPath)For example, to output the .ipa file to the old default directory (as in Xamarin.iOS 9.6 and lower), you can set the IpaPackageDir property to $(OutputPath) using one of the following approaches. 两种方法都与所有 Unified API Xamarin.iOS 内部版本兼容,包括 IDE 版本,以及使用 msbuild、xbuild 或 mdtool 的命令行版本 :Both approaches are compatible with all Unified API Xamarin.iOS builds, including IDE builds as well as command-line builds that use msbuild, xbuild, or mdtool:

  • 第一个选项是,在 MSBuild 文件的 <PropertyGroup> 元素内,设置 IpaPackageDir 属性。The first option is to set the IpaPackageDir property within a <PropertyGroup> element in an MSBuild file. 例如,可将以下 <PropertyGroup> 添加到 iOS 应用项目 .csproj 文件的底部(右 </Project> 标记前):For example, you could add the following <PropertyGroup> to the bottom of the iOS app project .csproj file (just before the closing </Project> tag):

    <PropertyGroup>
        <IpaPackageDir>$(OutputPath)</IpaPackageDir>
    </PropertyGroup>
    
  • 更好的方法是将 <IpaPackageDir> 元素添加到现有 <PropertyGroup> 的底部,后者对应用于生成 .ipa 文件的配置。A better approach is to add a <IpaPackageDir> element to the bottom of the existing <PropertyGroup> that corresponds to the configuration used to build the .ipa file. 此方法更好,因为会在 iOS IPA 选项项目属性页上使用计划设置针对将来的兼容性准备项目。This is better because it will prepare the project for future compatibility with a planned setting on the iOS IPA Options project properties page. 如果当前使用 Release|iPhone 配置生成 .ipa 文件,完整的已更新属性组可能类似如下所示:If you currently use the Release|iPhone configuration to build the .ipa file, the complete updated property group might look similar to the following:

    <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|iPhone' ">
        <Optimize>true</Optimize>
        <OutputPath>bin\iPhone\Release</OutputPath>
        <ErrorReport>prompt</ErrorReport>
        <WarningLevel>4</WarningLevel>
        <ConsolePause>false</ConsolePause>
        <CodesignKey>iPhone Developer</CodesignKey>
        <MtouchUseSGen>true</MtouchUseSGen>
        <MtouchUseRefCounting>true</MtouchUseRefCounting>
        <MtouchFloat32>true</MtouchFloat32>
        <CodesignEntitlements>Entitlements.plist</CodesignEntitlements>
        <MtouchLink>SdkOnly</MtouchLink>
        <MtouchArch>;ARMv7, ARM64</MtouchArch>
        <MtouchHttpClientHandler>HttpClientHandler</MtouchHttpClientHandler>
        <MtouchTlsProvider>Default</MtouchTlsProvider>
        <PlatformTarget>x86&</PlatformTarget>
        <BuildIpa>true</BuildIpa>
        <IpaPackageDir>$(OutputPath</IpaPackageDir>
    </PropertyGroup>
    

另一种用于 msbuild 或 xbuild 命令行生成的方法是添加 /p: 参数来设置 IpaPackageDir 属性 。An alternate technique for msbuild or xbuild command-line builds is to add a /p: argument to set the IpaPackageDir property. 请注意,在这种情况下,msbuild 不会展开传入到命令行的 $() 表达式,因此不能使用 $(OutputPath) 语法。In this case note that msbuild does not expand $() expressions passed in on the command line, so it is not possible to use the $(OutputPath) syntax. 必须改为提供完整路径名称。You must instead provide a full path name. Mono 的 xbuild 命令确实会展开 $() 表达式,但仍建议使用完整路径名称,因为 xbuild 已因支持 msbuild 的跨平台版本 而被弃用。Mono's xbuild command does expand $() expressions, but it is still preferable to use a full path name because xbuild has been deprecated in favor of the cross-platform version of msbuild.

使用此方法的完整示例可能与 Windows 上的以下示例类似:A complete example that uses this approach might look similar to the following on Windows:

msbuild /p:Configuration="Release" /p:Platform="iPhone" /p:ServerAddress="192.168.1.3" /p:ServerUser="macuser" /p:IpaPackageDir="%USERPROFILE%\Builds" /t:Build SingleViewIphone1.sln

或 Mac 上以下示例:Or the following on Mac:

msbuild /p:Configuration="Release" /p:Platform="iPhone" /p:IpaPackageDir="$HOME/Builds" /t:Build SingleViewIphone1.sln

使用 iTunes 安装 IPAInstalling an IPA using iTunes

生成的 IPA 包可以传递给测试用户,以便在其 iOS 设备上安装或将其进行装运,用于企业部署。The resulting IPA Package can be delivered to your test users for installing on their iOS devices or shipped for Enterprise deployment. 无论选择哪种方法,最终用户都将在其 Mac 或 Windows 电脑上的 iTunes 应用程序中,通过双击 IPA 文件或将文件拖动到打开的 iTunes 窗口来安装包。No matter which method is chosen, the end user will install the package in their iTunes application on their Mac or Windows PC by double-clicking the IPA file (or dragging it onto the open iTunes window).

新的 iOS 应用程序将显示在“我的应用” 部分,在其中右键单击应用程序即可获取它的相关信息:The new iOS application will be shown in the My Apps section, where you can right-click on it and get information about the application:

用户现可将 iTunes 与设备同步,以安装新的 iOS 应用程序。The user can now sync iTunes with their device to install the new iOS application.

总结Summary

本文涵盖了为非 App Store 版本准备 Xamarin.iOS 应用程序所需的设置。This article covered the setup required to prepare a Xamarin.iOS application for a non-App Store build. 介绍了如何创建 IPA 包,以及如何在最终用户的 iOS 设备上安装生成的 iOS 应用程序,用于测试或 In-House 分发。It showed how to create an IPA Package and has how to install the resulting iOS application on the end user's iOS device for testing or In-House Distribution.