通过

使用 CLI 发布适用于 Windows 的打包的 .NET MAUI 应用

  • 项目

分发适用于 Windows 的 .NET Multi-platform App UI (.NET MAUI) 应用时，可以将应用及其依赖项发布到文件夹，以便部署到另一个系统。 也可以将应用打包为 MSIX 包，这对安装应用的用户有很多好处。 要详细了解 MSIX 的优点，请参阅什么是 MSIX？

创建签名证书

发布应用时必须使用签名证书。 此证书用于为 MSIX 包签名。 以下步骤演示如何使用 PowerShell 创建和安装自签名证书：

注意

当创建并使用自签名证书时，只有安装并信任该证书的用户才能运行应用。 这很容易针对测试实现，但可能会阻止其他用户安装应用。 准备发布应用时，我们建议使用由受信任来源颁发的证书。 这种集中式信任系统有助于确保应用生态系统具有不同级别的验证手段，以保护用户免受恶意行为者的侵害。

  1. 打开 PowerShell 终端并导航到项目所在的目录。

  2. 使用 New-SelfSignedCertificate 命令生成自签名证书。

    当用户安装应用时，<PublisherName> 值将显示给用户，因此请提供你自己的值并省略 < > 字符。 可以将 FriendlyName 参数设置为所需的任何文本字符串。

    New-SelfSignedCertificate -Type Custom `
                          -Subject "CN=<PublisherName>" `
                          -KeyUsage DigitalSignature `
                          -FriendlyName "My temp dev cert" `
                          -CertStoreLocation "Cert:\CurrentUser\My" `
                          -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.3", "2.5.29.19={text}")

  3. 使用以下 PowerShell 命令在证书存储中查询已创建的证书：

    Get-ChildItem "Cert:\CurrentUser\My" | Format-Table Thumbprint, Subject, FriendlyName

    应看到结果类似于以下输出：

    Thumbprint                               Subject                                  FriendlyName
----------                               -------                                  ------------
DE8B962E7BF797CB48CCF66C8BCACE65C6585E2F CN=1f23fa36-2a2f-475e-a69e-3a14fe56ed4
A6CA34FD0BA6B439787391F51C87B1AD0C9E7FAE CN=someone@microsoft.com
94D93DBC97D4F7E4364A215F15C6ACFEFC71E569 CN=localhost                             ASP.NET Core HTTPS development certificate
F14211566DACE867DA0BF9C2F9C47C01E3CF1D9B CN=john
568027317BE8EE5E6AACDE5079D2DE76EC46EB88 CN=e1f823e2-4674-03d2-aaad-21ab23ad84ae
DC602EE83C95FEDF280835980E22306067EFCA96 CN=John Smith, OU=MSE, OU=Users, DC=com
07AD38F3B646F5AAC16F2F2570CAE40F4842BBE0 CN=Contoso                               My temp dev cert

  4. 证书的指纹将在以后使用，因此请将其复制到剪贴板。 它是 Thumbprint 值，其条目与证书的 Subject 和 FriendlyName 匹配。

有关详细信息，请参阅创建用于包签名的证书。

配置项目生成设置

项目文件是放置特定于 Windows 的生成设置的理想位置。 你可能不想将某些设置放入项目文件中，例如密码。 本节中描述的设置可以在命令行上以 -p:name=value 格式传递。 如果已在项目文件中定义了该设置，则在命令行上传递的设置将替代项目设置。

将以下 <PropertyGroup> 节点添加到项目文件中。 仅当目标框架为 Windows 且配置设置为 Release 时，此属性组才会得到处理。 每当在 Release 模式下进行生成或发布时，此配置部分都会运行。

<PropertyGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows' and '$(Configuration)' == 'Release'">
    <AppxPackageSigningEnabled>true</AppxPackageSigningEnabled>
    <PackageCertificateThumbprint>A10612AF095FD8F8255F4C6691D88F79EF2B135E</PackageCertificateThumbprint>
</PropertyGroup>
<PropertyGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows' and '$(RuntimeIdentifierOverride)' != ''">
    <RuntimeIdentifier>$(RuntimeIdentifierOverride)</RuntimeIdentifier>
</PropertyGroup>

将 <PackageCertificateThumbprint> 属性值替换为以前生成的证书指纹。 或者，也可以从项目文件中移除此设置并在命令行上提供。 例如：-p:PackageCertificateThumbprint=A10612AF095FD8F8255F4C6691D88F79EF2B135E。

要在 Windows SDK 中解决 bug，需要此示例中的第二个 <PropertyGroup>。 有关 bug 的详细信息，请参阅 WindowsAppSDK 问题 #3337。

发布

若要发布应用，请打开 VS2022 开发人员命令提示终端，然后导航到 .NET MAUI 应用项目的文件夹。 运行 dotnet publish 命令，并提供以下参数：

参数 值
-f 目标框架，即 net8.0-windows{version}。 此值为 Windows TFM，如 net8.0-windows10.0.19041.0。 确保此值与 .csproj 文件中 <TargetFrameworks> 节点中的值相同。
-c 生成配置，即 Release。
-p:RuntimeIdentifierOverride=win10-x64
- 或 -
-p:RuntimeIdentifierOverride=win10-x86		 避免 WindowsAppSDK 问题 #3337 中详述的 bug。 根据目标平台选择 -x64 或 -x86 版本的参数。

警告

尝试发布 .NET MAUI 解决方案将会导致 dotnet publish 命令尝试单独发布解决方案中的每个项目，当你已经将其他项目类型添加到解决方案时，这可能会导致出现问题。 因此，dotnet publish 命令的作用范围应为 .NET MAUI 应用项目。

例如：

dotnet publish -f net8.0-windows10.0.19041.0 -c Release -p:RuntimeIdentifierOverride=win10-x64

注意

在 .NET 8 中，dotnet publish 命令默认为 Release 配置。 因此，可以从命令行中省略生成配置。

发布会生成并打包应用，将已签名的包复制到 bin\Release\net8.0-windows10.0.19041.0\win10-x64\AppPackages\<appname>\ 文件夹。 <appname> 是以项目和版本命名的文件夹。 在此文件夹中，存在一个 msix 文件，即应用包。

有关 dotnet publish 命令的更多信息，请参阅 dotnet publish。

安装应用

若要安装应用，必须使用已信任的证书对其进行签名。 否则，Windows 将不允许安装该应用。 你将看到一个类似于以下内容的对话框，其中“安装”按钮处于禁用状态：

Installing an untrusted app.

请注意，在前面的图像中，发布者是“未知”。

要信任应用包的证书，请执行以下步骤：

  1. 右键单击 .msix 文件，然后选择“属性”。

  2. 选择“数字签名”选项卡。

  3. 选择证书，然后按“详细信息”。

    Properties pane of an MSIX file with the digital signatures tab selected.

  4. 选择“查看证书”。

  5. 选择“安装证书…”。

  6. 选择“本地计算机”，然后选择“下一步”。

    如果用户帐户控制提示：“是否要允许此应用对你的设备进行更改？”，请选择“是”。

  7. 在“证书导入向导”窗口中，选择“将所有证书放入以下存储区”。

  8. 选择“浏览…”然后选择“受信任的人员”存储区。 选择“确定”关闭对话框。

    Certificate import wizard window is shown while selecting the Trusted People store.

  9. 选择“下一步”，然后选择“完成”。 你应该会看到一个对话框，显示：“导入成功”。

    Certificate import wizard window with a successful import message.

  10. 在此过程中打开的任何窗口上选择“确定”，以关闭所有窗口。

现在尝试再次打开包文件以安装应用。 应会看到类似于以下内容的对话框，并会正确显示发布者：

Installing a trusted app.

如果你要安装应用，请选择“安装”按钮。

当前限制

下面列出了发布和打包的当前限制：

  • 如果尝试直接使用发布文件夹的可执行文件运行，已发布的应用将无法运行。
  • 运行应用的方法是首先通过打包的 MSIX 文件进行安装。