Introduction

Developing and deploying a custom virtual channel can require a considerable learning curve before seeing positive progress. The goal of this blog series will be to trim down that curve and enable a quicker time to market for developers.

We found in our experience that the initial barrier to the development of a custom virtual channel was implementing and understanding the virtual channel development environment. This post provides step-by-step instructions on creating a Windows development environment using example code, and how to test the code once compiled. Subsequent posts will detail the code functionality and additional custom virtual channel deployment considerations.

Why are virtual channels important?

As the centralization of IT and the cloud computing transition continues, business critical applications and virtual desktops are increasingly centralized in the corporate datacenter. In tandem, mobile and feature rich end devices continue to push the bar forward for the expected end user experience. Users expect their end devices and corporate enterprise apps to interact in harmony.

The challenge for the Citrix architect / administrator becomes, how do I marry my client device functionality and data, with my datacenter centric enterprise applications? One method includes, you guessed it, a Citrix virtual channel. Users already benefit from many default Citrix virtual channel features such as clipboard redirection, audio redirection, file redirection, microphone redirection, flash redirection, etc.

Developers can create custom virtual channels to expand upon the default functionality to fit their enterprise needs. Common use cases for custom virtual channels include:

• Creating a dedicated ICA data stream (such as for ICA printer traffic)
• Client / Server Data access control and operational management mechanisms (such as USB and clipboard redirection)
• Specialized client end device functionality management (such as Lync Redirection)

How do I build a development environment?

For this series of blog posts, we have created a hello world example using a Windows 8 device and Server 2008 R2 XenApp 6.5 server.

Development and testing requires a 3-step process:

• Development environment set up
• Code creation and compilation
• Installation of compiled files to test environment

The example development and test environment used the following components:

• XenApp 6.5 Controller on Windows 2008 R2 server (Citrix server device)
• Visual Studio 2012 installed on Windows 8 desktop (Client end device)

Once the example files have been installed on the test client device, the custom channel is ready to be opened. The instantiation of the channel is performed by loading an installed DLL on the client device at session launch time. If successful, a notification message is displayed on the client device acknowledging the instantiation of the channel.

An executable installed on the XenApp server is used to communicate across the new channel. When launched a “Hello World” message is then transmitted over the channel from the XenApp server, and displayed on the Windows client device. When the message from the server is closed on the client device, a second message is transmitted from the client and displayed in the server session.

To download the example documents please visit the following ShareFile link.

Development Environment Installation Steps (configured on Windows 8 desktop):

1. Install Citrix VCSDK version 13: http://community.citrix.com/display/xa/Virtual+Channel+SDK
2. Install Citrix WFAPI SDK: http://community.citrix.com/display/xa/WinFrame+API+SDK
3. Install Microsoft Visual Studio 2012
4. Install Microsoft Windows Software Development Kit for Windows 8: http://msdn.microsoft.com/en-us/windows/hardware/hh852363.aspx
5. Client-Side Compilation:

1. Navigate to client side files in the development folder
2. Copy vdhwclient.h to %driveLetter%\VCSDK\WIN32\src\examples\vc\shared\inc
3. Copy the folder vdhwclient to %driveLetter%\VCSDK\WIN32\src\examples\vc\client
4. Launch the “Developer Command Prompt for Visual Studio 2012”
5. Execute the code in the codeHWclient.txt file on the command prompt (Note that we installed the VCSDK onto the root of a secondary D drive. You will need to update the client-side compilation paths in the text containing D:\VCSDK to your chosen VCSDK installation destination.)

1. Navigate to server side files in the development folder
2. Copy vcnet to visual studio documents directory
3. Launch vcnet.sln in vcnet folder

Install custom channel onto end device and XenApp server:

1. Client Side Configuration (Windows 8 desktop with Citrix Receiver):Caution! This fix requires you to edit the registry. Using Registry Editor incorrectly can cause serious problems that might require you to reinstall your operating system. Citrix cannot guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk. Be sure to back up the registry before you edit it.

1. Install at minimum Receiver 3.0
2. Registry Entries:

1. HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Citrix\ICA Client\Engine\Configuration\Advanced\Modules\ICA 3.0\

1. Reg_SZ: VirtualDriverEx = HWclient

1. Reg_SZ:  DriverNameWin32 = vdhwclientn.dll

1. Copy CTXHW.exe and vcnet.dll to the folder location where the CTXHW.exe file will be executed
2. Publish a desktop of the test XenApp server to the test user

Test new virtual channel:

1. Launch XenApp desktop session from server with CTXHW.exe and from the client device with the custom channel DLL installed.
2. If the virtual channel is installed correctly a message prompt will appear immediately.

1. Note this prompt is meant for debugging and must be closed quickly or the Citrix session creation will fail.

Disclaimer: As typical with code development, the example provided is not meant to be the only possible solution. For example, if you are developing for a Windows 7 deployment, the code should be compiled on the same platform.

Wrapping Up

There is a lot more to implementing a custom virtual channel than just developing code. Additional considerations include client / server timing, client-side code deployment mechanisms, client-side device compatibility, server-side executable maintenance, and more. We hope to cover many of these topics in future posts including a detailed walkthrough of the example code.

We hope this post helps kick off the process of setting up a virtual channel development project. If you have any questions or feedback, please post them in the comments section below. In the meantime between our next post, take a look at these resources below for additional information to get started.

Continued education:

• Virtual Channel SDK Documentation: located in Virtual Channel SDK MSI
• In depth introduction to virtual channel architecture: CTX116890.

Disclaimer Notice

This software / sample code is provided to you “AS IS” with no representations, warranties or conditions of any kind. You may use, modify and distribute it at your own risk. CITRIX DISCLAIMS ALL WARRANTIES WHATSOEVER, EXPRESS, IMPLIED, WRITTEN, ORAL OR STATUTORY, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NONINFRINGEMENT. Without limiting the generality of the foregoing, you acknowledge and agree that (a) the software / sample code may exhibit errors, design flaws or other problems, possibly resulting in loss of data or damage to property; (b) it may not be possible to make the software / sample code fully functional; and (c) Citrix may, without notice or liability to you, cease to make available the current version and/or any future versions of the software / sample code. In no event should the software / code be used to support of ultra-hazardous activities, including but not limited to life support or blasting activities. NEITHER CITRIX NOR ITS AFFILIATES OR AGENTS WILL BE LIABLE, UNDER BREACH OF CONTRACT OR ANY OTHER THEORY OF LIABILITY, FOR ANY DAMAGES WHATSOEVER ARISING FROM USE OF THE software / SAMPLE CODE, INCLUDING WITHOUT LIMITATION DIRECT, SPECIAL, INCIDENTAL, PUNITIVE, CONSEQUENTIAL OR OTHER DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Although the copyright in the software / code belongs to Citrix, any distribution of the code should include only your own standard copyright attribution, and not that of Citrix. You agree to indemnify and defend Citrix against any and all claims arising from your use, modification or distribution of the code.