This post is part of a larger tutorial on DSL Tools and Visual Studio 2008 Isolated Shell, in this post I will go through the steps to setup project for the Shell application and DSL.

Previous step: Creating a custom project type

Creating a new setup project

We will start by adding a new setup project to our solution, so start by opening the solution from the previous post, if not already open.

1. New Project

Create a new Setup Project named “MyDslApplication”, by right-clicking the solution in the Solution Explorer and choosing Add New Project.

In the Add New Project choose Setup Project as shown below:

The solution should now look as shown below:

2. Set project properties

In the setup projects properties set Author and Manufacturer to “MyCompany” as shown below.

Adding output files

Now we are going to add assemblies and other files to the setup project, so you should now open the “File System” in the setup project. Right-click the setup project, MyDslApplication, in the Solution Explorer and choose View -> File System on the context menu.

1. Shell output

Add the Primary Output from the “MyDslShell” project (this will be the actual executable MyDslShell.exe) to the Application Folder.

Right-click the Application Folder, in the File System view, and choose and Add -> Project Output… from the context menu. Then select the “MyDslShell” project, Primary Output and Active configuration as shown below.

The solution should now look as shown below.

2. Add Shell config, icon and splash screen image

Add the following files from the folder “D:\project\DslToolsAndVsShell\Code\MyDSLApplication\MyDslShell\MyDslShell” to the Application Folder:

• MyDslShell.exe.config
• MyDslShell.ico
• Splash.bmp
• MyDslShell.prf

Right-click the Application Folder, in the File System view, and choose and Add -> File… from the context menu. Then select the files as shown below.

After this your solution should look as shown below.

3. Add PackagesToLoad and template folders

Add the following folders under the Application Folder:

• ItemTemplates
• ItemTemplatesCache
• ProjectTemplates
• ProjectTemplatesCache
• Profiles
• PackagesToLoad

And a folder named “1033” under the new “PackagesToLoad” folder.

Right-click the Application Folder or a subfolder, in the File System view, and choose and Add -> Folder from the context menu to add a folder.

Mark the “ItemTemplates”, “ItemTemplatesCache”, “ProjectTemplates” and “ProjectTemplatesCache” folders with the AlwaysCreate option as shown below

4. Add Shell UI output

Add the Primary Output from MyDslShellUI to the “1033” folder.

After adding the Shell UI output the solution should look as shown below.

5. Add DSL package output

Add the Primary Output from the “DslPackage” project to the “PackagesToLoad” folder

After adding the DSL package output the solution should look as shown below. Note that a lot of dependencies will be added, you can just ignore them for now.

6. Add MyDslProject output

Add the Primary Output from the “MyDslProject” project to the “PackagesToLoad” folder.

After adding the DSL project output the solution should look as shown below.

7. Exclude unwanted dependencies

Most of the dependencies that were added when adding the DslPackage and MyDslProject output need to be excluded. The only dependency you will want to keep is “MyCompany.MyDsl.Dsl.dll”.

In the Solution Explorer select all the dependencies to excluded as shown below and select exclude on the context menu.

The solution should now look as the solution shown below

8. Add pkgdef files

Add the “MyDslShell.pkgdef “ and “MyDslShell.pkgundef” from the folder “D:\project\DslToolsAndVsShell\Code\MyDSLApplication\MyDslShell\MyDslShell” to the “PackagesToLoad” folder

Your solution should now look as shown below.

9. Add pkgdef for project and dsl packages

Add the “MyCompany.MyDsl.DslPackage.pkgdef “ and “MyDslProject.pkgdef” from the folder “D:\project\DslToolsAndVsShell\Code\MyDSLApplication\Debug\PackagesToLoad” to the “PackagesToLoad” folder.

Please note that the file is taken from the “Debug” (not the “Release” folder”), this is not an optimal solution. The file should actually be taken from the active configuration output folder, but I could not find an easy way of doing this, so for now just use the Debug or Release folder as you like –it the same file.

Your solution should now look as shown below.

10. Add project template

Add the project template file “MyDslProject.zip” from the “D:\project\DslToolsAndVsShell\Code\MyDSLApplication\Debug\ProjectTemplates” folder to “ProjectTemplates”.

Your solution should now look as shown below.

11. Add profile file

Add the Visual Studio settings file “General.vssettings” from the “D:\project\DslToolsAndVsShell\Code\MyDSLApplication\MyDslShell\MyDslShell” folder to “Profiles”.

Your solution should now look as shown below.

12. Adding the DSL schema

You need to add the XML schema for your DSL, otherwise you will get a warning when running the application. This has to be placed in “C:\Program Files\Microsoft Visual Studio 9.0\Xml\Schemas”, even when we use the isolated shell.

Add the “Program Files” folder to your solution as shown below, by right-clicking the “File System on Target Machine” and choose Add Special Folder -> Program Files Folder

Under the Program Files folder add a folder named “Microsoft Visual Studio 9.0”, under this folder add a folder named “Xml” and under this folder add a folder named “Schemas”.

Add the file “MyDslSchema.xsd” from “D:\project\DslToolsAndVsShell\Code\MyDSLApplication\MyDsl\Dsl\GeneratedCode” to the newly created “Schemas” folder.

Your solution should now look as shown below.

13. Adding a start menu folder

Under “User’s Programs Menu” add a new folder named “MyCompany” and within that folder create a new folder named “MyDsl”.

14. Add a start menu shortcut

In the “MyDsl” folder, under the start menu, create a new shortcut pointing to the Shell executable.

And choose the primary output from the "MyDslShell" project

Name the shortcut “MyDslShell” as shown below

Choose the icon, “MyDslShell.ico”, in the Application Folder

Adding a launch conditions

Add a launch condition to ensure that Visual Studio 2008 isolated shell is installed before installing our application

1. Add registry search

Fill in the following values:

Name:	Search for Visual Studio Registration
Property:	VSINSTALLDIR
RegKey:	Software\Microsoft\VisualStudio\9.0
Root:	vsdrrHKLM
Value:	InstallDir

Your solution should look as shown below.

2. Add launch condition

Fill in the following values:

Name:	CheckForVS
Condition:	VSINSTALLDIR<>""
Install URL:	http://www.microsoft.com/DOWNLOADS/details.aspx?FamilyID=021b3bee-b2ad-42a8-854a-c5eaef69e927&displaylang=en
Message:	Install VS Shell Isolated SP1

Your solution should look as shown below.

Adding custom actions

During installation and uninstallation it is necessary to execute the shell application with some options to register and unregister its components. This is done by adding two custom actions to the installation.

1. Add setup custom action

Right-click the Install node and choose Add custom action…. In the Select Item in Project dialog choose the primary output from “MyDslShell” in the Application Folder.

After adding the action specify “/setup” as arguments in the properties window.

2. Add remove custom action

Right-click the Uninstall node and choose Add custom action…. In the Select Item in Project dialog choose the primary output from “MyDslShell” in the Application Folder

After adding the action specify “/remove” as arguments in the properties window.

Build and Test

Finally you are ready to test the entire solution, so just build and try out the installationv

1. Rebuild the setup project “MyDslApplication”

2. Install the application

Run the “setup.exe” from the folder “D:\project\DslToolsAndVsShell\Code\MyDSLApplication\MyDslApplication\Debug”

Just press next and install the application using its default settings

3. Run the application

Start the application from the Windows Start menu

You should now see your application

Now try to open the New Project dialog and should hopefully show your Dsl project as shown below

Create a new project and try out your application

Summary

This is the end of this tutorial, you have a running DSL application that can be redistributes, but there are still some things to do:

Download: DslToolsAndVsShell-06.zip (12 MB)

What next?

• Make a new splash screen image
• Remove menu items not relevant to your application
• And other details like adding an About box

This post is part of a larger tutorial on DSL Tools and Visual Studio 2008 Isolated Shell, in this post I will go through the steps to add a custom project type to the Shell application.

Previous step: Adding the DSL to the Shell

Creating a new Visual Studio Integration Package

A custom project types is implemented as a Visual Studio Integration Package, so the first step is to add a new integration package to the Shell solution.

1. New project

Choose Add New Project and select the Visual Studio Integration Package project template.

Name the project “MyDslProject” and accept the default location.

2. Welcome page

Just click next

3. Choose programming language and strong name key

Choose C# as programming language and just create a new strong name key.

4. Company name and package name

Specify company name and package name as shown below

5. Testing project

Deselect both Integration Test Project and Unit Test Project.

Press Finish to create the project

6. Resulting solution

The solution should now look as shown below.

7. Shell Dependencies

Now set the shell dependencies for the “MyDslShell” project, so the project will depend on “MyDslProject”. Right-click “MyDslShell” project and choose “Shell Dependencies…”.

Adding a Package Load Key (PLK)

The “MyDslProject” is a Visual Studio integration package, so we need to add a Package Load Key (PLK) to the project.

1. Gathering necessary information for obtaining a PLK

To obtain a PLK you will need the following information:

• Company name
• Package name
• Package Guid
• Package version

The first part of the information can be found in “MyDslProjectPackage.cs” file, as shown below

The package Guid can be found in “Guids.cs”

2. Obtaining a Package Load Key (PLK)

You can obtain a Package Load Key (PLK) from MSDN: Generate Load Keys

Enter the information about your package; choose “Standard” as Min. Product Edition and “Visual Studio 2008” as min. VS Version. Finally press “Generate PLK”.

3. Adding the Package Load Key (PLK) to MyDslProject

We have to add the PLK to the “MyDslProject” projects resource file “VSPackage.resx”. Insert in in the entry with “1” as name without any newlines.

Integrating Managed Package Framework for Projects

Next we have to integrate the Managed Package Framework for Projects into the “MyDslProject” project. This we will do be manually editing the “MyDslProject.csproj” in it’s XML form. If you have Power Commands for Visual Studio 2008 installed you can right-click the project and choose Edit Project File.

1. Editing the project file

First you will have to add the line shown below:

Then add the line below as shown below:

2. Reload the project in Visual Studio

When reloading the project, you will get a warning as show below. Just choose Load project normally.

3. Adding required reference

The Managed Package Framework for Projects uses some extra assemblies, which we need to reference before the project can compile.

Add a reference to EnvDTE, as show below.

Add a reference to Microsoft.VisualStudio.Designer.Interfaces, as show below.

The “MyDslProject” should now be able to compile.

Implementing the custom project type

Now we are ready to implement the new custom project type for the DSL project.

1. Defining a project type Guid

First we have to define a Guid for our new project type, just generate a new Guid.

Add the new project type Guid to the “Guids.cs” file as show below:

2. Adding factory and node classes

To implement a custom project we need a factory class for instantiating new projects and project node class.

Add two C# classes to the “MyDslProjectFactory” and “MyDslProjectNode.cs” to the “MyDslProject” project. Your solution should then look as shown below.

3. Implement the “MyDslProjectNode” class

Implement a simple project node as shown below:

The project node needs a Guid, just generate a new Guid not used in any other place.

4. Implement the “MyDslProjectFactory” class

Implement a simple project factory as shown below:

5. Change package base class

Change the base class in “MyDslProjectPackage” class, so that it inherits from ProjectPackage, as show below:

6. Register project type

The project factory must be registered in the Initialize method in the MyDslProjectPackage class. Add a call to RegisterProjectFactory as shown below:

7. Adding ProvideProjectFactory attribute

A package implementing a project type must be attributed with the “ProvideProjectFactory” attribute. Add a “ProvideProjectFactory” attribute to the “MyDslProjectPackage” class as show below:

Adding a project template

Finally we have to create a new project template for our custom project type.

1. Add template folder

First we have to add a template folder in the “MyDslProject”. Add a folder named “Templates”, a subfolder named “Projects” and finally a subfolder “MyDslProject”, as show below.

2. Add a DSL item file

Add an empty text file named “MyDsl1.mydsl1” to the “MyDslProject” folder, as shown below.

3. Add a project icon

Add an icon file named “MyDslProject.ico” to the “MyDslProject” folder, as shown below.

4. Add a project file

Add a project file named “MyDslProject.mydslproj” to the “MyDslProject” folder, with the content shown below:

5. Add a vstemplate file

Add a project file named “MyDslProject.vstemplate” to the “MyDslProject” folder, with the content shown below:

6. Set build action

Select the four template files added in the above steps and set the build action to ZipProject.

7. Add copy events

Add an after build action to copy the template file to the output folder. Open the “MyDslProject.csproj” file so you can edit it directly, and add the XML shown below:

8. Specify template folder

The Shell application needs to know where to look for templates, so you have to specify the template folders.

Open the “MyDslShell.pkgdef” in the “MyDslShell” project and append the following in to bottom of the file:

Testing the project

Everything should now be in place and we are ready to test the new custom project type.

1. Building the solution

Rebuild the entire solution. After rebuilding completes check the output folder (e.g. ), it should look as shown below.

2. Running the application

Run the solution and select File -> New -> Project on the menu and you should see the new project type as shown below.

3. Create a new project

Choose OK in the new project and you should get a new project with a DSL file as shown below.

You can now start use the DSL and create diagrams.

Summary

This end the fifth post about adding custom project type to the Shell application, next step is about creating a setup project for the entire Shell application, so it can be deployed.

Next step: Coming soon!

Download: DslToolsAndVsShell-05.zip (7 MB)

This post is part of a larger tutorial on DSL Tools and Visual Studio 2008 Isolated Shell , in this post I will go through the steps to add the DSL sample to the Shell application.

Previous step: Creating the Shell application

Adding the DSL projects

We will now add the DSL designer to the Shell application, so if not already open you should open the Shell solution.

1. Adding the Dsl project

Select add existing project and locate the Dsl.csproj and add it to the Shell solution

2. Adding the DslPackage project

Select add existing project and locate the DslPackage.csproj and add it to the Shell solution

3. Resulting solution

The solution should now look as shown below.

4. Setting Shell dependencies

Now set the shell dependencies for the “MyDslShell” project, so the project will depend on “DslPackage”. Right-click “MyDslShell” project and choose “Shell Dependencies…”.

5. Testing the DSL within the Shell application

The Shell application does not yet have the ability to create a new project with a DSL file, but it can open an existing DSL (.mydsl1 file) and display then activate the DSL designer.

You can just create an empty text file with extension “.mydsl1” or open an existing file, such as “D:\project\DslToolsAndVsShell\Code\MyDSLApplication\MyDsl\Debugging\Sample.mydsl1” which is created as part of the DSL.

You should then see your DSL designer running within the Shell application, as shown below.

Summary

This end the fourth post about adding the DSL to the Shell application, next step is about adding a custom project type to the Shell application, so it can create new projects with the DSL.

Next step: Creating a custom project type

Download: DslToolsAndVsShell-04.zip (5 MB)

This post is part of a larger tutorial on DSL Tools and Visual Studio 2008 Isolated Shell, in this post I will go through creating a Visual Studio 2008 shell application that we later can add the DSL and a custom project type to.

Previous step: Creating a sample DSL

Creating a new Isolated Shell application

In this section we will create a new Isolated Shell application in a new solution.

1. New project

Choose Visual Studio Shell Isolated and name the project “MyDslShell”, in the location select “D:\project\DslToolsAndVsShell\Code\MyDSLApplication” and uncheck Create directory for solution.

2. Created solution

Now you should have a new Shell solutions as shown below.

The folder structure should look as show below.

3. Set debugger

You should set debugger type on the “MyDslShell” project to Managed Only, otherwise you can encounter problems when trying to debug managed packages.

4. Testing the solution

Build the solution and press F5 to start, you should get an empty shell as shown below.

Adding a Shell Load Key (SLK)

1. Gathering necessary information for obtaining a SLK

To obtain a SLK you will need the following information:

• Company name
• Shell name
• Shell Guid
• Shell version

The information can be found in “MyDslShell” project in the file “MyDslShell.pkgdef”, please not that you will have to add some yourself.

The Shell Guid and Shell Name can be found in the beginning the file, as shown below.

Further down in the file you find Company Name and Product version, these are commented out, so you will have to uncomment them. The Company Name is NOT filled out by default, so you will have to fill that in yourself.

2. Obtaining a Shell Load Key (SLK)

You can obtain a Shell Load Key (PLK) from MSDN: Generate Load Keys

Enter the information from the Constants.cs, choose “Standard” as Min. Product Edition and “Visual Studio 2008” as min. VS Version. Finally press “Generate SLK”.

3. Adding the Shell Load Key (SLK) to Shell

We have to add the SLK to the “MyDslShell” projects resource file “MyDslShell.rc”. Open “MyDslShell.rc” and navigate to the String Table and find the entry “IDS_SLKSTRING” and fill in the SLK without any newlines.

Next we will have to add a value to the “MyDslShell.pkgdef” file. Find the line

    "ID"=dword:00000069

and uncomment it. Make sure that you get the right line; it should be below the common explaining SLK’s. Note the number 69, this is in hexadecimal, in decimal it will be 105 and must match the number on the above screen dump.

Adding a Package Load Key (PLK)

The “MyDslShellUI” project is a Visual Studio integration package, so we need to add a Package Load Key (PLK) to this project.

1. Gathering necessary information for obtaining a PLK

To obtain a PLK you will need the following information:

• Company name
• Package name
• Package Guid
• Package version

The information can be found in “MyDslShell” project (note, it’s not in the “MyDslShellUI” ) in the bottom of file “MyDslShell.pkgdef”, also not that you will have to add the company name yourself.

2. Obtaining a Package Load Key (PLK)

You can obtain a Package Load Key (PLK) from MSDN: Generate Load Keys

Enter the information from above, choose “Standard” as Min. Product Edition and “Visual Studio 2008” as min. VS Version. Finally press “Generate PLK”.

3. Adding the Package Load Key (PLK) to the Shell UI package

The Shell UI package has it’s Package Load Key (PLK) in the “MyDslShellUI.rc” file.

4. Running and validating the Shell

To test the SLK and PLK you have to add the /NoVSIP option to the debugging startup parameter. This will make Visual Studio perform the SLK and PLK validation even when you have you have Visual Studio SDK installed.

Now rebuild the solution and try to run the Shell using F5

Summary

This end the third post about creating a Shell application, next step is about adding the DSL to the Shell application.

Next step: Adding the DSL to the Shell

Download: DslToolsAndVsShell-03.zip (5 MB)

Note: This post is part of a larger tutorial on DSL Tools and Visual Studio 2008 Isolated Shell , in this post I will go through creating a sample DSL that can be used for hosting in Visual Studio 2008 shell.

Previous step: Prerequisites and Initial tasks

Creating a new DSL

We will start by creating a new DSL designer based on one of the standard templates. It’s is not the intention of this guide to describe how to develop DSL’s, so for the purpose of this guide we will just use the DSL as it is.

1. New project

In Visual Studio 2008, create a new DSL designer and place it in the MyDSLApplication folder (e.g. D:\project\DslToolsAndVsShell\Code\ MyDSLApplication). Name the DSL ”MyDsl”

2. Choose language type and name

Use the minimal language for this sample and name the DSL “MyDsl”.

3. Choose file extension and icon

Just accept the default file extension and icon. Please note that we will need to use the extension later, so if you use a different extension you will also have to use that later.

4. Choose product and company name

Specify a company name (we are going to use this later). Only use A-Z, space and 0-9 characters in the names.

5. Strong naming

Just create a new strong naming key.

6. Confirm project settings

Just accept the settings

7. Project creation result

Now you should have a solution as shown below.

Your folder structure should now look as shown below.

8. Testing the DSL

Test the language by starting it using F5. When running you should see something like this.

Adding a Package Load Key (PLK)

If we are going to distribute the final DSL application to users who don’t have Visual Studio 2008 and Visual Studio 2008 SDK installed, we need to provide a Package Load Key (PLK) for our DSL.

You can learn more about VSPackage Load Keys on MSDN: VSPackage Load Keys

1. Gathering necessary information for obtaining a PLK

To obtain a PLK you will need the following information:

• Company name
• Package name
• Package Guid
• Package version

The information can be found in DslPackage project under GeneratedCode/Constants.tt/Constants.cs

2. Obtaining a Package Load Key (PLK)

You can obtain a Package Load Key (PLK) from MSDN: Generate Load Keys

Enter the information from the Constants.cs, choose “Standard” as Min. Product Edition and “Visual Studio 2008” as min. VS Version. Finally press “Generate PLK”.

3. Adding the Package Load Key (PLK) to DSL

We have to add the PLK to the “DslPackage” projects resource file “VSPackage.resx”. Give it a Name, e.g. 120, and add the key without any newlines.

Next go to the “Package.tt” file and add the following line as shown on the screen dump below:

[VSShell::ProvideLoadKey("Standard", Constants.ProductVersion, Constants.ProductName, Constants.CompanyName, 120)]

Run “Transform All” and rebuild the solution.

Testing the Package Load Key (PLK)

1. Adding the NoVSIP option

To test the PLK you have to add the /NoVSIP option to the debugging startup parameter. This will make Visual Studio perform the PLK validation even when you have you have Visual Studio SDK installed.

Add the option to the Dsl project.

Add the option to the DslPackage project.

2. Running and validating the DSL

Now rebuild the solution and try to run the DSL using F5

If everything is ok you should see you DSL again, as show below.

Please check the output window and look for the following message: “VSIP: Developer edition disabled, normal security checks initiated.”

If you see this message, it means that Visual Studio is validating the PLK.

Summary

This ends the second post about creating a sample DSL, next step is about creating the Visual Studio 2008 Shell application.

Next step: Creating the Shell application

Download: DslToolsAndVsShell-02.zip (1,04 MB)

Note: This post is part of a larger tutorial on DSL Tools and Visual Studio 2008 Isolated Shell, for more information se the previous link.

In this post I will go through some Prerequisites and Initial tasks that need to be in place before starting the actual tutorial.

Prerequisites

• Microsoft Visual Studio 2008 (Professional edition or larger)
• Microsoft Visual Studio 2008 service pack 1 - Download
• Microsoft Visual Studio 2008 SDK 1.1 - Download
• Visual Studio 2008 Shell (isolated mode) with Service Pack 1 Redistributable Package - Download

When running the Visual Studio 2008 Shell (isolated mode) with Service Pack 1 Redistributable package, please note that the installer only extracts the files into the “C:\VS 2008 Shell Redist\Isolated Mode” folder. After running the first installer you will need to run “vs_shell_isolated.enu.exe” from “C:\VS 2008 Shell Redist\Isolated Mode” folder to actual install the Visual Studio 2008 Shell.

Initial tasks

1. Create a working folder

Start by creating an empty folder, on a local drive, for the code. In this guide we will use: ”D:\project\DslToolsAndVsShell\Code” as shown below:

2. Prepare Managed Package Framework for Projects

Later in this tutorial we will create a new Visual Studio custom project type, to simplify this process we will use Managed Package Framework for Projects available on CodePlex.

Download the Package Framework for Projects source code form the CodePlex site.

The download will consist of a zip file containing the source code. When you have extracted the downloaded file you will have file structure as shown below:

Create a new folder “MPFProj” under your code folder, e.g.in this guide “D:\project\DslToolsAndVsShell\Code”, and copy the “9.0” folder from the MPFProj download to this folder new folder.

Finally create a new folder “MyDSLApplication” under the “D:\project\DslToolsAndVsShell\Code” folder. This folder will be the base folder for the application.

Summary

This ends the first post about prerequisites and initial tasks, next is creating the DSL that we want to host in Visual Studio 2008 Shell.

Next step: Creating a sample DSL

Download: DslToolsAndVsShell-01.zip (510,1 KB)

Microsoft DSL Tools provides an easy way to create visual languages and designers that can be hosted in Visual Studio 2008, but sometimes it could be interesting to distribute the designers to user who don’t have Visual Studio 2008 installed. This can be archived by using the Visual Studio 2008 Isolated Shell to host the DSL designers, but implementing this can be a difficult process.

As a sample of this kind of application you can look at the Storyboard designer on CodePlex or the screen dump below.

After spending some time on creating a standalone application based on Microsoft DSL Tools and Microsoft Visual Studio 2008 Shell (isolated), I have decided to write end-to-end tutorial describing all the steps necessary to create a fully deployable standalone DSL Tools based application that can be used without Visual Studio 2008 installed. All the information on how to create such an application is available on the Internet, but only as separate pieces, so it can be difficult putting it all together.

The primary audience for this tutorial will be developers familiar with DSL Tools who wants to create a standalone DSL application, but don’t have a lot of experience with Visual Studio extensibility and Visual Studio Shell development in general. Anybody else interested in the subject can of cause also use the tutorial. I will not spend a lot of time on DSL Tools, the focus will be on how to create a standalone application based on a DSL designer.

I will post the tutorial on my blog as it progresses and add links from this post.

Table of content (links will be add when new posts come)

• Prerequisites and Initial tasks
• Creating a sample DSL
• Creating the Shell application
• Adding the DSL to the Shell
• Creating a custom project type
• Creating a setup package

In this small tutorial I will show how to create a simple UPnP hosted device containing a simple HelloWorld service using C# and the Windows UPnP framework.

Windows UPnP is available in Windows XP, Vista and 2008 Server, but not in Windows 2003 Server. If you want UPnP on Windows 2003, have a look at the Intel UPnP stack.

I will not explain the basic concepts of UPnP, so if you don’t feel familiar with basic UPnP concepts it might be at good idea to look at some of the documentation at UPNP.ORG or MSDN.

Intel has some great tools for working with UPnP and I will be using these during the tutorial, so it would a good idea to install then if you want to go through the steps. They can be downloaded from Intel’s website, pick Intel® Tools for UPnP Technologies (Build 2777) and the .NET 2.0 CLR edition.

Designing/specifying the service

First steps is to create a services description, this is just like an interface for the service – specifying methods, properties and events. This is done in an XML file, see paragraph 2.3 of UPnP Device Architecture 1.0 for a detailed description of the XML format.

For this example we will just create a simple “HelloWorld” service that can return a simple text message, so we will have a services description as shown below:

Specifying this service could be done using any text editor or by using the Intel Service Author application which comes a part of the Intel tools for UPnP.

Designing/specifying the device

Next we need to create a device specification; this is a specification of the services that should be published and other meta-information related to the devices and services. This will also be represented by an XML file, see paragraph 2.1 of UPnP Device Architecture 1.0 and Creating a Device Description on MSDN for a detailed description of the XML format.

Sample device description:

where MyService.xml is containing the services description.

Creating an application to get the device up and running

To get the device up and running we need an executable application where we can implement the service and register the device with the Windows UPnP host. For this purpose I will use a standard C# Console application.

Add the device description and service description files to the console application, mark then as “Content” and “Copy if newer”.

It is necessary to disable the use of Visual Studio host process when debugging, otherwise the application will fail when debugging (some COM related issue).

Next we need to add some references to the UPnP COM type libraries ("upnpcont.exe" and "upnp.dll" typical found in “c:\windows\system32”) for the Windows UPnP framework.

Now we are ready to implement the service, this is done by adding a plain C# class:

The service class should match the service description; have the same methods and properties. It also needs to be COM visible and implement the COM IDispatch interface.

Next we need a device control class which acts as a factory for instantiating the service class. This class is also a plain C# deriving from the interface IUPnPDeviceControl.

Finally we need to fill out the Main method with the code for registering the device control class with the Windows UPnP framework. See Registering a Hosted Device With the Device Host on MSDN for more information for more information.

Note that we need to make a call to CoInitializeSecurity to get the COM Interorp to work. For details abort this see the downloadable code.

Testing the UPnP device and service

Now we can build and start the program

To test the UPnP device and service we will use Intel Device Spy for UPnP, this way we can test the HelloWorld method without having to implement a UPnP client.

If our new UPnP device is running, we should see it in the UPnP Device Spy with the name MyDevice and should be able to find the service and HelloWorld method. Try invoking the HelloWorld method by right-clicking it.

Downloadable code

You can download the sample code here: MyUPnP-Tutorial-01.zip (33,37 KB)