In this guide we will show you how to create an executable extension that gathers details from the user along with a template file to create a connection file, this file can then be used when launching the application that accepts a configuration file as a command line parameter. If you don't know what an extension is, read this article.
We will create a cut down version of the Advanced RDP Client extension. The RDP client can save configuration files which can later be used to instantly launch a connection to a remote machine, rather than having to specify all of the arguments at the command line.
Before we begin I will explain how the template files are created and used.
First a template file must be created; this file will form the basis of all the replacement files created.
Secondly a <replacements> element is used to parse the template file and insert replacement values to create the final configuration file; this is a temporary file that will be deleted when the VPN Client is disconnected.
As RDP is a Windows native application this extension can only be used on Windows operating systems.
Extension Structure
To begin, create a new directory called 'WindowsAdvancedRDP' on your hard drive, and inside this directory create a file called 'extension.xml'.
Next run the RDP Client, run 'mstsc.exe' at the command line or launch it through the 'Start' menu, open the options section and select 'Save As', now save a file called 'Default.rdp' in our directory
We will be coming back to this file later on to set the parameters, but first we must start the extension.xml.
Open the xml for editing and enter the following code, or copy and paste if you must.
<extension name="Advanced Microsoft RDP Client" application="WindowsAdvancedRDP" type="executable" version="2.1" requiredHostVersion="0.1.13" license="Proprietary">
<description>
RDP is the remote access protocol that underpins Windows Terminal Services and Windows XP Remote Desktop Connection.
</description>
</extension> Collecting information from the user
We will now allow the user to define the parameters that will be used, the difference with these parameters is that they are going to be used in the replacement element to create the temporary connection file rather than be passed directly into the command line.
In this extension we will be using categories, categories allow you to group a number of parameters together under a common heading, for example a Connection Settings category could hold hostname, port and username details, a Display category could hold details regarding window size and colour depth, and so on.
First of all we will need the hostname and connecting port of the remote system we are connecting to.
<parameter name="hostname" category="1" sequence="0" type="0"/>
<parameter name="port" category="1" sequence="1" type="1" default="3389" optional="true"/>
As usual the hostname is a text field and the port is a number field, the default port number is 3389, this is the port that RDP uses normally. These are both in category 1 which we will use as a General Information category.
Next we will take in the username we will use to login and domain that the computer belongs to.
<parameter name="username" category="1" sequence="2" type="0" optional="true"/>
<parameter name="domain" category="1" sequence="3" type="0" optional="true"/>
Both username and domain fields have been set as text fields in category 1, they have been set as optional fields so the extension will not fail if the user does not enter a value for these fields.
In our second category we will configure the RDP display. First we will give the user the choice of a full screen display, or a specified display size.
<parameter name="screenmode" category="2" sequence="0" type="3" typeMeta="1,2" default="2" optional="true"/>
This will create a dropdown list, parameter type 3; this list will have two options. We define the values for these in the typeMeta argument. We are defining the parameter values as numbers because these values must match those used in the template file, we can add messages that give the parameters more meaning later. Here value 1 is the normal option and value 2 is the fullscreen option, as we have a choice of value we should select a default value for the parameter, we have chosen to default the parameter to value 2, fullscreen.
In case the user chooses to use the normal screen option we need allow them to define the screen size they would like. We do this with the following two parameters.
<parameter name="width" category="2" sequence="1" type="1" default="1024" optional="true"/>
<parameter name="height" category="2" sequence="2" type="1" default="768" optional="true"/>
Both width and height parameters are set as number fields and optional, the default values specify the size of the window used to display RDP, this is measured in pixels, so the default display is 1024x768 pixels, if your monitors display is smaller than this then the window will spill out of your screen. Of course if the user has chosen the fullscreen option then these two parameters will not actually be used.
The next parameter will measure the colour quality that will be used for the display.
<parameter name="bpp" category="2" sequence="3" type="3" typeMeta="8,15,16,24" default="16" optional="true"/>
We have used a dropdown list to display the values for this parameter, the user can select one of four values, each value represents the different number of colours that the display will use, for true Windows colour we would need to use value 24, however we will set the default as 16 so that we don't use quite so much bandwidth when we use the shortcut.
In our third and final category we will allow the user to set one parameter, the ability to share any local drives with the remote system. This can be used to transfer files from one computer to the other during the RDP session.
<parameter name="redirectdrives" category="3" sequence="0" type="3" typeMeta="0,1" default="1" optional="true"/>
Once again we have used a dropdown list with values 0 and 1, in this case 0 is no and 1 is yes, we have set the default a 1 just in case the user should wish to transfer any files.
Next we will specify the messages that will be displayed for each parameter and parameter value.
<messages>
<message key="category.1.name">General</message>
<message key="category.2.name">Display</message>
<message key="category.3.name">Local Resources</message>
First we specify the headers for the categories
<message key="hostname.name">Hostname</message>
<message key="port.name">Port</message>
<message key="username.name">Username</message>
<message key="domain.name">Domain</message>
Next we specify the messages for the first category
<message key="screenmode.name">Screen Mode</message>
<message key="screenmode.value.1">Normal</message>
<message key="screenmode.value.2">Fullscreen</message>
<message key="width.name">Width</message>
<message key="height.name">Height</message>
<message key="bpp.name">Colors</message>
<message key="bpp.value.8">256 Colors</message>
<message key="bpp.value.15">High Color (15 bit)</message>
<message key="bpp.value.16">High Color (16 bit)</message>
<message key="bpp.value.24">True Color (24 bit)</message>
<message key="redirectdrives.name">Redirect disk drives</message>
<message key="redirectdrives.value.0">No</message>
<message key="redirectdrives.value.1">Yes</message>
</messages>
As categories 2 and 3 use dropdown lists we need to specify messages for the values in those lists, this is done by using "parameter.value.value" for each of the values specified in the typeMeta argument.
Setting replacement values for the template files
Ok, leave the extension for a little while, now we are going to edit the template files so that they accept the parameters that we enter at shortcut creation. Open the Default.rdp file in a text editing application; you will see that some of the parameters in this file have the same names as the parameters in our extension.xml. We have done this so that we can keep name references simple.
We need to change the parameters that are already set so that they can be replaced by our parameter values. First you will need to find the 'full address' parameter, you need to replace the value so that it appears as follows.
full address:s:${tunnel:rdp.hostname}:${tunnel:rdp.port}
This will be replaced by the hostname and port of the tunnel we are using to proxy the RDP connection.
Here are the code lines for the remaining parameters that we will need to be replaced.
username:s:${param:username}
domain:s:${param:domain}
screen mode id:i:${param:screenmode}
desktopwidth:i:${param:width}
desktopheight:i:${param:height}
session bpp:i:${param:bpp}
redirectdrives:i:${param:redirectdrives} Defining a set of download files
Now we will need to download the files that we need from the server. We are very lucky with this extension because the software is available on most Windows operating systems. The only file that we need to download is our template file. Just add the following to the extension.xml
<files>
<file>Default.rdp</file>
</files> Configuring the replacement values in the templates to create temporary configuration files
Next we must create the temporary configuration file based on our template, to do this we use the element. This will create a new file from the template and replace all of the replacement values that we set entered with the parameters entered at shortcut creation.
<replacements templateFile="Default.rdp" parameter="file" encoding="US-ASCII"/>
Here we are specifying our template file in the templateFile attribute. The actual connection file that is generated is created using a random filename and the path to this filename will be set into a parameter specified by the parameter attribute. We can then use this parameter later to reference the generated connection file. Finally the encoding argument allows us to set a specific type of encoding for the text file. It is important to make sure whatever encoding the file is saved in is specified here.
Setting up a secure tunnel
Now that we have all of the information that we need we can launch the tunnel. This is done the same way as any other tunnel specification.
<tunnel name="rdp" hostname="${shortcut:hostname}" port="${shortcut:port}" usePreferredPort="false"/> Specifying the executable and its arguments
Executing the application is a rather easy affair, you just need to specify the location and name of the executable, and then pass the file parameter created by the <replacements> task through as the connection file location.
<executable program="mstsc.exe">
<arg>${param:file}</arg>
</executable> Packaging up the extension
You have now completed creating the extension.xml and collecting the necessary files, we can now package the folder into an extension that we can install on SSL-Explorer. You will need an archiving application, I use WinZip, use this application to archive the WindowsAdvancedRDP folder, starting at that folder. This should create a file called WindowsAdvancedRDP.zip that when extracted will create a folder called WindowsAdvancedRDP that contains all the contents of our current folder.
To install the extension simply login to SSL-Explorer using a user account that has permission to access the Extension Manager, once there select to manually install an extension, when you select the extension ensure that you select the WindowsAdvancedRDP.zip file and select upload.
This is only a basic extension for the Advanced RDP Client; the extension available from the Extension Store contains parameters for all of the options that the real RDP Client contains.
And theres more...
This article has been an introduction to the replacement features available in extensions. There are more articles in the knowledge base that explain the other advanced features and extensions types that are available.
If you have any comments or suggestions on the extension architecture you can contact me via email ashleygrant at users dot sourceforge dot net.
If you have any completed extensions that you would like us to publish on our Extension Store then please send them to support@3sp.com.
|
 Attachments
WindowsAd...dRDP.zip
1.5 KB
Downloaded 978 time(s)
|
Developers
Creating Extensions
Print
Add Comment