Uso dell'interfaccia della riga di comando di winapp con .NET

Questa guida dovrebbe funzionare per la maggior parte dei tipi di progetto .NET. I passaggi sono stati testati sia con progetti basati su console che su interfaccia utente come macchine virtuali Windows. Per esempi di lavoro, vedere gli esempi dotnet-app (console) e wpf-app (macchine virtuali Windows) nella cartella degli esempi.

Questa guida dimostra come utilizzare l'interfaccia della riga di comando winapp con un'applicazione .NET per eseguire il debug utilizzando l'identità del pacchetto e impacchettare l'applicazione come MSIX.

L'identità del pacchetto è un concetto di base nel modello di Windows app. Consente all'applicazione di accedere a API di Windows specifiche (ad esempio Notifiche, Sicurezza, API di intelligenza artificiale e così via), avere un'esperienza di installazione/disinstallazione pulita e altro ancora.

Un eseguibile standard (come quello creato con dotnet build) non ha un'identità del pacchetto. Questa guida illustra come aggiungerlo per il debug e quindi crearne il pacchetto per la distribuzione.

Prerequisiti

1. .NET SDK: installare .NET SDK (richiede un riavvio dopo l'installazione):

   winget install Microsoft.DotNet.SDK.10 --source winget
   

2. CLI winapp: installare lo winapp strumento con winget (o aggiornare se già installato):

   winget install Microsoft.winappcli --source winget
   

1. Creare una nuova app .NET

Per iniziare, creare una semplice applicazione console .NET:

dotnet new console -n dotnet-app
cd dotnet-app

Eseguirlo per verificare che tutto funzioni:

dotnet run

L'output deve essere "Hello, World!"

2. Aggiornare il codice per controllare l'identità

Aggiorneremo l'app per verificare se è in esecuzione con l'identità del pacchetto. Si userà l'API Windows Runtime per accedere alle API del pacchetto.

Prima di tutto, aggiornare il file project per specificare una versione specifica di Windows SDK. Aprire dotnet-app.csproj e modificare il TargetFramework per includere la versione Windows SDK:

  <TargetFramework>net10.0-windows10.0.26100.0</TargetFramework>

In questo modo è possibile accedere alle API di Windows Runtime senza dover aggiungere pacchetti aggiuntivi.

Sostituire ora il contenuto di Program.cs con il codice seguente. Questo codice tenta di recuperare l'identità del pacchetto corrente usando l'API Windows Runtime. Se ha esito positivo, stampa il nome della famiglia di pacchetti; in caso contrario, stampa "Non in pacchetto".

using Windows.ApplicationModel;

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

3. Eseguire senza identità

Eseguire ora l'app come di consueto:

dotnet run

Verrà visualizzato l'output "Non incluso nel pacchetto". Ciò conferma che l'eseguibile standard è in esecuzione senza alcuna identità del pacchetto.

4. Inizializzare il progetto con l'interfaccia della riga di comando di winapp

Il comando winapp init rileva automaticamente i file .csproj ed esegue un'installazione specifica di .NET. Configura tutto il necessario in una sola operazione: convalida il tuo TargetFramework, aggiunge i pacchetti NuGet necessari, genera il manifesto dell'app e gli asset.

Eseguire il comando seguente e seguire i prompt:

winapp init

Quando richiesto:

• Nome pacchetto: premere INVIO per accettare il valore predefinito (dotnet-app)
• Publisher nome: premere INVIO per accettare il valore predefinito o immettere il nome
• Versione: premere INVIO per accettare 1.0.0.0
• Description: premere INVIO per accettare il valore predefinito (Windows Applicazione) o immettere una descrizione
• SDK per app di Windows setup: Selezionare Stabile, Anteprima o Sperimentale (determina quale SDK per app di Windows versione viene aggiunta)
• Aggiornamento di TargetFramework: se il tuo TargetFramework non include una versione supportata dell'SDK di Windows, verrà richiesto di aggiornarlo (ad esempio, a net10.0-windows10.0.26100.0)
• Modalità sviluppatore: se viene richiesto "Modalità sviluppatore", è possibile attivarlo se si vuole, ma tenere presente che richiede privilegi amministrativi

Questo comando consentirà di:

• Aggiorna il TargetFramework nella .csproj a un TFM supportato da Windows (se necessario)
• Aggiungere Microsoft.WindowsAppSDK, Microsoft.Windows.SDK.BuildTools e Microsoft.Windows.SDK.BuildTools.WinApp riferimenti al pacchetto NuGet al .csproj
• Creare Package.appxmanifest e Assets cartelle per l'identità dell'app

È possibile aprire Package.appxmanifest per personalizzare ulteriormente le proprietà, ad esempio il nome visualizzato, l'editore e le funzionalità.

Per verificare che i pacchetti siano stati aggiunti al progetto:

dotnet list package

Nell'output verrà visualizzato Microsoft.WindowsAppSDK e Microsoft.Windows.SDK.BuildTools.

Aggiungere alias di esecuzione (per le app console)

Poiché si sta creando un'app console, è necessario assicurarsi di dotnet run mantenere l'output della console nel terminale corrente. Per impostazione predefinita, dotnet run avvia l'app in pacchetto tramite l'attivazione AUMID, che apre una nuova finestra e la finestra si chiude immediatamente al termine dell'app console, ingoiando qualsiasi output.

Per risolvere questo problema, aggiungerai un alias di esecuzione al manifesto e indicherai all'integrazione di esecuzione di avviare tramite quell'alias.

Skip questo passaggio se stai creando un'app per l'interfaccia utente (macchine virtuali Windows, WinForms, WinUI). Queste app eseguono il rendering della propria finestra, quindi l'avvio AUMID predefinito è quello che vuoi.

1. Aggiungi l'alias di esecuzione al manifesto:

   winapp manifest add-alias
   

   In questo modo si aggiunge un uap5:ExecutionAlias a Package.appxmanifest (per impostazione predefinita al nome exe del progetto) in maniera che l'app possa essere eseguita in base al nome da un terminale.

2. Indicare all'integrazione dotnet run di usare l'alias. Aprire dotnet-app.csproj e aggiungere quanto segue all'interno di qualsiasi <PropertyGroup> (o crearne uno nuovo <PropertyGroup> , se necessario):

   <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
   

   Con questa proprietà impostata, dotnet run avvia l'app tramite il suo alias di esecuzione ed eredita stdin/stdout/stderr del terminale corrente, in modo da visualizzare l'output della console in linea.

5. Eseguire il debug con l'identità

Poiché winapp init aggiunto il pacchetto NuGet Microsoft.Windows.SDK.BuildTools.WinApp al progetto, è sufficiente eseguire:

dotnet run

Questo richiama automaticamente winapp run sotto le quinte, creando un pacchetto di layout libero, registrandolo con Windows e avviando l'app con l'identità completa del pacchetto.

L'output dovrebbe essere simile al seguente:

Package Family Name: dotnet-app_12345abcde

Ciò conferma che l'app è in esecuzione con un'identità del pacchetto valida.

Alternativa: Manuale winapp run

Se non è stato usato winapp init (o rimosso il pacchetto NuGet), è possibile compilare ed eseguire manualmente:

dotnet build -c Debug
winapp run .\bin\Debug\net10.0-windows10.0.26100.0

Per aggiungere nuovamente il pacchetto NuGet: dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease

Alternativa: Identità pacchetto sparse

Se è necessario un comportamento specifico di pacchetto sparse (identità senza copiare file), è possibile utilizzare create-debug-identity invece. In questo modo viene registrato un pacchetto sparse che punta al file exe anziché creare un layout libero:

winapp create-debug-identity .\bin\Debug\net10.0-windows10.0.26100.0\dotnet-app.exe

Eseguire quindi il file eseguibile direttamente (non usare dotnet run perché potrebbe ricompilare/sovrascrivere il file):

.\bin\Debug\net10.0-windows10.0.26100.0\dotnet-app.exe

Alternativa: obiettivo MSBuild manuale

Se si preferisce non usare il pacchetto NuGet, è possibile aggiungere una destinazione MSBuild personalizzata che viene eseguita create-debug-identity dopo le compilazioni di Debug. Aggiungerlo al file .csproj alla fine, subito prima del tag di chiusura </Project>:

  <!-- Automatically apply debug identity after Debug builds -->
  <Target Name="ApplyDebugIdentity" AfterTargets="Build" Condition="'$(Configuration)' == 'Debug'">
    <Exec Command="winapp create-debug-identity &quot;$(TargetDir)$(TargetName).exe&quot;" 
          WorkingDirectory="$(ProjectDir)" 
          IgnoreExitCode="false" />
  </Target>

Con questa configurazione, dotnet build applica l'identità di debug ed è possibile eseguire direttamente l'eseguibile. Si noti che dotnet run può ricompilare e sovrascrivere l'identità, quindi eseguire manualmente l'exe dopo la compilazione.

Quando ignorare questo problema: se si preferisce un controllo esplicito su quando viene applicata l'identità o se si lavora sul codice che non richiede l'identità per la maggior parte del ciclo di sviluppo, l'approccio manuale precedente potrebbe essere più semplice.

6. Uso di SDK per app di Windows (facoltativo)

Il SDK per app di Windows consente di accedere alle API Windows moderne oltre a quanto fornito dall'SDK di base Windows, ad esempio il sistema di notifica, le API di windowing, la gestione del ciclo di vita delle app e l'intelligenza artificiale sul dispositivo. Se l'app necessita di una di queste funzionalità, questo passaggio è adatto alle proprie esigenze. Se è sufficiente l'identità del pacchetto per la distribuzione, è possibile passare al passaggio 7.

Se hai eseguito winapp init (passaggio 4), Microsoft.WindowsAppSDK è già stato aggiunto come riferimento al pacchetto NuGet nel .csproj. È possibile verificare con dotnet list package. Se l'installazione dell'SDK è stata ignorata durante l'init o se è necessario aggiungerla manualmente, eseguire:

dotnet add package Microsoft.WindowsAppSDK

Aggiornare Program.cs.

Sostituire l'intero contenuto di Program.cs con il codice seguente, che aggiunge un controllo della versione di runtime app di Windows:

using Windows.ApplicationModel;

class Program
{
    static void Main(string[] args)
    {
        try
        {
            var package = Package.Current;
            var familyName = package.Id.FamilyName;
            Console.WriteLine($"Package Family Name: {familyName}");
            
            // Get Windows App Runtime version using the API
            var runtimeVersion = Microsoft.Windows.ApplicationModel.WindowsAppRuntime.RuntimeInfo.AsString;
            Console.WriteLine($"Windows App Runtime Version: {runtimeVersion}");
        }
        catch (InvalidOperationException)
        {
            // Thrown when app doesn't have package identity
            Console.WriteLine("Not packaged");
        }
    }
}

Compilare ed eseguire

Ricompilare ed eseguire l'applicazione con SDK per app di Windows. Poiché è stato aggiunto WinAppSDK, è necessario ripetere la registrazione con l'identità affinché winapp aggiunga la dipendenza runtime. Se è stato aggiunto il pacchetto NuGet WinApp (scelta consigliata), è sufficiente eseguire dotnet run. In caso contrario (sostituire dotnet-app con il nome del progetto):

dotnet build -c Debug
winapp run .\bin\Debug\net10.0-windows10.0.26100.0

Verrà visualizzato un output simile al seguente:

Package Family Name: dotnet-app.debug_12345abcde
Windows App Runtime Version: 8000.770.947.0

Il pacchetto NuGet SDK per app di Windows include tutti gli assembly necessari per accedere alle API di Windows moderne, tra cui:

• Riquadri animati e notifiche
• Ciclo di vita delle finestre e delle app
• Notifiche push
• E molti altri componenti SDK per app di Windows

Per un utilizzo SDK per app di Windows più avanzato, vedere la documentazione SDK per app di Windows.

7. Pacchetto con MSIX

Quando si è pronti per distribuire l'app, è possibile crearne il pacchetto come MSIX usando lo stesso manifesto.

Compilazione per il Rilascio

Prima di tutto, compilare l'applicazione in modalità di rilascio per ottenere prestazioni ottimali:

dotnet build -c Release

Generare un certificato di sviluppo

Prima dell'imballaggio, è necessario un certificato di sviluppo per apporre la firma. Generarne uno se non è già stato fatto:

winapp cert generate --if-exists skip

Firma e pacchetto

È ora possibile creare un pacchetto e firmare. Puntare il comando pack alla cartella di output della compilazione (sostituire dotnet-app e il percorso TFM con i valori del progetto):

# package and sign the app with the generated certificate
winapp pack .\bin\Release\net10.0-windows10.0.26100.0 --manifest .\Package.appxmanifest --cert .\devcert.pfx 

Nota: Il pack comando usa automaticamente il file Package.appxmanifest dalla directory corrente e lo copia nella cartella di destinazione prima del confezionamento. Il file con estensione msix generato si troverà nella directory corrente.

Installare il certificato

Prima di poter installare il pacchetto MSIX, è necessario installare il certificato di sviluppo. Eseguire questo comando come amministratore:

winapp cert install .\devcert.pfx

Installare ed eseguire

Installare il pacchetto facendo doppio clic sul file *.msix generato.

È ora possibile eseguire l'app da qualsiasi punto del terminale digitando:

dotnet-app

Verrà visualizzato l'output "Package Family Name", che conferma che è installato e in esecuzione con l'identità.

Tips

1. Quando si è pronti per la distribuzione, è possibile firmare MSIX con un certificato di firma del codice da un'autorità di certificazione in modo che gli utenti non devono installare un certificato autofirmato.
2. Il Microsoft Store firmerà MSIX per te, non è necessario firmare prima dell'invio.
3. Potrebbe essere necessario creare più pacchetti MSIX, uno per ogni architettura supportata (x64, Arm64). Usare il -r flag con dotnet build per definire come destinazione architetture specifiche: dotnet build -c Release -r win-x64 o dotnet build -c Release -r win-arm64.

Automazione della creazione di pacchetti MSIX (facoltativo)

Per automatizzare il packaging MSIX come parte delle build di rilascio, aggiungi questo target al file .csproj (puoi aggiungerlo insieme al target di identità di debug):

  <!-- Automatically package as MSIX after Release builds -->
  <Target Name="PackageMsix" AfterTargets="Build" Condition="'$(Configuration)' == 'Release'">
    <!-- Package and sign directly from build output -->
    <Exec Command="winapp pack &quot;$(TargetDir.TrimEnd('\'))&quot; --cert &quot;$(ProjectDir)devcert.pfx&quot;" 
          WorkingDirectory="$(ProjectDir)" 
          IgnoreExitCode="false" />
  </Target>

Con questa configurazione:

• La compilazione in modalità rilascio (dotnet build -c Release) creerà automaticamente il pacchetto MSIX
• Il MSIX è confezionato e firmato con il tuo certificato di sviluppo
• Il file finale .msix sarà nella radice del progetto

È anche possibile creare una configurazione personalizzata , ad esempio PackagedRelease, modificando la condizione in '$(Configuration)' == 'PackagedRelease'.

Operazioni successive

• Distribute tramite winget: Presenta il tuo MSIX al Windows Gestione pacchetti Community Repository
• Pubblica al Microsoft Store: Utilizzare winapp store per inviare il pacchetto
• Configura CI/CD: utilizza l'azione setup-WinAppCli GitHub per automatizzare il confezionamento nella pipeline
• API Explore Windows: Con l'identità del pacchetto, è ora possibile usare Notifications, on-device AI e altre API dipendenti da identity