Distribución de la aplicación que usa Windows ML

Cuando estés listo para distribuir tu aplicación de C# o C++ que usa Windows ML, tendrás que seguir algunos pasos adicionales para asegurarte de que Windows ML Runtime se implemente en los dispositivos de los usuarios. Al implementar la aplicación en su propio dispositivo, el paquete NuGet lo configura automáticamente en su propio dispositivo.

Importante

Las API de Windows ML son actualmente experimentales y no se admiten para su uso en entornos de producción. Las aplicaciones que prueban estas API no deben publicarse en Microsoft Store.

Nota:

Las aplicaciones de Python no necesitan realizar ningún paso de distribución adicional. Los elementos iniciales pip install y import descritos en la página ejecutar modelos ONNX incluyen todo lo necesario para distribuir tu aplicación.

Estructura de paquetes MSIX

El paquete NuGet incluye paquetes MSIX que contienen el entorno de ejecución de Windows ML. Debe implementar estos paquetes como parte del proceso de instalación de la aplicación.

Puede indicar al paquete NuGet que copie estos archivos en el directorio de salida estableciendo el WinMLDeployMSIXToOutput en true.

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

Los paquetes MSIX se copiarán en tu directorio de salida con esta estructura...

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

Detección de arquitectura de hardware

Importante

Debe instalar el paquete MSIX que coincida con la plataforma de hardware, no la arquitectura de la aplicación. En el caso del hardware ARM64, use el paquete ARM64, incluso si la aplicación es x64 (que se ejecuta con emulación). Para hardware x64, use el paquete x64.

C#

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.
}

C++

#include <WinMLBootstrap.h>

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

Importante

La función de implementación MSIX está diseñada específicamente para escenarios de instalación. Busca automáticamente el archivo MSIX en el msix/win-{arch} subdirectorio relativo al ejecutable de la aplicación.

WinMLBootstrapAutoInitializeDisabled debe establecerse true en el proyecto del instalador para asegurarse de que el código de inicialización automática no se ejecute antes de implementar el paquete principal.

Implementación personalizada

Si necesita más control sobre el proceso de implementación, puede usar la clase Windows.Management.Deployment.PackageManager directamente.

Funcionalidad de Bootstrap

El paquete incluye la funcionalidad de arranque para proyectos de C# y C++, que se configuran automáticamente al instalar el paquete NuGet. Esto proporciona la inicialización en tiempo de ejecución y la administración de dependencias sin ninguna configuración adicional.

C#

Para los proyectos de C#, el paquete actúa automáticamente.

• Copia el WinMLBootstrap.dll en su directorio de salida.
• Incluye código de inicialización automática.

C++

En el caso de los proyectos de C++, el paquete se realiza automáticamente:

• Agrega rutas de inclusión necesarias.
• Agrega referencias de biblioteca necesarias (WinMLBootstrap.lib).
• Copia el WinMLBootstrap.dll en su directorio de salida.
• Incluye código de inicialización automática.

Opciones de configuración

La funcionalidad de Bootstrap se incluye por defecto, pero puede configurar su comportamiento con estas propiedades del proyecto:

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

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

1. Deshabilitar la inicialización automática

Cuando WinMLBootstrapAutoInitializeDisabled se establece en true, el código de inicialización automática no se incluye en el proyecto. En este caso, deberá inicializar y desinicializar manualmente el tiempo de ejecución, como se muestra a continuación.

2. Continuar a pesar del fallo de inicialización

Cuando WinMLContinueOnInitFailure se establece en true, la aplicación seguirá ejecutándose incluso si se produce un error en la inicialización. Puede comprobar el estado de inicialización mediante los métodos que se muestran en los ejemplos de inicialización manual.

Inicialización manual

Cuando la inicialización automática está deshabilitada, debe inicializar y desinicializar manualmente.

C#

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();

C++

#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();