Background
Extension SDKs are one of the new ways of distributing components for Metro-style applications. An Extension SDK is similar in concept to a regular assembly reference, but is instead a rich collection of files to cover various configurations and design time scenarios. Beyond a simple file reference, Extension SDKs provide the following:
- References folder (binaries to be referenced by the project)
- Redist folder (additional files that are needed for runtime or debugging and should be packaged as part of the application)
- DesignTime folder (files used for design-time)
- Configuration (debug, release, CommonConfiguration – have different files for different build types)
- Architecture (x86, x86, ARM – necessary if referencing native code)
- Locale (localized files)
The full details on how to create an Extension SDK are in the MSDN page linked above, but one thing to note is that by default, VS and MSBuild will only look for Extension SDKs in the following locations:
- \Program Files\Microsoft SDKs\Windows\v8.0\ExtensionSDKs
- \Users\[username]\AppData\Local\Microsoft SDKs\Windows\v8.0\ExtensionSDKs
- HKLM\Software\Microsoft\Microsoft SDKs\Windows\v8.0\ExtensionSDKs\[SDKName]\[SDKVersion]\@default = [SDK root]
Naturally, a question arises around storing an Extension SDK alongside their source code instead of in a separate location. There are a few reasons why some people want to do this:
- Traceability – some teams require that all tools and libraries used as part of a build, or referenced by their applications, live in source control so they know exactly what version was used to build an app at any point.
- No-installation – some teams do not want to have to install, or cannot place, packages on their build servers. The default locations are often off-limits in shared build environments.
- Versioning across branches – While you can have multiple SDK versions installed, every user who builds the app needs to have the right version already installed.
The solution is to put the libraries in version control in a “libs” directory. NuGet does this for existing libraries in a \packages directory at the solution-level; it does not yet support Extension SDKs. The good news is that both Visual Studio 11 and MSBuild already support defining additional locations for Extension SDK’s by overriding the SDKReferenceDirectoryRoot variable. The key is to add the override after the <Import> element near the end of the csproj/vbproj file like this:
<Import Project="$(MSBuildExtensionsPath)\Microsoft\WindowsXaml\v11.0\Microsoft.Windows.UI.Xaml.CSharp.targets" />
<PropertyGroup>
<SDKReferenceDirectoryRoot>$(SolutionDir)\libs;$(SDKReferenceDirectoryRoot)</SDKReferenceDirectoryRoot>
</PropertyGroup>
With that in place, you can then put your Extension SDK files alongside your solution:
\libs\Windows\v8.0\ExtensionSDKs\[SDKName]\[SDKVersion]\…
Once there, it will be available in the Visual Studio Add References dialog like any other Extension SDK.
An Example
Let’s walk through an example of how we can use the Bing Maps SDK for Metro style apps (beta) as a per-project SDK instead of being installed in either the user profile or program files locations. Initially, most Extension SDKs are likely going to be distributed as either a VSIX or MSI so they can install into the right location. The easiest approach is to install on one machine and then copy the files into your source tree. Then you can then uninstall the SDK if you’d like.
After downloading the Bing Maps SDK from the gallery, install the VSIX file:
Next, lets create a new Bing Maps Application using the template installed by the VSIX:
Once the project is created, if you expand References in the Solution Explorer, you’ll see that Bing has been added as a reference:
Right-clicking and selecting Properties on the reference will show you that it’s an SDK reference and where the file are located:
You can see from the Path that Visual Studio (and MSBuild) are reading the file from \Users\[username]\AppData\Local\Microsoft SDKs\Windows\v8.0\ExtensionSDKs.
Now, lets make our changes so we can store those files alongside our solution.
First, in Explorer, navigate to the folder with your solution in it, then create the following directory structure:
Libs\Windows\v8.0\ExtensionSDKs.
Next, in another Explorer window, go to your local AppData directory in your user profile and navigate to the ExtensionSDKs directory there:
Next, copy the two directories (or just the one you need, either Xaml for Managed code or the other for JavaScript) to the ExtensionSDKs directory you created earlier underneath the solution directory. They can now be checked into source control like any other project item.
The final step is to add the “libs” path from your solution to the search path for ExtensionSDKs in your project file. Right-click the project in the Solution Explorer and click Unload Project:
Now you can right-click the project again and select Edit Project File. This will bring up the csproj (or vbproj) file up in the XML editor. Scroll to the bottom of the file and you’ll see a line starting with “<Import Project=…”. On the next line, add the following XML:
<PropertyGroup>
<SDKReferenceDirectoryRoot>$(SolutionDir)\libs;$(SDKReferenceDirectoryRoot)</SDKReferenceDirectoryRoot>
</PropertyGroup>
That will tell Visual Studio and MSBuild to look for additional Extension SDKs in your libs directory before checking the default locations.
Save your changes and then reload the project file by right-clicking the project in the Solution Explorer and clicking Reload Project. If you check the properties for the reference, as before, you’ll now see it resolving to your project path instead of your user profile:
You’re now ready to check your changes in and share them with others. Build systems and other users of your code won’t need to install the extensions as they’ll be using the version alongside your project.
One additional thing to note is that after modifying your project file to include your libs directory, Visual Studio’s Add Reference dialog will automatically pick up any Extension SDKs that reside there:
Happy coding!
