Distributing a managed Windows Runtime component

  • Article

 

You can distribute your Windows Runtime component by file copy. However, if your component consists of many files, installation can be tedious for your users. Also, errors in placing files or failure to set references might cause problems for them. You can package a complex component as a Visual Studio extension SDK, to make it easy to install and use. Users only need to set one reference for the entire package. They can easily locate and install your component by using the Extensions and Updates dialog box, as described in Installing and Managing Visual Studio Tools and Extensions, in the MSDN Library.

Planning a distributable Windows Runtime component

Choose unique names for binary files, such as your .winmd files. We recommend the following format to ensure uniqueness:

company.product.purpose.extension
For example: Microsoft.Cpp.Build.dll

Your binary files will be installed in app packages, possibly with binary files from other developers. See "Extension SDKs" in How to: Create a Software Development Kit, in the MSDN Library.

To decide how to distribute your component, consider how complex it is. An extension SDK or similar package manager is recommended when:

  • Your component consists of multiple files.

  • You provide versions of your component for multiple platforms (x86 and ARM, for example).

  • You provide both debug and release versions of your component.

  • Your component has files and assemblies that are used only at design time.

An extension SDK is particularly useful if more than one of the above are true.

Note

For complex components, the NuGet package management system offers an open source alternative to extension SDKs. Like extension SDKs, NuGet enables you to create packages that simplify the installation of complex components. For a comparison of NuGet packages and Visual Studio extension SDKs, see Adding References Using NuGet Versus an Extension SDK in the MSDN Library.

Distribution by file copy

If your component consists of a single .winmd file, or a .winmd file and a resource index (.pri) file, you can simply make the .winmd file available for users to copy. Users can put the file wherever they want to in a project, use the Add Existing Item dialog box to add the .winmd file to the project, and then use the Reference Manager dialog box to create a reference. If you include a .pri file or an .xml file, instruct users to place those files with the .winmd file.

Note

Visual Studio 2012 always produces a .pri file when you build your Windows Runtime component, even if your project doesn't include any resources. If you have a test app for your component, you can determine whether the .pri file is used by examining the contents of the app package in the bin\debug\AppX folder. If the .pri file from your component doesn't appear there, you don't need to distribute it. Alternatively, you can use the MakePRI.exe tool to dump the resource file from your Windows Runtime component project. For example, in the Visual Studio Command Prompt window, type: makepri dump /if MyComponent.pri /of MyComponent.pri.xml You can read more about .pri files in Resource Management System (Windows).

Distribution by extension SDK

A complex component usually includes Windows resources, but see the note about detecting empty .pri files in the previous section.

To create an extension SDK

  1. Make sure you have the Visual Studio 2012 SDK installed. You can download the Visual Studio SDK from the Visual Studio Downloads page.

  2. Create a new project using the VSIX Project template. You can find the template under Visual C# or Visual Basic, in the Extensibility category. This template is installed as part of the Visual Studio 2012 SDK. (Walkthrough: Creating an SDK using C# or Visual Basic, in the MSDN Library, demonstrates the use of this template in a very simple scenario. )

  3. Determine the folder structure for your SDK. The folder structure begins at the root level of your VSIX project, with the References, Redist, and DesignTime folders.

    • References is the location for binary files that your users can program against. The extension SDK creates references to these files in your users' Visual Studio projects.

    • Redist is the location for other files that must be distributed with your binary files, in apps that are created by using your component.

    • DesignTime is the location for files that are used only when developers are creating apps that use your component.

    In each of these folders, you can create configuration folders. The permitted names are debug, retail, and CommonConfiguration. The CommonConfiguration folder is for files that are the same whether they're used by retail or debug builds. If you're only distributing retail builds of your component, you can put everything in CommonConfiguration and omit the other two folders.

    In each configuration folder, you can provide architecture folders for platform-specific files. If you use the same files for all platforms, you can supply a single folder named neutral. You can find details of the folder structure, including other architecture folder names, in How to: Create a Software Development Kit, in the MSDN Library. (How to: Create a Software Development Kit discusses both platform SDKs and extension SDKs. You may find it useful to collapse the section about platform SDKs, to avoid confusion. )

  4. Create an SDK manifest file. The manifest specifies name and version information, the architectures your SDK supports, .NET Framework versions, and other information about the way Visual Studio uses your SDK. You can find details and an example in How to: Create a Software Development Kit.

  5. Build and distribute the extension SDK. For in-depth information, including localizing and signing the VSIX package, see VSIX Deployment in the MSDN Library.

See Also

How to: Create a Software Development Kit
NuGet package management system
Resource Management System (Windows)
Installing and Managing Visual Studio Tools and Extensions
MakePRI.exe tool