Customization Files in Unified Service Desk

One of the primary concerns utilizing .NET framework based applications such as USD on the desktop has always been deployment.  While USD has always been primarily configuration driven, there was frequently times in which custom controls were desired.  Unfortunately these custom controls (dlls) had to be deployed to the desktop.  This process involved creating an MSI and going through internal processes to get the files pushed out in admin mode.

One of the most exciting new features of USD 2016 release changes all this.  Much like a browser that loads HTML and other content from a web server, USD now becomes a specialized browser loading all of it's content from a Dynamics CRM server.  This includes all of it's configuration as it always has but also any custom files that may have been created for special needs.

The new feature that makes this possible is called Customization Files.  A new option is added to the administration section for USD to support this features.

 

After clicking on this option, you will be presented with a list of customization files.  You can add a new customization file that will be automatically loaded by the desktop by clicking new on the toolbar.  You will be presented with a form resembling the following.

 

Provide a unique name and a version number.  The version number helps the admin assign the correct version of the file to the right group of users.  The beauty of this is that you may have 2 versions of the same file loaded in the server.  One version may be given to a user in one configuration while another version is given to another user in a different configuration.

 

Creating a USD Package

Before you just zip up your file and try to upload it, realize that this zip file is actually a Package.  Packages must contain a special [Content_Types.xml] file in the zip file that indicates the content type of each of the types of files located in the zip.

An example of this file resembles the following.

 <?xml version="1.0" encoding="utf-8"?>
 
 <Types xmlns="https://schemas.openxmlformats.org/package/2006/content-types">
 
 <Default Extension="xml" ContentType="application/octet-stream" />
 
 <Default Extension="dll" ContentType="application/octet-stream" />
 
 <Default Extension="exe" ContentType="application/octet-stream" />
 
 <Default Extension="config" ContentType="application/octet-stream" />
 
 </Types>
 

 

A command line utility was created to help control creators auto generate a package from your post build
step. This tool is not supported but the source is included in the zip.

<<USDCustomizationPackageCreator.zip>>

The syntax for
running this utility is as follows.

USDCustomizationPackageCreator.exe
filename1 [filename2] [-output outputname]

 

An example of
running the utility.

USDCustomizationPackageCreator.exe
MyCustomFile.dll -output MyCustomFile.zip

 

Currently the utility does not support wildcards.

Once the package is created, you can go back to CRM and upload it to the Customization File record.

 

How the User Gets the Customization File

When the user launches USD, the cache version is checked to see if the local configuration needs to be updated, just as it normally would (See https://technet.microsoft.com/en-us/library/dn646861(v=crm.6).aspx).  If the cache needs to be updated, the configuration will be reloaded by the client including the Configuration Files list.  For each of the Configuration Files, the package is downloaded to the Users profile and unzipped.

When you configure the hosted controls, you will want to specify the URI as you would if the DLL were to reside in the same folder as the EXE, without the path and extension.  When the hosted control needs loading, the system will load the file from the appropriate location in the user profile directory.

Considerations

Currently, you cannot include unmanaged binaries (non-.NET binaries) in your package that is deployed in this manner. This is something that should be resolved with the next release.

USDCustomizationPackageCreator.zip

Update: One of the important thing that developers miss out is the fact that the customizations file zip should contain the exact folder hierarchy as the hosted control would expect when extracted. For example - if the dlls files are to be in the root folder, zip the contents inside your folder and not the folder itself. As a tip - before you upload the customization file to CRM server, extract the zip file and check if the contents are showing up the way you expect. If they are inside the folder, you may have to remove that hierarchy and zip it again.