Creare un software development kit
Un software development kit (SDK) è una raccolta di API a cui è possibile fare riferimento come singolo elemento in Visual Studio. Nella finestra di dialogo Gestione riferimenti sono elencati tutti gli SDK rilevanti per il progetto. Quando si aggiunge un SDK a un progetto, le API sono disponibili in Visual Studio.
Esistono due tipi di SDK:
Gli SDK della piattaforma sono componenti obbligatori per lo sviluppo di app per una piattaforma. Ad esempio, Windows 8.1 SDK è necessario per sviluppare app di Windows 8.x Store.
Gli SDK di estensione sono componenti facoltativi che estendono una piattaforma, ma non sono obbligatori per lo sviluppo di app per tale piattaforma.
Le sezioni seguenti descrivono l'infrastruttura generale degli SDK e come creare un SDK per la piattaforma e un SDK di estensione.
Platform SDK
Gli SDK della piattaforma sono necessari per sviluppare app per una piattaforma. Ad esempio, Windows 8.1 SDK è necessario per sviluppare app per Windows 8.1.
Installazione
Tutti gli SDK della piattaforma verranno installati in HKLM\Software\Microsoft\Microsoft SDKs\[TPI]\v[TPV]\@InstallationFolder = [SDK root]. Di conseguenza, Windows 8.1 SDK viene installato in HKLM\Software\Microsoft\Microsoft SDKs\Windows\v8.1.
Layout
Gli SDK della piattaforma hanno il layout seguente:
\[InstallationFolder root]
SDKManifest.xml
\References
\[config]
\[arch]
\DesignTime
\[config]
\[arch]
| Nodo | Descrizione |
|---|---|
| Cartella Riferimenti | Contiene file binari che contengono API che possono essere codificate in base a . Questi possono includere file o assembly di metadati di Windows (WinMD). |
| Cartella DesignTime | Contiene i file necessari solo in fase di pre-esecuzione/debug. Questi potrebbero includere documenti XML, librerie, intestazioni, file binari della casella degli strumenti in fase di progettazione, artefatti MSBuild e così via La documentazione XML, idealmente, verrà inserita nella cartella \DesignTime , ma la documentazione XML per i riferimenti continuerà a essere inserita insieme al file di riferimento in Visual Studio. Ad esempio, il documento XML per un riferimento\References\[config]\[arch]\sample.dll sarà \References\[config]\[arch]\sample.xml e la versione localizzata di tale documento sarà \References\[config]\[arch]\[locale]\sample.xml. |
| Cartella di configurazione | Possono essere presenti solo tre cartelle: Debug, Retail e CommonConfiguration. Gli autori dell'SDK possono inserire i file in CommonConfiguration se lo stesso set di file SDK deve essere usato, indipendentemente dalla configurazione di destinazione del consumer SDK. |
| Cartella Architettura | È possibile che esista qualsiasi cartella dell'architettura supportata. Visual Studio supporta le architetture seguenti: x86, x64, ARM e neutrale. Nota: Win32 esegue il mapping a x86 e AnyCPU esegue il mapping a neutrale. MSBuild cerca solo in \CommonConfiguration\neutral per gli SDK della piattaforma. |
| SDKManifest.xml | Questo file descrive il modo in cui Visual Studio deve usare l'SDK. Esaminare il manifesto dell'SDK per Windows 8.1:<FileList DisplayName = "Windows" PlatformIdentity = "Windows, version=8.1" TargetFramework = ".NET for Windows Store apps, version=v4.5.1; .NET Framework, version=v4.5.1" MinVSVersion = "14.0"> <File Reference = "Windows.winmd"> <ToolboxItems VSCategory = "Toolbox.Default" /> </File> </FileList>DisplayName: valore visualizzato dal Visualizzatore oggetti nell'elenco Sfoglia. PlatformIdentity: l'esistenza di questo attributo indica a Visual Studio e MSBuild che l'SDK è un SDK della piattaforma e che i riferimenti aggiunti da esso non devono essere copiati localmente. TargetFramework: questo attributo viene usato da Visual Studio per garantire che solo i progetti destinati agli stessi framework specificati nel valore di questo attributo possano utilizzare l'SDK. MinVSVersion: questo attributo viene usato da Visual Studio per utilizzare solo gli SDK applicabili. Riferimento: questo attributo deve essere specificato solo per i riferimenti che contengono controlli. Per informazioni su come specificare se un riferimento contiene controlli, vedere di seguito. |
SDK di estensione
Le sezioni seguenti descrivono le operazioni da eseguire per distribuire un SDK di estensione.
Installazione
Gli SDK di estensione possono essere installati per un utente specifico o per tutti gli utenti senza specificare una chiave del Registro di sistema. Per installare un SDK per tutti gli utenti, usare il percorso seguente:
%Program Files%\Microsoft SDKs<target platform>\v<platform version number>\ExtensionSDKs
Per un'installazione specifica dell'utente, usare il percorso seguente:
%U edizione Standard RPROFILE%\AppData\Local\Microsoft SDKs<target platform>\v<platform number>\ExtensionSDKs
Se si vuole usare una posizione diversa, è necessario eseguire una delle due operazioni seguenti:
Specificarlo in una chiave del Registro di sistema:
HKLM\Software\Microsoft\Microsoft SDKs<target platform>\v<platform version number>\ExtensionSDKs<SDKName><SDKVersion>\
e aggiungere una sottochiave (Predefinita) con valore .
<path to SDK><SDKName><SDKVersion>Aggiungere la proprietà
SDKReferenceDirectoryRootMSBuild al file di progetto. Il valore di questa proprietà è un elenco delimitato da punto e virgola delle directory in cui si trovano gli SDK di estensione a cui si desidera fare riferimento.
Layout di installazione
Gli SDK di estensione hanno il layout di installazione seguente:
\<ExtensionSDKs root>
\<SDKName>
\<SDKVersion>
SDKManifest.xml
\References
\<config>
\<arch>
\Redist
\<config>
\<arch>
\DesignTime
\<config>
\<arch>
\<SDKName>\<SDKVersion>: il nome e la versione dell'SDK di estensione derivano dai nomi di cartella corrispondenti nel percorso della radice dell'SDK. MSBuild usa questa identità per trovare l'SDK su disco e Visual Studio visualizza questa identità nella finestra Proprietà e nella finestra di dialogo Gestione riferimenti.
Cartella Riferimenti : i file binari che contengono le API. Possono trattarsi di file o assembly di metadati di Windows (WinMD).
Cartella redist : i file necessari per il runtime/debug e devono essere inseriti nel pacchetto come parte dell'applicazione dell'utente. Tutti i file binari devono essere posizionati sotto \redist\<config>\<arch> e i nomi binari devono avere il formato seguente per garantire l'univocità: ]<company.<>prodotto>.<scopo>.<estensione>. Ad esempio, *Microsoft.Cpp.Build.dll. Tutti i file con nomi che possono essere in conflitto con i nomi di file di altri SDK (ad esempio, javascript, css, pri, xaml, png e jpg) devono essere inseriti sotto \redist\<config>\<arch>\<sdkname>* ad eccezione dei file associati ai controlli XAML. Questi file devono essere posizionati sotto *\redist\<config>\arch>\<<componentname>\.
Cartella DesignTime : i file necessari solo in fase di pre-esecuzione/debug e non devono essere inseriti nel pacchetto come parte dell'applicazione dell'utente. Possono trattarsi di documenti XML, librerie, intestazioni, file binari della fase di progettazione della casella degli strumenti, artefatti MSBuild e così via. Qualsiasi SDK destinato all'utilizzo da parte di un progetto nativo deve avere un file SDKName.props . Di seguito è riportato un esempio di questo tipo di file.
<?xml version="1.0" encoding="utf-8"?> <Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003"> <PropertyGroup> <ExecutablePath>C:\Temp\ExecutablePath;$(ExecutablePath)</ExecutablePath> <IncludePath>$(FrameworkSDKRoot)\..\v8.1\ExtensionSDKs\cppimagingsdk\1.0\DesignTime\CommonConfiguration\Neutral\include;$(IncludePath)</IncludePath> <AssemblyReferencePath>C:\Temp\AssemblyReferencePath;(AssemblyReferencePath)</AssemblyReferencePath> <LibraryPath>$(FrameworkSDKRoot)\..\v8.1\ExtensionSDKs\cppimagingsdk\1.0\DesignTime\Debug\ARM;$(LibraryPath)</LibraryPath> <SourcePath>C:\Temp\SourcePath\X64;$(SourcePath)</SourcePath> <ExcludePath>C:\Temp\ExcludePath\X64;$(ExcludePath)</ExcludePath> <_PropertySheetDisplayName>DevILSDK, 1.0</_PropertySheetDisplayName> </PropertyGroup> </Project>I documenti di riferimento XML vengono posizionati insieme al file di riferimento. Ad esempio, il documento di riferimento XML per l'assembly \References\<config>\<arch>\sample.dll è \References\<config>\arch>\<sample.xml e la versione localizzata di tale documento è \References\<config>\<arch>\<locale>\sample.xml.
Cartella di configurazione : tre sottocartelle: Debug, Retail e CommonConfiguration. Gli autori dell'SDK possono inserire i file in CommonConfiguration quando lo stesso set di file SDK deve essere usato, indipendentemente dalla configurazione di destinazione del consumer SDK.
Cartella architettura : sono supportate le architetture seguenti: x86, x64, ARM, neutral. Win32 esegue il mapping a x86 e AnyCPU esegue il mapping a neutrale.
SDKManifest.xml
Il file SDKManifest.xml descrive in che modo Visual Studio deve usare l'SDK. Di seguito è riportato un esempio:
<FileList DisplayName = "My SDK"
ProductFamilyName = "My SDKs"
TargetFramework = ".NETCore, version=v4.5.1; .NETFramework, version=v4.5.1"
MinVSVersion = "14.0"
MaxPlatformVersion = "8.1"
AppliesTo = "WindowsAppContainer + WindowsXAML"
SupportPrefer32Bit = "True"
SupportedArchitectures = "x86;x64;ARM"
SupportsMultipleVersions = "Error"
CopyRedistToSubDirectory = "."
DependsOn = "SDKB, version=2.0"
MoreInfo = "https://msdn.microsoft.com/MySDK">
<File Reference = "MySDK.Sprint.winmd" Implementation = "XNASprintImpl.dll">
<Registration Type = "Flipper" Implementation = "XNASprintFlipperImpl.dll" />
<Registration Type = "Flexer" Implementation = "XNASprintFlexerImpl.dll" />
<ToolboxItems VSCategory = "Toolbox.Default" />
</File>
</FileList>
L'elenco seguente fornisce gli elementi del file:
DisplayName: valore visualizzato in Gestione riferimenti, Esplora soluzioni, Visualizzatore oggetti e altre posizioni nell'interfaccia utente per Visual Studio.
ProductFamilyName: nome del prodotto SDK complessivo. Ad esempio, Windows Library for JavaScript (WinJS) SDK è denominato "Microsoft.WinJS.1.0" e "Microsoft.WinJS.2.0", che appartengono alla stessa famiglia di prodotti SDK, "Microsoft.WinJS". Questo attributo consente a Visual Studio e MSBuild di stabilire tale connessione. Se questo attributo non esiste, il nome dell'SDK viene usato come nome della famiglia di prodotti.
FrameworkIdentity: specifica una dipendenza da una o più librerie di componenti di Windows. Il valore di questo attributo viene inserito nel manifesto dell'app che usa. Questo attributo è applicabile solo alle librerie dei componenti di Windows.
TargetFramework: specifica gli SDK disponibili in Gestione riferimenti e nella casella degli strumenti. Si tratta di un elenco delimitato da punto e virgola dei moniker del framework di destinazione, ad esempio ".NET Framework, version=v2.0; .NET Framework, version=v4.5.1". Se vengono specificate più versioni dello stesso framework di destinazione, Gestione riferimenti usa la versione più bassa specificata a scopo di filtro. Ad esempio, se è specificato ".NET Framework, version=v2.0; .NET Framework, version=v4.5.1", Reference Manager userà ".NET Framework, version=v2.0". Se viene specificato un profilo framework di destinazione specifico, solo il profilo verrà usato da Gestione riferimenti per scopi di filtro. Ad esempio, quando si specifica "Silverlight, version=v4.0, profile=Windows Telefono", Gestione riferimenti filtra solo il profilo di Windows Telefono; Un progetto destinato al framework Silverlight 4.0 completo non visualizza l'SDK in Gestione riferimenti.
MinVSVersion: versione minima di Visual Studio.
MaxPlatformVerson: la versione massima della piattaforma di destinazione deve essere usata per specificare le versioni della piattaforma in cui l'SDK dell'estensione non funzionerà. Ad esempio, il pacchetto di runtime di Microsoft Visual C++ v11.0 deve essere fatto riferimento solo ai progetti Windows 8. Pertanto, maxplatformversion del progetto Windows 8 è 8.0. Ciò significa che Gestione riferimenti filtra il pacchetto di runtime di Microsoft Visual C++ per un progetto Windows 8.1 e MSBuild genera un errore quando un progetto Windows 8.1 vi fa riferimento. Nota: questo elemento è supportato a partire da Visual Studio 2013.
AppliesTo: specifica gli SDK disponibili in Gestione riferimenti specificando i tipi di progetto di Visual Studio applicabili. Vengono riconosciuti nove valori: WindowsAppContainer, VisualC, VB, CSharp, WindowsXAML, JavaScript, Managed e Native. L'autore dell'SDK può usare e ("+") o ("|"), non ("!") operatori per specificare esattamente l'ambito dei tipi di progetto che si applicano all'SDK.
WindowsAppContainer identifica i progetti per le app di Windows 8.x Store.
SupportPrefer32Bit: i valori supportati sono "True" e "False". Il valore predefinito è "True". Se il valore è impostato su "False", MSBuild restituisce un errore per i progetti Windows 8.x Store (o un avviso per i progetti desktop) se il progetto che fa riferimento all'SDK ha Prefer32Bit abilitato. Per altre informazioni su Prefer32Bit, vedere Pagina compilazione, Progettazione progetti (C#) o Pagina Compilazione, Progettazione progetti (Visual Basic).For more information about Prefer32Bit, see Build page, Project Designer (C#) or Compile page, Project Designer (Visual Basic).
SupportedArchitectures: elenco delimitato da punto e virgola di architetture supportate dall'SDK. MSBuild visualizza un avviso se l'architettura dell'SDK di destinazione nel progetto di utilizzo non è supportata. Se questo attributo non è specificato, MSBuild non visualizza mai questo tipo di avviso.
SupportsMultipleVersions: se questo attributo è impostato su Error o Warning, MSBuild indica che lo stesso progetto non può fare riferimento a più versioni della stessa famiglia SDK. Se questo attributo non esiste o è impostato su Consenti, MSBuild non visualizza questo tipo di errore o avviso.
AppX: specifica il percorso dei pacchetti dell'app per la libreria dei componenti di Windows sul disco. Questo valore viene passato al componente di registrazione della libreria dei componenti di Windows durante il debug locale. La convenzione di denominazione per il nome file è <Company>.<Prodotto>.<Architettura>.<Configurazione>.<Versione>.appx. La configurazione e l'architettura sono facoltative nel nome dell'attributo e nel valore dell'attributo se non si applicano alla libreria dei componenti di Windows. Questo valore è applicabile solo alle librerie dei componenti di Windows.
CopyRedistToSubDirectory: specifica dove copiare i file nella cartella \redist rispetto alla radice del pacchetto dell'app (ovvero il percorso del pacchetto scelto nella creazione guidata pacchetto dell'app) e la radice del layout di runtime. Il percorso predefinito è la radice del pacchetto dell'app e del layout F5 .
DependsOn: elenco di identità SDK che definiscono gli SDK da cui dipende questo SDK. Questo attributo viene visualizzato nel riquadro dei dettagli di Gestione riferimenti.
MoreInfo: URL della pagina Web che fornisce informazioni e altre informazioni. Questo valore viene usato nel collegamento Altre informazioni nel riquadro destro di Gestione riferimenti.
Tipo di registrazione: specifica la registrazione WinMD nel manifesto dell'app ed è necessaria per WinMD nativo, che ha una DLL di implementazione controparte.
Riferimento file: specificato solo per i riferimenti che contengono controlli o sono WinMD nativi. Per informazioni su come specificare se un riferimento contiene controlli, vedere Specificare la posizione degli elementi della casella degli strumenti di seguito.
Specificare il percorso degli elementi della casella degli strumenti
L'elemento ToolBoxItems dello schema SDKManifest.xml specifica i nomi dei controlli, gli assembly di origine e i nomi di tabulazioni della casella degli strumenti negli SDK della piattaforma e dell'estensione. Gli esempi seguenti illustrano vari scenari. Questo è applicabile ai riferimenti WinMD o DLL.
Si noti che in Visual Studio 2019 e versioni precedenti, anziché elencare i nomi dei controlli della casella degli strumenti nel manifesto, Visual Studio enumerò dinamicamente i tipi di controllo negli assembly dell'SDK. A partire da Visual Studio 2022, questo non è più supportato; Gli elementi della casella degli strumenti devono essere elencati in modo esplicito in SDKManifest.xml.
Posizionare i controlli nella categoria predefinita della casella degli strumenti.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Toolbox.Default"> <Item Type = "Namespace.ControlName1" /> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Posizionare i controlli con un nome di categoria specifico.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory= "MyCategoryName"> <Item Type = "Namespace.ControlName1" /> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Posizionare i controlli in nomi di categoria specifici.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Graph"> <Item Type = "Namespace.ControlName1" /> </ToolboxItems> <ToolboxItems VSCategory = "Data"> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Posizionare i controlli con nomi di categoria diversi in Blend e Visual Studio.
// Blend accepts a slightly different structure for the category name because it allows a path rather than a single category. <File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Graph" BlendCategory = "Controls/sample/Graph"> <Item Type = "Namespace.ControlName1" /> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Enumerare controlli specifici in modo diverso in Blend e Visual Studio.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Graph"> <Item Type = "Namespace.ControlName1" /> </ToolboxItems> <ToolboxItems BlendCategory = "Controls/sample/Graph"> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Enumerare controlli specifici e inserirli nel percorso comune di Visual Studio o solo nel gruppo Tutti i controlli.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Toolbox.Common"> <Item Type = "Namespace.ControlName1" /> </ToolboxItems> <ToolboxItems VSCategory = "Toolbox.All"> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Enumera controlli specifici e mostra solo un set specifico in ChooseItems senza che siano presenti nella casella degli strumenti.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Toolbox.ChooseItemsOnly"> <Item Type = "Namespace.ControlName1" /> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>