分发使用 Windows ML 的应用

2025-05-20

准备好分发使用 Windows ML 的 C# 或C++应用时，必须执行一些其他步骤，以确保将 Windows ML 运行时部署到用户的设备。在自己的设备上部署应用时，NuGet 包会自动在自己的设备上设置此应用。

重要

Windows ML API 目前是实验性的， 不支持 在生产环境中使用。尝试这些 API 的应用不应发布到 Microsoft 应用商店。

注释

Python 应用不需要执行任何其他分发步骤。 pip install页上的初始import和描述包括分发应用所需的所有内容。

MSIX 包结构

NuGet 包包括包含 Windows ML 运行时的 MSIX 包。应在应用程序的安装过程中部署这些包。

可以指示 NuGet 包通过设置以下值WinMLDeployMSIXToOutputtrue来将这些文件复制到输出目录：

<PropertyGroup>
  <!-- Copy architecture-specific MSIX files to output directory -->
  <WinMLDeployMSIXToOutput>true</WinMLDeployMSIXToOutput>
  <!-- Installers should not enable auto-initialization -->
  <WinMLBootstrapAutoInitializeDisabled>true</WinMLBootstrapAutoInitializeDisabled>
</PropertyGroup>

然后，MSIX 包将按照这种结构复制到你的输出目录中。

msix/
├── win-x64/
│   └── Microsoft.Windows.AI.MachineLearning.msix
└── win-arm64/
    └── Microsoft.Windows.AI.MachineLearning.msix

硬件体系结构检测

重要

必须安装与硬件平台匹配的 MSIX 包，而不是应用程序的体系结构。对于 ARM64 硬件，请使用 ARM64 包，即使应用程序是 x64（在仿真下运行）。对于 x64 硬件，请使用 x64 包。

using Microsoft.Windows.AI.MachineLearning.Bootstrap;

// Deploy the package.
// Auto-detects hardware architecture, and uses the appropriate MSIX.
int hr = NativeMethods.WinMLDeployMainPackage();
if (hr < 0)
{
    // Handle deployment failure.
}

#include <WinMLBootstrap.h>

// Deploy the package.
// Auto-detects hardware architecture, and uses the appropriate MSIX.
HRESULT hr = WinMLDeployMainPackage();
if (FAILED(hr))
{
    // Handle deployment failure.
}

重要

MSIX 部署函数专为安装方案而设计。它会自动查找位于应用程序可执行文件的msix/win-{arch}子目录中的 MSIX 文件。

WinMLBootstrapAutoInitializeDisabled 应在安装程序项目中设置为 true ，以确保在部署主包之前不执行自动初始化代码。

自定义部署

如果需要更好地控制部署过程，则可以直接使用 Windows.Management.Deployment.PackageManager 类。

Bootstrap 功能

该包包括 C# 和 C++ 项目的启动功能，在安装 NuGet 包时会自动配置。这提供运行时初始化和依赖项管理，无需任何其他设置。

对于 C# 项目，软件包会自动：

将WinMLBootstrap.dll复制到你的输出目录
包括自动初始化代码。

配置选项

默认情况下包含 Bootstrap 功能，但可以使用以下项目属性配置其行为：

<PropertyGroup>
  <!-- Disable auto-initialization completely -->
  <WinMLBootstrapAutoInitializeDisabled>true</WinMLBootstrapAutoInitializeDisabled>

  <!-- Allow execution to continue even if initialization fails (default: false) -->
  <WinMLContinueOnInitFailure>true</WinMLContinueOnInitFailure>
</PropertyGroup>

1.禁用自动初始化

如果 WinMLBootstrapAutoInitializeDisabled 设置为 true，则项目中不包含自动初始化代码。在这种情况下，您需要手动初始化和反初始化运行时，如下所示。

2.在初始化失败时继续

如果 WinMLContinueOnInitFailure 设置为， true即使初始化失败，应用程序也会继续运行。可以使用手动初始化示例中所示的方法检查初始化状态。

手动初始化

禁用自动初始化时，需要手动初始化和取消初始化。

using Microsoft.Windows.AI.MachineLearning.Bootstrap;

// Initialize
int hr = NativeMethods.WinMLInitialize();
if (hr < 0)
{
    // Handle initialization failure...
}

// Execution provider download and registration should use the WinRT API.

// Get the initialization status at any point.
int status = NativeMethods.WinMLGetInitializationStatus();

// Later, uninitialize before application exit.
NativeMethods.WinMLUninitialize();

#include <WinMLBootstrap.h>

// Initialize
HRESULT hr = WinMLInitialize();
if (FAILED(hr))
{
    // Handle initialization failure...
}

// Get the initialization status at any point.
HRESULT status = WinMLGetInitializationStatus();

// On first application run attempt to download necessary ExecutionProviderPackages.
HANDLE downloadEvent = CreateEvent(nullptr, FALSE, FALSE, nullptr);
auto downloadCallback = [](void* context, HRESULT result)
{
    HANDLE event = static_cast<HANDLE>(context);
    if (FAILED(result))
    {
        // Handle failure to download execution provider packages.
        exit(-1);
    }
    SetEvent(event);
};

status = WinMLDownloadExecutionProviders(downloadCallback, &downloadContext);
if (SUCCEEDED(status))
{
    if (!WaitForSingleObject(downloadEvent, 120 * 1000))
    {
        if (GetLastError() == WAIT_TIMEOUT)
        {
            // Handle download timeouts here.
            return;
        }
    }
}
else
{
    // Handle failures to download execution provider packages.
}

// Before interacting with Ort register the execution providers.
HANDLE dEvent = CreateEvent(nullptr, FALSE, FALSE, nullptr);
auto registerCallback = [](void* context, HRESULT result)
{
    HANDLE event = static_cast<HANDLE>(context);
    if (FAILED(result))
    {
        // Handle failure to register execution providers.
        exit(-1);
    }
    SetEvent(event);
};

status = WinMLRegisterExecutionProviders(registerCallback, &downloadContext);
if (SUCCEEDED(status))
{
    WaitForSingleObject(registerEvent, INFINITE);
}
else
{
    // Handle failure to register execution providers.
}

// Now interact with Ort APIs.

...

// Later, uninitialize before application exit.
WinMLUninitialize();

通过