One popular customisation applied to Web Interface is to rewrite the Client Name used in the session to allow policies or local scripts to reflect a custom business need.
Some customisations are fairly simple. For example, some would copy the user name into the client name, but other customers used complex logic to encode many different fields into this data. In WI, the changes here were made by altering WI directly. To achieve the same rewrite with StoreFront, it is necessary to use the Store Customisation SDK. Using this SDK will require writing some C# code, with a full range of context information available allowing quite complex changes to be made if necessary.
Simple changes are also straightforward and a set of sample changes are included. The SDK interface will be maintained across StoreFront versions, removing the problem of upgrades requiring customisations to be recoded, which was a risk with the WI mechanism. For more details of the SDK, see http://www.citrix.com/go/citrix-developer/storefront-receiver-developer-community/store-customization-sdk.html. Note that the SDK includes a sample which demonstrates how to alter the client name.
In conversations with some customers, they have mentioned that they’re concerned that getting to grips with this SDK will take them a while, even if the customisation they would like to apply is quite straightforward. This delays their transition to StoreFront. To assist with this, I would like to offer the following customisation DLL which can apply client name rewrites based on a template.
To use this, you’ll need to copy the downloaded DLL into the appropriate Store directory and provide the relevant template via config. Full instructions are below and in the download.
The customisation template can be any string, but where that string contains a particular token, the token will be replaced by some information from the User Context, as shown by the table below:
Token: Corresponding Data
$U User name
$D User domain
$N Existing Client Name variable
$R Roaming status – “I”:internal or “E”:external
$A Detected Address
$S Supplied Address
$V DeviceID
$G Gateway name (without domain). Empty string if the connection is not made through a gateway.
$P Receiver Platform (WIndows, MAc, LInux, IOs, ANdroid, CHromebook, BRowser,
BLackberry, WindowsRt, WindowsPhone, UNknown)
$<anything else> is copied into the result.
A couple of examples:
If the intent was just to replace the ClientName with the user name, the template is then just “$U”.
If you wanted to use the existing ClientName but know whether the connection was through a gateway then you could use “$N_$R” which would result in the ClientName with a ‘_I’ or ‘_E’ suffix.
Normal Client Name restrictions apply: max 20 chars (anything over will be truncated), and no reserved characters from the following list: “/ []:;|=\,+*?<>. Any template containing these characters will be rejected.
To install the DLL
Locate the existing placeholder DLL for the customisation SDK in your deployment (\inetpub\wwwroot\Citrix\storename\bin\StoreCustomization_Input.dll). Save this file so that you can restore your deployment to default if required. Move the backup file to another directory, do not rename it within the same directory to avoid risks of DLL conflicts. Copy the StoreCustomization_Input.dll from the download zip into the bin directory. Note: if you are using a StoreFront group, perform the propagation action to push the new assembly to other members of the group.
To create the template
Locate the existing web.config fie for the Store (\inetpub\wwwroot\Citrix\storename\web.config).
Take a backup.
Edit the file in a text editor.
Locate the following line in the file
<appSettings>
Change this XML to look like the following
<appSettings>
<add key=”clientNameRewriteRule” value=”$N” />
</appSettings>
Remember to make sure the first line no longer includes a trailing slash. Warning: the presentation of the above has a habit of translating the simple double quotes characters into open/close quote characters. If you copy & paste from the browser, make sure the quotes are the simple ones otherwise IIS gets confused and rejects the setting.
Now locate the <launch> element in the file that looks like the following (you won’t see the …, sections, those removed for simplicity)
<launch setNoLoadBiasFlag=”off” addressResolutionType=”DNS-port” … overrideIcaClientName=”on” requireLaunchReference=”on” … >
Change the overrideIcaClientName setting to “on”.
Save the file changes.
If you are using a Storefront group, now propagate these changes to all members of the group.
Your deployment should now operate…exactly the same as before! What you now can do is alter the template value from the “$N” above as you wish and note the changes in the supplied client name. Changes will take place on the next operation after the web.config file has been saved.
Update: there is a restriction here for users using a browser to access StoreFront. The ClientName that is used as input for this case will be the StoreFront generated one (WR_xxxxx).The reason for this is that the browser cannot provide the client machine name to the StoreFront service. Without the customisation in place, the client name that winds up in the session is controlled by the overrideICAClientName setting – if set, the client name will be the SF generated one (it’s passed back to the client in the ICA launch params). If this setting is false, SF doesn’t pass anything to the client and the client will pass the computer name as part of native ICA negotiation. For the customisation to work, the override setting must be on (so that the new client name is passed back to the client). Thus when above I suggested using $N would yield the same result as before, I should have made it clear that it would be the same as before… with overrideClientName set! Apologies if that has caused any confusion. Native Receivers supply their client name to StoreFront as part of the launch params and do not suffer the same restriction.
Please note that this customisation comes without warranty and is not officially supported. It was originally tested with StoreFront 2.6 and 3.0 releases. Customers have successfully used it on all 3.x releases (i.e. to current 3.9 release with the expectation it should continue to be functional on further 3.X releases).
Download can be found here: https://github.com/citrix/Storefront-Clientname-template/blob/master/StoreCustomization_Input.dll?raw=true
MD5 hash of the zip is 98eb1130b5844123088f0ac58f08e92b.
Update: I’ve had a few requests for the source of the customisation. I hadn’t intended to post it as I had assumed that if anyone was comfortable working at that level, they wouldn’t need the template approach. However, I’m happy to share it, see download link below. What I would ask though is that if you modify the sample to alter the template approach, please drop a comment to this blog to let me know of what extra information you’ve added into the template as I’m interested to learn about requirements here.
One specific question was what the source technique was to read the appSettings element. It’s very simple: use the System.Configuration.ConfigurationManager class as follows:
string clientNameRewriteRule = ConfigurationManager.AppSettings["clientNameRewriteRule"];
The 3.0 version of the Store Customisation SDK includes a couple of new examples that illustrate this technique.
Customisation source download link: https://github.com/citrix/Storefront-Clientname-template/blob/master/InputModifier.cs?raw=true
The Store Customisation SDK for StoreFront 2.6 can be found here.
The Store Customisation SDK for Storefront 3.X can be found here.
Note downloading either of these will require MyCitrix login.
Hope that helps someone!
Simon