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="">
 <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" />


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.


The syntax for
running this utility is as follows.

filename1 [filename2] [-output outputname]


An example of
running the utility.

MyCustomFile.dll -output


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  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.


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.

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.

Comments (19)
  1. I can not make it work says:

    All done. Files created with the tool and uploaded to CRM, and added to the configuration. But when USD is launched, custom actions are not there and I can not see them downloaded anywhere. Is it needed to reference configuration files from anywhere in the hosted control? How to do this?

    Thanks in advance

  2. Custom actions? says:

    Can you please clarify when you say custom actions are not there. The Customization files section only downloads the DLLs with your hosted controls in them. You still need to configure these controls to load within the Hosted Controls section and add the action names as you normally would with custom files.

  3. Trying to clarify says:

    Sorry for my poor description, I am an USD newbe :).

    I have configured a web hosted application to use a dll for some kind of automation. It works just copying the dlls into the USD installation directory. With this solution you are proposing, I think this will not be needed any more. I have followed these steps:

    – I have created the zip file using your tool (it Works like a charm 🙂 ).

    – I have created a customization file entry on CRM for my zip file.

    – I have added my customization file to my configuration.

    – I have not made any additional changes on my hosted control, I keep the configuration and actions that make the control Works when copying the dll into the installation folder.

    – Now I am launching USD from a clean PC to test it Works. It doesn't. Automation is not there.

    I guess that with this approach the zip file will be downloaded by USD but I can not find this customization file on the USD installation folder or the cache folder in AppData.

    So I don't know if I am missing something or I am not looking on the right places.

    Thanks for your time!

  4. Getting closer says:

    Ok, I finally have found the local folder were files are downloaded, something like this


    Now, a log file place on this folder shows this error:

    System.IO.FileNotFoundException: Could not load file or assembly 'mydll' or one of its dependencies. The system cannot find the file specified.

    If I copy the dll into the .exe folder, it Works properly. So I think USD client is not able to read the download folder. Any ideas? This is Windows 8.1

    Thanks in advance

  5. USD 2.0 backward compatible? says:

    Please confirm if USD 2.0 featuring this Customization facility, is backward compatible with CRM 2013 SP1?

  6. Getting closer - more tests says:

    I have tried this on Windows 10. It does not work. I can see procmonitor accessing and downloading the zip files and unzipping the files later, but finally not working.

    I am discarding hosted control configuration or dlls framework version as it I copy the dlls from the App folder to the installation folder, it Works.

    From your article, I think the hosted control configuration is:

    URI: dll without path and extensión

    Type: namespace.class

    Right? Nothing special.

    And I would say no additional path or configuration must be created apart from customization file creation and add them to the configuration. Am I right?

    Thanks in advance

  7. Can't get it to work says:

    I'am having the same problem described above.

    – created the zip with the assemblies + content types XML.

    – created the customization file in the CRM and upload the zip into it.

    – associated the customization file with the configuration "config1"

    on the client side I log with an agent associated with "config1".

    No control is loaded. I can the see contents of the zip in "%appdata%LocalMicrosoftUnifiedServiceDesk<MyOrganizationName>" and all DLLs are there

    but in the log file I see FileNotFoundExceptions for the URI's defined in the my config hosted controls. If the DDL's are copied to the USD dir it naturally works.

    Some help is much appreciated. Thanks.

    1. This issue seems to be working fine with the new release of USD

  8. You have to configure only the assembly name as the Hosted Control Assembly URI. if you give the path, this will not work.

    For example –

    Assembly URI should be something line myxxx.dll

    instead of

    c:program filesabcmyxxx.dll

    if this is still does not address the problem, please start at thread on the communities site (under Microsoft Dynamics CRM Forums > Microsoft Dynamics CRM


    Sid Gundavarapu

  9. Can't get it to work says:

    Thank you friend but we were already doing that. The assembly URI we put is the assembly name. This phrase caught my attention:

    "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."

    Although we do not have unmanaged DLL's we link native code. I think this is the problem.

  10. Arpit Shrivastava says:

    Hello Guys,  pls help me out in this…

    In my dev crm org i already have package deployer of old usd ver and now I have to update it to USD 2.0 Package Deployer, and when i updated it , customization file is not working….

    I also tried by creating a trial crm organisation, i install old USD ver package deployer then install USD 2.0 package deployer and still am not able to reflect my custom dlls changes…

    But intresting thing is that when i installed only fresh USD 2.0 package deployer. Customization File is working fine….

    Please let me know is there any bug in new USD 2.0 package deployer or is there any other approach to do the same.

    Because in my dev crm org, old usd ver package deployer is already installed , i have to update it to new USD 2.0 package deployer.

    1. Scott Hoff says:

      Hello Arpit,

      You described a few situations where Customization Files either work or don’t. Can you please clarify: When it works, how do you know that it did? When it doesn’t work, how do you know that it didn’t?

  11. Nguyen says:


    First, thanks for your post so much.
    And I have a problem with my project.
    Is there any way to export the customization File to another CRM server? example: From dev environment to production Environment, (we cannot let user upload Customization Files manually)
    I have tried using the Migration Tool that Microsoft supported but it isn’t work with Customization Files.

    Thanks so much.

    1. You can include annotation table in the schema and export the configurations from the source CRM server. After export, extract the file and edit data.xml. Locate all the annotations from the file and keep only the ones for your customization files. Once done, save your file and compress the files back to file.

      You can now import this file to your destination CRM server to automatically copy the customization files.

      Hope this helps!

  12. All, I’ve updated the blog post with a paragraph at the end to provide more information on one of the most common reasons why this feature does not work and how to address that.


  13. Ashok says:

    Hi, I am currently trying to automate the upload task of file. Is there any ps1 script or sdk api to upload custoamization file ? Thanks.

    1. JaymePechan says:

      It is a record attachment so it goes into ActivityMimeAttachment. It is a function of creating a new record in CRM.

      1. Ashok says:

        Thanks for the reply. I am new to CRM 🙂 & still learning a lot. Will try it.

  14. Pankaj Jain says:

    Worked like a charm! Thanks a lot for the post!

Comments are closed.

Skip to main content