A software development kit (SDK) is a collection of files that Visual Studio treats as a single reference item. The Reference Manager dialog box lists all SDKs that are relevant to the project that invokes the Reference Manager dialog box. When you add an SDK to a project, all of the APIs are displayed in IntelliSense, Toolbox, designers, Object Browser, and are available throughout the debugging, build, deployment, and packaging processes.
There are two types of SDKs:
Platform SDKs are components that are required for developing apps for a platform. For example, the Windows 8 SDK is required to develop Windows Store apps.
Extension SDKs are optional components that extend a platform but aren’t mandatory for developing apps for that platform.
The following sections describe the general infrastructure of SDKs and how to create a platform SDK and an extension SDK.
Visual Studio 2012 supports two properties:
Target Platform Identifier (TPI): The valid values of this property consist of the various platforms for which you can develop software. Windows is an example of a platform.
Target Platform Version (TPV): This property identifies the version of the target platform. For example, for Windows 8, the TPV is 8.0, and the TPI is Windows.
Together, these two properties form the Target Platform Moniker (TPM), which forms the foundation for the Windows 8 and SDK referencing infrastructure. For example, the TPM for Windows 8 is “Windows, version=8.0”.
Platform SDKs are required to develop apps for a platform. For example, the Windows 8 SDK is required to develop apps for Windows 8.
Platform SDKs have the following installation layout:
\[InstallationFolder root]
SDKManifest.xml
\References
\[config]
\[arch]
\DesignTime
\[config]
\[arch]
The following are the nodes in the layout.
References folder: the binaries that contain the APIs. These could include Windows Metadata (WinMD) files or assemblies.
DesignTime folder: the files that are needed only at pre-run/debugging time. These could include XML docs, libraries, headers, Toolbox design-time binaries, MSBuild artifacts, and so forth.
XML docs for references are placed alongside the reference files. For example, the XML document for a reference \References\[config]\[arch]\sample.dll is \References\[config]\[arch]\sample.xml, and the localized version of that doc is \References\[config]\[arch]\[locale]\sample.xml.
Configuration folder: three subfolders: Debug, Release and CommonConfiguration. SDK authors can place their files under CommonConfiguration if the same set of SDK files should be consumed, regardless of the configuration that the SDK consumer targets.
Architecture folder: The following architectures are supported: x86, x64, ARM, and neutral. Win32 maps to x86, and AnyCPU maps to neutral. In .NET Framework 4.5, MSBuild looks only under \CommonConfiguration\neutral for Platform SDKs.
The SDKManifest.xml file describes how Visual Studio should consume the SDK. Here is the SDK manifest file for Windows 8:
<FileList
DisplayName = “Windows”
PlatformIdentity = “Windows, version=8.0”
TargetFramework = “.NET for Windows Store apps, version=v4.5; .NET Framework, version=v4.5”
MinVSVersion = “11.0”>
<File Reference = “Windows.winmd”>
<ToolboxItems VSCategory = “Toolbox.Default” />
</File>
</FileList>
The following are the elements of the manifest.
DisplayName: the value that the Object Browser displays in the Browse list.
PlatformIdentity: specifies the SDK to be a platform SDK, so that the references added from it shouldn't be copied locally.
TargetFramework: ensures that only projects that target the same frameworks as specified in the value of this attribute can consume the SDK.
MinVSVersion: the minimum version for SDKs that this SDK consumes.
File Reference: specified for only those references that contain controls. For information about how to specify whether a reference contains controls, see Specifying the Location of Toolbox Items below.
The Reference Manager looks at the Target Platform Moniker (TPM) and then substitutes the property values in HKLM\Software\Microsoft\Microsoft SDKs\[TPI]\v[TPV]\@InstallFolder = [SDK root] to discover the disk location of the Platform SDK. The Reference Manager will then:
Open the SDK Manifest to determine whether the platform SDK is applicable to the Visual Studio version in which the Reference Manager has been invoked and whether the platform SDK is applicable as per the targeted Framework of the project invoking the Reference Manager. If the platform SDK is applicable on both counts, the Reference Manager will use the Target Platform Identifier property for the name of the tab in which to enumerate the platform SDK references. If the platform SDK is not found on disk, the tab will still appear, but the middle pane will show the message “[TPI] SDK was not found on the machine”.
Enumerate all the references specified under the [InstallFolder root]\references\CommonConfiguration\neutral folder in the [TPI] | Core tab.
Users can then add the references in the Platform SDK to their project and consume them in code as they would any assembly or WinMD.
Extension SDKs extend a platform but aren’t required for developing applications for that platform. For example, the Bing Maps and Windows Live SDKs extend Windows 8 but aren’t needed by all developers for that operating system.
Extension SDKs can be put in one of four locations:
\Program Files\Microsoft SDKs\[TPI]\v[TPV]\ExtensionSDKs
\Users\[username]\AppData\Local\Microsoft SDKs\[TPI]\v[TPV]\ExtensionSDKs
In the project file as <PropertyGroup><SDKReferenceDirectoryRoot>dir1;dir2</SDKReferenceDirectoryRoot></PropertyGroup> where dir1 and dir2 identify any two locations on disk
HKLM\Software\Microsoft\Microsoft SDKs\[TPI]\v[TPV]\ExtensionSDKs\[SDKName]\[SDKVersion]\@default = [SDK root] where [SDK root] is [Path to SDK]\[SDKName]\[SDKVersion]\
For the first three locations, no registry keys are needed. You can just drop the Extension SDK in the machine-wide, user-specific, or custom location, and Visual Studio will simply pick up the SDK. If none of those mechanisms is suitable, you can specify the custom location of the SDK by using the registry path in the fourth location.
Extension SDKs have the following installation layout:
\[ExtensionSDKs root]
\[SDKName]
\[SDKVersion]
SDKManifest.xml
\References
\[config]
\[arch]
\Redist
\[config]
\[arch]
\DesignTime
\[config]
\[arch]
\[SDKName]\[SDKVersion]: Specifies the identity of the Extension SDK. In other words, the name and version of the Extension SDK is derived from the corresponding folder names in the path to the SDK root. MSBuild uses this identity to find the SDK on disk, and Visual Studio displays this identity in the Properties window and Reference Manager.
References folder: the binaries that contain the APIs. These could be Windows Metadata (WinMD) files or assemblies.
Redist folder: the files that are needed for runtime/debugging and should get packaged as part of the user’s application. All binaries should be placed underneath \redist\[config]\[arch], and the binary names should have the following format to ensure uniqueness: [company].[product].[purpose].[extension]. For example, Microsoft.Cpp.Build.dll. All files with names that may collide with file names from other SDKs (for example, javascript, css, pri, xaml, png, and jpg files) should be placed underneath \redist\[config]\[arch]\[sdkname]\ except for the files that are associated with XAML controls. These files should be placed underneath \redist\[config]\[arch]\[componentname]\.
DesignTime folder: the files that are needed at only pre-run/debugging time and shouldn’t be packaged as part of the user’s application. These could be XML docs, libraries, headers, toolbox design-time binaries, MSBuild artifacts, and so forth. Any SDK that is intended for consumption by a native project must have an SDKName.props file. The following shows a sample of this type of 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.0\ExtensionSDKs\cppimagingsdk\1.0\DesignTime\CommonConfiguration\Neutral\include;$(IncludePath)</IncludePath> <AssemblyReferencePath>C:\Temp\AssemblyReferencePath;$(AssemblyReferencePath)</AssemblyReferencePath> <LibraryPath>$(FrameworkSDKRoot)\..\v8.0\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>XML reference documents are placed alongside the reference file in Visual Studio 2012. For example, the XML reference document for the \References\[config]\[arch]\sample.dll assembly is \References\[config]\[arch]\sample.xml, and the localized version of that doc is \References\[config]\[arch]\[locale]\sample.xml.
Configuration folder: three subfolders: Debug, Release, and CommonConfiguration. SDK authors can place their files under CommonConfiguration when the same set of SDK files should be consumed, regardless of the configuration targeted by the SDK consumer.
Architecture folder: the following architectures are supported: x86, x64, ARM, neutral. Win32 maps to x86, and AnyCPU maps to neutral.
This file describes how Visual Studio should consume the SDK. The following is an example of an extension SDKManifest.xml file.
<FileList DisplayName = “My SDK” ProductFamilyName = “My SDKs” FrameworkIdentity-Debug = “Name=MySDK.10.Debug, MinVersion=1.0.0.0” FrameworkIdentity-Retail = “Name=MySDK.10, MinVersion=1.0.0.0” TargetFramework = “.NETCore, version=v4.5; .NETFramework, version=v4.5” MinVSVersion = “11.0” AppliesTo = "WindowsAppContainer + WindowsXAML" SupportPrefer32Bit = “OS” SupportedArchitectures = “x86;x64;ARM” SupportsMultipleVersions = “Error” AppX-Debug-x86 = “.\AppX\Debug\x86\Microsoft.MySDK.x86.Debug.1.0.appx” AppX-Debug-x64 = “.\AppX\Debug\x64\Microsoft.MySDK.x64.Debug.1.0.appx” AppX-Debug-ARM = “.\AppX\Debug\ARM\Microsoft.MySDK.ARM.Debug.1.0.appx” AppX-Release-x86 = “.\AppX\Retail\x86\Microsoft.MySDK.x86.1.0.appx” AppX-Release-x64 = “.\AppX\Retail\x64\Microsoft.MySDK.x64.1.0.appx” AppX-Release-ARM = “.\AppX\Retail\ARM\Microsoft.MySDK.ARM.1.0.appx” CopyRedistToSubDirectory = “.” DependsOn = “SDKB, version=2.0” MoreInfo = “http://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>
The following list gives the elements of the file.
DisplayName: the value that appears in the Reference Manager, Solution Explorer, Object Browser, and other locations in the user interface for Visual Studio.
ProductFamilyName: The overall SDK product name. For example, the Windows Library for JavaScript (WinJS) SDK is named “Microsoft.WinJS.1.0” and “Microsoft.WinJS.2.0”, which belong to the same family of SDK products family, “Microsoft.WinJS”. This attribute allows Visual Studio and MSBuild to make that connection. If this attribute doesn’t exist, the SDK Name is used as the product family name.
FrameworkIdentity: specifies a dependency on one or more Windows component libraries The value of this attribute is put into the consuming app’s manifest. This attribute is applicable only to Windows component libraries.
TargetFramework: specifies the SDKs that are available in the Reference Manager and the toolbox. This is a semicolon-delimited list of Target Framework Monikers. If several versions of the same Target Framework are specified, the Reference Manager will use the lowest specified version for filtering purposes. For example, if “.NET Framework, version=v2.0; .NET Framework, version=v4.0” is specified, Reference Manager will use “.NET Framework, version=v2.0”. If a specific Target Framework Profile is specified, only that profile will be used by the Reference Manager for filtering purposes. For example, when “Silverlight, version=v4.0, profile=WindowsPhone” is specified, Reference Manager will only filter on the Windows Phone profile; a project targeting the full Silverlight 4.0 Framework will not see the SDK in the Reference Manager.
MinVSVersion: Filters the SDKs that show up in each version of Visual Studio.
AppliesTo: specifies the SDKs that are available in the Reference Manager by specifying applicable Visual Studio project types. In Visual Studio 2012, nine values are recognized: WindowsAppContainer, VisualC, VB, CSharp, WindowsXAML, JavaScript, Managed, and Native. The SDK author can use and (“+’), or (“|”), not (“!”) operators to specify exactly the scope of project types that apply to the SDK.
WindowsAppContainer identifies projects for Windows Store apps.
SupportPrefer32Bit: Supported values are “True” and “False”. If the value is set to “True”, the result is the same as if the attribute weren’t set; that is, the default assumption is that Prefer32Bit is supported. If the value is set to “False”, MSBuild returns an error for Windows Store projects (or a warning for desktop projects) if the project that references the SDK has Prefer32Bit enabled. For more information about Prefer32Bit, see Build Page, Project Designer (C#) or Compile Page, Project Designer (Visual Basic).
SupportedArchitectures: a semi-colon delimited list of architectures that the SDK supports. MSBuild displays a warning if the targeted SDK architecture in the consuming project isn't supported. If this attribute isn't specified, MSBuild never displays this type of warning.
SupportsMultipleVersions: if this attribute is set to Error or Warning, MSBuild indicates that the same project can't reference multiple versions of the same SDK family. If this attribute doesn’t exist or is set to Allow, MSBuild doesn't display this type of error or warning.
AppX: specifies the path to the app packages for the Windows component library on the disk. This value is passed to the registration component of the Windows component library during local debugging. The naming convention for the file name is [Company].[Product].[Architecture].[Configuration].[Version].appx. Configuration and Architecture are optional in the attribute name and the attribute value if they don’t apply to the Windows component library. This value is applicable only to Windows component libraries.
CopyRedistToSubDirectory: determines where the files under the \redist folder should be copied relative to the app package root (that is, the Package location chosen in the Create App Package wizard) and runtime layout root. The default location is the root of the app package and F5 layout.
DependsOn: A list of SDK identities that define the SDKs on which this SDK depends. This attribute appears in the details pane of the Reference Manager.
MoreInfo: the URL to the webpage that provides the consumer of the SDK with guidance. This value is used in the More Information link in the right pane of the Reference Manager.
File Reference: specified only for assembly/WinMD references that either contain controls or are native WinMD for which the registration type must be specified.
Registration Type: specifies the WinMD registration in the app manifest and is required for native WinMD, which has a counterpart implementation DLL.
File Reference: specified for only those references that contain controls. For information about how to specify whether a reference contains controls, see Specifying the Location of Toolbox Items below.
The Reference Manager looks at the Target Platform Moniker (TPM) and then substitute the property values in \Program Files\Microsoft SDKs\[TPI]\v[TPV]\ExtensionSDKs, \Users\[username]\Microsoft SDKs\[TPI]\v[TPV]\ExtensionSDKs, and HKLM\Software\Microsoft\Microsoft SDKs\[TPI]\v[TPV]\ExtensionSDKs\ to discover the disk location of the Extension SDKs.
The Reference Manager then opens the SDK Manifest of each Extension SDK to determine whether the Extension SDK is applicable to the Visual Studio version in which the Reference Manager has been invoked, whether the Extension SDK is applicable as per the targeted Framework of the project that invoked the Reference Manager, and whether the AppliesTo attribute values match the advertised capabilities of the project system that invoked the Reference Manager. If the Extension SDK is applicable on all counts, the Reference Manager shows the DisplayName, version, and SDK dependencies and then populate the More Information link correctly as per the Extension SDK Manifest.
An Extension SDK appears as a single entry in the Reference Manager. Once added, it appears as a single node in Solution Explorer for managed apps and Windows Store apps built for Windows using JavaScript. The SDK also appears as a single entry in the property pages for Visual C++ projects. The user now does not have to take any further action. The user is set for IntelliSense, toolbox, designers, Object Browser, build, deployment, debugging, and packaging.
 Note |
|---|
|
The ToolBoxItems element of the SDKManifest.xml schema specifies the category and location of toolbox items in both platform and extension SDKs. The following examples show how to specify different locations. This is applicable to either WinMD or DLL references.
Enumerate all controls, and place them in the toolbox default category.
<File Reference = “sample.winmd”> <ToolboxItems VSCategory = “Toolbox.Default”/> </File>Enumerate all controls, and place them under a particular category name.
<File Reference = “sample.winmd”> <ToolboxItems VSCategory= “MyCategoryName”/> </File>Enumerate specific controls, and place them under particular category names.
<File Reference = “sample.winmd”> < ToolboxItems VSCategory = “Graph”> <item Type = “sample.bargraph”/> <Item Type = “sample.piegraph”/> < ToolboxItems/> < ToolboxItems VSCategory = “Data”> <Item Type = “sample.datagrid”/> <Item Type = “sample.dataconnection”/> < ToolboxItems /> </File>Enumerate specific controls, and place them under different category names in Blend and 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 = “sample.bargraph”/> <Item Type = “sample.piegraph”/> < ToolboxItems /> </File>Enumerate specific controls differently in Blend and Visual Studio.
<File Reference = “sample.winmd”> < ToolboxItems VSCategory = “Graph”> <item Type = “sample.bargraph”/> <Item Type = “sample.piegraph”/> <ToolboxItems/> < ToolboxItems BlendCategory = “Controls/sample/Graph”> <Item Type = “sample.piegraph”/> <ToolboxItems/> </File>Enumerate specific controls, and place them under the Visual Studio Common Path or only in the All Controls Group.
<File Reference = “sample.winmd”> < ToolboxItems VSCategory = “Toolbox.Common”> <item Type = “sample.bargraph”/> <Item Type = “sample.piegraph”/> < ToolboxItems /> < ToolboxItems VSCategory = “Toolbox.All”> <Item Type = “sample.datagrid”/> <Item Type = “sample.dataconnection”/> < ToolboxItems /> </File>Enumerate specific controls, and show only a specific set in ChooseItems without them being in the toolbox.
<File Reference = “sample.winmd”> < ToolboxItems VSCategory = “Toolbox.ChooseItemsOnly”> <item Type = “sample.bargraph”/> <Item Type = “sample.piegraph”/> < ToolboxItems /> </File>
