Uso de la CLI de winapp con aplicaciones basadas en archivos .NET

Para obtener un ejemplo de trabajo, consulte el ejemplo dotnet-file-app. Para obtener la referencia completa, consulte Modo de archivo único en la referencia de la CLI.

.NET 10 puede ejecutar un único archivo .cs sin ningún archivo del proyecto. En esta guía se muestra cómo ejecutar ese archivo con identidad de paquete mediante winapp run, para que las API como Windows.ApplicationModel.Package.Current, las notificaciones de aplicaciones y la inteligencia artificial en el dispositivo funcionen. No tienes que crear un manifiesto ni recursos de imagen: winapp los genera automáticamente.

La identidad del paquete es un concepto básico en el modelo de Windows app. Permite a tu aplicación acceder a API de Windows específicas, tener una experiencia de instalación y desinstalación limpia, etc. Una aplicación basada en archivos que se ejecuta con dotnet run no tiene identidad de paquete.

Prerequisites

  1. .NET SDK 10.0.300 o posterior: instale el SDK de .NET 10 (requiere un reinicio después de la instalación):

    winget install Microsoft.DotNet.SDK.10 --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. Creación de una aplicación basada en archivos

Cree una carpeta con un archivo denominado hello.cs:

#:property OutputType=Exe
#:property TargetFramework=net10.0-windows10.0.19041.0

using Windows.ApplicationModel;

try
{
    Console.WriteLine($"Package Family Name: {Package.Current.Id.FamilyName}");
}
catch (InvalidOperationException)
{
    // Thrown when the app doesn't have package identity
    Console.WriteLine("Not packaged");
}

Las líneas #:property configuran la aplicación como lo haría un .csproj. El TargetFramework de Windows da al código acceso a las API de Windows Runtime, como Package.

Ejecútelo con dotnet run:

dotnet run hello.cs

La salida es Not packaged: la aplicación se ejecuta sin identidad de paquete.

2. Ejecutar con la identidad del paquete

Ejecute el mismo archivo con winapp:

winapp run hello.cs

Winapp compila la aplicación, genera un manifiesto y recursos de imagen predeterminados en la salida de compilación, registra la aplicación como un paquete y la inicia. La salida muestra ahora la identidad del paquete:

Package Family Name: hello-<hash>_<publisher-hash>

La carpeta de origen sigue conteniendo solo hello.cs. Dado que se trata de una aplicación de consola (OutputType=Exe), winapp la inicia a través de un alias de ejecución, por lo que su salida aparece en el terminal.

El registro permanece en su lugar después de que se cierre la aplicación, por lo que, al ejecutar winapp run hello.cs de nuevo, se reutiliza la misma identidad. Quítelo en el paso 5.

3. Asigne un nombre al paquete.

De forma predeterminada, el nombre del paquete es el nombre de archivo más un hash corto de la ruta de acceso del archivo. Para elegir su propio nombre, anule primero el registro del paquete actual, ya que un nuevo nombre registra un nuevo paquete:

winapp unregister hello.cs

A continuación, agregue #:property directivas a la parte superior de hello.cs:

#:property WinAppPackageName=com.contoso.hello
#:property WinAppDisplayName=Contoso Hello
#:property Version=1.0.0

Ejecútelo de nuevo:

winapp run hello.cs

La salida muestra el nuevo nombre, por ejemplo Package Family Name: com.contoso.hello_<publisher-hash>. La aplicación también aparece en el menú Inicio como Contoso Hello.

Para cada propiedad de identidad y su valor predeterminado, consulte Propiedades del manifiesto.

4. Ejecutar con dotnet run

Para obtener el mismo lanzamiento empaquetado desde dotnet run sin formato, haga referencia al paquete Microsoft.Windows.SDK.BuildTools.WinApp en la parte superior de hello.cs:

#:package Microsoft.Windows.SDK.BuildTools.WinApp@*

dotnet run hello.cs

La salida muestra la misma identidad de paquete que winapp run. Dado que dotnet run se compila en una carpeta de salida diferente, advierte de que reemplaza un registro existente instalado desde otra ubicación. Esto es lo esperado y puedes ignorarlo.

El paquete también proporciona a la aplicación un icono de ventana de marcador de posición, por lo que una aplicación con ventana muestra un icono en su barra de título. Para usar el suyo, apunte ApplicationIcon a un .ico archivo:

#:property ApplicationIcon=Assets\MyApp.ico

Para las propiedades que controlan este lanzamiento, consulte Ejecución con dotnet run.

5. Limpiar

Quite el registro al pasar el archivo .cs a winapp unregister:

winapp unregister hello.cs

Agregar funcionalidades o un manifiesto personalizado

Algunas API necesitan una funcionalidad declarada. Por ejemplo, las API de ia de Windows necesitan systemAIModels:

#:property WinAppCapabilities=systemAIModels

winapp escribe cada funcionalidad en el elemento de manifiesto correcto. Consulte Funcionalidades para obtener la lista completa y las reglas de nomenclatura.

Los controladores de protocolo, las asociaciones de archivos y otras integraciones de shell necesitan un manifiesto creado. Coloque un hello.appxmanifest elemento junto a hello.cs y winapp lo usa en lugar de generar uno. Consulte Traer su propio manifiesto.

Pasos siguientes

  • Se actualizó por última vez el