Créer un kit de développement logiciel (SDK)
Un kit de développement logiciel (SDK) est une collection d’API que vous pouvez référencer en tant qu’élément unique dans Visual Studio. La boîte de dialogue Gestionnaire de références répertorie tous les kits de développement logiciel (SDK) pertinents pour le projet. Lorsque vous ajoutez un kit de développement logiciel (SDK) à un projet, les API sont disponibles dans Visual Studio.
Il existe deux types de kits de développement logiciel (SDK) :
Les kits SDK de plateforme sont des composants obligatoires pour le développement d’applications pour une plateforme. Par exemple, le kit SDK Windows 8.1 est nécessaire pour développer des applications Windows 8.x Store.
Les kits SDK d’extension sont des composants facultatifs qui étendent une plateforme, mais qui ne sont pas obligatoires pour le développement d’applications pour cette plateforme.
Les sections suivantes décrivent l'infrastructure générale des kits SDK et expliquent comment créer un kit SDK de plateforme et un kit SDK d'extension.
SDK de plateforme
Les kits SDK de plateforme sont nécessaires pour développer des applications pour une plateforme. Par exemple, le kit SDK Windows 8.1 est nécessaire pour développer des applications Windows 8.1.
Installation
Tous les kits SDK de plateforme seront installés dans HKLM\Software\Microsoft\Microsoft SDKs\[TPI]\v[TPV]\@InstallationFolder = [SDK root]. En conséquence, le kit SDK Windows 8.1 est installé dans HKLM\Software\Microsoft\Microsoft SDKs\Windows\v8.1.
Disposition
Les kits SDK de plateforme ont la présentation suivante :
\[InstallationFolder root]
SDKManifest.xml
\References
\[config]
\[arch]
\DesignTime
\[config]
\[arch]
| Nœud | Description |
|---|---|
| Dossier de références | Contient des fichiers binaires qui contiennent des API qui peuvent être codées. Il peut s'agir de fichiers ou d'assemblies de métadonnées Windows (WinMD). |
| Dossier DesignTime | Contient des fichiers qui ne sont nécessaires qu'au moment de la pré-exécution/débogage. Il peut s'agir de documentation XML, de bibliothèques, d'en-têtes, de binaires de conception de la boîte à outils, d’artefacts de MSBuild, etc. La documentation XML devraient idéalement être placés dans le dossier \DesignTime, mais la documentation XML pour les références continueront d'être placés à côté du fichier de référence dans Visual Studio. Par exemple, la documentation XML pour une référence\References\[config]\[arch]\sample.dll sera \References\[config]\[arch]\sample.xml et la version localisée de cette documentation sera \References\[config]\[arch]\[locale]\sample.xml. |
| Dossier de configuration | Il ne peut y avoir que trois dossiers : Debug, Retail et CommonConfiguration. Les auteurs du Kit de développement logiciel (SDK) peuvent placer leurs fichiers sous CommonConfiguration si le même jeu de fichiers du kit SDK doit être consommé, quelle que soit la configuration que le consommateur du kit SDK cible. |
| Dossier d'architecture | Tout dossier d'architecture pris en charge peut exister. Visual Studio prend en charge les architectures suivantes : x86, x64, ARM et neutre. Note : Win32 correspond à x86, et AnyCPU correspond à neutre. MSBuild consulte uniquement \CommonConfiguration\neutral pour les kits SDK de plateforme. |
| SDKManifest.xml | Ce fichier décrit comment Visual Studio doit consommer le Kit de développement logiciel (SDK). Examinez le manifeste du kit SDK pour 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 : la valeur que l’explorateur d'objets affiche dans la liste de navigation. PlatformIdentity : l’existence de cet attribut indique à Visual Studio et MSBuild que le kit SDK est un kit SDK de plateforme et que les références ajoutées à partir de celle-ci ne doivent pas être copiées localement. TargetFramework : cet attribut est utilisé par Visual Studio pour s'assurer que seuls les projets qui ciblent les mêmes cadres que ceux spécifiés dans la valeur de cet attribut peuvent consommer le kit SDK. MinVSVersion : cet attribut est utilisé par Visual Studio pour consommer uniquement les kits SDK qui s'appliquent à lui. Reference : cet attribut doit être spécifié uniquement pour les références qui contiennent des contrôles. Pour plus d'informations sur comment spécifier si une référence contient des contrôles, voir ci-dessous. |
Kits SDK d’extension
Les sections suivantes décrivent ce qu’il faut faire pour déployer un Kit de développement logiciel (SDK) d’extension.
Installation
Les kits SDK d'extension peuvent être installés pour un utilisateur spécifique ou pour tous les utilisateurs sans spécifier de clé de registre. Pour installer un kit SDK pour tous les utilisateurs, utilisez le chemin d'accès suivant :
%Program Files%\Microsoft SDKs<target platform>\v<platform version number>\ExtensionSDKs
Pour une installation spécifique à l'utilisateur, utilisez le chemin d'accès suivant :
%USERPROFILE%\AppData\Local\Microsoft SDKs<target platform>\v<platform version number>\ExtensionSDKs
Si vous souhaitez utiliser un autre emplacement, vous devez procéder de l'une des deux manières suivantes :
Spécifiez-le dans une clé de Registre :
HKLM\Software\Microsoft\Microsoft SDKs<target platform>\v<platform version number>\ExtensionSDKs<SDKName><SDKVersion>\
et ajoutez une sous-clé (par défaut) dont la valeur est
<path to SDK><SDKName><SDKVersion>.Ajoutez la propriété MSBuild
SDKReferenceDirectoryRootà votre fichier projet. La valeur de cette propriété est une liste de répertoires délimités par des points-virgules dans lesquels résident les kits SDK d'extension que vous souhaitez référencer.
Schéma d'installation
Les kits SDK d’extension ont le schéma d’installation suivant :
\<ExtensionSDKs root>
\<SDKName>
\<SDKVersion>
SDKManifest.xml
\References
\<config>
\<arch>
\Redist
\<config>
\<arch>
\DesignTime
\<config>
\<arch>
\<SDKName>\<SDKVersion> : le nom et la version du Kit de SDK d’extension sont dérivés des noms de dossiers correspondants dans le chemin d’accès à la racine du kit SDK. MSBuild utilise cette identité pour trouver le kit SDK sur le disque, et Visual Studio affiche cette identité dans la fenêtre Propriétés et la boîte de dialogue Gestionnaire de références.
Dossier Reference : les binaires qui contiennent les API. Il peut s'agir de fichiers ou d'assemblies de métadonnées Windows (WinMD).
Dossier Redist : les fichiers nécessaires à l'exécution/au débogage et qui doivent être intégrés à l'application de l'utilisateur. Tous les binaires doivent être placés sous \redist\<config>\<arch>, et les noms des binaires doivent avoir le format suivant pour garantir l'unicité : ]<société>.<produit>.<objet>.<extension>. Par exemple, *Microsoft.Cpp.Build.dll. Tous les fichiers dont les noms peuvent entrer en conflit avec ceux d'autres kit SDK (par exemple, les fichiers javascript, css, pri, xaml, png et jpg) doivent être placés sous \redist\<config>\<arch>\<sdkname>*, à l'exception des fichiers associés aux contrôles XAML. Ces fichiers doivent être placés sous *redist\<config>\<arch>\<componentname>\.
Dossier DesignTime : les fichiers qui ne sont nécessaires qu'au moment de la pré-exécution/du débogage et qui ne doivent pas être intégrés à l'application de l'utilisateur. Il peut s'agir de documentation XML, de bibliothèques, d'en-têtes, de binaires de conception de la boîte à outils, d’artefacts de MSBuild, etc. Tout kit SDK destiné à être consommé par un projet natif doit avoir un fichier SDKName.props. Voici un exemple de ce type de fichier.
<?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>Les documents de référence XML sont placés à côté du fichier de référence. Par exemple, le document de référence XML pour l'assembly \References\<config>\<arch>\sample.dll est \References\<config>\<arch>\sample.xml, et la version localisée de ce document est \References\<config>\<arch>\<locale>\sample.xml.
Dossier Configuration : trois sous-dossiers : Debug, Retail et CommonConfiguration. Les auteurs du kit SDK peuvent placer leurs fichiers sous CommonConfiguration si le même jeu de fichiers du kit SDK doit être consommé, quelle que soit la configuration visée par le consommateur du kit SDK.
Dossier Architecture : les architectures suivantes sont prises en charge : x86, x64, ARM, neutre. Win32 correspond à x86, et AnyCPU correspond à neutre.
SDKManifest.xml
Le fichier SDKManifest.xml décrit comment Visual Studio doit consommer le Kit de développement logiciel (SDK). Par exemple :
<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>
La liste suivante fournit les éléments du fichier :
DisplayName : la valeur qui apparaît dans le Gestionnaire de références, l'Explorateur de solutions, l’Explorateur d'objets et d'autres emplacements de l'interface utilisateur de Visual Studio.
ProductFamilyName : le nom général du produit du kit de développement logiciel (SDK). Par exemple, le kit SDK de la bibliothèque Windows pour JavaScript (WinJS) est nommé « Microsoft.WinJS.1.0 » et « Microsoft.WinJS.2.0 », qui appartiennent à la même famille de produits du kit SDK, « Microsoft.WinJS ». Cet attribut permet à Visual Studio et MSBuild d’établir cette connexion. Si cet attribut n’existe pas, le nom du kit SDK est utilisé comme nom de famille de produits.
FrameworkIdentity : spécifie une dépendance à l'égard d'une ou plusieurs bibliothèques de composants Windows. La valeur de cet attribut est placée dans le manifeste de l’application consommatrice. Cet attribut s’applique uniquement aux bibliothèques de composants Windows.
TargetFramework : spécifie les Kits de développement logiciel (SDK) disponibles dans le Gestionnaire de références et la boîte à outils. Il s'agit d'une liste de monikers de framework cible délimitée par des points-virgules, par exemple « .NET Framework, version=v2.0 ; .NET Framework, version=v4.5.1 ». Si plusieurs versions du même cadre cible sont spécifiées, le Gestionnaire de référence utilise la version la plus basique spécifiée à des fins de filtrage. Par exemple, si « .NET Framework, version=v2.0 ; .NET Framework, version=v4.5.1 » est spécifié, le gestionnaire de référence utilisera « .NET Framework, version=v2.0 ». Si un profil de cadre cible spécifique est spécifié, seul ce profil sera utilisé par le Gestionnaire de référence à des fins de filtrage. Par exemple, lorsque « Silverlight, version=v4.0, profile=WindowsPhone » est spécifié, le gestionnaire de référence filtre uniquement sur le profil téléphone Windows ; un projet ciblant le cadre complet Silverlight 4.0 ne voit pas le kit SDK dans le gestionnaire de référence.
MinVSVersion : version minimale de Visual Studio.
MaxPlatformVerson : La version maximale de la plateforme cible doit être utilisée pour spécifier les versions de plateforme sur lesquelles votre kit SDK d'extension ne fonctionnera pas. Par exemple, le package d'exécution Microsoft Visual C++ v11.0 ne doit être référencé que par les projets Windows 8. Par conséquent, MaxPlatformVersion du projet Windows 8 est 8.0. Cela signifie que le gestionnaire de références filtre le package d'exécution Microsoft Visual C++ pour un projet Windows 8.1, et que MSBuild génère une erreur lorsqu'un projet Windows 8.1 y fait référence. Note : cet élément est pris en charge à partir de Visual Studio 2013.
AppliesTo : spécifie les SDK disponibles dans le gestionnaire de référence en spécifiant les types de projets Visual Studio applicables. Neuf valeurs sont reconnues : WindowsAppContainer, VisualC, VB, CSharp, WindowsXAML, JavaScript, Managed et Native. L’auteur du kit de développement logiciel (SDK) peut utiliser les opérateurs et (« + »), ou (« | »), et pas (« ! ») pour spécifier exactement l’étendue des types de projet qui s’appliquent au kit de développement logiciel (SDK).
WindowsAppContainer identifie les projets pour les applications du Windows 8.x Store.
SupportPrefer32Bit : les valeurs prises en charge sont « True » et « False ». La valeur par défaut est « `True » (Vrai). Si la valeur est définie sur « False », MSBuild renvoie une erreur pour les projets Windows 8.x Store (ou un avertissement pour les projets desktop) si le projet qui fait référence au kit SDK a Prefer32Bit activé. Pour plus d'informations sur Prefer32Bit, consultez la page Build, Project Designer (C#) ou la page Compile, Project Designer (Visual Basic).
SupportedArchitectures : une liste délimitée par des points-virgules des architectures prises en charge par le kit de développement logiciel (SDK). MSBuild affiche un avertissement si l’architecture du Kit de développement logiciel (SDK) ciblée dans le projet consommateur n’est pas prise en charge. Si cet attribut n’est pas spécifié, MSBuild n’affiche jamais ce type d’avertissement.
SupportsMultipleVersions : si cet attribut est défini sur Erreur ou Avertissement, MSBuild indique que le même projet ne peut pas référencer plusieurs versions de la même famille de kit SDK. Si cet attribut n’existe pas ou est défini sur Autoriser, MSBuild n’affiche pas ce type d’erreur ou d’avertissement.
AppX: spécifie le chemin d’accès aux packages d’application pour la bibliothèque de composants Windows sur le disque. Cette valeur est transmise au composant d’inscription de la bibliothèque de composants Windows pendant le débogage local. La convention d’affectation de noms pour le nom de fichier est <Company>.<Product>.<Architecture>.<Configuration>.<Version>.appx. La configuration et l’architecture sont facultatives dans le nom de l’attribut et la valeur d’attribut si elles ne s’appliquent pas à la bibliothèque de composants Windows. Cette valeur ne s'applique qu'aux bibliothèques de composants Windows.
CopyRedistToSubDirectory : spécifie où les fichiers du dossier \redist doivent être copiés par rapport à la racine du package de l'application (c'est-à-dire l'emplacement du package choisi dans l'assistant de Création du package de l’application) et à la racine du schéma d'exécution. L'emplacement par défaut est la racine du package de l'application et du schéma F5.
DependsOn : une liste des identités du kit SDK qui définissent les kits SDK dont dépend ce kit SDK. Cet attribut apparaît dans le volet Détails du gestionnaire de référence.
MoreInfo : l’URL de la page web qui fournit de l’aide et plus d’informations. Cette valeur est utilisée dans le lien Plus d'informations dans le volet droit du gestionnaire de référence.
Type d’inscription : spécifie l’inscription WinMD dans le manifeste de l’application et est requis pour WinMD natif, qui a un équivalent dans l'implémentation de la DLL.
Référence de fichier : spécifiée uniquement pour les références qui contiennent des contrôles ou qui sont des WinMD natifs. Pour plus d'informations sur comment spécifier si une référence contient des contrôles, consultez Spécifier l'emplacement des éléments de la boîte à outils ci-dessous.
Spécifier l’emplacement des éléments de boîte à outils
L'élément ToolBoxItems du schéma SDKManifest.xml spécifie les noms de contrôle, les assemblies source et les noms des onglets de la boîte à outils dans les kits SDK de plateforme et d'extension. Les exemples suivants montrent différents scénarios. Cela s’applique aux références WinMD ou DLL.
Notez que dans Visual Studio 2019 et les versions antérieures, plutôt que de répertorier les noms des contrôles de la boîte à outils dans le manifeste, Visual Studio a énuméré dynamiquement les types de contrôle dans les assemblies du kit de développement logiciel (SDK). À partir de Visual Studio 2022, cette prise en charge prendra fin ; les éléments de boîte à outils doivent être répertoriés explicitement dans SDKManifest.xml.
Placez les contrôles dans la catégorie par défaut de la boîte à outils.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Toolbox.Default"> <Item Type = "Namespace.ControlName1" /> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Placer les contrôles sous le nom d'une catégorie particulière.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory= "MyCategoryName"> <Item Type = "Namespace.ControlName1" /> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Placer les contrôles sous des noms de catégories particulières.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Graph"> <Item Type = "Namespace.ControlName1" /> </ToolboxItems> <ToolboxItems VSCategory = "Data"> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Placez des contrôles sous différents noms de catégorie dans Blend et 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>Enumérez les contrôles spécifiques différemment dans Blend et 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>Enumérez les contrôles spécifiques et placez-les sous le chemin d'accès commun de Visual Studio ou uniquement dans Tout le groupe de contrôles.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Toolbox.Common"> <Item Type = "Namespace.ControlName1" /> </ToolboxItems> <ToolboxItems VSCategory = "Toolbox.All"> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>Enumérez les contrôles spécifiques et affichez uniquement un jeu spécifique dans ChooseItems sans qu'ils se trouvent dans la boîte à outils.
<File Reference = "sample.winmd"> <ToolboxItems VSCategory = "Toolbox.ChooseItemsOnly"> <Item Type = "Namespace.ControlName1" /> <Item Type = "Namespace.ControlName2" /> </ToolboxItems> </File>