Uso dell'interfaccia della riga di comando di winapp con app basate su file .NET

Per un esempio funzionante, vedere l'esempio dotnet-file-app. Per informazioni di riferimento complete, vedere Modalità file singolo nel riferimento all'interfaccia della riga di comando.

.NET 10 può eseguire un singolo .cs file senza file di progetto. Questa guida illustra come eseguire il file con l'identità del pacchetto usando winapp run, così che API come Windows.ApplicationModel.Package.Current, le notifiche dell'app e l'IA sul dispositivo funzionino. Non si creano manifest o asset di immagine: winapp li genera automaticamente.

L'identità del pacchetto è un concetto di base nel modello di Windows app. Consente all'applicazione di accedere a API Windows specifiche, avere un'esperienza di installazione/disinstallazione pulita e altro ancora. Un'app basata su file eseguita con dotnet run non ha un'identità del pacchetto.

Prerequisites

1. .NET SDK 10.0.300 o versione successiva: installare .NET 10 SDK (richiede un riavvio dopo l'installazione):

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

2. CLI di Winapp: installare lo strumento tramite winget (o aggiornare se già installato):

   winget install Microsoft.winappcli --source winget
   

1. Creare un'app basata su file

Creare una cartella con un file denominato 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");
}

Le #:property righe configurano l'app nel modo in cui farebbe un .csproj. Il Windows TargetFramework consente al codice di accedere alle API di Windows Runtime, come Package.

Eseguilo con dotnet run:

dotnet run hello.cs

L'output è Not packaged: l'app viene eseguita senza identità del pacchetto.

2. Eseguire con l'identità del pacchetto

Eseguire lo stesso file con winapp:

winapp run hello.cs

Winapp compila l'app, genera un manifest e gli asset di immagine predefiniti nell'output di compilazione, registra l'app come pacchetto e la avvia. L'output mostra ora l'identità del pacchetto:

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

La cartella di origine contiene ancora solo hello.cs. Poiché si tratta di un'app console (OutputType=Exe), winapp la avvia tramite un alias di esecuzione, in modo che l'output venga visualizzato nel terminale.

La registrazione rimane attiva dopo la chiusura dell'app, quindi eseguendo di nuovo winapp run hello.cs si riutilizza la stessa identità. Si rimuove nel passaggio 5.

3. Assegnare un nome al pacchetto

Per impostazione predefinita, il nome del pacchetto è il nome del file più un breve hash del percorso del file. Per scegliere un nome personalizzato, deregistrare prima il pacchetto corrente, perché un nuovo nome registra un nuovo pacchetto:

winapp unregister hello.cs

#:property Aggiungere quindi direttive all'inizio di hello.cs:

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

Eseguilo di nuovo:

winapp run hello.cs

L'output mostra il nuovo nome, ad esempio Package Family Name: com.contoso.hello_<publisher-hash>. L'app viene visualizzata anche nel menu Start come Contoso Hello.

Per ogni proprietà di identità e il valore predefinito corrispondente, vedere Proprietà del manifesto.

4. Eseguire con dotnet run

Per ottenere lo stesso avvio in pacchetto da dotnet run non pacchettizzato, fare riferimento al pacchetto Microsoft.Windows.SDK.BuildTools.WinApp all'inizio di hello.cs:

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

dotnet run hello.cs

L'output mostra la stessa identità del pacchetto come winapp run. Poiché dotnet run genera l'output in una cartella diversa, segnala che sostituisce una registrazione esistente installata da un percorso diverso. Questo è previsto ed è possibile ignorarlo.

Il pacchetto fornisce anche all'app un'icona di finestra segnaposto, quindi un'app con finestra mostra un'icona nella barra del titolo. Per usare il tuo, puntare ApplicationIcon a un .ico file:

#:property ApplicationIcon=Assets\MyApp.ico

Per le proprietà che controllano l'avvio, vedere Esecuzione con dotnet run.

5. Pulizia

Rimuovere la registrazione passando il .cs file a winapp unregister:

winapp unregister hello.cs

Aggiungere funzionalità o un manifest personalizzato

Alcune API richiedono una capacità dichiarata. Ad esempio, le API di intelligenza artificiale Windows richiedono systemAIModels:

#:property WinAppCapabilities=systemAIModels

winapp scrive ogni funzionalità nell'elemento del manifesto corretto. Vedere Funzionalità per l'elenco completo e le regole di denominazione.

I gestori di protocollo, le associazioni di file e altre integrazioni della shell necessitano di un manifest scritto. Posiziona hello.appxmanifest accanto a hello.cs e winapp lo userà invece di generarne uno. Vedi Bring your own manifest.

Operazioni successive

• Pacchetto di distribuzione: winapp run registra l'app solo per lo sviluppo. Per produrre un MSIX che è possibile distribuire, spostare il codice in un progetto e seguire Package with MSIX nella guida .NET.
• API Explore Windows: Con l'identità del pacchetto, è ora possibile usare Notifications, on-device AI e altre API dipendenti da identity