.NET, BrokeredComponent, UWP, XAML

Part 1: Brokered Component for UWP App

Why use brokered component?
I am currently working on migrating a legacy application built in .net and some c++ libraries to windows universal application (UWP). Brokered winRT component is one way for us to be able to access legacy functionality on a side loaded application. As of the moment there’s an existing template for creating brokered component for visual studio 2013 targeting windows 8.1 application but not for VS2015 targeting windows 10 universal app. I tried to read the whitepaper  and tried to create a template that can be used for universal windows app.

Brokered component allows side loaded application to access or call functionalities of legacy .net applications. You can download the project templates I created from visual studio gallery. The extension contains three project template, the Brokered Client, Brokered Proxy and the Brokered Server.

Click here to download the project templates installer.

Here are the basic steps to create a brokered component for universal windows apps using the project templates.

First we have to create the projects.

Pre requisite
1. Create a client Project
– Go to File>New>Project then search for Brokered Client.
2. Create a server component project
– Right click on solution, Add>New Project and search for Brokered Server
3. Create a Brokered Proxy project
– Right click on solution, Add>New Project and search for Brokered Proxy

Once you have all projects in place we can start configuring it.

Server Component
Server component is a project where we can reference or use native .net codes such as legacy dlls. This project will generate a .winmd file which we can reference later on in our client application (Universal Windows). This will also generate some files that we are going to add to our proxy project later on.

1. You can start creating your BrokeredComponent class (i.e. BrokeredComponent1). Rename it and write your implementation in this class. You can write native .net code in this class.
2. Right click on the Server project and click properties.
3. Go to the Build Event tab and look at the post build event.
4. Make sure that all the reference to the Proxy project’s path is correct. Change the folder name ‘Proxy’ to the name of your Proxy project.

Note: You can copy the build event to notepad or notepad++ to make it easier to edit. You should be replacing 4 instances of Proxy in the post build event script. You will only do this if your proxy project’s name is not ‘Proxy’.replaceproxy
5. Build the server component project
6. Four files will be generated in the folder where the proxy project is.
– Dlldata.c
– A header file (e.g. Server.h)
– A *_i.c file (e.g. Server_i.c)
– A *_p.c file (e.g. Server_p.c)
7. A new folder in {SolutionFolder}\Debug will be created if it doesn’t exist yet.
8. Metadata files (.winmd) will be generated in the Debug\impl and Debug\reference. The file in the impl is the implementation file which is automatically copied to the {SolutionFolder}\Debug. And the one in the reference folder is the one that the client will use by adding it as reference.

Note: The folder structure is very critical in the post build event. Make sure you follow the steps precisely or you can customize the post build event so that it can work on the folder structure that you desire. 

Proxy
This project will generate a dll which we will register later on using regsvr32.

1. Right click on the Proxy project from the solution explorer
2. Click on Add\Existing items
3. Add the files that was generated by the Server (Dlldata.c, Server.h, Server_i.c, Server_p.c)
4. Build the proxy project
6. It will generate the proxy dll in the {SolutionFolder}\Debug

Register
1. Open the command prompt
2. Go to the {SolutionFolder}\Debug
3. Enter the following command:
icacls . /T /grant “ALL APPLICATION PACKAGES”:RX
4. Register the dll by entering:
Regsvr32 Proxy.dll

Client
This is the side-loaded universal windows app.

1. Right click on the package.appmanifest, then click “View Code”
2. Scroll down to the Extension tag
3. In the ActivatableClass tag, type in the fully qualified name of the server class (i.e Server.BrokeredComponen1) in the ActivatableClassId attribute
4. In the ActivatableClassAttribute tag type in the path to the {SolutionFolder}\Debug or anywhere where the proxy together with the .winmd file is in. By default it will be generated in the {SolutionFolder}\Debug.
5. Right click on the Project then add reference then click browse and then go to {Server Project Folder}\bin\Debug\reference\Server.winmd file.
6. You can now create an instance of the class (BrokeredComponent1) in the client project.

Conclusion
The idea of the brokered component is to generate a reference file (.winmd) that we can reference in the UWP, an implementation file (.winmd) and a proxy dll that will be registered to the system. The implementation winmd file should be in the folder where the proxy.dll file is and the reference\Server.winmd should be the one that we reference in the client project. I have created some project templates to skip the project files configuration steps that you can see in the white paper.

Brokered component cannot be submitted to the windows store. It won’t even pass the local certification process using the Windows Application Certification Kit. You can install the app by sideloading. I’m trying to figure out a good way to deploy sideloaded apps to other devices. I’ll be discussing it on my next post.

References:
https://msdn.microsoft.com/en-us/library/windows/apps/dn630195.aspx

http://blogs.msdn.com/b/wsdevsol/archive/2014/04/14/cheat-sheet-for-using-brokered-windows-runtime-components-for-side-loaded-windows-store-apps.aspx

Update:

You can now download the latest version of the Templates that includes the Brokered Component Starter Kit.