Condividi tramite

Creare pacchetti UWP

  • Articolo

La piattaforma UWP (Universal Windows Platform) è una piattaforma applicativa comune per ogni dispositivo che esegue Windows 10. In questo modello le app UWP possono chiamare sia le API WinRT comuni a tutti i dispositivi che le API (incluse Win32 e .NET) specifiche della famiglia di dispositivi su cui l'app è in esecuzione.

Questa procedura dettagliata descrive come creare un pacchetto NuGet con un componente UWP nativo (incluso un controllo XAML) che può essere usato in progetti sia gestiti che nativi.

Prerequisiti

  1. Visual Studio 2017 o Visual Studio 2015. Installare l'edizione 2017 Community gratuitamente da visualstudio.com. È anche possibile usare le edizioni Professional ed Enterprise.

  2. Interfaccia della riga di comando di NuGet. Scaricare la versione più recente nuget.exe da nuget.org/downloads, salvandola in una posizione di propria scelta (il download include direttamente il file .exe). Aggiungere quindi tale posizione alla variabile di ambiente PATH, se necessario.

Creare un componente Windows Runtime UWP

  1. In Visual Studio scegliere File > nuovo > Project, espandere il nodo Visual C++ > Windows > Universale, selezionare il modello Windows Runtime Component (Universal Windows), modificare il nome in ImageEnhancer e fare clic su OK. Accettare i valori predefiniti per Versione di destinazione e Versione minima quando richiesto.

    Creating a new UWP Windows Runtime Component project

  2. Fare clic con il pulsante destro del mouse sul progetto in Esplora soluzioni, scegliere Aggiungi > nuovo elemento, fare clic sul nodo XAML di Visual C++>, selezionare Controllo basato su modelli, modificare il nome in AwesomeImageControl.cpp e fare clic su Aggiungi:

    Adding a new XAML Templated Control item to the project

  3. Fare clic con il pulsante destro del mouse sul progetto in Esplora soluzioni e scegliere Proprietà. Nella pagina Proprietà espandere Proprietà > di configurazione C/C++ e fare clic su File di output. Nel riquadro a destra impostare il valore di Genera file di documentazione XML su Sì:

    Setting Generate XML Documentation Files to Yes

  4. Fare clic con il pulsante destro del mouse sulla soluzione, scegliere Compilazione batch e selezionare le tre caselle Debug nella finestra di dialogo, come illustrato sotto. Ciò assicura che, quando si esegue una compilazione, venga generato un set completo di elementi per ogni sistema di destinazione supportato da Windows.

    Batch Build

  5. Nella finestra di dialogo Compilazione batch fare clic su Compila per verificare il progetto e creare i file di output necessari per il pacchetto NuGet.

Nota

In questa procedura dettagliata vengono usati gli elementi Debug per il pacchetto. Per il pacchetto non di debug, selezionare invece le opzioni Versione nella finestra di dialogo Compilazione batch e fare riferimento alle cartelle Versione risultanti nei passaggi che seguono.

Creare e aggiornare il file con estensione nuspec

Per creare il file .nuspec iniziale, eseguire i tre passaggi elencati sotto. Le sezioni che seguono forniscono quindi indicazioni dettagliate sugli altri aggiornamenti necessari.

  1. Aprire un prompt dei comandi e passare alla cartella contenente ImageEnhancer.vcxproj, che sarà una sottocartella sotto la posizione in cui si trova il file della soluzione.

  2. Eseguire il comando spec di NuGet per generare ImageEnhancer.nuspec. Il nome del file viene ricavato dal nome del file .vcxproj:

    nuget spec

  3. Aprire ImageEnhancer.nuspec in un editor e aggiornarlo in modo che corrisponda a quanto segue, sostituendo YOUR_NAME con un valore appropriato. Il valore <id>, in particolare, deve essere univoco in nuget.org. Vedere le convenzioni di denominazione descritte in Creazione di un pacchetto. Tenere inoltre presente che è anche necessario aggiornare i tag relativi all'autore e alla descrizione o si verifica un errore durante il passaggio di creazione del pacchetto.

    <?xml version="1.0"?>
<package >
    <metadata>
    <id>ImageEnhancer.YOUR_NAME</id>
    <version>1.0.0</version>
    <title>ImageEnhancer</title>
    <authors>YOUR_NAME</authors>
    <owners>YOUR_NAME</owners>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>Awesome Image Enhancer</description>
    <releaseNotes>First release</releaseNotes>
    <copyright>Copyright 2016</copyright>
    <tags>image enhancer imageenhancer</tags>
    </metadata>
</package>

Nota

Per i pacchetti compilati per uso pubblico, prestare particolare attenzione all'elemento <tags>, perché questi tag consentono ad altri utenti di trovare il pacchetto e di conoscerne le funzioni.

Aggiunta di metadati Windows al pacchetto

Un componente Windows Runtime richiede metadati che descrivono tutti i tipi disponibili pubblicamente, per consentire ad altre app e librerie di utilizzare il componente. Questi metadati sono contenuti in un file con estensione winmd, che viene creato quando si compila il progetto e deve essere incluso nel pacchetto NuGet insieme a un file XML con dati IntelliSense che viene compilato nello stesso momento.

Aggiungere il nodo <files> seguente al file .nuspec:

<package>
    <metadata>
        ...
    </metadata>

    <files>
        <!-- WinMd and IntelliSense files -->
        <file src="..\Debug\ImageEnhancer\ImageEnhancer.winmd" target="lib\uap10.0"/>
        <file src="..\Debug\ImageEnhancer\ImageEnhancer.xml" target="lib\uap10.0"/>
    </files>
</package>

Aggiunta di contenuto XAML

Per includere un controllo XAML con il componente, è necessario aggiungere il file XAML contenente il modello predefinito per il controllo (generato dal modello di progetto). Anche questo va inserito nella sezione <files>:

<?xml version="1.0"?>
<package >
    <metadata>
        ...
    </metadata>
    <files>
        ...

        <!-- XAML controls -->
        <file src="Themes\Generic.xaml" target="lib\uap10.0\Themes"/>

    </files>
</package>

Aggiunta di librerie di implementazione native

Nel componente la logica principale del tipo ImageEnhancer si trova nel codice nativo, che è contenuto nei diversi assembly ImageEnhancer.dll generati per ogni runtime di destinazione (ARM, x86 e x64). Per includerli nel pacchetto, farvi riferimento nella sezione <files> insieme ai file di risorse PRI associati:

<?xml version="1.0"?>
<package >
    <metadata>
        ...
    </metadata>
    <files>
        ...

        <!-- DLLs and resources -->
        <file src="..\ARM\Debug\ImageEnhancer\ImageEnhancer.dll" target="runtimes\win10-arm\native"/>
        <file src="..\ARM\Debug\ImageEnhancer\ImageEnhancer.pri" target="runtimes\win10-arm\native"/>

        <file src="..\ARM64\Debug\ImageEnhancer\ImageEnhancer.dll" target="runtimes\win10-arm64\native"/>
        <file src="..\ARM64\Debug\ImageEnhancer\ImageEnhancer.pri" target="runtimes\win10-arm64\native"/>

        <file src="..\x64\Debug\ImageEnhancer\ImageEnhancer.dll" target="runtimes\win10-x64\native"/>
        <file src="..\x64\Debug\ImageEnhancer\ImageEnhancer.pri" target="runtimes\win10-x64\native"/>

        <file src="..\Debug\ImageEnhancer\ImageEnhancer.dll" target="runtimes\win10-x86\native"/>
        <file src="..\Debug\ImageEnhancer\ImageEnhancer.pri" target="runtimes\win10-x86\native"/>

    </files>
</package>

Aggiunta del file con estensione targets

Per i progetti C++ e JavaScript che potrebbero utilizzare il pacchetto NuGet è poi necessario un file con estensione targets per identificare i file di assembly e winmd necessari. I progetti C# e Visual Basic eseguono questa operazione automaticamente. Creare questo file copiando il testo seguente in ImageEnhancer.targets e salvarlo nella stessa cartella del .nuspec file. Nota: questo file .targets deve avere lo stesso nome dell'ID di pacchetto (ad esempio, l'elemento <Id> nel file .nupspec):

<?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <PropertyGroup>
        <ImageEnhancer-Platform Condition="'$(Platform)' == 'Win32'">x86</ImageEnhancer-Platform>
        <ImageEnhancer-Platform Condition="'$(Platform)' != 'Win32'">$(Platform)</ImageEnhancer-Platform>
    </PropertyGroup>
    <ItemGroup Condition="'$(TargetPlatformIdentifier)' == 'UAP'">
        <Reference Include="$(MSBuildThisFileDirectory)..\..\lib\uap10.0\ImageEnhancer.winmd">
            <Implementation>ImageEnhancer.dll</Implementation>
        </Reference>
    <ReferenceCopyLocalPaths Include="$(MSBuildThisFileDirectory)..\..\runtimes\win10-$(ImageEnhancer-Platform)\native\ImageEnhancer.dll" />
    </ItemGroup>
</Project>

Fare quindi riferimento a ImageEnhancer.targets nel file .nuspec:

<?xml version="1.0"?>
<package >
    <metadata>
        ...
    </metadata>
    <files>
        ...

        <!-- .targets -->
        <file src="ImageEnhancer.targets" target="build\native"/>

    </files>
</package>

File con estensione nuspec finale

Il file .nuspec finale sarà simile al seguente, dove YOUR_NAME deve essere sostituito con un valore appropriato:

<?xml version="1.0"?>
<package >
    <metadata>
    <id>ImageEnhancer.YOUR_NAME</id>
    <version>1.0.0</version>
    <title>ImageEnhancer</title>
    <authors>YOUR_NAME</authors>
    <owners>YOUR_NAME</owners>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>Awesome Image Enhancer</description>
    <releaseNotes>First Release</releaseNotes>
    <copyright>Copyright 2016</copyright>
    <tags>image enhancer imageenhancer</tags>
    </metadata>
    <files>
    <!-- WinMd and IntelliSense -->
    <file src="..\Debug\ImageEnhancer\ImageEnhancer.winmd" target="lib\uap10.0"/>
    <file src="..\Debug\ImageEnhancer\ImageEnhancer.xml" target="lib\uap10.0"/>

    <!-- XAML controls -->
    <file src="Themes\Generic.xaml" target="lib\uap10.0\Themes"/>

    <!-- DLLs and resources -->
    <file src="..\ARM\Debug\ImageEnhancer\ImageEnhancer.dll" target="runtimes\win10-arm\native"/>
    <file src="..\ARM\Debug\ImageEnhancer\ImageEnhancer.pri" target="runtimes\win10-arm\native"/>
    <file src="..\ARM64\Debug\ImageEnhancer\ImageEnhancer.dll" target="runtimes\win10-arm64\native"/>
    <file src="..\ARM64\Debug\ImageEnhancer\ImageEnhancer.pri" target="runtimes\win10-arm64\native"/>     
    <file src="..\x64\Debug\ImageEnhancer\ImageEnhancer.dll" target="runtimes\win10-x64\native"/>
    <file src="..\x64\Debug\ImageEnhancer\ImageEnhancer.pri" target="runtimes\win10-x64\native"/>
    <file src="..\Debug\ImageEnhancer\ImageEnhancer.dll" target="runtimes\win10-x86\native"/>
    <file src="..\Debug\ImageEnhancer\ImageEnhancer.pri" target="runtimes\win10-x86\native"/>

    <!-- .targets -->
    <file src="ImageEnhancer.targets" target="build\native"/>

    </files>
</package>

Creare un pacchetto per il componente

Dopo avere completato il file .nuspec che fa riferimento a tutti i file da includere nel pacchetto, è possibile eseguire il comando pack:

nuget pack ImageEnhancer.nuspec

Questo codice genera ImageEnhancer.YOUR_NAME.1.0.0.nupkg. Aprendo il file in uno strumento come NuGet Package Explorer ed espandendo tutti i nodi, vengono visualizzati i contenuti seguenti:

NuGet Package Explorer showing the ImageEnhancer package

Suggerimento

Un file .nupkg è solo un file ZIP con un'estensione diversa. È anche possibile esaminare i contenuti del pacchetto, modificando .nupkg in .zip, ma si ricordi di ripristinare l'estensione prima di caricare un pacchetto in nuget.org.

Per rendere disponibile il pacchetto ad altri sviluppatori, seguire le istruzioni riportate in Pubblicare un pacchetto.