Tutorial: Creating and using extension SDKs

Expand
1 out of 2 rated this helpful Rate this topic

Tutorial: Creating and using extension SDKs

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

You can add an entire software development kit (SDK) to your project without having to add the components one at a time. You can also group together your own assemblies, components, and resources into an SDK and distribute it as one piece. SDKs that you can add to your app or create and distribute as one piece are called extensions SDKs.

Extensions SDKs come in two flavors:

  • Framework extension SDKs, which are included in Windows Developer Preview and Visual Studio. For example, the C runtime SDK. If an app uses a framework extension SDK, it is marked in the manifest file as a dependency. When the app runs, the framework extension SDK is downloaded from the Windows Store.

  • Non-framework extension SDKs, which are created by you, your friend, or a vendor. The non-framework SDK is deployed with the app that uses it. Non-framework SDKs can be installed as a VSIX extension. For more information on VSIX extensions, see VSIX Deployment.

In this tutorial, we focus exclusively on non-framework extension SDKs.

To follow this tutorial, you must be running Windows with Visual Studio 11 Express for Windows Developer Preview installed. For more information, see First Look at Visual Studio Express.

This tutorial contains code written in Microsoft Visual C#, but you don’t need to know the language to follow along. Just cut and paste the code as you find it.

Let’s create a simple extension SDK with two components. First we must decide what kind of app will use this SDK.

  • Managed Windows Metro style apps can use managed assemblies.

  • Managed Metro style apps can also use Windows metadata ( .winmd) components.

  • Native Metro style apps can use native assemblies.

  • Native Metro style apps can also use .winmd components.

  • WWA Metro style apps can also use .winmd components.

We’ll be adding our extension SDK to a managed Metro style app. Because managed assemblies are simpler and easier to create than Windows metadata components, we’ll use them to build our extension SDK.

Creating the components

Let’s create an extension SDK with two components. To avoid name collisions with other components, you should add your company name to the start of each component name, followed by a period.

Tip Tip

You can use multiple words separated by periods, for example Fabrikam.Systems.Ultimate.Controls.DataGrid.Cell.dll

  1. Open Visual Studio. Accept the software license terms and the UAC prompt if you see them.

  2. Create a new Visual C# Windows Class Library for Tailored Applications project named MyCompany.Alpha.

  3. Add a new Visual C# Windows Class Library for Tailored Applications project named MyCompany.Beta.

  4. In the Solution Explorer, choose Show All Files for each project node. Examine the bin/Release folders and verify that you’ve built two managed assemblies.

Installing your extension SDK using folder layout

You can combine your two assemblies into an extension SDK and install it to your machine this way:

  1. Navigate to the folder

    C:\Program Files\Microsoft SDKs\Windows\v8.0\ExtensionSDKs
    
  2. Create a new subfolder named MyCompany.Extension.

  3. Create a new subfolder in this folder named by the version number of your extension, for example, 1.0:

    MyCompany.Extension\1.0
    
  4. Create a new manifest text file named SDKManifest.xml on your desktop.

    Tip Tip

    Your text editor can’t directly edit files in the Program File folder.

  5. Fill the manifest file with the following xml:

    <?xml version="1.0"?>
    <FileList AppliesTo="TailoredC#,TailoredVB"
        MinToolsVersion="4.0" MinVSVersion="11.0" 
        DisplayName="Brand name of extension"> 
        <File Reference="MyCompany.Alpha.dll"/> 
        <File Reference="MyCompany.Beta.dll"/> 
    </FileList>
    

    This roughly translates to “This extension requires Visual Studio 11.0 or later and .Net Framework 4.0 or later. It can be used by Visual C# or Visual Basic Metro style apps. The extension version is 1.0 and the name that appears in the Add Reference dialog is Brand name of extension. The extension consists of two files, both of which are managed DLLs.”

  6. Copy the manifest file to the version subfolder

    MyCompany.Extension\1.0\SDKManifest.xml
    
  7. Create a new subfolder named References in the version folder

    MyCompany.Extension\1.0\References
    
  8. Create a new subfolder named CommonConfiguration in the References folder

    MyCompany.Extension\1.0\References\CommonConfiguration
    
  9. Create a new subfolder named neutral in the CommonConfiguration folder

    MyCompany.Extension\1.0\References\CommonConfiguration\neutral
    
  10. Copy the MyCompany.Alpha and MyCompany.Beta assemblies to the neutral folder.

The CommonConfiguration folder indicates that regardless of the configuration being targeted by the project consuming your SDK, you always want the references in this folder to be used. To limit the extension to a release configuration, name the folder Retail. To limit it to a debug configuration, name it Debug.

The neutral folder indicates that your extension can be used for apps built for Any CPU.

Caution note Caution

Actually, folders are examined in order from the least specific to the most specific:

  • \commonconfiguration\neutral

  • \commonconfiguration\[arch]

  • \[config]\neutral

  • \[config]\[arch]

By putting your assemblies in the least specific folder, you do not have to put the same assembly in two folders.

Your extension is immediately available through the Add Reference dialog in Visual Studio.

  1. Close and restart Visual Studio.

  2. Create a new Visual C# Windows Tailored Application named AnApp.

  3. In the Solution Explorer, open the References node shortcut menu, then choose Add Reference. The Reference Manager appears.

    Tip Tip

    Notice that there are no references at all under the References node. Managed Metro style apps invisibly include references to all of the WinSDK and the .NET 4.5 Core API. For the same reason, there is no Framework item in the Assemblies tab in the Reference Manager.

  4. In the left pane, choose the Windows tab, then choose the Extensions SDK item.

    You will see a list of extensions appear in the middle pane.

  5. Choose My company, my extension.

    The Name, Version, and Source details appear in the left pane.

    Extension SDK reference dialog
  6. Choose Add, then choose Close.

    Your extension appears in the Solution Explorer under the References node.

  7. Open the shortcut menu for your extension reference and choose View in Object Browser.

The Object Browser appears and displays the namespaces, classes, members of both MyCompany.Alpha and MyCompany.Beta.

Extension SDK object browser

These namespaces, classes, and members are also available through Intellisense. To see this in action, open the MainPage.xaml.cs file and add this line to the constructor:

MyCompany.Alpha.Class1 alpha = new MyCompany.Alpha.Class1();

Note that as you type , Intellisense knows about your namespace and classes and tries to help you with statement completion.

Did you find this helpful?
(1500 characters remaining)