发布用于临时分发的 Mac Catalyst 应用
在 Mac App Store 外分发 Mac Catalyst 应用时,还可以选择将应用分发给已注册设备上数量有限的用户。 这称为临时分发,主要用于在一部分人中测试应用。 不过,每个会员年度仅限 100 台设备,而且这些设备必须添加到 Apple 开发者帐户中。 Apple Developer Program 和 Apple Developer Enterprise Program 的会员可以使用此分发方式。
分发 Mac Catalyst 应用需要使用预配配置文件预配应用。 预配配置文件是包含代码签名信息、应用标识及其预期分发机制的文件。
若要通过临时分发在 Mac App Store 外分发 .NET Multi-platform App UI (.NET MAUI) Mac Catalyst 应用,需要为其生成一个特定的开发预配配置文件。 通过该配置文件,应用可以通过数字签名进行发布,从而可以在 Mac 上安装。 临时开发预配配置文件包含 App ID、开发证书和可安装应用的设备列表。 如果还没有开发证书,则需要创建一个来标识自己或组织。
预配用于临时分发的 .NET MAUI Mac Catalyst 应用的过程如下:
- 创建证书签名请求。 有关详细信息,请参阅创建证书签名请求。
- 创建开发证书。 有关详细信息,请参阅创建开发证书。
- 创建 App ID。 有关详细信息,请参阅创建 App ID。
- 将设备添加到 Apple 开发者帐户。 有关详细信息,请参阅添加设备。
- 创建预配配置文件。 有关详细信息,请参阅创建预配配置文件。
- 下载预配配置文件。 有关详细信息,请参阅在 Xcode 中下载预配配置文件。
重要说明
本文介绍了如何使用属于 Apple Developer Program 的 Apple 开发者帐户预配临时分发。 本文也可用于属于 Apple Developer Enterprise Program 的 Apple 开发者帐户,因为所需的步骤基本相同。
然后,完成预配后,应准备要发布的应用,并按以下流程进行发布:
- 为应用添加权利(可选)。 有关详细信息,请参阅添加权利。
- 更新应用的 Info.plist 文件。 有关详细信息,请参阅更新 Info.plist。
- 使用命令行发布应用。 有关详细信息,请参阅使用命令行进行发布。
创建证书签名请求
在创建分发证书之前,首先需要在 Mac 上的“密钥链访问”中创建证书签名请求 (CSR):
在 Mac 上启动“密钥链访问”。
在“密钥链访问”中,选择“密钥链访问”>“证书助理”>“从证书颁发机构请求证书…”菜单项。
在“证书助理”对话框的“用户电子邮件地址”字段中输入电子邮件地址。
在“证书助理”对话框的“公用名”字段中输入密钥的名称。
在“证书助理”对话框中,将“CA 电子邮件地址”字段留空。
在“证书助理”对话框中,选择“保存到磁盘”单选按钮,然后选择“继续”:
将证书签名请求保存到已知位置。
在“证书助理”对话框中,选择“完成”按钮。
关闭“密钥链访问”。
创建开发证书
使用 CSR 可以生成用于确认标识的开发证书。 必须使用 Apple 开发者帐户的 Apple ID 创建开发证书:
在 Web 浏览器中,登录到 Apple 开发者帐户。
在 Apple 开发人员帐户中,选择“ 证书、ID 和配置文件 ”选项卡。
在“ 证书,标识符和配置文件 ”页上,选择 + 用于创建新证书的按钮。
在“创建新证书”页上,选择“Apple 开发”单选按钮,然后选择“继续”按钮:
在“创建新证书”页上,选择“选择文件”:
在“选择要上传的文件”对话框中,选择之前创建的证书请求文件(文件扩展名为
.certSigningRequest
的文件),然后选择“上传”。在“创建新证书”页上,选择“继续”按钮:
在“下载证书”页上,选择“下载”按钮:
证书文件(扩展名为
.cer
的文件)将下载到所选位置。在 Mac 上,双击下载的证书文件,将证书安装到密钥链。 证书将显示在“密钥链访问”中的“我的证书”类别中,并以“Apple 开发”开头:
注意
记下密钥链访问中的完整证书名称。 签名应用时需要使用该名称。
创建开发配置文件
通过临时开发预配配置文件,可以对 .NET MAUI Mac Catalyst 应用进行数字签名,从而将其安装到特定 Mac 上。 临时开发预配配置文件包含 App ID、开发证书和可安装应用的设备列表。
创建 App ID
需要 App ID 才能标识要分发的应用。 App ID 类似于反向 DNS 字符串,可唯一标识应用,应与应用的捆绑包标识符相同。 可以使用将应用部署到设备进行测试时使用的同一 App ID。
App ID 有两种类型:
- 通配符。 通配符 App ID 允许使用单个 App ID 来匹配多个应用,通常采用
com.domainname.*
形式。 通配符 App ID 可用于分发多个应用,并且应用于未启用应用特定功能的应用。 - 精确。 精确 App ID 对于单个应用而言是唯一的,通常采用
com.domainname.myid
形式。 通过一个精确 App ID 可分发一个具有匹配捆绑包标识符的应用。 精确 App ID 通常用于启用了应用特定功能的应用,例如 Apple Pay 或 Game Center。 有关功能的详细信息,请参阅功能。
若要创建新的 App ID,请执行以下操作:
在 Apple 开发人员帐户中,导航到 证书、ID 和配置文件。
在“ 证书,标识符和配置文件 ”页上,选择“ 标识符 ”选项卡。
在“标识符”页上,选择 + 按钮创建新 App ID。
在“注册新标识符”页上,选择“App ID”单选按钮,然后选择“继续”按钮:
在“注册新标识符”页上,选择“App”,然后选择“继续”按钮:
在“注册 App ID”页上,输入说明,然后选择“精确”或“通配符”捆绑包 ID 单选按钮。 然后,以反向 DS 格式输入应用的捆绑包 ID:
重要说明
输入的捆绑包 ID 必须与应用项目中 Info.plist 文件中的捆绑包标识符相对应。
.NET MAUI 应用的捆绑包标识符以“应用程序 ID”属性的形式存储在项目文件中:
- 在 Visual Studio 的“解决方案资源管理器”中,右键单击 .NET MAUI 应用项目,然后选择“属性”。 然后,导航到“MAUI 共享”>“常规”选项卡。“应用程序 ID”字段会列出捆绑包标识符。
- 在 Visual Studio for Mac 的“解决方案窗口”中,右键单击 .NET MAUI 应用项目,然后选择“属性”。 然后,在“项目属性”窗口中,选择“生成”>“应用信息”选项卡。“应用程序 ID”字段会列出捆绑包标识符。
“应用程序 ID”字段的值更新后,Info.plist 中的“捆绑包标识符”的值将自动更新。
在“注册 App ID”页上,选择应用使用的任何功能。 任何功能都必须在此页面和应用项目的 Entitlements.plist 文件中同时配置。 有关详细信息,请参阅功能和权利。
在“注册 App ID”页上,选择“继续”按钮。
在“确认 App ID”页上,选择“注册”按钮。
添加设备
创建用于临时分发的预配配置文件时,配置文件必须包含哪些设备可以运行应用。 在选择要添加到预配配置文件的设备之前,必须先将设备添加到 Apple 开发者帐户。 可以按照以下步骤进行添加:
选择“Apple”>“关于此 Mac”菜单项。
在“概述”选项卡中,选择“系统报告...”按钮。
在“系统报告”中,选择“硬件”扩展器查看硬件概述。 报告会显示通用唯一标识符 (UUID),在 macOS 10.15 及更早版本中为“硬件 UUID”,在 macOS 11.0 及更高版本中为“预配 UDID”。
选择“硬件 UUID”或“预配 UDID”值并将其复制到剪贴板。
在 Web 浏览器中,转到 Apple 开发者帐户的设备部分,然后单击 + 按钮。
在“注册新设备”页中,将“平台”设置为“macOS”,并为新设备命名。 然后将剪贴板中的标识符粘贴到“设备 ID (UUID)”字段中,并单击“继续”按钮:
在“注册新设备”页中,查看信息,然后单击“注册”按钮。
对于想要通过临时分发部署 .NET MAUI Mac Catalyst 应用的任何 Mac,重复上述步骤。
创建预配配置文件
创建 App ID 后,应创建开发预配配置文件。 通过该配置文件,可以对应用进行发布,从而将其安装到特定 Mac 上。
若要为临时分发创建预配配置文件,请执行以下操作:
在 Apple 开发人员帐户的“证书、标识符和配置文件”页中,选择“ 配置文件 ”选项卡。
在“配置文件”选项卡中,单击 + 按钮以创建新的配置文件。
在“注册新预配配置文件”页上,选择“macOS 应用开发”单选按钮,然后单击“继续”按钮:
在“生成预配配置文件”页上,选择“Mac Catalyst”单选按钮。 然后,在“App ID”下拉列表中,选择之前创建的 App ID,然后单击“继续”按钮:
在“生成预配配置文件”页中,选择对应于开发证书的复选框,然后单击“继续”按钮:
在“生成预配配置文件”页中,选择要安装应用的设备,然后单击“继续”按钮。
在“生成预配配置文件”页,输入预配配置文件的名称,然后单击“生成”按钮:
注意
记下预配配置文件名称,因为对应用进行签名时需要用到它。
在“生成预配配置文件”页,(可选)单击“下载”按钮可下载预配配置文件。
注意
现在无需下载预配配置文件。 而是需要在 Xcode 中进行下载。
在 Xcode 中下载预配配置文件
在 Apple 开发者帐户中创建预配配置文件后,Xcode 可以下载该配置文件,以用于对应用进行签名:
在 Mac 上,启动 Xcode。
在 Xcode 中,选择“Xcode”>“首选项...”菜单项。
在“首选项”对话框中,选择“帐户”选项卡。
在“帐户”选项卡中,单击 + 按钮将 Apple 开发者帐户添加到 Xcode:
在“帐户类型”弹出窗口中,选择“Apple ID”,然后单击“继续”按钮:
在登录弹出窗口中,输入 Apple ID 并单击“下一步”按钮。
在登录弹出窗口中,输入 Apple ID 并单击“下一步”按钮:
在“帐户”选项卡中,单击“管理证书...”按钮,确保已下载分发证书。
在“帐户”选项卡中,单击“下载手动配置文件”按钮下载预配配置文件:
等待下载完成,然后关闭 Xcode。
添加权利
Apple 的 App 沙盒可限制对 Mac 应用中的系统资源和用户数据的访问,以便在应用遭到入侵时抑制损害。 通过 Mac App Store 分发的 Mac Catalyst 应用必须启用 App 沙盒,而在 Mac App Store 外分发的 Mac Catalyst 应用可以选择启用。
这可以通过将 Entitlements.plist 文件添加到 .NET MAUI 应用项目的 Platforms/MacCatalyst 文件夹来实现:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.security.app-sandbox</key>
<true/>
</dict>
</plist>
App 沙盒权利是使用 com.apple.security.app-sandbox
类型的 boolean
密钥定义的。 有关 App 沙盒的信息,请参阅 developer.apple.com 上的使用 App 沙盒保护用户数据。 有关 App 沙盒权利的信息,请参阅 App 沙盒权利。
如果应用打开传出网络连接,则还需要将 boolean
类型的 com.apple.security.network.client
密钥添加到 Entitlements.plist 文件:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.security.app-sandbox</key>
<true/>
<key>com.apple.security.network.client</key>
<true/>
</dict>
</plist>
有关出站网络连接权利的信息,请参阅 developer.apple.com 上的 com.apple.security.network.client。
更新 Info.plist
在分发应用之前,应更新其 Info.plist 文件并添加其他信息。
注意
虽然在分发应用进行测试时不需要更新应用的 Info.plist 文件,但分发应用的最终测试版本时需要这些更新。 因此,最佳做法是执行这些更新。
指定用户界面风格
Mac Catalyst 应用可以以 iPad 或 Mac 用户界面风格运行:
- iPad 用户界面风格会告诉 macOS 缩放应用的用户界面,以匹配 Mac 显示环境,同时保留类似 iPad 的外观。
- Mac 用户界面风格不会缩放应用的用户界面以匹配 Mac 显示环境。 某些控件会更改其大小和外观,与它们交互的感觉和与
AppKit
控件交互的感觉相同。
默认情况下,.NET MAUI Mac Catalyst 应用使用 iPad 用户界面风格。 如果这是你想要的行为,请确保应用的 Info.plist 文件仅将 2 指定为 UIDeviceFamily
键的值:
<key>UIDeviceFamily</key>
<array>
<integer>2</integer>
</array>
若要采用 Mac 界面用户风格,请更新应用的 Info.plist 文件,将 6 指定为 UIDeviceFamily
键的值:
<key>UIDeviceFamily</key>
<array>
<integer>6</integer>
</array>
有关 Mac Catalyst 用户界面风格的详细信息,请参阅指定 Mac Catalyst 应用的 UI 风格。
设置应用的默认语言和区域
将应用的 Info.plist 中的 CFBundleDevelopmentRegion
键设置为表示本地化开发区域的 string
:
<key>CFBundleDevelopmentRegion</key>
<string>en</string>
此键的值应为语言指示符,具有可选的区域指示符。 有关详细信息,请参阅 developer.apple.com 上的 CFBundleDevelopmentRegion。
设置版权键
将应用的 Info.plist 中的 NSHumanReadableCopyright
键设置为表示应用的人类可读版权声明的 string
:
<key>NSHumanReadableCopyright</key>
<string>MyMauiApp © 2023</string>
有关详细信息,请参阅 developer.apple.com 上的 NSHumanReadableCopyright。
声明应用使用加密
如果应用使用加密,并且计划将其分发到美国或加拿大境外,则它受美国出口合规性要求的约束。 可以在应用的 Info.plist 文件中提供有关应用使用加密的信息。
为此,可以在应用的 Info.plist 中添加 ITSAppUsesNonExemptEncryption
键,其中包含一个 boolean
值,可指示应用是否使用加密:
<key>ITSAppUsesNonExemptEncryption</key>
<false/>
有关详细信息,请参阅 developer.apple.com 上的遵守加密出口条例。
使用命令行发布
若要在 Mac 上通过命令行发布 Mac Catalyst 应用,请打开终端并导航到 .NET MAUI 应用项目的文件夹。 使用以下参数运行 dotnet publish
命令:
参数 | 值 |
---|---|
-f 或 --framework |
目标框架,即 net8.0-maccatalyst 。 |
-c 或 --configuration |
生成配置,即 Release 。 |
-p:MtouchLink |
项目的链接模式,可以是 None 、SdkOnly 或 Full 。 |
-p:CreatePackage |
设置为 true ,以便在生成结束时为应用创建包 (.pkg)。 |
-p:EnableCodeSigning |
设置为 true ,以启用代码签名。 |
-p:CodesignKey |
代码签名密钥的名称。 设置为“密钥链访问”中显示的分发证书名称。 |
-p:CodesignProvision |
签名应用捆绑包时要使用的预配配置文件。 |
-p:CodesignEntitlements |
权利文件的路径,用于指定应用所需的权利。 设置为 Platforms\MacCatalyst\Entitlements.plist 。 |
-p:RuntimeIdentifier |
项目的运行时标识符 (RID)。 .NET MAUI Mac Catalyst 应用的发布生成默认使用 maccatalyst-x64 和 maccatalyst-arm64 作为运行时标识符,以支持通用应用。 若要仅支持单个体系结构,请指定 maccatalyst-x64 或 maccatalyst-arm64 。 |
-p:UseHardenedRuntime |
设置为 true ,以启用强化版运行时,在 Mac App Store 外分发 Mac Catalyst 应用必须启用该功能。 |
警告
尝试发布 .NET MAUI 解决方案将导致 dotnet publish
命令尝试单独发布解决方案中的每个项目,这可能会导致将其他项目类型添加到解决方案后出现问题。 因此,dotnet publish
命令的范围应限定为 .NET MAUI 应用项目。
如果项目文件的 <PropertyGroup>
中未提供其他生成参数,则可以在命令行上指定这些参数。 下表列出了一些常用参数:
参数 | 值 |
---|---|
-p:ApplicationTitle |
用户可见的应用名称。 |
-p:ApplicationId |
应用的唯一标识符,例如 com.companyname.mymauiapp 。 |
-p:ApplicationVersion |
标识应用迭代的生成版本。 |
-p:ApplicationDisplayVersion |
应用的版本号。 |
-p:RuntimeIdentifier |
项目的运行时标识符 (RID)。 .NET MAUI Mac Catalyst 应用的发布生成默认使用 maccatalyst-x64 和 maccatalyst-arm64 作为运行时标识符,以支持通用应用。 若要仅支持单个体系结构,请指定 maccatalyst-x64 或 maccatalyst-arm64 。 |
有关生成属性的完整列表,请参阅项目文件属性。
重要说明
无需在命令行中提供所有这些参数的值。 可以在项目文件中提供它们。 当在命令行和项目文件中都提供了参数时,命令行参数优先。 有关在项目文件中提供生成属性的详细信息,请参阅在项目文件中定义生成属性。
例如,使用以下命令在 Mac 上生成并签名 .pkg,以便向已注册设备上的用户进行临时分发:
dotnet publish -f net8.0-maccatalyst -c Release -p:MtouchLink=SdkOnly -p:CreatePackage=true -p:EnableCodeSigning=true -p:CodesignKey="Apple Development: John Smith (AY2GDE9QM7)" -p:CodesignProvision="MyMauiApp (Ad-hoc)" -p:CodesignEntitlements="Platforms\MacCatalyst\Entitlements.plist" -p:UseHardenedRuntime=true
注意
在 .NET 8 中,dotnet publish
命令默认为 Release
配置。 因此,可以从命令行中省略生成配置。
发布可生成应用并对其进行签名、打包,然后将 .pkg 复制到 bin/Release/net8.0-maccatalyst/publish/ 文件夹。 如果仅使用单个体系结构发布应用,则会将其发布到 bin/Release/net8.0-maccatalyst/{architecture}/publish/ 文件夹。
在签名过程中,可能需要输入登录密码并允许运行 codesign
:
有关 dotnet publish
命令的详细信息,请参阅 dotnet publish。
在项目文件中定义生成属性
在命令行上指定生成参数的另一种方法是在项目文件的 <PropertyGroup>
中指定它们。 下表列出了一些常用生成属性:
属性 | 值 |
---|---|
<ApplicationTitle> |
用户可见的应用名称。 |
<ApplicationId> |
应用的唯一标识符,例如 com.companyname.mymauiapp 。 |
<ApplicationVersion> |
标识应用迭代的生成版本。 |
<ApplicationDisplayVersion> |
应用的版本号。 |
<CodesignKey> |
代码签名密钥的名称。 设置为“密钥链访问”中显示的分发证书名称。 |
<CodesignEntitlements> |
权利文件的路径,用于指定应用所需的权利。 设置为 Platforms\MacCatalyst\Entitlements.plist 。 |
<CodesignProvision> |
签名应用捆绑包时要使用的预配配置文件。 |
<CreatePackage> |
设置为 true ,以便在生成结束时为应用创建包 (.pkg)。 |
<EnableCodeSigning> |
设置为 true ,以启用代码签名。 |
<MtouchLink> |
项目的链接模式,可以是 None 、SdkOnly 或 Full 。 |
<RuntimeIdentifier> |
项目的运行时标识符 (RID)。 .NET MAUI Mac Catalyst 应用的发布生成默认使用 maccatalyst-x64 和 maccatalyst-arm64 作为运行时标识符,以支持通用应用。 若要仅支持单个体系结构,请指定 maccatalyst-x64 或 maccatalyst-arm64 。 |
<UseHardenedRuntime> |
设置为 true ,以启用强化版运行时,在 Mac App Store 外分发 Mac Catalyst 应用必须启用该功能。 |
有关生成属性的完整列表,请参阅项目文件属性。
重要说明
无需在项目文件中提供这些生成属性的值。 发布应用时,可以在命令行中提供它们。 这样就能够从项目文件中省略特定值。
以下示例显示了一个典型的属性组,用于生成 Mac Catalyst 应用并对其进行签名,以便向已注册设备上的用户进行临时分发:
<PropertyGroup Condition="'$(Configuration)|$(TargetFramework)|$(Platform)'=='Release|net8.0-maccatalyst|AnyCPU'">
<MtouchLink>SdkOnly</MtouchLink>
<EnableCodeSigning>True</EnableCodeSigning>
<CreatePackage>true</CreatePackage>
<CodesignKey>Apple Development: John Smith (AY2GDE9QM7)</CodesignKey>
<CodesignProvision>MyMauiApp (Ad-hoc)</CodesignProvision>
<CodesignEntitlements>Platforms\MacCatalyst\Entitlements.plist</CodesignEntitlements>
<UseHardenedRuntime>true</UseHardenedRuntime>
</PropertyGroup>
此示例 <PropertyGroup>
添加了条件检查,除非条件检查通过,否则将阻止处理这些设置。 条件检查会检查两个项目:
- 生成配置是否设置为
Release
。 - 目标框架是否设置为包含文本
net8.0-maccatalyst
。 - 平台是否设置为
AnyCPU
。
如果其中任何一个条件失败,则不会处理设置。 更重要的是,不会设置 <CodesignKey>
和 <CodesignProvision>
设置,这将导致应用无法获得签名。
添加上述属性组后,可在 Mac 上通过命令行发布应用,方法是打开终端并导航到 .NET MAUI 应用项目的文件夹。 然后,运行以下命令:
dotnet build -f net8.0-maccatalyst -c Release
发布可生成应用并对其进行签名、打包,然后将 .pkg 复制到 bin/Release/net8.0-maccatalyst/publish/ 文件夹。
分发应用以进行测试
.pkg 可以分发给已注册设备上的用户,可以通过双击 .pkg 文件来安装运行应用。
有关如何在 Mac 上安全打开应用的信息,请参阅 support.apple.com 上的在 Mac 上安全打开应用。
另请参阅
- Developer.apple.com 上的将应用分发给已注册设备
- Developer.apple.com 上的准备用于分发的应用
- Developer.apple.com 上的强化版运行时
反馈
https://aka.ms/ContentUserFeedback。
即将发布:在整个 2024 年,我们将逐步淘汰作为内容反馈机制的“GitHub 问题”,并将其取代为新的反馈系统。 有关详细信息,请参阅:提交和查看相关反馈