Uso de la CLI de winapp con Rust

En esta guía se muestra cómo usar la winapp CLI con una aplicación de Rust para depurar con la identidad del paquete y empaquetar la aplicación como MSIX.

Para obtener un ejemplo de trabajo completo, consulte el ejemplo de Rust en este repositorio.

La identidad del paquete es un concepto básico en el modelo de Windows app. Permite a la aplicación acceder a api de Windows específicas (como notificaciones, seguridad, API de IA, etc.), tener una experiencia de instalación o desinstalación limpia, etc.

Un archivo ejecutable estándar (como uno creado con cargo build) no tiene la identidad del paquete. Esta guía muestra cómo agregarlo para depuración y luego empaquetarlo para su distribución.

Prerrequisitos

  1. Cadena de herramientas de Rust: instale Rust mediante rustup o winget (o actualice si ya está instalado):

    winget install Rustlang.Rustup --source winget

  2. CLI de winapp: instale la winapp herramienta mediante winget (o actualice si ya está instalada):

    winget install microsoft.winappcli --source winget

1. Crear una nueva aplicación de Rust

Empiece por crear una aplicación de Rust sencilla:

cargo new rust-app
cd rust-app

Ejecútelo para asegurarse de que todo funciona:

cargo run

La salida debe ser "Hello, world!"

2. Actualizar código para comprobar la identidad

Actualizaremos la aplicación para comprobar si se ejecuta con la identidad del paquete. Esto nos ayudará a comprobar que la identidad funciona correctamente en pasos posteriores. Usaremos la windows crate para acceder a las API de Windows.

En primer lugar, agregue la windows dependencia a Cargo.toml mediante la ejecución de:

cargo add windows --features ApplicationModel

Esto agrega los enlaces de API de Windows con la característica ApplicationModel, que nos proporciona acceso a la API de Package para comprobar la identidad.

A continuación, reemplace todo el contenido de src/main.rs por el código siguiente. Este código intenta recuperar la identidad del paquete actual. Si se realiza correctamente, imprime el nombre de familia del paquete; de lo contrario, imprime "No empaquetado".

Nota:

El ejemplo full también incluye código para mostrar una notificación Windows si la identidad está presente, pero para esta guía, nos centraremos en la comprobación de identidad.

use windows::ApplicationModel::Package;

fn main() {
    match Package::Current() {
        Ok(package) => {
            match package.Id() {
                Ok(id) => match id.FamilyName() {
                    Ok(name) => println!("Package Family Name: {}", name),
                    Err(e) => println!("Error getting family name: {}", e),
                },
                Err(e) => println!("Error getting package ID: {}", e),
            }
        }
        Err(_) => println!("Not packaged"),
    }
}

3. Ejecutar sin identidad

Ahora, compile y ejecute la aplicación como de costumbre:

cargo run

Debería ver el resultado "No empaquetado". Esto confirma que el ejecutable estándar se está ejecutando sin ninguna identidad de paquete.

4. Inicializar Project con la CLI de winapp

El winapp init comando configura todo lo que necesita en un solo uso: manifiesto de aplicación y recursos. El manifiesto define la identidad de la aplicación (nombre, publicador, versión) que Windows usa para conceder acceso a la API.

Ejecute el siguiente comando y siga las indicaciones:

winapp init

Cuando se le solicite,

  • Nombre del paquete: presione Entrar para aceptar el valor predeterminado (rust-app)
  • Nombre del editor: Presione Intro para aceptar el valor predeterminado o escriba su nombre.
  • Versión: presione Entrar para aceptar 1.0.0.0.
  • Descripción: presione Entrar para aceptar el valor predeterminado o escriba una descripción.
  • Configurar SDKs: seleccione "No configurar SDKs" (Rust usa su propio paquete, no los encabezados del SDK de C++).

Este comando hará lo siguiente:

  • Crear Package.appxmanifest : el manifiesto que define la identidad de la aplicación
  • Crear la carpeta Assets — iconos necesarios para el empaquetado MSIX y la publicación en la Tienda

Nota:

Dado que no se administra ningún paquete de SDK, no winapp.yaml se crea , Rust usa la windows caja a través de Cargo, por lo que no hay nada para winapp restore/update realizar el seguimiento.

Puede abrir Package.appxmanifest para personalizar aún más las propiedades, como el nombre para mostrar, el publicador y las funcionalidades.

Agregar alias de ejecución (para aplicaciones de consola)

Dado que cargo new crea una aplicación de consola, es necesario agregar un alias de ejecución al manifiesto. Sin ella, winapp run inicia la aplicación a través de la activación de AUMID, que abre una nueva ventana, y esa ventana se cierra inmediatamente cuando finaliza una aplicación de consola, tragándose cualquier salida.

El alias también permite a los usuarios ejecutar la aplicación por su nombre desde cualquier terminal después de instalar MSIX. El manifiesto registra un alias como rust-app.exe (el valor predeterminado es el nombre exe del proyecto), que los usuarios pueden invocar como rust-app o rust-app.exe.

Omita este paso si va a compilar una aplicación de interfaz de usuario (una aplicación de Rust que representa su propia ventana). Esas aplicaciones funcionan bien con el inicio predeterminado de AUMID.

Agregue el alias:

winapp manifest add-alias

Esto agrega una uap5:ExecutionAlias entrada a Package.appxmanifest.

5. Depurar con identidad

Para probar las características que requieren identidad (como notificaciones) sin empaquetar completamente la aplicación, use winapp run. Esto registra toda la carpeta de salida de compilación como un paquete de diseño flexible ( al igual que una instalación MSIX real) e inicia la aplicación. No se necesita ningún certificado ni firma para la depuración.

  1. Compile el archivo ejecutable:

    cargo build

  2. Ejecute con identidad:

    winapp run .\target\debug --with-alias

La --with-alias marca inicia la aplicación a través de su alias de ejecución para que la salida de la consola permanezca en el terminal actual. Esto requiere el uap5:ExecutionAlias que agregamos en el paso 4.

Nota:

winapp run también registra el paquete en el sistema. Este es el motivo por el que MSIX puede aparecer como "ya instalado" al intentar instalarlo más adelante en el paso 6. Use winapp unregister para limpiar los paquetes de desarrollo cuando haya terminado.

Ahora debería ver una salida similar a la siguiente:

Package Family Name: rust-app_12345abcde

Esto confirma que la aplicación se está ejecutando con una identidad de paquete válida.

Sugerencia

Para obtener flujos de trabajo de depuración avanzados (adjuntar depuradores, configuración del IDE, depuración de inicio), consulte la Guía de depuración.

6. Empaquetar con MSIX

Una vez que esté listo para distribuir la aplicación, puede empaquetarla como MSIX mediante el mismo manifiesto. MSIX proporciona una instalación o desinstalación limpia, actualizaciones automáticas y una experiencia de instalación de confianza.

Preparar el directorio de paquetes

En primer lugar, compile la aplicación en modo de versión para obtener un rendimiento óptimo:

cargo build --release

A continuación, cree un directorio con solo los archivos necesarios para la distribución. La target\release carpeta contiene artefactos de compilación que no forman parte de la aplicación; solo necesitamos el archivo ejecutable:

mkdir dist
copy .\target\release\rust-app.exe .\dist\

Generación de un certificado de desarrollo

Los paquetes MSIX deben estar firmados. Para las pruebas locales, genere un certificado de desarrollo autofirmado:

winapp cert generate --if-exists skip

Importante

El emisor del certificado debe coincidir con el Publisher en tu Package.appxmanifest. El cert generate comando lo lee automáticamente desde el manifiesto.

Firmar y empaquetar

Ahora puede empaquetar y firmar en un paso:

winapp pack .\dist --cert .\devcert.pfx

Nota: El pack comando usa automáticamente Package.appxmanifest desde el directorio actual y lo copia en la carpeta de destino antes de empaquetar. El archivo .msix generado estará en el directorio actual.

Instalación del certificado

Para poder instalar el paquete MSIX, debe confiar en el certificado de desarrollo en el equipo. Ejecute este comando como administrador (solo tiene que hacerlo una vez por certificado):

winapp cert install .\devcert.pfx

Instalación y ejecución

Nota:

Si usó winapp run en el paso 5, es posible que el paquete ya esté registrado en el sistema. Use winapp unregister primero para quitar el registro de desarrollo y, a continuación, instale el paquete de versión.

Instale el paquete haciendo doble clic en el archivo generado .msix o a través de PowerShell:

Add-AppxPackage .\rust-app.msix

Ahora puede ejecutar la aplicación desde cualquier lugar del terminal escribiendo:

rust-app

Debería ver la salida "Nombre de familia de paquete", confirmando que está instalada y en ejecución con la identidad.

Sugerencia

Si necesita volver a empaquetar la aplicación (por ejemplo, después de realizar cambios en el código), incremente Version en su Package.appxmanifest antes de volver a ejecutar winapp pack. Windows requiere un número de versión superior para actualizar un paquete instalado.

Tips

  1. Una vez que esté listo para su distribución, puede firmar su MSIX con un certificado de firma de código de una entidad de certificación para que los usuarios no tengan que instalar un certificado autofirmado.
  2. El Microsoft Store firmará el MSIX por usted, no es necesario firmar antes del envío.
  3. Es posible que tenga que crear varios paquetes MSIX, uno para cada arquitectura que admita (x64, Arm64)

Pasos siguientes

  • Last updated on